diff --git a/.env.example b/.env.example index 6c84f25b3b..0cc0f22bf0 100644 --- a/.env.example +++ b/.env.example @@ -67,6 +67,14 @@ DISABLE_SQLITE_AUTO_BACKUP=false # Used by: src/shared/utils/rateLimiter.ts # Example: redis://localhost:6379 (or redis://redis:6379 in Docker) # REDIS_URL=redis://localhost:6379 +# Host interface docker-compose publishes the Redis sidecar on. +# Default: 127.0.0.1 (loopback only). The compose Redis runs WITHOUT +# `requirepass`, and app containers reach it over the compose network +# (redis:6379) — the published port is only for host-side tooling. Setting this +# to 0.0.0.0 exposes an unauthenticated Redis to your whole LAN. +# REDIS_BIND_HOST=127.0.0.1 +# Host port for the compose Redis sidecar. Default: 6379. +# REDIS_PORT=6379 # ═══════════════════════════════════════════════════════════════════════════════ # 3. NETWORK & PORTS @@ -445,6 +453,13 @@ ALLOW_API_KEY_REVEAL=false # Default: false # OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=false +# Per-model concurrency cap for round-robin combos (#9100). +# Used by: open-sse/services/comboConfig.ts — the round-robin combo semaphore +# was hard-capped at 3 concurrent requests per model with no override, which +# serialized higher-concurrency traffic behind that cap. +# Validated to >= 1, clamped to <= 32. | Default: 3 +# COMBO_CONCURRENCY_PER_MODEL=3 + # ═══════════════════════════════════════════════════════════════════════════════ # 7. URLS & CLOUD SYNC # ═══════════════════════════════════════════════════════════════════════════════ @@ -1166,6 +1181,17 @@ CURSOR_USER_AGENT="Cursor/3.4" # fallback when FETCH_TIMEOUT_MS is unset. Default: 120000 (2 min). # OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS=120000 +# ── Proxy/relay fetch (connection pooling, #9158) ── +# Used by: open-sse/utils/proxyFetch.ts. +# A hung relay must fail BEFORE the client/agent timeout (typically 30s) so the +# caller sees a relay-specific failure instead of a generic upstream timeout. +# Capped at 29000ms so this timeout always fires first. Default: 25000 (25s). +# OMNIROUTE_RELAY_FETCH_TIMEOUT_MS=25000 + +# Shared retry backoff (ms) for the direct/relay/proxy retry-once paths. +# 0 = retry immediately. Default: 10. +# OMNIROUTE_RETRY_BACKOFF_MS=10 + # ── Firecrawl web-fetch executor ── # Point at a self-hosted Firecrawl instance (defaults to the public cloud API). # When set to a non-cloud base URL, the API key becomes optional. @@ -1227,6 +1253,14 @@ CURSOR_USER_AGENT="Cursor/3.4" # OMNIROUTE_BROWSER_POOL=on # WEB_COOKIE_USE_BROWSER=0 +# ── Adobe Firefly browser sign-in (system Chrome/Edge CDP) ── +# Used by: open-sse/services/adobeFireflyBrowserLogin.ts. The Firefly login +# flow drives a real, system-installed Chrome or Microsoft Edge via CDP so the +# user can sign in interactively; the executable is auto-detected from common +# install paths per OS. Set this to override that detection (e.g. a portable +# install or a non-standard path) when auto-detection fails. +# OMNIROUTE_LOGIN_BROWSER_PATH= + # ── Circuit breaker thresholds and reset windows ── # Used by: open-sse/config/constants.ts → src/lib/resilience/settings.ts. # Defaults match historical PROVIDER_PROFILES values (post-scaling for @@ -1338,6 +1372,10 @@ APP_LOG_TO_FILE=true # Default: 100000 # CALL_LOGS_TABLE_MAX_ROWS=100000 +# Force detailed request logging on or off, overriding the dashboard setting. +# Values: true | false | Default: unset (follow dashboard setting) +# ENABLE_REQUEST_LOGS=false + # Maximum age for orphaned active request log entries before the in-memory # pending-request reaper removes them. Accepts milliseconds. # Default: 3600000 (1 hour) @@ -1898,6 +1936,15 @@ APP_LOG_TO_FILE=true # CHANGELOG_BASE_REF=origin/release/v0.0.0 # ALLOW_CHANGELOG_REMOVALS=1 +# ── Remote audio provider nodes ── +# Used by: src/app/api/v1/_shared/audioProviderNodes.ts — lets the /v1/audio/* +# routes use an OpenAI-compatible provider node hosted outside localhost. +# OFF by default: routing audio to a remote host changes egress identity, so it +# must be an explicit operator decision. Loopback/private nodes (localhost, +# 127.0.0.1, 172.16-31.x) are always allowed and unaffected by this flag. +# When enabled, the node authenticates with the API key stored on its connection. +# AUDIO_REMOTE_PROVIDER_NODES=false + # ── 1Proxy egress pool ── # Used by: src/lib/oneproxySync.ts — fetches proxy nodes from the OmniRoute # CrofAI 1Proxy service. Disable, override URL, or tune the import quality. @@ -2230,6 +2277,11 @@ QUOTA_STORE_DRIVER=sqlite # sqlite | redis # Host port for the 1-click Redis launcher. Default: 6379. Bump if the host # already binds 6379. The container's internal port stays 6379. # OMNIROUTE_REDIS_HOST_PORT= +# Host interface the 1-click Redis launcher publishes on. Default: 127.0.0.1 +# (loopback only). The launcher starts Redis WITHOUT a password, so binding +# 0.0.0.0 hands every host on your LAN an unauthenticated Redis — only widen +# this if you also set a password on the instance yourself. +# OMNIROUTE_REDIS_BIND_HOST= # Redis image used by the 1-click Redis launcher. Default: redis:7-alpine. # Override to redis:8-alpine or a private registry mirror as needed. # OMNIROUTE_REDIS_IMAGE= diff --git a/.fakebin-9475/npm b/.fakebin-9475/npm new file mode 100755 index 0000000000..9422990b9c --- /dev/null +++ b/.fakebin-9475/npm @@ -0,0 +1,4 @@ +#!/usr/bin/env bash +if [ "$1" = "view" ]; then echo "3.8.99"; exit 0; fi +if [ "$1" = "install" ]; then echo "added 1 package"; exit 0; fi +exit 0 diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000000..954ac64653 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,57 @@ +name: Build App + +on: + workflow_dispatch: + push: + branches: ["**"] + +permissions: + contents: read + +jobs: + build: + name: Fast Production Build + runs-on: ubuntu-latest + steps: + - name: Expand Virtual Memory (Native 10GB Swap) + run: | + sudo swapoff -a || true + sudo rm -f /mnt/swapfile /swapfile + sudo fallocate -l 10G /mnt/swapfile || sudo dd if=/dev/zero of=/mnt/swapfile bs=1M count=10240 + sudo chmod 600 /mnt/swapfile + sudo mkswap /mnt/swapfile + sudo swapon /mnt/swapfile + free -h + + - name: Checkout repository + uses: actions/checkout@v7 + with: + persist-credentials: false + + - name: Setup Node.js + uses: actions/setup-node@v7 + with: + node-version: "24" + cache: npm + + - name: Install dependencies + run: npm ci + + - name: Build Next.js app & CLI bundle + run: | + npm run build:release + env: + NODE_OPTIONS: "--max-old-space-size=12288" + OMNIROUTE_BUILD_MEMORY_MB: "12288" + OMNIROUTE_USE_TURBOPACK: "1" + + - name: Archive build outputs + run: | + tar -czf omniroute-build.tar.gz .build dist + + - name: Upload build artifact + uses: actions/upload-artifact@v4 + with: + name: omniroute-build + path: omniroute-build.tar.gz + retention-days: 7 diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 4ec8ae2dab..ccfd170c9b 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -4,6 +4,7 @@ on: push: branches: - main + - "release/v*" tags: - "v*" paths-ignore: @@ -57,39 +58,20 @@ jobs: REF_TYPE: ${{ github.ref_type }} INPUT_VERSION: ${{ inputs.version }} PROMOTE_INPUT: ${{ inputs.promote_latest }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} run: | set -euo pipefail - # 1) Resolve version string from the trigger (all inputs come via env). - case "$EVENT_NAME" in - workflow_dispatch) - VERSION="${INPUT_VERSION#v}" - ;; - push) - if [ "$REF_TYPE" = "tag" ]; then - VERSION="${REF_NAME#v}" - else - # Push to main → build & tag as `main` only. Never touch :latest. - VERSION="main" - fi - ;; - release) - VERSION="${REF_NAME#v}" - ;; - *) - VERSION="${REF_NAME#v}" - ;; - esac - # Sanity-check: only allow [A-Za-z0-9._-] in VERSION (defense in depth). - if ! printf '%s' "$VERSION" | grep -qE '^[A-Za-z0-9._-]+$'; then - echo "Refusing to use unsafe VERSION value: $VERSION" >&2 - exit 1 - fi + # 1) Resolve version/channel from the trigger. Only the current default + # release branch publishes the mutable `next` channel; main keeps `main`. + VERSION=$(bash scripts/ci/resolve-docker-publish-version.sh \ + "$EVENT_NAME" "$REF_TYPE" "$REF_NAME" "$INPUT_VERSION" "$DEFAULT_BRANCH") echo "version=$VERSION" >> "$GITHUB_OUTPUT" - # 2) Decide whether to promote :latest. + # 2) Decide whether to promote :latest. Floating channels are never + # eligible, and the helper independently fails closed for non-semver. PROMOTE="false" - if [ "$VERSION" = "main" ]; then + if [ "$VERSION" = "main" ] || [ "$VERSION" = "next" ]; then PROMOTE="false" elif printf '%s' "$VERSION" | grep -qE -- '-(rc|alpha|beta|pre|next)'; then echo "Pre-release identifier detected — skipping :latest." @@ -109,10 +91,10 @@ jobs: fi echo "promote_latest=$PROMOTE" >> "$GITHUB_OUTPUT" - # 3) Skip if this exact version is already published in Docker Hub. - # `main` is always rebuilt (mutable floating tag). + # 3) Skip immutable version tags that already exist. Floating `main` + # and `next` channels are intentionally rebuilt on every matching push. SKIP="false" - if [ "$VERSION" != "main" ]; then + if [ "$VERSION" != "main" ] && [ "$VERSION" != "next" ]; then if docker manifest inspect "diegosouzapw/omniroute:${VERSION}" >/dev/null 2>&1; then echo "Image diegosouzapw/omniroute:${VERSION} already exists on Docker Hub — skipping rebuild." SKIP="true" @@ -397,7 +379,7 @@ jobs: - name: Update Docker Hub description # Only refresh README/description when we actually promote :latest - # (avoids overwriting from main pushes or back-fill builds). + # (avoids overwriting from main, next, or back-fill builds). if: needs.prepare.outputs.promote_latest == 'true' uses: peter-evans/dockerhub-description@v5 with: diff --git a/.github/workflows/nightly-release-green.yml b/.github/workflows/nightly-release-green.yml index f435bf5acd..65d12db4de 100644 --- a/.github/workflows/nightly-release-green.yml +++ b/.github/workflows/nightly-release-green.yml @@ -193,7 +193,7 @@ jobs: gh issue comment "$EXISTING" --repo "$GITHUB_REPOSITORY" --body-file issue-body.md echo "Updated existing issue #$EXISTING" else - gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --body-file issue-body.md + gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --label base-red --body-file issue-body.md fi - name: Upload report artifact @@ -291,7 +291,7 @@ jobs: gh issue comment "$EXISTING" --repo "$GITHUB_REPOSITORY" --body-file issue-body.md echo "Updated existing issue #$EXISTING" else - gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --body-file issue-body.md + gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --label base-red --body-file issue-body.md fi - name: Upload report artifact diff --git a/@omniroute/opencode-plugin/src/index.ts b/@omniroute/opencode-plugin/src/index.ts index dcd881ab4e..f54adb8d50 100644 --- a/@omniroute/opencode-plugin/src/index.ts +++ b/@omniroute/opencode-plugin/src/index.ts @@ -4271,7 +4271,7 @@ export function buildStaticProviderEntry( // has no corresponding provider block. So bare keys (no `/`) MUST be // prefixed with the resolved providerId. Already-prefixed keys // (e.g. `cc/claude-opus-4-7`) are left as-is to avoid double-prefixing. - models[raw.id.includes("/") ? raw.id : `${opts.providerId}/${raw.id}`] = entry; + models[raw.id] = entry; } // Combo entries → stripped LCD shape. Each combo is keyed as @@ -4466,7 +4466,7 @@ export function buildStaticProviderEntry( // (`opencode-omniroute/opencode-omniroute/`), and `parseModel()` // resolves credentials for the nonexistent provider `opencode-omniroute` // instead of `omniroute`. See #7976. - models[buildComboKey(combo, usedComboKeys, opts.omnirouteProviderId)] = entry; + models[buildComboKey(combo, usedComboKeys, opts.omnirouteProviderId).split("/").pop()!] = entry; // Make this combo's resolved entry available to parent combos // that reference it via combo-ref. Use the friendly name since diff --git a/AGENTS.md b/AGENTS.md index c57fdd55b2..faaa956fdb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,63 +1,229 @@ # OmniRoute agent guide -## Project +> **Single source of truth.** This file holds ALL project rules, conventions, architecture notes +> and Hard Rules for every AI assistant working this repository (Claude Code, Gemini, Codex, +> Copilot, and any other agent). `CLAUDE.md` and `GEMINI.md` only add assistant-specific deltas +> and point back here. When a rule needs to change, change it HERE — never re-fork it into an +> assistant-specific file. -OmniRoute is a unified AI proxy/router. The repository contains the Next.js application -(`src/`), streaming engine workspace (`open-sse/`), Electron desktop app (`electron/`), -CLI (`bin/`), and tests (`tests/`). +## Quick Start -## Setup and focused checks +```bash +npm install # Install deps (auto-generates .env from .env.example) +npm run dev # Dev server at http://localhost:20128 +npm run build # Production build (Next.js 16 standalone) +npm run build:release # Release build +npm run lint # ESLint (0 errors expected; warnings are pre-existing) +npm run typecheck:core # TypeScript check (should be clean) +npm run typecheck:noimplicit:core # Strict check (no implicit any) +npm run test:coverage # Unit tests + coverage gate (60/60/60/60 — statements/lines/functions/branches) +npm run check # lint + test combined +npm run check:cycles # Detect circular dependencies +npm run check:docs-all # Run after changing documentation (includes fabricated-docs validation) +``` -- Runtime: Node.js `>=22.22.3 <23` or `>=24.0.0 <27`; npm 10+. -- Install dependencies: `npm install`. -- Start development: `npm run dev`. -- Build: `npm run build`; release build: `npm run build:release`. -- Lint: `npm run lint`. -- Core type check: `npm run typecheck:core`. -- Run the most focused test for changed code first: - `node --import tsx/esm --test tests/unit/.test.ts`. -- Other suites: `npm run test:vitest`, `npm run test:e2e`, - `npm run test:protocols:e2e`, and `npm run test:ecosystem`. -- Run `npm run check:docs-all` after changing documentation. +### Running Tests -For the complete test matrix, coverage requirements, and pull-request gates, read -[`CONTRIBUTING.md`](CONTRIBUTING.md#running-tests). +Run the most focused test for changed code first: -## Documentation accuracy +```bash +# Single test file (Node.js native test runner — most tests) +node --import tsx/esm --test tests/unit/your-file.test.ts -Documentation must describe verified behavior, not plausible behavior. +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest -1. Before documenting an API name, endpoint, path, CLI command, or environment variable, - search for it: `rg -n "name" src/ open-sse/ bin/`. If it has no source match, do not - document it. -2. Measure mutable counts instead of writing them from memory: use `wc -l ` or a - directory-specific count command. -3. Copy code examples from working usage or run them. Prefer a source link such as - `path/to/file.ts:line` to an invented signature. -4. Run `npm run check:docs-all` for edits under `docs/`; it includes the fabricated-docs - validation. +# All suites +npm run test:all +``` -## Code conventions +Other suites: `npm run test:e2e`, `npm run test:protocols:e2e`, `npm run test:ecosystem`. -- Format with Prettier: two spaces, semicolons, double quotes, 100-character line width, - and ES5 trailing commas. Run Prettier on changed files. -- TypeScript target is ES2022 with bundler module resolution. Prefer explicit types. -- Import order: external, internal (`@/` and `@omniroute/open-sse`), then relative. -- Do not add logic to `src/lib/localDb.ts`; import from the owning `src/lib/db/` module. -- Use specific errors and contextual logging. Do not silently swallow SSE-stream failures; - use abort signals for cleanup and return appropriate HTTP status codes. +For full test matrix, see `CONTRIBUTING.md` → "Running Tests". For deep architecture, see the +Repository map and Reference Documentation sections below. -## Security requirements +--- -- Never commit credentials or log SQLite encryption keys. -- Validate API inputs with Zod and use the route's required authentication path. -- Sanitize user HTML with DOMPurify. -- Use `resolvePublicCred()` for public upstream OAuth identifiers; never add them as string - literals. See [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md). -- Use `buildErrorBody()` or `sanitizeErrorMessage()` for HTTP, SSE, executor, and MCP errors; - do not return raw `err.stack` or `err.message`. See - [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md). -- Pass runtime values to `exec()` or `spawn()` through `env`, not interpolation into a script. +## Project at a Glance + +**OmniRoute** — unified AI proxy/router. One endpoint, 291 LLM providers, auto-fallback. + +| Layer | Location | Purpose | +| ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| API Routes | `src/app/api/v1/` | Next.js App Router — entry points | +| Handlers | `open-sse/handlers/` | Request processing (chat, embeddings, etc) | +| Executors | `open-sse/executors/` | Provider-specific HTTP dispatch | +| Translators | `open-sse/translator/` | Format conversion (OpenAI↔Claude↔Gemini) | +| Transformer | `open-sse/transformer/` | Responses API ↔ Chat Completions | +| Services | `open-sse/services/` | Combo routing, rate limits, caching, etc | +| Database | `src/lib/db/` | SQLite domain modules (130 migrations) | +| Domain/Policy | `src/domain/` | Policy engine, cost rules, fallback logic | +| MCP Server | `open-sse/mcp-server/` | 104 tools (42 base + memory/skill/agentSkill/pool/notion/obsidian/gamification/plugin modules), 3 transports (stdio / SSE / Streamable HTTP), 31 scopes | +| A2A Server | `src/lib/a2a/` | JSON-RPC 2.0 agent protocol | +| Skills | `src/lib/skills/` | Extensible skill framework | +| Memory | `src/lib/memory/` | Persistent conversational memory | + +Monorepo: `src/` (Next.js 16 app), `open-sse/` (streaming engine workspace), `electron/` (desktop app), `tests/`, `bin/` (CLI entry point). + +--- + +## Request Pipeline + +``` +Client → /v1/chat/completions (Next.js route) + → CORS → Zod validation → auth? → policy check → prompt injection guard + → handleChatCore() [open-sse/handlers/chatCore.ts] + → cache check → rate limit → combo routing? + → resolveComboTargets() → handleSingleModel() per target + → translateRequest() → getExecutor() → executor.execute() + → fetch() upstream → retry w/ backoff + → response translation → SSE stream or JSON + → If Responses API: responsesTransformer.ts TransformStream +``` + +API routes follow a consistent pattern: `Route → CORS preflight → Zod body validation → Optional auth (extractApiKey/isValidApiKey) → API key policy enforcement → Handler delegation (open-sse)`. No global Next.js middleware — interception is route-specific. + +**Combo routing** (`open-sse/services/combo.ts`): 19 public strategies (priority, weighted, fill-first, round-robin, p2c, random, least-used, cost-optimized, reset-aware, reset-window, headroom, strict-random, auto, lkgp, context-optimized, cache-optimized, context-relay, fusion, pipeline). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks. The `fusion` strategy is the exception: it fans out to a panel of models in parallel, then a judge model synthesizes one final answer (`open-sse/services/fusion.ts`). See `docs/routing/AUTO-COMBO.md` for the 13-factor Auto-Combo scoring + the full strategy table and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers. + +--- + +## Resilience Runtime State + +OmniRoute has three related but distinct temporary-failure mechanisms. Keep their +scope separate when debugging routing behavior. See the +[3-layer resilience diagram](./docs/diagrams/exported/resilience-3layers.svg) +(source: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd)) +for an at-a-glance map. + +### Provider Circuit Breaker + +**Scope**: whole provider, e.g. `glm`, `openai`, `anthropic`. + +**Purpose**: stop sending traffic to a provider that is repeatedly failing at the +upstream/service level, so one unhealthy provider does not slow down every request. + +**Implementation**: + +- Core class: `src/shared/utils/circuitBreaker.ts` +- Chat gate/execution wiring: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts` +- Runtime status API: `src/app/api/monitoring/health/route.ts` +- Shared wrappers: `open-sse/services/accountFallback.ts` +- Persisted state table: `domain_circuit_breakers` + +**States**: + +- `CLOSED`: normal traffic is allowed. +- `OPEN`: provider is temporarily blocked; callers get a provider-circuit-open response + or combo routing skips to another target. +- `HALF_OPEN`: reset timeout has elapsed; allow a probe request. Success closes the + breaker, failure opens it again. + +**Defaults** (`open-sse/config/constants.ts`): + +- OAuth providers: threshold `3`, reset timeout `60s`. +- API-key providers: threshold `5`, reset timeout `30s`. +- Local providers: threshold `2`, reset timeout `15s`. + +Only provider-level failure statuses should trip the provider breaker: + +```ts +(408, 500, 502, 503, 504); +``` + +Do not trip the whole-provider breaker for normal account/key/model errors like most +`401`, `403`, or `429` cases. Those usually belong to connection cooldown or model +lockout. A generic API-key provider `403` should be recoverable unless it is classified +as a terminal provider/account error. + +The breaker uses lazy recovery, not a background timer. When `OPEN` expires, reads such +as `getStatus()`, `canExecute()`, and `getRetryAfterMs()` refresh the state to +`HALF_OPEN`, so dashboards and combo candidate builders do not keep excluding an +expired provider forever. + +### Connection Cooldown + +**Scope**: one provider connection/account/key. + +**Purpose**: temporarily skip one bad key/account while allowing other connections for +the same provider to continue serving requests. + +**Implementation**: + +- Write/update path: `src/sse/services/auth.ts::markAccountUnavailable()` +- Account selection/filtering: `src/sse/services/auth.ts::getProviderCredentials...` +- Cooldown calculation: `open-sse/services/accountFallback.ts::checkFallbackError()` +- Settings: `src/lib/resilience/settings.ts` + +Important fields on provider connections: + +```ts +rateLimitedUntil; +testStatus: "unavailable"; +lastError; +lastErrorType; +errorCode; +backoffLevel; +``` + +During account selection, a connection is skipped while: + +```ts +new Date(rateLimitedUntil).getTime() > Date.now(); +``` + +Cooldowns are also lazy: when `rateLimitedUntil` is in the past, the connection becomes +eligible again. On successful use, `clearAccountError()` clears `testStatus`, +`rateLimitedUntil`, error fields, and `backoffLevel`. + +Default connection cooldown behavior: + +- OAuth base cooldown: `5s`. +- API-key base cooldown: `3s`. +- API-key `429` should prefer upstream retry hints (`Retry-After`, reset headers, or + parseable reset text) when available. +- Repeated recoverable failures use exponential backoff: + +```ts +baseCooldownMs * 2 ** failureIndex; +``` + +The anti-thundering-herd guard prevents concurrent failures on the same connection from +repeatedly extending the cooldown or double-incrementing `backoffLevel`. + +Terminal states are not cooldowns. `banned`, `expired`, and `credits_exhausted` are +intended to stay unavailable until credentials/settings change or an operator resets +them. Do not overwrite terminal states with transient cooldown state. + +### Model Lockout + +**Scope**: provider + connection + model. + +**Purpose**: avoid disabling a whole connection when only one model is unavailable or +quota-limited for that connection. + +Examples: + +- Per-model quota providers returning `429`. +- Local providers returning `404` for one missing model. +- Provider-specific mode/model permission failures such as selected Grok modes. + +Model lockout lives in `open-sse/services/accountFallback.ts` and lets the same +connection continue serving other models. + +### Debugging Guidance + +- If all keys for a provider are skipped, inspect both provider breaker state and each + connection's `rateLimitedUntil`/`testStatus`. +- If a provider appears permanently excluded after the reset window, check whether code + is reading raw `state` instead of using `getStatus()`/`canExecute()`. +- If one provider key fails but others should work, prefer connection cooldown over + provider breaker. +- If only one model fails, prefer model lockout over connection cooldown. +- If a state should self-recover, it should have a future timestamp/reset timeout and a + read path that refreshes expired state. Permanent statuses require manual credential + or config changes. + +--- ## Repository map @@ -76,6 +242,217 @@ Read the nearest `AGENTS.md` and the linked deep-dive before making a non-trivia | Safety and governance | `src/lib/{guardrails,compliance}/`, `src/server/authz/` | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md), [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) | | Operations | `src/mitm/`, tunnel modules, `electron/` | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md), [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md) | +--- + +## File placement & repo-root hygiene + +- **Test files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`). +- **Scripts and utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside one of the `scripts/` subfolders (`build/`, `dev/`, `check/`, `docs/`, `i18n/`, `ad-hoc/`). One-shot or experimental code goes under `scripts/ad-hoc/`. NEVER dump loose scripts in the project root (`/`) or the top-level `scripts/` folder. + +**The project root MUST ONLY contain:** + +- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, `tsconfig*.json`, `playwright.config.ts`, `prettier.config.mjs`, `postcss.config.mjs`, `sonar-project.properties`, `fly.toml`, `docker-compose*.yml`, `Dockerfile`) +- Dependency files (`package.json`, `package-lock.json`) +- Documentation files (`README.md`, `CHANGELOG.md`, `LICENSE`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `llm.txt`, `Tuto_Qdrant.md`) +- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`, `.npmignore`, `.npmrc`, `.node-version`, `.nvmrc`, `.env.example`) + +When creating _any_ validation tests or one-off logic scripts, default to `scripts/ad-hoc/` or `tests/unit/` according to your goals. Do not pollute the `/` root context. + +--- + +## Key Conventions + +### Code Style + +- **2 spaces**, semicolons, double quotes, 100 char width, es5 trailing commas (enforced by lint-staged via Prettier) — run Prettier on changed files +- **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative +- **Naming**: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE +- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = error everywhere; `no-explicit-any` = **error** in `open-sse/` and `tests/` (since #6218 — pre-existing violations are frozen in `config/quality/eslint-suppressions.json`, new ones must be fixed; `npm run lint` applies the suppressions and is what CI runs) +- **TypeScript**: `strict: false`, target ES2022, module esnext, resolution bundler. Prefer explicit types. + +### Database + +- **Always** go through `src/lib/db/` domain modules — **never** write raw SQL in routes or handlers +- **Never** add logic to `src/lib/localDb.ts` (re-export layer only) +- **Never** barrel-import from `localDb.ts` — import specific `db/` modules instead +- DB singleton: `getDbInstance()` from `src/lib/db/core.ts` (WAL journaling) +- Migrations: `src/lib/db/migrations/` — versioned SQL files, idempotent, run in transactions + +### Error Handling + +- try/catch with specific error types, log with pino context +- Never swallow errors in SSE streams — use abort signals for cleanup +- Return proper HTTP status codes (4xx/5xx) + +### Security + +- **Never** use `eval()`, `new Function()`, or implied eval +- Validate all inputs with Zod schemas +- Encrypt credentials at rest (AES-256-GCM); never log SQLite encryption keys +- Sanitize user HTML with DOMPurify +- Upstream header denylist: `src/shared/constants/upstreamHeaders.ts` — keep sanitize, Zod schemas, and unit tests aligned when editing +- **Public upstream credentials** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web keys extracted from public CLIs): **MUST** be embedded via `resolvePublicCred()` from `open-sse/utils/publicCreds.ts` — **never** as string literals. See `docs/security/PUBLIC_CREDS.md` for the mandatory pattern. +- **Error responses** (HTTP / SSE / executor / MCP handler): **MUST** route through `buildErrorBody()` or `sanitizeErrorMessage()` from `open-sse/utils/error.ts` — **never** put raw `err.stack` or `err.message` in a response body. See `docs/security/ERROR_SANITIZATION.md`. +- **Shell commands built from variables**: when calling `exec()`/`spawn()` with a script that needs runtime values, pass them via the `env` option (shell-escaped automatically) — **never** string-interpolate untrusted/external paths into the script body. Reference: `src/mitm/cert/install.ts::updateNssDatabases`. +- **Secure-by-default libraries** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): prefer Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink over custom implementations whenever adding new security-sensitive surfaces. + +--- + +## Documentation accuracy + +Documentation must describe verified behavior, not plausible behavior. + +1. Before documenting an API name, endpoint, path, CLI command, or environment variable, + search for it: `rg -n "name" src/ open-sse/ bin/`. If it has no source match, do not + document it. +2. Measure mutable counts instead of writing them from memory: use `wc -l ` or a + directory-specific count command. +3. Copy code examples from working usage or run them. Prefer a source link such as + `path/to/file.ts:line` to an invented signature. +4. Run `npm run check:docs-all` for edits under `docs/`; it includes the fabricated-docs + validation. + +--- + +## Common Modification Scenarios + +### Adding a New Provider + +1. Register in `src/shared/constants/providers.ts` (Zod-validated at load) +2. Add executor in `open-sse/executors/` if custom logic needed (extend `BaseExecutor`) +3. Add translator in `open-sse/translator/` if non-OpenAI format +4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` if OAuth-based — if the upstream CLI ships a public client_id/secret, embed via `resolvePublicCred()` (see `docs/security/PUBLIC_CREDS.md`), **never** as a literal +5. Register models in `open-sse/config/providerRegistry.ts` +6. Write tests in `tests/unit/` (include the publicCreds shape assertion if you added a new embedded default) + +### Adding a New API Route + +1. Create directory under `src/app/api/v1/your-route/` +2. Create `route.ts` with `GET`/`POST` handlers +3. Follow pattern: CORS → Zod body validation → optional auth → handler delegation +4. Handler goes in `open-sse/handlers/` (import from there, not inline) +5. Error responses use `buildErrorBody()` / `errorResponse()` from `open-sse/utils/error.ts` (auto-sanitized — never put `err.stack` or `err.message` raw in the body). See `docs/security/ERROR_SANITIZATION.md`. +6. Add tests — including at least one assertion that error responses do not leak stack traces (`!body.error.message.includes("at /")`) + +### Adding a New DB Module + +1. Create `src/lib/db/yourModule.ts` — import `getDbInstance` from `./core.ts` +2. Export CRUD functions for your domain table(s) +3. Add migration in `src/lib/db/migrations/` if new tables needed +4. Re-export from `src/lib/localDb.ts` (add to the re-export list only) +5. Write tests + +### Adding a New MCP Tool + +1. Add tool definition in `open-sse/mcp-server/tools/` with Zod input schema + async handler +2. Register in tool set (wired by `createMcpServer()`) +3. Assign to appropriate scope(s) +4. Write tests (tool invocation logged to `mcp_audit` table) + +### Adding a New A2A Skill + +1. Create skill in `src/lib/a2a/skills/` (5 already exist: smart-routing, quota-management, provider-discovery, cost-analysis, health-report) +2. Skill receives task context (messages, metadata) → returns structured result +3. Register in `A2A_SKILL_HANDLERS` in `src/lib/a2a/taskExecution.ts` +4. Expose in `src/app/.well-known/agent.json/route.ts` (Agent Card) +5. Write tests in `tests/unit/` +6. Document in `docs/frameworks/A2A-SERVER.md` skill table + +### Adding a New Cloud Agent + +1. Create agent class in `src/lib/cloudAgent/agents/` extending `CloudAgentBase` (3 already exist: codex-cloud, devin, jules) +2. Implement `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources` +3. Register in `src/lib/cloudAgent/registry.ts` +4. Add OAuth/credentials handling if needed (`src/lib/oauth/providers/`) +5. Tests + document in `docs/frameworks/CLOUD_AGENT.md` + +### Adding a New Embedded Service + +1. Create installer in `src/lib/services/installers/{name}.ts` modeled on `ninerouter.ts` (use `runNpm` from `installers/utils.ts` — no shell interpolation, hard rule #13). +2. Register the service in `src/lib/services/bootstrap.ts` (add to `SERVICES[]` array and extend `buildSpawnArgsFactory()`). +3. Add a DB seed row for the new service in `src/lib/db/migrations/` (`version_manager` table, `status='not_installed'`, `auto_start=0`). +4. Create 7 API endpoints under `src/app/api/services/{name}/` (`_lib.ts`, `install`, `start`, `stop`, `restart`, `update`, `status`, `auto-start`). All delegate errors through `createErrorResponse()`. The shared `logs` endpoint is already wired via `[name]/logs/route.ts`. +5. Verify `/api/services/` is in `LOCAL_ONLY_API_PREFIXES` in `src/server/authz/routeGuard.ts`; add a test asserting `isLocalOnlyPath()` returns `true` for the new prefix if you add one (hard rule #17). +6. Add a UI tab in `src/app/(dashboard)/dashboard/providers/services/tabs/` reusing `ServiceStatusCard`, `ServiceLifecycleButtons`, `ServiceLogsPanel`. +7. Document in `docs/frameworks/EMBEDDED-SERVICES.md` (update §1 service table + §4 API reference) and `docs/openapi.yaml`. +8. Write tests: unit (`tests/unit/services/`), integration (`tests/integration/services/`, gated by `RUN_SERVICES_INT=1`), and update `docs/ops/RELEASE_CHECKLIST.md` smoke section. + +### Adding a New Guardrail / Eval / Skill / Webhook event + +- Guardrail: `src/lib/guardrails/` → docs: `docs/security/GUARDRAILS.md` +- Eval suite: `src/lib/evals/` → docs: `docs/frameworks/EVALS.md` +- Skill (sandbox): `src/lib/skills/` → docs: `docs/frameworks/SKILLS.md` +- Webhook event: `src/lib/webhookDispatcher.ts` → docs: `docs/frameworks/WEBHOOKS.md` + +--- + +## Reference Documentation + +For any non-trivial change, read the matching deep-dive first: + +| Area | Doc | +| --------------------------------------------- | ------------------------------------------------------- | +| Repo navigation | `docs/architecture/REPOSITORY_MAP.md` | +| Architecture | `docs/architecture/ARCHITECTURE.md` | +| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` | +| Auto-Combo (13-factor scoring, 19 strategies) | `docs/routing/AUTO-COMBO.md` | +| Resilience (3 mechanisms) | `docs/architecture/RESILIENCE_GUIDE.md` | +| Reasoning replay | `docs/routing/REASONING_REPLAY.md` | +| Skills framework | `docs/frameworks/SKILLS.md` | +| Memory system (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` | +| Cloud agents | `docs/frameworks/CLOUD_AGENT.md` | +| Guardrails (PII / injection / vision) | `docs/security/GUARDRAILS.md` | +| Public upstream credentials (Gemini/etc.) | `docs/security/PUBLIC_CREDS.md` | +| Error message sanitization | `docs/security/ERROR_SANITIZATION.md` | +| Evals | `docs/frameworks/EVALS.md` | +| Compliance / audit | `docs/security/COMPLIANCE.md` | +| Webhooks | `docs/frameworks/WEBHOOKS.md` | +| Authorization pipeline | `docs/architecture/AUTHZ_GUIDE.md` | +| Stealth (TLS / fingerprint) | `docs/security/STEALTH_GUIDE.md` | +| Agent protocols (A2A / ACP / Cloud) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` | +| MCP server | `docs/frameworks/MCP-SERVER.md` | +| A2A server | `docs/frameworks/A2A-SERVER.md` | +| API reference + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` | +| Provider catalog (auto-generated) | `docs/reference/PROVIDER_REFERENCE.md` | +| Tunnels | `docs/ops/TUNNELS_GUIDE.md` | +| Electron desktop app | `docs/guides/ELECTRON_GUIDE.md` | +| Release flow | `docs/ops/RELEASE_CHECKLIST.md` | +| Embedded services | `docs/frameworks/EMBEDDED-SERVICES.md` | +| Quality gates (~48 scripts, allowlist policy) | `docs/architecture/QUALITY_GATES.md` | + +--- + +## Testing + +| What | Command | +| ----------------------- | --------------------------------------------------------------------------- | +| Unit tests | `npm run test:unit` | +| Single file | `node --import tsx/esm --test tests/unit/your-file.test.ts` | +| Vitest (MCP, autoCombo) | `npm run test:vitest` | +| E2E (Playwright) | `npm run test:e2e` | +| Protocol E2E (MCP+A2A) | `npm run test:protocols:e2e` | +| Ecosystem | `npm run test:ecosystem` | +| Coverage gate | `npm run test:coverage` (60/60/60/60 — statements/lines/functions/branches) | +| Coverage report | `npm run coverage:report` | + +**PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`, you must include or update tests in the same PR. + +**Test layer preference**: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix. + +**Both test runners must pass**: `npm run test:unit` (Node native — most tests) AND `npm run test:vitest` (MCP server, autoCombo, cache) cover **non-overlapping files**. Both are wired in CI (jobs `test-unit` and `test-vitest`) and must be green before merging. A PR where only one suite passes may silently ship broken MCP tools or routing regressions. + +**Bug fix / issue triage protocol (Hard Rule #18)**: Every fix for a reported issue must be validated by one of the following — no exceptions: + +1. **TDD (preferred)** — write a failing test reproducing the bug → fix it → confirm the test passes. The test becomes the permanent regression guard. Touch only the files the test proves need changing; nothing more. +2. **Real-environment test (when TDD is not possible)** — deploy to the production VPS (`root@192.168.0.15`) and run a documented live test. Record the exact command + result in the PR description. Applies to: OAuth upstream flows, Cloudflare/WS upstream behavior, UI-only regressions, hardware-dependent behavior. +3. "It worked locally without a test" does not count. A fix without a test or a VPS validation record is not a fix — it is a guess. + +Why this matters: fixing bug A while opening bug B is worse than not fixing at all. The TDD/VPS gate enforces surgical scope — you touch only what the failing test proves is broken. Examples where this paid off: #3090 (claude-web 403), #3113 (WS HTTP fallback), #3052 (heap-guard auto-calibration). + +**Copilot coverage policy**: When a PR changes production code and coverage is below 60% (statements/lines/functions/branches), do not just report — add or update tests, rerun the coverage gate, then ask for confirmation. Include commands run, changed test files, and final coverage result in the PR report. + +--- + ## Review focus - Keep database operations in `src/lib/db/`; do not issue raw SQL from routes. @@ -88,6 +465,119 @@ Read the nearest `AGENTS.md` and the linked deep-dive before making a non-trivia - Do not close a contributor pull request after using its code; merge it through GitHub so the contributor receives credit. +--- + +## Planning & Research Artifacts + +`_tasks/` is a **separate, isolated git repository** that is gitignored by the main +repo (`.gitignore` → `_tasks/`). It is the canonical home for working artifacts — +plans, specs/designs, research, hand-offs — so they stay **versioned in their own +repo** instead of polluting the main OmniRoute tree. + +**Hard rule — never write planning / research output under `docs/` or the repo root.** +Whenever any plan/spec/research generator runs in this project (superpowers or otherwise), +save to `_tasks/` using the filename convention: + +| Artifact | Save here | +| -------------- | ------------------------------------------------------------- | +| Plans | `_tasks/superpowers/plans/YYYY-MM-DD-.md` | +| Specs / design | `_tasks/superpowers/specs/YYYY-MM-DD--design.md` | +| Research | `_tasks/research/…` | +| Hand-offs | `_tasks/hands-off/__v_sess-/` | + +Commit those artifacts inside the `_tasks/` repo (`git -C _tasks …`), never in the main repo. + +--- + +## Git Workflow + +```bash +# Never commit directly to main +git checkout -b feat/your-feature +git commit -m "feat: describe your change" +git push -u origin feat/your-feature +``` + +**Branch prefixes**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/` + +**Commit format** (Conventional Commits): `feat(db): add circuit breaker` — scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills` + +**Husky hooks**: + +- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11` + `check:tracked-artifacts` +- **pre-push**: intentionally light (PATH/npm sanity only). `any-budget` + `tracked-artifacts` + already run on pre-commit; re-running them on every push was pure double-pay. CI still + enforces both. (Was Fase 6A.12 full pre-push gate; folded into pre-commit in #6716.) + +### Worktree isolation (MANDATORY for every development task) + +Multiple sessions/agents work this repo in parallel. The main checkout is **shared**, so a +`git checkout`/branch switch in it silently discards another session's uncommitted work and +yanks the branch out from under whatever else is running (incidents: 2026-06-05, 2026-06-13). + +**Rule: never develop on the shared main checkout. Every task gets its own git worktree on its +own dedicated branch, and you MUST confirm the base branch with the operator before creating it.** + +1. **Ask first — which base branch?** Before creating anything, ask the operator (unless they + already told you) from which branch the new worktree/branch should be cut. Do NOT assume + `main` or "whatever I'm on" — the answer is usually the active `release/vX.Y.Z`, but it can + be another feature/release branch. Get the base explicitly. +2. **Create an isolated worktree + branch off that base** (never reuse the main checkout). + **🔴 MANDATORY PATH: every worktree lives under `.claude/worktrees/` — and nowhere else.** + This is the single canonical location. It is gitignored AND in the `tsconfig.json` / + `.dockerignore` excludes, so worktrees never leak into the build scope. **Never** use + `.worktrees/`, repo-root, or any other path — a worktree outside `.claude/worktrees/` + (a) escapes the build-scope excludes and poisons `next build` (the `tsconfig` + `include: **/*` globs ~70× the codebase → OOM; incident 2026-06-25) and (b) scatters + worktrees across two dirs. + + ```bash + BASE_BRANCH="release/vX.Y.Z" # ← the branch the operator confirmed in step 1 + TASK="feat/your-feature" # feat/ fix/ refactor/ docs/ test/ chore/ + git fetch origin "$BASE_BRANCH" + git worktree add ".claude/worktrees/${TASK##*/}" -b "$TASK" "origin/$BASE_BRANCH" + cd ".claude/worktrees/${TASK##*/}" + # Reuse the main checkout's node_modules to skip a per-worktree npm install. + # HARD LINKS (`cp -al`), never a symlink: ~5s for the whole tree and near-zero extra + # disk (the inodes are shared), and unlike a symlink it does not break the dev server. + cp -al "$(git -C rev-parse --show-toplevel)/node_modules" node_modules + ``` + + **Never `ln -s` node_modules.** Turbopack rejects a symlink that resolves outside the + project root, so `npm run dev` dies with a FATAL panic (`Symlink [project]/node_modules +is invalid, it points out of the filesystem root`) while typecheck, lint and the test + runners all keep passing — the error names "filesystem root", not the worktree, so it + reads like a Next/build bug and costs real time to trace (incident 2026-07-31, #9043). + +3. **Work, commit, push, open the PR — all from inside the worktree.** Never `git checkout` a + different branch inside a worktree another session might share. +4. **Tear down only your own** worktree + branch when done, from the main checkout: + `git worktree remove .claude/worktrees/` then `git branch -D `. Never blanket-delete + `fix/*`/`feat/*` — other sessions keep their own; delete only the branches you created, by name. +5. **Never touch another session's worktree, branch, or uncommitted changes.** If `git worktree +list` shows worktrees you didn't create, leave them alone. End every session with the main + checkout back on the branch it started on (the active `release/vX.Y.Z`, never `main`). + +### Base-green check (PRs must not be born red) + +Before cutting a branch, merging the base into a PR branch, mass-retargeting PRs, or opening a +PR: check whether the base tip is green. The `Release-Green (continuous)` workflow +(`.github/workflows/nightly-release-green.yml`) publishes the verdict in a single deduplicated +issue titled `🔴 Release branch not green: ` (label `base-red`). One call replaces any +local suite run for this purpose: + +```bash +gh issue list --repo diegosouzapw/OmniRoute --state open \ + --search "Release branch not green: in:title" +``` + +If the base is red: never treat the inherited failures as your branch's defect; never "fix" them +inside your feature branch (a base-red fix is its own freeze-gated `fix/release-vX.Y.Z-basereds` +PR); and if you must open a PR anyway, add `⚠️ base-red inherited: #` to the PR body so +reviewers and CI babysitters do not chase ghosts. + +--- + ## Upstream contributions This checkout is a fork of `diegosouzapw/OmniRoute`. Keep fork-only deployment and personal @@ -103,15 +593,98 @@ git switch -c upstream/ Target that same release branch in the pull request. Stage only the intended files, run the focused checks, and use a Conventional Commit message (for example, `docs: slim AGENTS.md`). -## Reference documentation +--- -Use the source of truth for the area you are changing: +## Environment -| Area | Reference | -| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Repository navigation and architecture | [`docs/architecture/REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md), [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) | -| API and providers | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md), [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md), [`docs/openapi.yaml`](docs/openapi.yaml) | -| Routing, resilience, and reasoning | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md), [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md), [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md) | -| Security | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md), [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md), [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) | -| Platform features | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md), [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md), [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md), [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md) | -| Releases and quality | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md), [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md) | +- **Runtime**: Node.js ≥22.0.0 <23 || ≥24.0.0 <27, ES Modules. This is the **only supported** runtime for the published `omniroute` CLI, the server, and the test suites (`node:test` + vitest) — `engines.node` is authoritative and end users never need Bun. A **best-effort `bun:sqlite` compatibility path** exists so a global Bun install (`bun install -g omniroute`) can start without `better-sqlite3` (driver adapter + Bun-aware process spawning); it is **not** a supported runtime — no support guarantees — and every Bun-specific runtime change MUST preserve the Node driver/fallback chain and ship a Bun test (`test:bun:db`) or an explicit reason why the path is Node-only. +- **Bun (build/dev script runner + compatibility smoke only)**: Bun `1.3.14` is pinned as an **exact devDependency** (provisioned through the existing `npm ci` via the lockfile's `@oven/bun-*` platform binaries — no `setup-bun`/ad-hoc install). It is used **only** to execute a small, allow-listed set of TypeScript **gate/generator scripts** (replacing `node --import tsx` for startup speed): the CI checks `check:provider-consistency`, `check:compression-budget`, `check:known-symbols`, and the non-CI `gen:provider-reference`, `bench:compression` — plus the focused `test:bun:db` compatibility smoke suite for the best-effort `bun:sqlite` path. **Do NOT** widen Bun to `npm install`, the build (`build:cli*`), `check:pack-artifact`, the supported published runtime, or the main test runners — those stay on Node. Any new Bun-invoking gate/generator script must be validated byte-identical against its `node --import tsx` output first. After pulling the lockfile change, run `npm install` so `bun` resolves locally (a stale `node_modules` will fail those scripts with `bun: not found`). +- **TypeScript**: 6.0+, target ES2022, module esnext, resolution bundler +- **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*` +- **Default port**: 20128 (API + dashboard on same port) +- **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/` +- **Key env vars**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL` +- Setup: `cp .env.example .env` then generate `JWT_SECRET` (`openssl rand -base64 48`) and `API_KEY_SECRET` (`openssl rand -hex 32`) + +--- + +## Quality Gates & Ratchets + +OmniRoute has **~48 quality-gate scripts** (`scripts/check/` + `scripts/quality/`) wired +across **9 gate-running jobs** in `.github/workflows/ci.yml` (`lint`, `quality-gate`, +`quality-extended`, `docs-sync-strict`, `i18n-ui-coverage`, `i18n`, `pr-test-policy`, +`test-vitest`, `sonarqube`), plus the `quality.yml` fast-gates job (PR→`release/**`) and +3 nightly workflows (`nightly-property`, `nightly-resilience`, `nightly-llm-security`; +`nightly-mutation` once merged). Full inventory, per-job breakdown, and operational +procedures are in [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md). + +**Quick reference:** + +- Gates in jobs `lint` + `docs-sync-strict`: pass/fail policy gates — + fix the violation or add an allowlist entry with a justification comment + tracking issue. +- Gates in job `quality-gate`: ratchet — metrics (ESLint warnings, code coverage, duplication, + complexity) must not regress vs `quality-baseline.json`. Update via + `npm run quality:ratchet -- --update` when a metric genuinely improves. +- Job `test-vitest` runs `npm run test:vitest` (MCP tools, autoCombo, cache) — blocking. + `test:vitest:ui` is advisory until UI component tests are triaged. + +**Allowlist policy (short form):** Fix the cause; use the allowlist only for pre-existing +violations you cannot fix in the same PR. Add a comment with justification + issue number. +Stale allowlist entries (suppressing a violation that no longer exists) will be caught by +the stale-enforcement added in Fase 6A.3. + +--- + +## Hard Rules + +1. Never commit secrets or credentials +2. Never add logic to `localDb.ts` +3. Never use `eval()` / `new Function()` / implied eval +4. Never commit directly to `main` +5. Never write raw SQL in routes — use `src/lib/db/` modules +6. Never silently swallow errors in SSE streams +7. Always validate inputs with Zod schemas +8. Always include tests when changing production code +9. Coverage must not regress below the baseline frozen in `quality-baseline.json` (ratchet); absolute floor is 60% (statements/lines/functions/branches). Update the baseline via `npm run quality:ratchet -- --update` only when coverage genuinely improves. See `docs/architecture/QUALITY_GATES.md`. +10. Never bypass Husky hooks (`--no-verify`, `--no-gpg-sign`) without explicit operator approval. +11. Never embed public upstream OAuth client_id/secret or Firebase Web keys as string literals — always go through `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). See `docs/security/PUBLIC_CREDS.md`. +12. Never return raw `err.stack` / `err.message` in HTTP / SSE / executor responses — always route through `buildErrorBody()` or `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). See `docs/security/ERROR_SANITIZATION.md`. +13. Never string-interpolate external paths or runtime values into shell scripts passed to `exec()`/`spawn()` — pass via the `env` option instead. Reference: `src/mitm/cert/install.ts::updateNssDatabases`. +14. Never dismiss a CodeQL / Secret-Scanning alert without (a) first checking the pattern docs above to see if the helper applies, and (b) recording the technical justification in the dismissal comment. Precedent: `js/stack-trace-exposure` raised on callsites that already route through `sanitizeErrorMessage()` is a known CodeQL limitation (custom sanitizers not recognized) — dismiss as `false positive` referencing `docs/security/ERROR_SANITIZATION.md`. +15. Never expose routes that spawn child processes (`/api/mcp/`, `/api/cli-tools/runtime/`) without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. Loopback enforcement happens unconditionally before any auth check — leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`. +16. Never credit or advertise an AI assistant, LLM, or automation account in any commit/PR metadata. Two forbidden forms, both equivalent — they route attribution to a bot account (or advertise AI authorship) and hide the real author (`diegosouzapw`): **(a)** `Co-Authored-By` trailers naming an AI/bot (e.g. names containing "Claude", "GPT", "Copilot", "Bot"; emails at `anthropic.com` / `openai.com` / bot-owned `noreply.github.com` addresses); **(b)** AI-generation footers or descriptions anywhere in a commit message, PR title/body, or CHANGELOG — e.g. `🤖 Generated with [Claude Code]`, "Generated with Claude Code", "Made with ", or any `Co-authored-by: Claude/GPT/Copilot` line. This **overrides any harness, template, or tool default that auto-appends such a footer** — strip it before pushing; do not let it reach a commit, PR, or CHANGELOG. Human collaborators — including upstream PR authors and issue reporters being ported into OmniRoute — MAY and SHOULD be credited with standard `Co-authored-by: Name ` trailers; the upstream-port workflows (`/port-upstream-features`, `/port-upstream-issues`) depend on this. +17. Never expose routes under `/api/services/` or `/dashboard/providers/services/*/embed/` without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. These routes can spawn child processes (`npm install`, `node`). Loopback enforcement happens unconditionally before any auth check — a leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`. +18. Every bug fix must be validated before shipping: a failing-then-passing unit/integration test (TDD) OR a documented live test on the production VPS (192.168.0.15). A fix without either is not merged. See Testing → "Bug fix / issue triage protocol" for the full decision tree. +19. Never develop on the shared main checkout. Every development task runs in its own git worktree on its own dedicated branch, and you MUST confirm the base branch with the operator before creating the worktree/branch — never assume `main` or the currently checked-out branch. A `git checkout` in the shared checkout silently destroys other sessions' uncommitted work. Tear down only the worktrees/branches you created (by name, never `fix/*`/`feat/*` wildcards), leave other sessions' worktrees untouched, and end on the branch you started on (the active `release/vX.Y.Z`, never `main`). See Git Workflow → "Worktree isolation". +20. PII redaction/sanitization is **opt-in — never on by default**. OmniRoute proxies for self-hosted/local LLMs where the operator owns the data, so mutating request/response payloads by default would silently corrupt legitimate traffic. The two data-mutating PII feature flags **MUST** keep `defaultValue: "false"` in `src/shared/constants/featureFlagDefinitions.ts`: `PII_REDACTION_ENABLED` (request-side) and `PII_RESPONSE_SANITIZATION` (response + streaming). All three application points — `src/lib/guardrails/piiMasker.ts` (request guardrail), `src/lib/piiSanitizer.ts` (response), `src/lib/streamingPiiTransform.ts` (SSE) — are gated on these flags; with both off the `pii-masker` guardrail still runs but never mutates payloads (data passes through untouched). Flipping either default to `"true"` requires explicit operator approval. The regression guard is `tests/unit/pii-opt-in-default.test.ts` (asserts both definition defaults + behavioral pass-through). Opt-in is per-operator via env or the settings/DB override (`src/lib/db/featureFlags.ts`), never a silent default. See `docs/security/GUARDRAILS.md`. +21. **Release-freeze — the FROZEN release branch belongs to the release captain; development does NOT stop (parallel-cycle model, 2026-07-04).** `/generate-release` opens a marker issue labeled `release-freeze` at the start of reconciliation (Phase 0a), **immediately cuts the next cycle's branch `release/vX+1` from the frozen tip (Phase 0a.0b — bump + living release PR + re-home of open PRs)**, and closes the freeze once the release PR squash-merges to `main`. Before merging **any** PR, every campaign workflow (`/review-prs`, `/review-group-prs`, `/merge-prs`, `/triage-fix-bugs`, `/implement-fix-bugs`, `/triage-features`, `/implement-features`, `/green-prs`, `/port-upstream-*`) **MUST** check `gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open` — if a freeze is active: **NEVER merge into the frozen `release/vX.Y.Z` named in the freeze title**; instead resolve the ACTIVE development branch (the **highest** `release/v*` by semver — normally `release/vX+1`, announced in a freeze-issue comment) and **retarget the PR there** (`gh pr edit --base release/vX+1`, then VERIFY with `gh pr view --json baseRefName` — the edit fails silently) and merge normally. **HOLD only when the highest release/v\* branch IS the frozen one** (the short window before 0a.0b completes, or a pre-parallel-cycle release) — in that case leave the PR ready and open, tell the operator, and resume when the next branch appears or the freeze lifts. The just-shipped fixes reach `release/vX+1` via the Phase 5 sync-back (`scripts/release/sync-next-cycle.mjs`); do not try to sync mid-release. This is a **coordination signal, not a permission lock**: the release captain and the campaign sessions share the `diegosouzapw` identity, so a GitHub branch-protection lock cannot distinguish them — only this honored marker prevents the mid-release commit races that forced full CHANGELOG re-reconciliation in v3.8.40/v3.8.41 (a parallel campaign advanced `release/vX.Y.Z` by 34 commits mid-run). The release captain's own reconciliation/cycle-open pushes are exempt — they _are_ the release. Fixes that must land during a freeze (a homologation finding) follow the post-merge read-only rule: land on `main` first via `fix/release-vX.Y.Z-*`. **⛔ ONLY `/generate-release` may raise a release-freeze, and ONLY at its Phase 0a (start of generating a new version) — lifted at Phase 12c after the squash-merge to `main`.** No campaign, session, or agent may open a `release-freeze` marker at any other time — a freeze is **never** a mid-development coordination tool. If a session ever believes a freeze is genuinely, unavoidably necessary outside the `/generate-release` flow, it **MUST first ask the operator (`diegosouzapw`) in chat, explicitly alert "estou criando um freeze" and get an explicit yes** — never open, extend, or re-open a `release-freeze` autonomously. Conversely, do **not** close/lift an active `/generate-release` freeze to unblock campaign merges: it protects the captain's single clean CI run and auto-lifts at Phase 12c — closing it early re-triggers the exact commit race it prevents. Verify a freeze is legitimate before acting on it: an open `release-freeze` whose title/body references an **OPEN** release PR (`gh pr view --json state`) is the authorized captain freeze — hold, don't touch. (Cycle-model proposal: `_tasks/finished/release-flow/2026-07-04_proposta-ciclo-paralelo-v2.md`.) +22. **Cross-session safety — this repo is worked by MANY parallel sessions/agents at once; never step on another's in-flight work.** Two absolute bans, both recurring incidents (this rule exists because they keep happening): + - **(a) Never `git stash` / `git stash pop` — ANYWHERE in this repo, including inside an isolated worktree, and including inside any subagent you dispatch.** `git stash` operates on the **shared repository object store**, not the per-worktree working tree — so a stash pushed or popped in one session can silently clobber or resurrect another parallel session's uncommitted changes. This is not hypothetical: 2026-07-02 a `#5923` quotaCache change leaked into the unrelated `#2296` worktree via a global `stash pop`, and the same class reincided through a **subagent**. To compare working changes against a base ref **without** stashing, use `git show :` or `git diff -- `; to confirm a typecheck/lint error is pre-existing on the base, inspect the base ref directly (`git show origin/release/vX.Y.Z:`) — never stash your tree away to "get it clean". **Put this ban verbatim in the prompt of every subagent that touches git** (agents don't inherit this file's context — the recurrence was a subagent). + - **(b) Never merge, push, rebase, or force-push a PR / branch / worktree that another session is actively working.** An open PR whose head is a live fix worktree in `.claude/worktrees/` you did **not** create (e.g. `fix-5852`/`fix-5923` carrying fresh commits, even when they share your `diegosouzapw` identity), or any branch another session owns, is **off-limits — HOLD**, and let the owning session merge it. **Before** merging or pushing to any PR you did not create _this_ session, run `git worktree list` to check for a matching in-flight worktree and re-check `gh pr view --json state,headRefOid`. Only the owning session merges its own in-flight PR; mid-flight merges race the owner and re-trigger the exact commit/CHANGELOG races Rule #19 and Rule #21 guard against. (Reinforces Rule #19.) + +--- + +## PII & Stream Sanitization Learnings + +### 1. Regex Security (ReDoS) + +All regex patterns matching variable-length strings (e.g. IPv6 address, credit cards) must use strictly bounded, non-overlapping sequences (e.g., limit occurrences with bounded ranges `{1,7}`) to prevent catastrophic backtracking when processing untrusted inputs. + +### 2. SSE Snapshot Handling + +When parsing streaming LLM responses (e.g. Responses API), check if a chunk represents a final snapshot (`done` or `completed` events). Snapshot text must be sanitized directly as a standalone string (bypassing rolling delta buffers) to prevent text duplication at the end of the stream. + +### 3. Database Handles in Tests + +Ensure that any unit tests that trigger database migrations or establish SQLite connections call `resetDbInstance()` and properly clean up/close all DB handles in a `test.after(...)` hook. Failure to release database connection handles will cause Node's native test runner to hang indefinitely. + +--- + +## Local development access + +The dashboard is reachable at the operator's chosen URL/port (default `http://localhost:20128`). Credentials are operator-specific: + +- **Initial admin password** is read from the `INITIAL_PASSWORD` env var on first install (defaults to `CHANGEME` in `.env.example`; rotate immediately after first login). +- **Local VPS / shared dev environments**: ask the operator for the URL and current credentials — they live in their personal vault, NOT in this repo. + +> Any credential observed in a previous version of this file was a non-production demo value; treat it as compromised and do not reuse it. diff --git a/CLAUDE.md b/CLAUDE.md index 170bbb08d0..102ecd1378 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,406 +1,42 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +@AGENTS.md -## Quick Start +**All project rules live in [`AGENTS.md`](AGENTS.md)** — the single source of truth for every AI +assistant (architecture, conventions, testing, quality gates, git workflow, the 22 Hard Rules, +PII learnings). Read it in full; do not re-add project rules here. Everything below applies ONLY +to Claude Code — operational refinements of rules already defined in `AGENTS.md`. -```bash -npm install # Install deps (auto-generates .env from .env.example) -npm run dev # Dev server at http://localhost:20128 -npm run build # Production build (Next.js 16 standalone) -npm run lint # ESLint (0 errors expected; warnings are pre-existing) -npm run typecheck:core # TypeScript check (should be clean) -npm run typecheck:noimplicit:core # Strict check (no implicit any) -npm run test:coverage # Unit tests + coverage gate (60/60/60/60 — statements/lines/functions/branches) -npm run check # lint + test combined -npm run check:cycles # Detect circular dependencies -``` +## Worktree isolation — Claude Code specifics -### Running Tests +The full mandatory worktree protocol (base-branch confirmation, `.claude/worktrees/` canonical +path, `cp -al` node_modules, teardown rules) is in `AGENTS.md` → Git Workflow → "Worktree +isolation". Claude-Code-specific points: -```bash -# Single test file (Node.js native test runner — most tests) -node --import tsx/esm --test tests/unit/your-file.test.ts +- Confirm the base branch with the operator via `AskUserQuestion` (Hard Rule #19) unless they + already told you. +- Prefer the native `EnterWorktree` tool — it already creates worktrees under + `.claude/worktrees/` (the canonical path). Create the worktree with the documented `git +worktree add` command, then call `EnterWorktree` with its `path`. -# Vitest (MCP server, autoCombo, cache) -npm run test:vitest +## Cross-session safety — Claude Code specifics -# All suites -npm run test:all -``` +Hard Rules #19/#21/#22 (in `AGENTS.md`) govern parallel sessions. Operational reminders for this +harness: -For full test matrix, see `CONTRIBUTING.md` → "Running Tests". For deep architecture, see `AGENTS.md`. +- **Replicate the `git stash` ban verbatim in the prompt of every subagent that touches git** + (Agent tool / Workflow scripts) — subagents do not inherit this file, and the recorded + recurrence of the stash incident came through a subagent. +- Before merging or pushing to any PR you did not create _this session_, run `git worktree list` + and re-check `gh pr view --json state,headRefOid` (Hard Rule #22b). +- End every session with the main checkout on the branch it started on. ---- +## Superpowers / planning artifacts — path overrides -## Project at a Glance - -**OmniRoute** — unified AI proxy/router. One endpoint, 290 LLM providers, auto-fallback. - -| Layer | Location | Purpose | -| ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| API Routes | `src/app/api/v1/` | Next.js App Router — entry points | -| Handlers | `open-sse/handlers/` | Request processing (chat, embeddings, etc) | -| Executors | `open-sse/executors/` | Provider-specific HTTP dispatch | -| Translators | `open-sse/translator/` | Format conversion (OpenAI↔Claude↔Gemini) | -| Transformer | `open-sse/transformer/` | Responses API ↔ Chat Completions | -| Services | `open-sse/services/` | Combo routing, rate limits, caching, etc | -| Database | `src/lib/db/` | SQLite domain modules (130 migrations) | -| Domain/Policy | `src/domain/` | Policy engine, cost rules, fallback logic | -| MCP Server | `open-sse/mcp-server/` | 104 tools (42 base + memory/skill/agentSkill/pool/notion/obsidian/gamification/plugin modules), 3 transports (stdio / SSE / Streamable HTTP), 31 scopes | -| A2A Server | `src/lib/a2a/` | JSON-RPC 2.0 agent protocol | -| Skills | `src/lib/skills/` | Extensible skill framework | -| Memory | `src/lib/memory/` | Persistent conversational memory | - -Monorepo: `src/` (Next.js 16 app), `open-sse/` (streaming engine workspace), `electron/` (desktop app), `tests/`, `bin/` (CLI entry point). - ---- - -## Request Pipeline - -``` -Client → /v1/chat/completions (Next.js route) - → CORS → Zod validation → auth? → policy check → prompt injection guard - → handleChatCore() [open-sse/handlers/chatCore.ts] - → cache check → rate limit → combo routing? - → resolveComboTargets() → handleSingleModel() per target - → translateRequest() → getExecutor() → executor.execute() - → fetch() upstream → retry w/ backoff - → response translation → SSE stream or JSON - → If Responses API: responsesTransformer.ts TransformStream -``` - -API routes follow a consistent pattern: `Route → CORS preflight → Zod body validation → Optional auth (extractApiKey/isValidApiKey) → API key policy enforcement → Handler delegation (open-sse)`. No global Next.js middleware — interception is route-specific. - -**Combo routing** (`open-sse/services/combo.ts`): 19 public strategies (priority, weighted, fill-first, round-robin, p2c, random, least-used, cost-optimized, reset-aware, reset-window, headroom, strict-random, auto, lkgp, context-optimized, cache-optimized, context-relay, fusion, pipeline). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks. The `fusion` strategy is the exception: it fans out to a panel of models in parallel, then a judge model synthesizes one final answer (`open-sse/services/fusion.ts`). See `docs/routing/AUTO-COMBO.md` for the 13-factor Auto-Combo scoring + the full strategy table and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers. - ---- - -## Resilience Runtime State - -OmniRoute has three related but distinct temporary-failure mechanisms. Keep their -scope separate when debugging routing behavior. See the -[3-layer resilience diagram](./docs/diagrams/exported/resilience-3layers.svg) -(source: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd)) -for an at-a-glance map. - -### Provider Circuit Breaker - -**Scope**: whole provider, e.g. `glm`, `openai`, `anthropic`. - -**Purpose**: stop sending traffic to a provider that is repeatedly failing at the -upstream/service level, so one unhealthy provider does not slow down every request. - -**Implementation**: - -- Core class: `src/shared/utils/circuitBreaker.ts` -- Chat gate/execution wiring: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts` -- Runtime status API: `src/app/api/monitoring/health/route.ts` -- Shared wrappers: `open-sse/services/accountFallback.ts` -- Persisted state table: `domain_circuit_breakers` - -**States**: - -- `CLOSED`: normal traffic is allowed. -- `OPEN`: provider is temporarily blocked; callers get a provider-circuit-open response - or combo routing skips to another target. -- `HALF_OPEN`: reset timeout has elapsed; allow a probe request. Success closes the - breaker, failure opens it again. - -**Defaults** (`open-sse/config/constants.ts`): - -- OAuth providers: threshold `3`, reset timeout `60s`. -- API-key providers: threshold `5`, reset timeout `30s`. -- Local providers: threshold `2`, reset timeout `15s`. - -Only provider-level failure statuses should trip the provider breaker: - -```ts -(408, 500, 502, 503, 504); -``` - -Do not trip the whole-provider breaker for normal account/key/model errors like most -`401`, `403`, or `429` cases. Those usually belong to connection cooldown or model -lockout. A generic API-key provider `403` should be recoverable unless it is classified -as a terminal provider/account error. - -The breaker uses lazy recovery, not a background timer. When `OPEN` expires, reads such -as `getStatus()`, `canExecute()`, and `getRetryAfterMs()` refresh the state to -`HALF_OPEN`, so dashboards and combo candidate builders do not keep excluding an -expired provider forever. - -### Connection Cooldown - -**Scope**: one provider connection/account/key. - -**Purpose**: temporarily skip one bad key/account while allowing other connections for -the same provider to continue serving requests. - -**Implementation**: - -- Write/update path: `src/sse/services/auth.ts::markAccountUnavailable()` -- Account selection/filtering: `src/sse/services/auth.ts::getProviderCredentials...` -- Cooldown calculation: `open-sse/services/accountFallback.ts::checkFallbackError()` -- Settings: `src/lib/resilience/settings.ts` - -Important fields on provider connections: - -```ts -rateLimitedUntil; -testStatus: "unavailable"; -lastError; -lastErrorType; -errorCode; -backoffLevel; -``` - -During account selection, a connection is skipped while: - -```ts -new Date(rateLimitedUntil).getTime() > Date.now(); -``` - -Cooldowns are also lazy: when `rateLimitedUntil` is in the past, the connection becomes -eligible again. On successful use, `clearAccountError()` clears `testStatus`, -`rateLimitedUntil`, error fields, and `backoffLevel`. - -Default connection cooldown behavior: - -- OAuth base cooldown: `5s`. -- API-key base cooldown: `3s`. -- API-key `429` should prefer upstream retry hints (`Retry-After`, reset headers, or - parseable reset text) when available. -- Repeated recoverable failures use exponential backoff: - -```ts -baseCooldownMs * 2 ** failureIndex; -``` - -The anti-thundering-herd guard prevents concurrent failures on the same connection from -repeatedly extending the cooldown or double-incrementing `backoffLevel`. - -Terminal states are not cooldowns. `banned`, `expired`, and `credits_exhausted` are -intended to stay unavailable until credentials/settings change or an operator resets -them. Do not overwrite terminal states with transient cooldown state. - -### Model Lockout - -**Scope**: provider + connection + model. - -**Purpose**: avoid disabling a whole connection when only one model is unavailable or -quota-limited for that connection. - -Examples: - -- Per-model quota providers returning `429`. -- Local providers returning `404` for one missing model. -- Provider-specific mode/model permission failures such as selected Grok modes. - -Model lockout lives in `open-sse/services/accountFallback.ts` and lets the same -connection continue serving other models. - -### Debugging Guidance - -- If all keys for a provider are skipped, inspect both provider breaker state and each - connection's `rateLimitedUntil`/`testStatus`. -- If a provider appears permanently excluded after the reset window, check whether code - is reading raw `state` instead of using `getStatus()`/`canExecute()`. -- If one provider key fails but others should work, prefer connection cooldown over - provider breaker. -- If only one model fails, prefer model lockout over connection cooldown. -- If a state should self-recover, it should have a future timestamp/reset timeout and a - read path that refreshes expired state. Permanent statuses require manual credential - or config changes. - ---- - -## Key Conventions - -### Code Style - -- **2 spaces**, semicolons, double quotes, 100 char width, es5 trailing commas (enforced by lint-staged via Prettier) -- **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative -- **Naming**: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE -- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = error everywhere; `no-explicit-any` = **error** in `open-sse/` and `tests/` (since #6218 — pre-existing violations are frozen in `config/quality/eslint-suppressions.json`, new ones must be fixed; `npm run lint` applies the suppressions and is what CI runs) -- **TypeScript**: `strict: false`, target ES2022, module esnext, resolution bundler. Prefer explicit types. - -### Database - -- **Always** go through `src/lib/db/` domain modules — **never** write raw SQL in routes or handlers -- **Never** add logic to `src/lib/localDb.ts` (re-export layer only) -- **Never** barrel-import from `localDb.ts` — import specific `db/` modules instead -- DB singleton: `getDbInstance()` from `src/lib/db/core.ts` (WAL journaling) -- Migrations: `src/lib/db/migrations/` — versioned SQL files, idempotent, run in transactions - -### Error Handling - -- try/catch with specific error types, log with pino context -- Never swallow errors in SSE streams — use abort signals for cleanup -- Return proper HTTP status codes (4xx/5xx) - -### Security - -- **Never** use `eval()`, `new Function()`, or implied eval -- Validate all inputs with Zod schemas -- Encrypt credentials at rest (AES-256-GCM) -- Upstream header denylist: `src/shared/constants/upstreamHeaders.ts` — keep sanitize, Zod schemas, and unit tests aligned when editing -- **Public upstream credentials** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web keys extracted from public CLIs): **MUST** be embedded via `resolvePublicCred()` from `open-sse/utils/publicCreds.ts` — **never** as string literals. See `docs/security/PUBLIC_CREDS.md` for the mandatory pattern. -- **Error responses** (HTTP / SSE / executor / MCP handler): **MUST** route through `buildErrorBody()` or `sanitizeErrorMessage()` from `open-sse/utils/error.ts` — **never** put raw `err.stack` or `err.message` in a response body. See `docs/security/ERROR_SANITIZATION.md`. -- **Shell commands built from variables**: when calling `exec()`/`spawn()` with a script that needs runtime values, pass them via the `env` option (shell-escaped automatically) — **never** string-interpolate untrusted/external paths into the script body. Reference: `src/mitm/cert/install.ts::updateNssDatabases`. -- **Secure-by-default libraries** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): prefer Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink over custom implementations whenever adding new security-sensitive surfaces. - ---- - -## Common Modification Scenarios - -### Adding a New Provider - -1. Register in `src/shared/constants/providers.ts` (Zod-validated at load) -2. Add executor in `open-sse/executors/` if custom logic needed (extend `BaseExecutor`) -3. Add translator in `open-sse/translator/` if non-OpenAI format -4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` if OAuth-based — if the upstream CLI ships a public client_id/secret, embed via `resolvePublicCred()` (see `docs/security/PUBLIC_CREDS.md`), **never** as a literal -5. Register models in `open-sse/config/providerRegistry.ts` -6. Write tests in `tests/unit/` (include the publicCreds shape assertion if you added a new embedded default) - -### Adding a New API Route - -1. Create directory under `src/app/api/v1/your-route/` -2. Create `route.ts` with `GET`/`POST` handlers -3. Follow pattern: CORS → Zod body validation → optional auth → handler delegation -4. Handler goes in `open-sse/handlers/` (import from there, not inline) -5. Error responses use `buildErrorBody()` / `errorResponse()` from `open-sse/utils/error.ts` (auto-sanitized — never put `err.stack` or `err.message` raw in the body). See `docs/security/ERROR_SANITIZATION.md`. -6. Add tests — including at least one assertion that error responses do not leak stack traces (`!body.error.message.includes("at /")`) - -### Adding a New DB Module - -1. Create `src/lib/db/yourModule.ts` — import `getDbInstance` from `./core.ts` -2. Export CRUD functions for your domain table(s) -3. Add migration in `src/lib/db/migrations/` if new tables needed -4. Re-export from `src/lib/localDb.ts` (add to the re-export list only) -5. Write tests - -### Adding a New MCP Tool - -1. Add tool definition in `open-sse/mcp-server/tools/` with Zod input schema + async handler -2. Register in tool set (wired by `createMcpServer()`) -3. Assign to appropriate scope(s) -4. Write tests (tool invocation logged to `mcp_audit` table) - -### Adding a New A2A Skill - -1. Create skill in `src/lib/a2a/skills/` (5 already exist: smart-routing, quota-management, provider-discovery, cost-analysis, health-report) -2. Skill receives task context (messages, metadata) → returns structured result -3. Register in `A2A_SKILL_HANDLERS` in `src/lib/a2a/taskExecution.ts` -4. Expose in `src/app/.well-known/agent.json/route.ts` (Agent Card) -5. Write tests in `tests/unit/` -6. Document in `docs/frameworks/A2A-SERVER.md` skill table - -### Adding a New Cloud Agent - -1. Create agent class in `src/lib/cloudAgent/agents/` extending `CloudAgentBase` (3 already exist: codex-cloud, devin, jules) -2. Implement `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources` -3. Register in `src/lib/cloudAgent/registry.ts` -4. Add OAuth/credentials handling if needed (`src/lib/oauth/providers/`) -5. Tests + document in `docs/frameworks/CLOUD_AGENT.md` - -### Adding a New Embedded Service - -1. Create installer in `src/lib/services/installers/{name}.ts` modeled on `ninerouter.ts` (use `runNpm` from `installers/utils.ts` — no shell interpolation, hard rule #13). -2. Register the service in `src/lib/services/bootstrap.ts` (add to `SERVICES[]` array and extend `buildSpawnArgsFactory()`). -3. Add a DB seed row for the new service in `src/lib/db/migrations/` (`version_manager` table, `status='not_installed'`, `auto_start=0`). -4. Create 7 API endpoints under `src/app/api/services/{name}/` (`_lib.ts`, `install`, `start`, `stop`, `restart`, `update`, `status`, `auto-start`). All delegate errors through `createErrorResponse()`. The shared `logs` endpoint is already wired via `[name]/logs/route.ts`. -5. Verify `/api/services/` is in `LOCAL_ONLY_API_PREFIXES` in `src/server/authz/routeGuard.ts`; add a test asserting `isLocalOnlyPath()` returns `true` for the new prefix if you add one (hard rule #17). -6. Add a UI tab in `src/app/(dashboard)/dashboard/providers/services/tabs/` reusing `ServiceStatusCard`, `ServiceLifecycleButtons`, `ServiceLogsPanel`. -7. Document in `docs/frameworks/EMBEDDED-SERVICES.md` (update §1 service table + §4 API reference) and `docs/openapi.yaml`. -8. Write tests: unit (`tests/unit/services/`), integration (`tests/integration/services/`, gated by `RUN_SERVICES_INT=1`), and update `docs/ops/RELEASE_CHECKLIST.md` smoke section. - -### Adding a New Guardrail / Eval / Skill / Webhook event - -- Guardrail: `src/lib/guardrails/` → docs: `docs/security/GUARDRAILS.md` -- Eval suite: `src/lib/evals/` → docs: `docs/frameworks/EVALS.md` -- Skill (sandbox): `src/lib/skills/` → docs: `docs/frameworks/SKILLS.md` -- Webhook event: `src/lib/webhookDispatcher.ts` → docs: `docs/frameworks/WEBHOOKS.md` - ---- - -## Reference Documentation - -For any non-trivial change, read the matching deep-dive first: - -| Area | Doc | -| --------------------------------------------- | ------------------------------------------------------- | -| Repo navigation | `docs/architecture/REPOSITORY_MAP.md` | -| Architecture | `docs/architecture/ARCHITECTURE.md` | -| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` | -| Auto-Combo (13-factor scoring, 19 strategies) | `docs/routing/AUTO-COMBO.md` | -| Resilience (3 mechanisms) | `docs/architecture/RESILIENCE_GUIDE.md` | -| Reasoning replay | `docs/routing/REASONING_REPLAY.md` | -| Skills framework | `docs/frameworks/SKILLS.md` | -| Memory system (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` | -| Cloud agents | `docs/frameworks/CLOUD_AGENT.md` | -| Guardrails (PII / injection / vision) | `docs/security/GUARDRAILS.md` | -| Public upstream credentials (Gemini/etc.) | `docs/security/PUBLIC_CREDS.md` | -| Error message sanitization | `docs/security/ERROR_SANITIZATION.md` | -| Evals | `docs/frameworks/EVALS.md` | -| Compliance / audit | `docs/security/COMPLIANCE.md` | -| Webhooks | `docs/frameworks/WEBHOOKS.md` | -| Authorization pipeline | `docs/architecture/AUTHZ_GUIDE.md` | -| Stealth (TLS / fingerprint) | `docs/security/STEALTH_GUIDE.md` | -| Agent protocols (A2A / ACP / Cloud) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` | -| MCP server | `docs/frameworks/MCP-SERVER.md` | -| A2A server | `docs/frameworks/A2A-SERVER.md` | -| API reference + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` | -| Provider catalog (auto-generated) | `docs/reference/PROVIDER_REFERENCE.md` | -| Release flow | `docs/ops/RELEASE_CHECKLIST.md` | -| Embedded services | `docs/frameworks/EMBEDDED-SERVICES.md` | -| Quality gates (~48 scripts, allowlist policy) | `docs/architecture/QUALITY_GATES.md` | - ---- - -## Testing - -| What | Command | -| ----------------------- | --------------------------------------------------------------------------- | -| Unit tests | `npm run test:unit` | -| Single file | `node --import tsx/esm --test tests/unit/file.test.ts` | -| Vitest (MCP, autoCombo) | `npm run test:vitest` | -| E2E (Playwright) | `npm run test:e2e` | -| Protocol E2E (MCP+A2A) | `npm run test:protocols:e2e` | -| Ecosystem | `npm run test:ecosystem` | -| Coverage gate | `npm run test:coverage` (60/60/60/60 — statements/lines/functions/branches) | -| Coverage report | `npm run coverage:report` | - -**PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`, you must include or update tests in the same PR. - -**Test layer preference**: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix. - -**Both test runners must pass**: `npm run test:unit` (Node native — most tests) AND `npm run test:vitest` (MCP server, autoCombo, cache) cover **non-overlapping files**. Both are wired in CI (jobs `test-unit` and `test-vitest`) and must be green before merging. A PR where only one suite passes may silently ship broken MCP tools or routing regressions. - -**Bug fix / issue triage protocol (Hard Rule #18)**: Every fix for a reported issue must be validated by one of the following — no exceptions: - -1. **TDD (preferred)** — write a failing test reproducing the bug → fix it → confirm the test passes. The test becomes the permanent regression guard. Touch only the files the test proves need changing; nothing more. -2. **Real-environment test (when TDD is not possible)** — deploy to the production VPS (`root@192.168.0.15`) and run a documented live test. Record the exact command + result in the PR description. Applies to: OAuth upstream flows, Cloudflare/WS upstream behavior, UI-only regressions, hardware-dependent behavior. -3. "It worked locally without a test" does not count. A fix without a test or a VPS validation record is not a fix — it is a guess. - -Why this matters: fixing bug A while opening bug B is worse than not fixing at all. The TDD/VPS gate enforces surgical scope — you touch only what the failing test proves is broken. Examples where this paid off: #3090 (claude-web 403), #3113 (WS HTTP fallback), #3052 (heap-guard auto-calibration). - -**Copilot coverage policy**: When a PR changes production code and coverage is below 60% (statements/lines/functions/branches), do not just report — add or update tests, rerun the coverage gate, then ask for confirmation. Include commands run, changed test files, and final coverage result in the PR report. - ---- - -## Planning & Research Artifacts (superpowers, deep-research) - -`_tasks/` is a **separate, isolated git repository** that is gitignored by the main -repo (`.gitignore` → `_tasks/`). It is the canonical home for working artifacts — -plans, specs/designs, research, hand-offs — so they stay **versioned in their own -repo** instead of polluting the main OmniRoute tree. - -**Hard rule — never write superpowers / planning / research output under `docs/` or -the repo root.** The superpowers skills ship with defaults that point at `docs/…` -(`writing-plans` → `docs/superpowers/plans/`, `brainstorming` → `docs/superpowers/specs/`). -Those defaults are **overridden here**. Whenever you invoke superpowers (or any -plan/spec/research generator) in this project, save to `_tasks/` instead, using the -same filename convention: +The `_tasks/` convention is defined in `AGENTS.md` → "Planning & Research Artifacts". The +superpowers skills ship with defaults that point at `docs/…` — those defaults are **overridden +here**. When a superpowers skill announces a path like "saved to `docs/superpowers/plans/…`", +rewrite it to the `_tasks/…` equivalent before writing: | Artifact (skill) | Default (do NOT use) | Save here instead | | ---------------------------------- | ------------------------- | ------------------------------------------------------------- | @@ -409,164 +45,11 @@ same filename convention: | Research (`deep-research`, ad-hoc) | `docs/research/` | `_tasks/research/…` | | Hand-offs (`/handoff`) | — | `_tasks/hands-off/__v_sess-/` | -When a superpowers skill announces a path like "saved to `docs/superpowers/plans/…`", -rewrite it to the `_tasks/…` equivalent before writing. Commit those artifacts inside -the `_tasks/` repo (`git -C _tasks …`), never in the main repo. +Commit those artifacts inside the `_tasks/` repo (`git -C _tasks …`), never in the main repo. -## Git Workflow +## Base-green before opening PRs -```bash -# Never commit directly to main -git checkout -b feat/your-feature -git commit -m "feat: describe your change" -git push -u origin feat/your-feature -``` - -**Branch prefixes**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/` - -**Commit format** (Conventional Commits): `feat(db): add circuit breaker` — scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills` - -**Husky hooks**: - -- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11` + `check:tracked-artifacts` -- **pre-push**: intentionally light (PATH/npm sanity only). `any-budget` + `tracked-artifacts` - already run on pre-commit; re-running them on every push was pure double-pay. CI still - enforces both. (Was Fase 6A.12 full pre-push gate; folded into pre-commit in #6716.) - -### Worktree isolation (MANDATORY for every development task) - -Multiple sessions/agents work this repo in parallel. The main checkout is **shared**, so a -`git checkout`/branch switch in it silently discards another session's uncommitted work and -yanks the branch out from under whatever else is running (incidents: 2026-06-05, 2026-06-13). - -**Rule: never develop on the shared main checkout. Every task gets its own git worktree on its -own dedicated branch, and you MUST confirm the base branch with the operator before creating it.** - -1. **Ask first — which base branch?** Before creating anything, ask the operator (via - `AskUserQuestion`, unless they already told you) from which branch the new worktree/branch - should be cut. Do NOT assume `main` or "whatever I'm on" — the answer is usually the active - `release/vX.Y.Z`, but it can be another feature/release branch. Get the base explicitly. -2. **Create an isolated worktree + branch off that base** (never reuse the main checkout). - **🔴 MANDATORY PATH: every worktree lives under `.claude/worktrees/` — and nowhere else.** - This is the single canonical location (the same dir the native `EnterWorktree` tool uses). It - is gitignored AND in the `tsconfig.json` / `.dockerignore` excludes, so worktrees never leak - into the build scope. **Never** use `.worktrees/`, repo-root, or any other path — a worktree - outside `.claude/worktrees/` (a) escapes the build-scope excludes and poisons `next build` (the - `tsconfig` `include: **/*` globs ~70× the codebase → OOM; incident 2026-06-25) and (b) scatters - worktrees across two dirs. - - ```bash - BASE_BRANCH="release/vX.Y.Z" # ← the branch the operator confirmed in step 1 - TASK="feat/your-feature" # feat/ fix/ refactor/ docs/ test/ chore/ - git fetch origin "$BASE_BRANCH" - git worktree add ".claude/worktrees/${TASK##*/}" -b "$TASK" "origin/$BASE_BRANCH" - cd ".claude/worktrees/${TASK##*/}" - # Reuse the main checkout's node_modules to skip a per-worktree npm install. - # HARD LINKS (`cp -al`), never a symlink: ~5s for the whole tree and near-zero extra - # disk (the inodes are shared), and unlike a symlink it does not break the dev server. - cp -al "$(git -C rev-parse --show-toplevel)/node_modules" node_modules - ``` - - **Never `ln -s` node_modules.** Turbopack rejects a symlink that resolves outside the - project root, so `npm run dev` dies with a FATAL panic (`Symlink [project]/node_modules - is invalid, it points out of the filesystem root`) while typecheck, lint and the test - runners all keep passing — the error names "filesystem root", not the worktree, so it - reads like a Next/build bug and costs real time to trace (incident 2026-07-31, #9043). - - In Claude Code prefer the native `EnterWorktree` tool (it already creates worktrees under - `.claude/worktrees/`): create the worktree with the command above, then call `EnterWorktree` - with its `path`. - -3. **Work, commit, push, open the PR — all from inside the worktree.** Never `git checkout` a - different branch inside a worktree another session might share. -4. **Tear down only your own** worktree + branch when done, from the main checkout: - `git worktree remove .claude/worktrees/` then `git branch -D `. Never blanket-delete - `fix/*`/`feat/*` — other sessions keep their own; delete only the branches you created, by name. -5. **Never touch another session's worktree, branch, or uncommitted changes.** If `git worktree -list` shows worktrees you didn't create, leave them alone. End every session with the main - checkout back on the branch it started on (the active `release/vX.Y.Z`, never `main`). - ---- - -## Environment - -- **Runtime**: Node.js ≥22.0.0 <23 || ≥24.0.0 <27, ES Modules. This is the **only supported** runtime for the published `omniroute` CLI, the server, and the test suites (`node:test` + vitest) — `engines.node` is authoritative and end users never need Bun. A **best-effort `bun:sqlite` compatibility path** exists so a global Bun install (`bun install -g omniroute`) can start without `better-sqlite3` (driver adapter + Bun-aware process spawning); it is **not** a supported runtime — no support guarantees — and every Bun-specific runtime change MUST preserve the Node driver/fallback chain and ship a Bun test (`test:bun:db`) or an explicit reason why the path is Node-only. -- **Bun (build/dev script runner + compatibility smoke only)**: Bun `1.3.14` is pinned as an **exact devDependency** (provisioned through the existing `npm ci` via the lockfile's `@oven/bun-*` platform binaries — no `setup-bun`/ad-hoc install). It is used **only** to execute a small, allow-listed set of TypeScript **gate/generator scripts** (replacing `node --import tsx` for startup speed): the CI checks `check:provider-consistency`, `check:compression-budget`, `check:known-symbols`, and the non-CI `gen:provider-reference`, `bench:compression` — plus the focused `test:bun:db` compatibility smoke suite for the best-effort `bun:sqlite` path. **Do NOT** widen Bun to `npm install`, the build (`build:cli*`), `check:pack-artifact`, the supported published runtime, or the main test runners — those stay on Node. Any new Bun-invoking gate/generator script must be validated byte-identical against its `node --import tsx` output first. After pulling the lockfile change, run `npm install` so `bun` resolves locally (a stale `node_modules` will fail those scripts with `bun: not found`). -- **TypeScript**: 6.0+, target ES2022, module esnext, resolution bundler -- **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*` -- **Default port**: 20128 (API + dashboard on same port) -- **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/` -- **Key env vars**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL` -- Setup: `cp .env.example .env` then generate `JWT_SECRET` (`openssl rand -base64 48`) and `API_KEY_SECRET` (`openssl rand -hex 32`) - ---- - -## Quality Gates & Ratchets - -OmniRoute has **~48 quality-gate scripts** (`scripts/check/` + `scripts/quality/`) wired -across **9 gate-running jobs** in `.github/workflows/ci.yml` (`lint`, `quality-gate`, -`quality-extended`, `docs-sync-strict`, `i18n-ui-coverage`, `i18n`, `pr-test-policy`, -`test-vitest`, `sonarqube`), plus the `quality.yml` fast-gates job (PR→`release/**`) and -3 nightly workflows (`nightly-property`, `nightly-resilience`, `nightly-llm-security`; -`nightly-mutation` once merged). Full inventory, per-job breakdown, and operational -procedures are in [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md). - -**Quick reference:** - -- Gates in jobs `lint` + `docs-sync-strict`: pass/fail policy gates — - fix the violation or add an allowlist entry with a justification comment + tracking issue. -- Gates in job `quality-gate`: ratchet — metrics (ESLint warnings, code coverage, duplication, - complexity) must not regress vs `quality-baseline.json`. Update via - `npm run quality:ratchet -- --update` when a metric genuinely improves. -- Job `test-vitest` runs `npm run test:vitest` (MCP tools, autoCombo, cache) — blocking. - `test:vitest:ui` is advisory until UI component tests are triaged. - -**Allowlist policy (short form):** Fix the cause; use the allowlist only for pre-existing -violations you cannot fix in the same PR. Add a comment with justification + issue number. -Stale allowlist entries (suppressing a violation that no longer exists) will be caught by -the stale-enforcement added in Fase 6A.3. - ---- - -## Hard Rules - -1. Never commit secrets or credentials -2. Never add logic to `localDb.ts` -3. Never use `eval()` / `new Function()` / implied eval -4. Never commit directly to `main` -5. Never write raw SQL in routes — use `src/lib/db/` modules -6. Never silently swallow errors in SSE streams -7. Always validate inputs with Zod schemas -8. Always include tests when changing production code -9. Coverage must not regress below the baseline frozen in `quality-baseline.json` (ratchet); absolute floor is 60% (statements/lines/functions/branches). Update the baseline via `npm run quality:ratchet -- --update` only when coverage genuinely improves. See `docs/architecture/QUALITY_GATES.md`. -10. Never bypass Husky hooks (`--no-verify`, `--no-gpg-sign`) without explicit operator approval. -11. Never embed public upstream OAuth client_id/secret or Firebase Web keys as string literals — always go through `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). See `docs/security/PUBLIC_CREDS.md`. -12. Never return raw `err.stack` / `err.message` in HTTP / SSE / executor responses — always route through `buildErrorBody()` or `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). See `docs/security/ERROR_SANITIZATION.md`. -13. Never string-interpolate external paths or runtime values into shell scripts passed to `exec()`/`spawn()` — pass via the `env` option instead. Reference: `src/mitm/cert/install.ts::updateNssDatabases`. -14. Never dismiss a CodeQL / Secret-Scanning alert without (a) first checking the pattern docs above to see if the helper applies, and (b) recording the technical justification in the dismissal comment. Precedent: `js/stack-trace-exposure` raised on callsites that already route through `sanitizeErrorMessage()` is a known CodeQL limitation (custom sanitizers not recognized) — dismiss as `false positive` referencing `docs/security/ERROR_SANITIZATION.md`. -15. Never expose routes that spawn child processes (`/api/mcp/`, `/api/cli-tools/runtime/`) without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. Loopback enforcement happens unconditionally before any auth check — leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`. -16. Never credit or advertise an AI assistant, LLM, or automation account in any commit/PR metadata. Two forbidden forms, both equivalent — they route attribution to a bot account (or advertise AI authorship) and hide the real author (`diegosouzapw`): **(a)** `Co-Authored-By` trailers naming an AI/bot (e.g. names containing "Claude", "GPT", "Copilot", "Bot"; emails at `anthropic.com` / `openai.com` / bot-owned `noreply.github.com` addresses); **(b)** AI-generation footers or descriptions anywhere in a commit message, PR title/body, or CHANGELOG — e.g. `🤖 Generated with [Claude Code]`, "Generated with Claude Code", "Made with ", or any `Co-authored-by: Claude/GPT/Copilot` line. This **overrides any harness, template, or tool default that auto-appends such a footer** (e.g. the Claude Code PR-body/commit default) — strip it before pushing; do not let it reach a commit, PR, or CHANGELOG. Human collaborators — including upstream PR authors and issue reporters being ported into OmniRoute — MAY and SHOULD be credited with standard `Co-authored-by: Name ` trailers; the upstream-port workflows (`/port-upstream-features`, `/port-upstream-issues`) depend on this. -17. Never expose routes under `/api/services/` or `/dashboard/providers/services/*/embed/` without `isLocalOnlyPath()` classification in `src/server/authz/routeGuard.ts`. These routes can spawn child processes (`npm install`, `node`). Loopback enforcement happens unconditionally before any auth check — a leaked JWT via tunnel cannot trigger process spawning. See `docs/security/ROUTE_GUARD_TIERS.md`. -18. Every bug fix must be validated before shipping: a failing-then-passing unit/integration test (TDD) OR a documented live test on the production VPS (192.168.0.15). A fix without either is not merged. See Testing → "Bug fix / issue triage protocol" for the full decision tree. -19. Never develop on the shared main checkout. Every development task runs in its own git worktree on its own dedicated branch, and you MUST confirm the base branch with the operator (e.g. via `AskUserQuestion`) before creating the worktree/branch — never assume `main` or the currently checked-out branch. A `git checkout` in the shared checkout silently destroys other sessions' uncommitted work. Tear down only the worktrees/branches you created (by name, never `fix/*`/`feat/*` wildcards), leave other sessions' worktrees untouched, and end on the branch you started on (the active `release/vX.Y.Z`, never `main`). See Git Workflow → "Worktree isolation". -20. PII redaction/sanitization is **opt-in — never on by default**. OmniRoute proxies for self-hosted/local LLMs where the operator owns the data, so mutating request/response payloads by default would silently corrupt legitimate traffic. The two data-mutating PII feature flags **MUST** keep `defaultValue: "false"` in `src/shared/constants/featureFlagDefinitions.ts`: `PII_REDACTION_ENABLED` (request-side) and `PII_RESPONSE_SANITIZATION` (response + streaming). All three application points — `src/lib/guardrails/piiMasker.ts` (request guardrail), `src/lib/piiSanitizer.ts` (response), `src/lib/streamingPiiTransform.ts` (SSE) — are gated on these flags; with both off the `pii-masker` guardrail still runs but never mutates payloads (data passes through untouched). Flipping either default to `"true"` requires explicit operator approval. The regression guard is `tests/unit/pii-opt-in-default.test.ts` (asserts both definition defaults + behavioral pass-through). Opt-in is per-operator via env or the settings/DB override (`src/lib/db/featureFlags.ts`), never a silent default. See `docs/security/GUARDRAILS.md`. -21. **Release-freeze — the FROZEN release branch belongs to the release captain; development does NOT stop (parallel-cycle model, 2026-07-04).** `/generate-release` opens a marker issue labeled `release-freeze` at the start of reconciliation (Phase 0a), **immediately cuts the next cycle's branch `release/vX+1` from the frozen tip (Phase 0a.0b — bump + living release PR + re-home of open PRs)**, and closes the freeze once the release PR squash-merges to `main`. Before merging **any** PR, every campaign workflow (`/review-prs`, `/review-group-prs`, `/merge-prs`, `/triage-fix-bugs`, `/implement-fix-bugs`, `/triage-features`, `/implement-features`, `/green-prs`, `/port-upstream-*`) **MUST** check `gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open` — if a freeze is active: **NEVER merge into the frozen `release/vX.Y.Z` named in the freeze title**; instead resolve the ACTIVE development branch (the **highest** `release/v*` by semver — normally `release/vX+1`, announced in a freeze-issue comment) and **retarget the PR there** (`gh pr edit --base release/vX+1`, then VERIFY with `gh pr view --json baseRefName` — the edit fails silently) and merge normally. **HOLD only when the highest release/v\* branch IS the frozen one** (the short window before 0a.0b completes, or a pre-parallel-cycle release) — in that case leave the PR ready and open, tell the operator, and resume when the next branch appears or the freeze lifts. The just-shipped fixes reach `release/vX+1` via the Phase 5 sync-back (`scripts/release/sync-next-cycle.mjs`); do not try to sync mid-release. This is a **coordination signal, not a permission lock**: the release captain and the campaign sessions share the `diegosouzapw` identity, so a GitHub branch-protection lock cannot distinguish them — only this honored marker prevents the mid-release commit races that forced full CHANGELOG re-reconciliation in v3.8.40/v3.8.41 (a parallel campaign advanced `release/vX.Y.Z` by 34 commits mid-run). The release captain's own reconciliation/cycle-open pushes are exempt — they _are_ the release. Fixes that must land during a freeze (a homologation finding) follow the post-merge read-only rule: land on `main` first via `fix/release-vX.Y.Z-*`. **⛔ ONLY `/generate-release` may raise a release-freeze, and ONLY at its Phase 0a (start of generating a new version) — lifted at Phase 12c after the squash-merge to `main`.** No campaign, session, or agent may open a `release-freeze` marker at any other time — a freeze is **never** a mid-development coordination tool. If a session ever believes a freeze is genuinely, unavoidably necessary outside the `/generate-release` flow, it **MUST first ask the operator (`diegosouzapw`) in chat, explicitly alert "estou criando um freeze" and get an explicit yes** — never open, extend, or re-open a `release-freeze` autonomously. Conversely, do **not** close/lift an active `/generate-release` freeze to unblock campaign merges: it protects the captain's single clean CI run and auto-lifts at Phase 12c — closing it early re-triggers the exact commit race it prevents. Verify a freeze is legitimate before acting on it: an open `release-freeze` whose title/body references an **OPEN** release PR (`gh pr view --json state`) is the authorized captain freeze — hold, don't touch. -22. **Cross-session safety — this repo is worked by MANY parallel sessions/agents at once; never step on another's in-flight work.** Two absolute bans, both recurring incidents (this rule exists because they keep happening): - - **(a) Never `git stash` / `git stash pop` — ANYWHERE in this repo, including inside an isolated worktree, and including inside any subagent you dispatch.** `git stash` operates on the **shared repository object store**, not the per-worktree working tree — so a stash pushed or popped in one session can silently clobber or resurrect another parallel session's uncommitted changes. This is not hypothetical: 2026-07-02 a `#5923` quotaCache change leaked into the unrelated `#2296` worktree via a global `stash pop`, and the same class reincided through a **subagent**. To compare working changes against a base ref **without** stashing, use `git show :` or `git diff -- `; to confirm a typecheck/lint error is pre-existing on the base, inspect the base ref directly (`git show origin/release/vX.Y.Z:`) — never stash your tree away to "get it clean". **Put this ban verbatim in the prompt of every subagent that touches git** (agents don't inherit this file's context — the recurrence was a subagent). - - **(b) Never merge, push, rebase, or force-push a PR / branch / worktree that another session is actively working.** An open PR whose head is a live fix worktree in `.claude/worktrees/` you did **not** create (e.g. `fix-5852`/`fix-5923` carrying fresh commits, even when they share your `diegosouzapw` identity), or any branch another session owns, is **off-limits — HOLD**, and let the owning session merge it. **Before** merging or pushing to any PR you did not create _this_ session, run `git worktree list` to check for a matching in-flight worktree and re-check `gh pr view --json state,headRefOid`. Only the owning session merges its own in-flight PR; mid-flight merges race the owner and re-trigger the exact commit/CHANGELOG races Rule #19 and Rule #21 guard against. (Reinforces Rule #19.) - ---- - -## PII & Stream Sanitization Learnings - -### 1. Regex Security (ReDoS) - -All regex patterns matching variable-length strings (e.g. IPv6 address, credit cards) must use strictly bounded, non-overlapping sequences (e.g., limit occurrences with bounded ranges `{1,7}`) to prevent catastrophic backtracking when processing untrusted inputs. - -### 2. SSE Snapshot Handling - -When parsing streaming LLM responses (e.g. Responses API), check if a chunk represents a final snapshot (`done` or `completed` events). Snapshot text must be sanitized directly as a standalone string (bypassing rolling delta buffers) to prevent text duplication at the end of the stream. - -### 3. Database Handles in Tests - -Ensure that any unit tests that trigger database migrations or establish SQLite connections call `resetDbInstance()` and properly clean up/close all DB handles in a `test.after(...)` hook. Failure to release database connection handles will cause Node's native test runner to hang indefinitely. +Before cutting a branch or opening a PR, run the base-green check (`AGENTS.md` → Git Workflow → +"Base-green check"; project skills reference it as `.agents/skills/_shared/base-green.md`). A PR +opened while the base tip is red must carry `⚠️ base-red inherited: #` in its body. To +drain an accumulated red state (base tip + red PRs), use the `/sweep-reds` skill. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8688d253d6..564aedadfa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,6 +15,12 @@ coverage, and reconciliation steps. - **Node.js** `>=22.22.3 <23`, or `>=24.0.0 <27` (recommended: 24 LTS) - **npm** 10+ + +> **npm v11+ users (Node 24+):** After `npm install`, verify native modules were installed: +> `node -e "require('better-sqlite3')"`. If it fails with `MODULE_NOT_FOUND`, +> run `npm approve-scripts better-sqlite3 && npm install`. See +> [Troubleshooting](docs/guides/TROUBLESHOOTING.md#npm-v11-better-sqlite3-not-installed-cannot-find-module). + - **Git** ### Clone & Install diff --git a/Dockerfile b/Dockerfile index 1924fcef5a..905fb294e0 100644 --- a/Dockerfile +++ b/Dockerfile @@ -77,7 +77,7 @@ RUN test -f package-lock.json \ # a broken/rate-limited fetch fails the BUILD loudly instead of shipping a # broken image. RUN --mount=type=cache,id=npm-cache,target=/root/.npm \ - npm ci --no-audit --no-fund --legacy-peer-deps --ignore-scripts \ + npm ci --include=optional --no-audit --no-fund --legacy-peer-deps --ignore-scripts \ && (cd node_modules/better-sqlite3 \ && node /usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js rebuild) \ && node -e "require('better-sqlite3')(':memory:').close()" \ @@ -119,7 +119,9 @@ ENV NODE_OPTIONS="--max-old-space-size=${OMNIROUTE_BUILD_MEMORY_MB}" COPY . ./ RUN --mount=type=cache,id=next-cache,target=/app/.build/next/cache \ - mkdir -p /app/data && npm run build + mkdir -p /app/data \ + && npm run build \ + && node --input-type=module -e "import { createRequire } from 'node:module'; import { pathToFileURL } from 'node:url'; const standaloneRoot = '/app/.build/next/standalone/node_modules/'; const require = createRequire('/app/.build/next/standalone/package.json'); for (const pkg of ['@atjsh/llmlingua-2', '@huggingface/transformers', '@tensorflow/tfjs', 'js-tiktoken']) { const resolved = require.resolve(pkg); if (!resolved.startsWith(standaloneRoot)) throw new Error(pkg + ' resolved outside standalone: ' + resolved); await import(pathToFileURL(resolved).href); } const onnxRuntime = require.resolve('onnxruntime-node'); if (!onnxRuntime.startsWith(standaloneRoot)) throw new Error('onnxruntime-node resolved outside standalone: ' + onnxRuntime); await import(pathToFileURL(onnxRuntime).href);" # ── Runner base ──────────────────────────────────────────────────────────── FROM base AS runner-base @@ -179,8 +181,8 @@ EXPOSE 20128 USER node # Warns if the mounted data volume has wrong ownership -COPY --chmod=755 scripts/check-permissions.sh /tmp/check-permissions.sh -ENTRYPOINT ["/tmp/check-permissions.sh"] +COPY --chmod=755 scripts/check-permissions.sh /app/check-permissions.sh +ENTRYPOINT ["/app/check-permissions.sh"] HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \ CMD ["node", "healthcheck.mjs"] diff --git a/GEMINI.md b/GEMINI.md index 31cc71e761..7c33fee37b 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,50 +1,13 @@ -# Security and Cleanliness Rules for AI Assistants +# GEMINI.md -> **Scope:** rules for Gemini-based agents. For Claude Code, see `CLAUDE.md`. For other AI assistants, see `AGENTS.md`. +> **Single source of truth:** all project rules for AI assistants live in +> [`AGENTS.md`](AGENTS.md). Read it in full before any change — it contains the 22 Hard Rules, +> quality gates, code conventions, file-placement / repo-root hygiene rules, the repository map +> and the local development access notes that used to live in this file. -## 1. File Placement & Organization +Gemini-specific notes: -- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`). -- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside one of the `scripts/` subfolders (`build/`, `dev/`, `check/`, `docs/`, `i18n/`, `ad-hoc/`). One-shot or experimental code goes under `scripts/ad-hoc/`. NEVER dump loose scripts in the project root (`/`) or the top-level `scripts/` folder. - -**The Project Root MUST ONLY CONTAIN:** - -- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, `tsconfig*.json`, `playwright.config.ts`, `prettier.config.mjs`, `postcss.config.mjs`, `sonar-project.properties`, `fly.toml`, `docker-compose*.yml`, `Dockerfile`) -- Dependency files (`package.json`, `package-lock.json`) -- Documentation files (`README.md`, `CHANGELOG.md`, `LICENSE`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `llm.txt`, `Tuto_Qdrant.md`) -- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`, `.npmignore`, `.npmrc`, `.node-version`, `.nvmrc`, `.env.example`) - -When creating _any_ validation tests or one-off logic scripts, default to using `scripts/ad-hoc/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context. - -## 2. Hard Rules (mirror of `CLAUDE.md`) - -1. **Never commit secrets or credentials.** Use `.env` (auto-generated from `.env.example`) or a vault. Passwords, OAuth secrets, API keys, and Cookie values must never appear in committed files. -2. **Never add logic to `src/lib/localDb.ts`.** It is a re-export barrel only. -3. **Never use `eval()`, `new Function()`, or any implied eval.** ESLint enforces this. -4. **Never commit directly to `main`.** Use `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, or `chore/` branches. -5. **Never write raw SQL in routes** — always go through `src/lib/db/` domain modules. -6. **Never silently swallow errors in SSE streams** — propagate them or abort the stream cleanly. -7. **Never bypass Husky hooks** (`--no-verify`, `--no-gpg-sign`) without explicit operator approval. -8. **Always validate inputs with Zod schemas** from `src/shared/validation/schemas.ts`. -9. **Always include tests when changing production code** (`src/`, `open-sse/`, `electron/`, `bin/`). -10. **Coverage must stay** ≥ 60 % statements / lines / functions / branches — the official CI gate (`npm run test:coverage`). The ratchet baseline in `quality-baseline.json` may freeze a higher floor; never regress it. - -## 3. Codebase navigation - -| Task | Read this first | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Understand the codebase | `docs/architecture/REPOSITORY_MAP.md` | -| Architecture overview | `docs/architecture/ARCHITECTURE.md` | -| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` | -| Add a feature | `CONTRIBUTING.md` + the matching `docs/.md` | -| Per-area deep dives | `docs/frameworks/SKILLS.md`, `docs/frameworks/MEMORY.md`, `docs/frameworks/EVALS.md`, `docs/security/GUARDRAILS.md`, `docs/security/COMPLIANCE.md`, `docs/frameworks/CLOUD_AGENT.md`, `docs/frameworks/MCP-SERVER.md`, `docs/frameworks/A2A-SERVER.md`, `docs/architecture/AUTHZ_GUIDE.md`, `docs/architecture/RESILIENCE_GUIDE.md`, `docs/routing/AUTO-COMBO.md`, `docs/frameworks/WEBHOOKS.md`, `docs/routing/REASONING_REPLAY.md`, `docs/security/STEALTH_GUIDE.md`, `docs/ops/TUNNELS_GUIDE.md`, `docs/guides/ELECTRON_GUIDE.md`, `docs/reference/PROVIDER_REFERENCE.md` | -| Release flow | `docs/ops/RELEASE_CHECKLIST.md` | - -## 4. Local development access - -The dashboard is reachable at the operator's chosen URL/port (default `http://localhost:20128`). Credentials are operator-specific: - -- **Initial admin password** is read from the `INITIAL_PASSWORD` env var on first install (defaults to `CHANGEME` in `.env.example`; rotate immediately after first login). -- **Local VPS / shared dev environments**: ask the operator for the URL and current credentials — they live in their personal vault, NOT in this repo. - -> Any credential observed in a previous version of this file was a non-production demo value; treat it as compromised and do not reuse it. +- Skills activate via the `activate_skill` tool (skill metadata is loaded at session start and + the full content is activated on demand). +- There are no other Gemini-only rules today. Do not re-add project rules here — edit + `AGENTS.md` instead, so every assistant sees the same instructions. diff --git a/README.md b/README.md index 6cde157bb9..96d39c9a84 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ # 🚀 OmniRoute — The Free AI Gateway -OmniRoute — Never stop coding. Every AI tool → 290 providers — 90+ free — through one endpoint. Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini with auto-fallback. RTK + Caveman stacked compression saves 15–95% tokens (~89% avg) — never hit limits. 290 AI providers · 90+ free tiers · ~1.53B free tokens/mo · 19 routing strategies · $0 to start. +OmniRoute — Never stop coding. Every AI tool → 291 providers — 90+ free — through one endpoint. Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini with auto-fallback. RTK + Caveman stacked compression saves 15–95% tokens (~89% avg) — never hit limits. 291 AI providers · 90+ free tiers · ~1.53B free tokens/mo · 19 routing strategies · $0 to start. @@ -81,7 +81,7 @@ ⚙️ Features 🎯 Combos - 🌐 Providers + 🌐 Providers 🔌 CLI & MCP @@ -188,7 +188,7 @@ curl http://localhost:20128/v1/chat/completions \ -The Promise — One endpoint. 290 providers. Never stop building — OmniRoute picks the cheapest one that works. Six pillars: Never hit limits (auto-fallback across 290 providers in milliseconds, zero downtime) · Save up to 95% tokens (RTK + Caveman stacked compression cuts 15–95%, ~89% avg on tool-heavy sessions) · $0 to start (90+ free tiers, 40+ free forever — no card needed) · Every tool works (33 coding agents through one config) · One endpoint (OpenAI ↔ Claude ↔ Gemini ↔ Responses API at /v1) · Production-grade (circuit breakers, TLS stealth, MCP 104 tools, A2A, memory, guardrails, evals — 25,000+ tests). +The Promise — One endpoint. 291 providers. Never stop building — OmniRoute picks the cheapest one that works. Six pillars: Never hit limits (auto-fallback across 291 providers in milliseconds, zero downtime) · Save up to 95% tokens (RTK + Caveman stacked compression cuts 15–95%, ~89% avg on tool-heavy sessions) · $0 to start (90+ free tiers, 40+ free forever — no card needed) · Every tool works (33 coding agents through one config) · One endpoint (OpenAI ↔ Claude ↔ Gemini ↔ Responses API at /v1) · Production-grade (circuit breakers, TLS stealth, MCP 104 tools, A2A, memory, guardrails, evals — 25,000+ tests).

@@ -439,7 +439,7 @@ All **19** strategies — mix & match per combo step: -What sets OmniRoute apart — comparison table vs 9router, OpenRouter, CLIProxyAPI and LiteLLM across 13 capabilities. OmniRoute: 290 providers, 90+ free providers built-in, 19 routing strategies, 12-engine token compression, built-in MCP server with 104 tools, A2A agent protocol, persistent memory, guardrails, cloud agents, TLS fingerprint stealth, Desktop/Termux/PWA, 43 i18n UI locales, 100% MIT self-hosted. OmniRoute is the only one with the full set; competitors show a mix of checks, partials and crosses. Verified from each project's docs. +What sets OmniRoute apart — comparison table vs 9router, OpenRouter, CLIProxyAPI and LiteLLM across 13 capabilities. OmniRoute: 291 providers, 90+ free providers built-in, 19 routing strategies, 12-engine token compression, built-in MCP server with 104 tools, A2A agent protocol, persistent memory, guardrails, cloud agents, TLS fingerprint stealth, Desktop/Termux/PWA, 43 i18n UI locales, 100% MIT self-hosted. OmniRoute is the only one with the full set; competitors show a mix of checks, partials and crosses. Verified from each project's docs. 📊 Full methodology & per-feature detail vs 9router, OpenRouter, CLIProxyAPI & LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) @@ -452,7 +452,6 @@ OmniRoute is MIT-licensed and maintained in the open. If it saves you time or mo - @@ -514,7 +513,7 @@ Pix copia-e-cola: - **🖼️ New endpoints** — `/v1/ocr` (Mistral OCR) and `/v1/audio/translations` (Whisper-style) round out the media surface. → [API Reference](docs/reference/API_REFERENCE.md) - **🎨 Image / video / audio generation** — one API for media: xAI Grok Imagine & Novita AI video, ComfyUI, Freepik, Adobe Firefly, Microsoft Designer, Google Imagen, Segmind, EdgeTTS. → [API Reference](docs/reference/API_REFERENCE.md) - **🌍 Deployment & ops** — reverse-proxy `basePath`, browser-language auto-detect, per-key device tracking, root-less MITM trust, zh-TW localization. → [Environment](docs/reference/ENVIRONMENT.md) -- **🤝 More providers & agents** — Cursor Cloud Agent, Grok Build (xAI) with browser + OAuth login, Ollama first-class card, Claude Opus 5 & Sonnet 5, Kimi official partnership (Code/Web/Moonshot), Zed, Requesty, SenseNova, Yuanbao, Agnes AI… and a refreshed **290-provider catalog**. → [Providers](docs/reference/PROVIDER_REFERENCE.md) +- **🤝 More providers & agents** — Cursor Cloud Agent, Grok Build (xAI) with browser + OAuth login, Ollama first-class card, Claude Opus 5 & Sonnet 5, Kimi official partnership (Code/Web/Moonshot), Zed, Requesty, SenseNova, Yuanbao, Agnes AI… and a refreshed **291-provider catalog**. → [Providers](docs/reference/PROVIDER_REFERENCE.md) - **📡 Routing transparency** — every response carries an `X-OmniRoute-Decision` header naming the strategy/provider/latency that served it, a new `cache-optimized` combo strategy + Auto-Combo `cacheAffinity` factor route repeat requests back to the connection holding the cached prefix, and a read-only `/v1/auto-combo/{channel}/candidates` endpoint exposes an `auto/*` channel's live candidate pool. → [Auto-Combo](docs/routing/AUTO-COMBO.md) - **⚡ Local performance & infra** — one-click local Redis, Cloudflare Workers / Deno Deploy relay deployers, Bifrost & Mux as supervised embedded services. → [Embedded Services](docs/frameworks/EMBEDDED-SERVICES.md) @@ -533,7 +532,7 @@ Pix copia-e-cola: - + @@ -575,11 +574,11 @@ Pix copia-e-cola:
-## 🌐 290 AI Providers — 90+ Free +## 🌐 291 AI Providers — 90+ Free
-> The most complete catalog of any open-source router: **290 providers**, **90+ with a free tier**, **40+ free forever**. +> The most complete catalog of any open-source router: **291 providers**, **90+ with a free tier**, **40+ free forever**.
@@ -891,6 +890,12 @@ docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \ -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest ``` +> **Pre-release Docker channel:** `diegosouzapw/omniroute:next` and +> `diegosouzapw/omniroute:next-web` follow the current default `release/v*` +> branch. These mutable tags are intended only for testing unreleased fixes and +> are **not supported for production**. See +> [Docker Release Channels](docs/guides/DOCKER_RELEASE_CHANNELS.md). + **🛠️ From source** ```bash diff --git a/_references/_sistemas_cli/01-relatorio-pesquisa-clis-omniroute.md b/_references/_sistemas_cli/01-relatorio-pesquisa-clis-omniroute.md new file mode 100644 index 0000000000..450ff31530 --- /dev/null +++ b/_references/_sistemas_cli/01-relatorio-pesquisa-clis-omniroute.md @@ -0,0 +1,296 @@ +# Relatorio de pesquisa: repositorios de CLI integraveis com OmniRoute + +> **Status final (2026-08-03):** este documento preserva o inventário inicial. A pesquisa foi concluída para `104/104` casos. Para resultados por projeto, use `04-tracker-integracoes-clis.md`; para o fechamento executivo e a estratégia de publicação, use `06-relatorio-final-104-clis-e-estrategia-prs.md`. + +**Data da pesquisa:** 2026-08-01 +**Escopo:** agentes de codigo de terminal, CLIs de LLM, runtimes de agentes e harnesses que possam consumir um endpoint HTTP compativel com OpenAI, Anthropic ou Gemini, ou que possam ser adaptados por provider/plugin/ACP/MITM. +**Fonte local principal:** `_tasks/hands-off/2026-08-01_release-v3.8.50_v3.8.50_sess-e1846bc2/handoff.md` +**Fontes externas principais:** GitHub Search/API, READMEs dos repositorios e a lista publica `bradAGI/awesome-cli-coding-agents` (atualizada em 2026-07-29). + +## 1. Resumo executivo + +O OmniRoute ja possui uma integracao funcional com o jcode e um catalogo local de ferramentas CLI. O proximo ganho de maior valor e transformar o OmniRoute em um endpoint reconhecido pelos principais agentes de terminal, priorizando configuracao nativa e PR upstream quando o projeto aceitar contribuicoes. + +A pesquisa encontrou: + +- **33 entradas de ferramentas no registro local `CLI_TOOLS`**, contando o registro extraido de Grok Build em `src/shared/constants/cliToolsGrokBuild.ts`, incluindo Claude Code, Codex CLI, Cline, Kilo, Continue, OpenCode, Aider, jcode, Smelt, Pi, Crush, Goose, Open Interpreter, OpenClaw, Hermes Agent, Letta CLI e outros. +- **Mais de 90 projetos publicos** no inventario externo consultado, entre agentes de codigo, CLIs generalistas, forks, runtimes e orquestradores. +- **Candidatos com evidencia forte de endpoint customizavel:** Gemini CLI, Claw Code, Plandex, MiMo Code, Trae Agent, Kimi CLI, Every Code, Open Codex, VT Code, OpenHands CLI, gptme, Nanocoder, RA.Aid, CoreCoder, Grok CLI, Gitlawb Zero, DeepSeek Reasonix, KlaatCode, CodeMini, DvalinCode, Coro Code, Mini-Kode, Late CLI, Agentty, Aizen, Minacode, YottaCode, aichat, ShellGPT, Mistral Vibe, OpenSquilla, Kode CLI e outros. +- **Candidatos que exigem pesquisa confirmatoria:** projetos com README generico, configuracao recente, repositorio ambiguo, binario fechado ou sem evidencia textual suficiente de `base_url`/provider. +- **Candidatos que podem ser integrados por outros caminhos:** ACP, MCP, wrapper/launcher, provider adapter, proxy MITM ou apenas documentacao; eles nao devem ser classificados automaticamente como OpenAI-compatible. + +Conclusao: devemos pesquisar e tentar todos os candidatos tecnicamente viaveis, mas separar claramente `suporte no catalogo OmniRoute`, `configuracao generica`, `adaptacao upstream publicada` e `PR/issue aceita`. O tracker acompanha essas dimensoes separadamente. + +## 2. Metodo e limites + +### 2.1 Como a busca foi feita + +1. Leitura integral do handoff do caso jcode para capturar o padrao de integracao, validacao, publicacao e as restricoes de worktree. +2. Inspecao do catalogo local em `src/shared/constants/cliTools.ts`, da documentacao de CLI e do fluxo de setup em `docs/guides/CLI-INTEGRATIONS.md`. +3. Consulta do GitHub Search/API para resolver o repositorio canonico de cada nome, evitando homonimos. +4. Leitura de README/raw quando disponivel, procurando sinais como `base_url`, `baseURL`, `OPENAI_BASE_URL`, `OPENAI_API_BASE`, `LLM_BASE_URL`, `provider`, `gateway`, `model provider`, `Anthropic` e `Gemini`. +5. Consulta da lista `https://github.com/bradAGI/awesome-cli-coding-agents`, que serve como descoberta ampla, nao como prova de compatibilidade. +6. Classificacao por adocao, manutencao, licenca, evidencia de endpoint, maturidade, potencial de PR e utilidade para o ecossistema OmniRoute. + +### 2.2 O que ainda nao foi afirmado + +- Nao foi feita implementacao ou abertura de PR/issue para os candidatos abaixo; o unico caso publicado nesta sessao anterior e o jcode. +- A presenca da palavra `provider` no README nao prova que uma URL arbitraria funciona em runtime. +- Estrelas e datas sao snapshots aproximados obtidos em 2026-08-01 e podem mudar. +- Repositorios fechados ou com EULA entram no inventario para avaliacao de configuracao, mas nao implicam possibilidade de fork ou PR. +- Cada task de integracao precisa repetir a pesquisa no upstream antes de editar codigo. + +## 3. Baseline do OmniRoute + +### 3.1 Superficie que o OmniRoute oferece + +- Endpoint OpenAI em `/v1`. +- Superficie Anthropic na raiz, usada por clientes que esperam `/v1/messages` a partir do `ANTHROPIC_BASE_URL`. +- Superficie Gemini em `/v1beta`. +- Catalogo de modelos consultavel pelos comandos de setup quando o cliente suporta descoberta. +- Chave via `OMNIROUTE_API_KEY` ou chave selecionada no dashboard. +- Traducao entre formatos, streaming SSE, tool calling, fallback, combos, custos e politicas de autenticacao. +- Modos de consumo: configuracao de ambiente, arquivo nativo do cliente, provider customizado, ACP/MCP e MITM. + +### 3.2 Catalogo local ja registrado + +Fonte: `src/shared/constants/cliTools.ts` e `src/shared/constants/cliToolsGrokBuild.ts`. + +**Codigo/CLI:** Claude Code, OpenAI Codex CLI, Factory Droid, OpenClaw, Cursor, Cline, Kilo Code, Continue, Antigravity, GitHub Copilot CLI, OpenCode, Kiro, Qwen Code, Aider, ForgeCode, Cursor Agent CLI, Roo Code, jcode, DeepSeek TUI, CodeWhale, Smelt, Pi, Crush. + +**Agentes:** Hermes, Hermes Agent, Goose, Open Interpreter, Oh My Pi, Letta CLI, Warp AI, Agent Deck. + +Os documentos do catalogo tambem mantem um backlog MITM para ferramentas sem base URL, como Windsurf, Amp, Amazon Q/Kiro CLI e Cowork. Esses casos devem permanecer separados de uma integracao direta. + +### 3.3 Caso jcode (referencia validada) + +- Upstream: `https://github.com/1jehuang/jcode` +- Mecanismo: perfil OpenAI-compatible dirigido por metadados; nao foi criado um plugin de runtime. +- Branch: `feat/omniroute-provider` +- Commit: `ee4f904e6` +- PR no fork: `https://github.com/diegosouzapw/jcode/pull/1` +- Issue no upstream: `https://github.com/1jehuang/jcode/issues/704` +- Diff: 6 arquivos, `+56/-3`. +- Validacao: `cargo check --workspace` limpo; 205 testes passaram e uma falha foi preexistente/ambiental. +- Estado: aguardando mantenedor; o upstream nao aceita PR de forks externos, por isso a issue e o artefato oficial. +- Pendencia prometida: adicionar no README do OmniRoute a secao "Tools & repositories that work with OmniRoute". + +Licao: o trabalho deve comecar descobrindo o mecanismo real de providers do upstream. Nem todos os clientes precisam de mudanca no OmniRoute; alguns precisam somente de um perfil local, e outros exigirao um adaptador especifico. + +## 4. Candidatos prioritarios com evidencia concreta + +As evidencias abaixo sao sinais de README/configuracao observados na pesquisa inicial. A task individual deve abrir o arquivo exato, confirmar a versao atual e executar um smoke test. + +| Projeto | Repositorio | Evidencia inicial | Rota provavel | +|---|---|---|---| +| Gemini CLI | `google-gemini/gemini-cli` | `GOOGLE_GEMINI_BASE_URL` | configuracao direta; possivel PR/documentacao | +| Claw Code | `ultraworkers/claw-code` | `OPENAI_BASE_URL`, provider compativel | configuracao direta ou provider | +| Plandex | `plandex-ai/plandex` | providers customizados com `baseUrl` | provider/preset | +| MiMo Code | `XiaomiMiMo/MiMo-Code` | `@ai-sdk/openai-compatible` e `baseURL` | provider customizado | +| Trae Agent | `bytedance/trae-agent` | `model_providers` e `base_url` | provider/config | +| Kimi CLI | `MoonshotAI/kimi-cli` | modos `openai_legacy`, `openai_responses`, `anthropic` e `base_url` | provider nativo/config | +| Every Code | `just-every/code` | fork Codex com providers OpenAI/Claude/Gemini | perfil/provider | +| Open Codex | `ymichael/open-codex` | multi-provider e OpenAI-compatible | fork/provider | +| VT Code | `vinhnx/vtcode` | `custom_providers[].base_url`, failover | provider customizado | +| OpenHands CLI | `OpenHands/OpenHands-CLI` | `LLM_BASE_URL` | configuracao direta | +| gptme | `gptme/gptme` | `OPENAI_BASE_URL` e providers | configuracao direta | +| Nanocoder | `Nano-Collective/nanocoder` | qualquer API OpenAI-compatible | configuracao direta | +| RA.Aid | `ai-christianson/RA.Aid` | `OPENAI_API_BASE` | configuracao direta | +| CoreCoder | `he-yufeng/CoreCoder` | `OPENAI_BASE_URL` | configuracao direta | +| Grok CLI | `superagent-ai/grok-cli` | `GROK_BASE_URL`/`baseURL` | configuracao direta | +| Gitlawb Zero | `Gitlawb/zero` | provider `custom-openai-compatible`, `--base-url` | provider/flag | +| DeepSeek Reasonix | `esengine/DeepSeek-Reasonix` | provider compativel e endpoint | confirmar configuracao | +| KlaatCode | `KlaatAI/klaatcode` | `customModels` OpenAI-compatible | configuracao JSON | +| CodeMini CLI | `havingautism/Codemini-CLI` | `gateway.base_url` | gateway/config | +| Zot | `patriceckhart/zot` | `--base-url` e provider custom em `models.json` | flag/config | +| Pool | `poolsideai/pool` | `POOLSIDE_STANDALONE_BASE_URL`; licenca proprietaria | configuracao, sem PR assumido | +| Octomind | `Muvon/octomind` | `_API_URL`/`LOCAL_API_URL` | provider/env | +| Coro Code | `Blushyes/coro-code` | `OPENAI_BASE_URL` | configuracao direta | +| Mini-Kode | `minmaxflow/mini-kode` | `MINIKODE_BASE_URL` | configuracao direta | +| Late CLI | `mlhher/late-cli` | `OPENAI_BASE_URL`/`api-url` | env/flag | +| Agentty | `1ay1/agentty` | modelo agnostico e endpoints compativeis | confirmar arquivo de config | +| Aizen | `aizen-stack/aizen` | CLI Rust OpenAI-compatible; `AIZEN_BASE_URL` | configuracao direta | +| Clif-Code | `DLhugly/Clif-Code` | OpenRouter/OpenAI/Anthropic/Ollama | provider/config | +| Minacode | `hit9/minacode` | provider e compatibilidade no README | confirmar URL | +| YottaCode | `yottadynamics/yottacode` | modelo escolhido, gateway/provider | confirmar config | +| aichat | `sigoden/aichat` | providers OpenAI/Claude/Gemini e compatibilidade | `models.yaml`/provider | +| ShellGPT | `TheR1D/shell_gpt` | `API_BASE_URL` | env/config | +| Mistral Vibe | `mistralai/mistral-vibe` | `base_url`, API base e provider | config/env | +| OpenSquilla | `opensquilla/opensquilla` | 20+ providers e gateway | provider/config | +| Kode CLI | `shareAI-lab/Kode-cli` | provider, endpoint e Anthropic/OpenAI/Gemini | config | +| Crush | `charmbracelet/crush` | `base_url`, provider compativel | ja catalogado no OmniRoute; validar upstream | +| Hermes Agent | `NousResearch/hermes-agent` | endpoint/gateway e 300+ modelos | ja catalogado; validar modo de endpoint | +| OpenClaw | `openclaw/openclaw` | providers, gateway e endpoints | ja catalogado; validar configuracao atual | + +## 5. Inventario amplo localizado + +### 5.1 Agentes de terminal e coding CLIs + +Os projetos desta tabela foram encontrados na lista curada ou no GitHub Search. `Pesquisa` indica o proximo gate; nao significa que a integracao ja esta pronta. + +| Projeto | Repositorio | Licenca/sinal publico | Situacao inicial | +|---|---|---|---| +| OpenCode | `anomalyco/opencode` | multi-provider, 75+ providers | ja suportado; acompanhar provider/plugin | +| Codex CLI | `openai/codex` | Apache-2.0, provider configuravel | ja suportado | +| OpenHands principal | `All-Hands-AI/OpenHands` | OSS, CLI e web | pesquisar CLI e `LLM_BASE_URL` | +| Pi | `badlogic/pi-mono` | harness multi-provider | ja suportado; confirmar repo atual | +| Open Interpreter | `OpenInterpreter/open-interpreter` | Apache-2.0, `--api_base` | ja suportado | +| Cline | `cline/cline` | Apache-2.0, base URL/gateway | ja suportado | +| Goose | `aaif-goose/goose` | Apache-2.0, providers | ja suportado | +| Aider | `Aider-AI/aider` | Apache-2.0, Anthropic/OpenAI | ja suportado | +| Continue | `continuedev/continue` | Apache-2.0, multi-model | ja suportado | +| Deep Agents Code | `langchain-ai/deepagents` | MIT, tool-calling LLM | pesquisar pacote `deepagents-code` | +| Crush | `charmbracelet/crush` | provider/base URL | ja suportado | +| Kilo Code | `Kilo-Org/kilocode` | MIT, providers | ja suportado | +| Qwen Code | `QwenLM/qwen-code` | Apache-2.0, providers | ja suportado | +| Roo Code | `RooCodeInc/Roo-Code` | Apache-2.0 | ja catalogado; validar CLI | +| Grok Build | `xai-org/grok-build` | Apache-2.0, provider | ja suportado | +| Oh My Pi | `can1357/oh-my-pi` | provider custom em YAML | ja suportado | +| SWE-agent | `SWE-agent/SWE-agent` | MIT | pesquisar backend e base URL | +| Smol Developer | `smol-ai/developer` | embeddable agent | adapter/SDK, nao necessariamente CLI | +| Claude Engineer | `Doriandarko/claude-engineer` | CLI Claude | pesquisar provider | +| Claurst | `Kuberwastaken/claurst` | GPL-3.0, provider | confirmar endpoint e politica de fork | +| Free Code | `paoloanzn/free-code` | fork de Claude Code | pesquisar licenca e endpoint | +| Codebuff | `CodebuffAI/codebuff` | multi-agent CLI | pesquisar provider | +| ForgeCode | `antinomyhq/forge` | 300+ modelos | ja suportado | +| OpenSquilla | `opensquilla/opensquilla` | Apache-2.0, gateway | candidato forte | +| Kode CLI | `shareAI-lab/Kode-cli` | Apache-2.0, endpoint | candidato forte | +| Devon | `entropy-research/Devon` | pair programmer TUI | pesquisar backend | +| AutoCodeRover | `AutoCodeRoverSG/auto-code-rover` | agente de issues | pesquisar configuracao de modelos | +| Letta Code | `letta-ai/letta-code` | Apache-2.0, model-agnostic | pesquisar API base | +| CodeMachine CLI | `moazbuilds/CodeMachine-CLI` | multi-agent local | pesquisar provider | +| Codel | `semanser/codel` | AGPL-3.0, Docker/web UI | confirmar servidor OpenAI e restricoes AGPL | +| Agentless | `OpenAutoCoder/Agentless` | workflow sem loop persistente | pesquisar entrada de modelo | +| Amazon Q Developer CLI | `aws/amazon-q-developer-cli` | Apache-2.0 | provavelmente auth/ecossistema AWS; pesquisar | +| Neovate Code | `neovateai/neovate-code` | MIT, plugin/multi-provider | candidato forte | +| Groq Code CLI | `build-with-groq/groq-code-cli` | multi-model | pesquisar endpoint | +| Dexto | `truffle-ai/dexto` | CLI/web/API, subagentes | pesquisar provider | +| claw-code-agent | `HarnessLab/claw-code-agent` | Python, sem dependencias | confirmar endpoint | +| g3 | `dhanji/g3` | Rust, provider abstraction | confirmar licenca e URL | +| Coro Code | `Blushyes/coro-code` | base URL/OpenAI | candidato | +| Mini-Kode | `minmaxflow/mini-kode` | MIT, referencia educacional | candidato | +| zot | `patriceckhart/zot` | MIT, TUI/JSON/RPC | candidato | +| agentty | `1ay1/agentty` | MIT, ACP e multi-provider | candidato | +| nori-cli | `tilework-tech/nori-cli` | multi-provider sobre Codex | pesquisar base URL | +| cursor-agent clone | `civai-technologies/cursor-agent` | OpenAI/Claude/Ollama | pesquisar maturidade e licenca | +| DvalinCode | `arthurpanhku/dvalincode` | MIT, OpenAI-compatible | candidato | +| OpenHarness | `zhijiewong/openharness` | Apache-2.0, any LLM | candidato | +| Octomind | `Muvon/octomind` | Apache-2.0, 13+ providers | candidato | +| Codex Infinity | `lee101/codex-infinity` | fork Codex | pesquisar endpoint | +| San | `genai-io/san` | Apache-2.0, provider-neutral | pesquisar endpoint | +| Waveloom | `Menfre01/waveloom` | Apache-2.0, DeepSeek-focused | pesquisar provider | +| picocode | `jondot/picocode` | Rust, multi-LLM | pesquisar provider | +| QQCode | `qnguyen3/qqcode` | Rust, skills | pesquisar provider | +| Keen Code | `mochow13/keen-code` | MIT, 9+ providers | pesquisar provider | +| Smelt | `leonardcser/smelt` | MIT, OpenAI-compatible | ja suportado | +| Grinta | `josephsenior/Grinta-Coding-Agent` | MIT, Python | pesquisar provider | +| Zap | `zap-coding-agent/zap-coding-agent` | MIT, MCP, local/OpenAI | pesquisar endpoint | +| Binharic | `CogitatorTech/binharic-cli` | multi-provider | pesquisar endpoint | +| Darce | `AmerSarhan/darce-cli` | MIT, multi-model | pesquisar endpoint | +| CLAII | `agencyswarm/CLAII` | multi-agent/MCP | pesquisar endpoint | + +### 5.2 Agentes generalistas e ecossistema OpenClaw + +Estes podem consumir OmniRoute como backend, mas a task deve confirmar se a interface de configuracao e realmente uma CLI de codigo ou apenas um gateway de agente. + +| Projeto | Repositorio | Possivel caminho | +|---|---|---| +| OpenClaw | `openclaw/openclaw` | provider/gateway; ja catalogado | +| nanobot | `HKUDS/nanobot` | provider OpenAI-compatible | +| ZeroClaw | `zeroclaw-labs/zeroclaw` | trait de provider | +| NanoClaw | `gavrielc/nanoclaw` | Anthropic SDK; pesquisar base | +| PicoClaw | `sipeed/picoclaw` | provider/config | +| IronClaw | `nearai/ironclaw` | provider Rust | +| NullClaw | `nullclaw/nullclaw` | 23+ providers | +| Clawith | `dataelement/Clawith` | gateway/teams | +| claw0 | `shareAI-lab/claw0` | tutorial/runtime; pesquisa de viabilidade | +| Moltis | `moltis-org/moltis` | provider Rust | +| GitClaw | `open-gitagent/gitclaw` | agente Git-native; pesquisar | +| LionClaw | `moshthepitt/lionclaw` | CLI local; pesquisar | +| Aizen | `aizen-stack/aizen` | OpenAI-compatible | +| aichat | `sigoden/aichat` | provider/model YAML | +| ShellGPT | `TheR1D/shell_gpt` | `API_BASE_URL` | +| gptme | `gptme/gptme` | `OPENAI_BASE_URL` | + +### 5.3 Orquestradores, wrappers e ferramentas adjacentes + +Nao sao todos alvos de um provider OmniRoute. Devem ser avaliados para launcher, ACP, MCP, observabilidade ou configuracao de seus agentes filhos. + +| Projeto | Repositorio | Tipo de integracao a investigar | +|---|---|---| +| Agent Deck | `asheshgoplani/agent-deck` | config dos CLIs filhos; ja catalogado | +| VibePod | `VibePod/vibepod-cli` | wrapper Docker e metricas | +| zeroshot | `the-open-engine/zeroshot` | launcher/worktrees | +| Fractal | `plasma-ai/fractal` | orquestrador de CLIs | +| Bernstein | `chernistry/bernstein` | orquestrador/verificador | +| Traycer | `traycerai/traycer` | CLI custom e agentes filhos | +| h5i | `h5i-dev/h5i` | execucao paralela | +| OMK | `dmae97/open-multi-agent-kit` | control plane/provider-neutral | +| kodo | `ikamensh/kodo` | orquestrador | +| ORCH | `oxgeneral/ORCH` | fila de tarefas | +| LoopTroop | `LoopTroop-ai/LoopTroop` | orchestration sobre OpenCode | +| Galley | `shinpr/galley` | worktree/PR handoff | +| Relay | `jcast90/relay` | MCP/orquestracao | +| sage | `youwangd/SageCLI` | runtime-agnostic | +| 5dive | `5dive-ai/5dive` | agentes em servidor | +| agx | `ramarlina/agx` | checkpoints e agentes | +| claude-code-router | `musistudio/claude-code-router` | proxy/roteamento; possivel upstream consumidor | +| cc-router | `finch-xu/cc-router` | proxy Anthropic multi-provider | +| OneCLI | `onecli/onecli` | broker de credenciais, nao agente | +| agent-browser | `vercel-labs/agent-browser` | ferramenta MCP/plugin | +| OpenWork | `different-ai/openwork` | desktop sobre OpenCode | +| Mistral Vibe | `mistralai/mistral-vibe` | provider/base URL | +| Junie CLI | `junie.jetbrains.com` | fechado; configuracao BYOK a confirmar | +| Pool | `poolsideai/pool` | binario/EULA; sem PR presumido | + +## 6. Evidencias tecnicas e mapeamento para OmniRoute + +### 6.1 Padroes de endpoint encontrados + +| Padrao observado | Exemplos | Acao OmniRoute | +|---|---|---| +| `OPENAI_BASE_URL`/`OPENAI_API_BASE` | Claw Code, RA.Aid, CoreCoder, Coro Code | fornecer root ou `/v1` conforme o cliente; testar append de path | +| `base_url`/`baseURL` em provider | Plandex, MiMo Code, Trae Agent, VT Code, KlaatCode | gerar bloco de provider e modelo | +| `LLM_BASE_URL` | OpenHands CLI | configurar surface OpenAI e validar streaming/tool calling | +| `GOOGLE_GEMINI_BASE_URL` | Gemini CLI | usar superficie `/v1beta`/Gemini; confirmar formato esperado | +| `GROK_BASE_URL` | Grok CLI | decidir se o cliente fala xAI ou OpenAI; testar traducoes | +| `--base-url` | Gitlawb Zero, Zot, jcode | launcher ou perfil persistido | +| `API_BASE_URL` | ShellGPT | config/env direta | +| `_API_URL`/gateway | Octomind, Pool, OpenSquilla | provider selecionavel; testar cada preset | +| ACP/MCP sem URL direta | Agentty, Kimi CLI, Goose, OpenCode | avaliar se OmniRoute deve ser provider ou backend ACP | +| endpoint nao customizavel | Cursor desktop, Antigravity, Kiro, Windsurf, Amp | somente MITM/guide; nao prometer integracao direta | + +### 6.2 Superficies e riscos de protocolo + +- **`/v1` duplicado:** alguns clientes recebem a raiz e acrescentam `/v1/chat/completions`; outros exigem a URL final com `/v1`. Cada task deve registrar o resultado real. +- **Chat Completions vs Responses:** forks do Codex e clientes modernos podem usar Responses; testar ambas quando o cliente permitir. +- **Anthropic:** clientes que mandam `/v1/messages` esperam `ANTHROPIC_BASE_URL` sem `/v1` no valor. A traducao Anthropic do OmniRoute deve ser validada com streaming e tool use. +- **Gemini:** Gemini CLI pode esperar uma base Gemini nativa, nao somente OpenAI-compatible; validar `generateContent`, streaming e headers. +- **Tool calling:** o agente pode exigir nomes/ids de ferramenta estaveis, JSON estrito, `tool_choice` ou blocos de pensamento especificos. +- **Descoberta de modelos:** `/v1/models` pode ser obrigatorio, opcional ou inexistente. O setup precisa aceitar `--model` fixo quando a descoberta nao for suportada. +- **Autenticacao:** alguns projetos leem somente env, outros gravam tokens em arquivo/keyring e alguns usam OAuth proprietario. Nunca reutilizar credenciais de um upstream sem verificar escopo. +- **Streaming e retry:** SSE, timeouts, abort signals e re-tentativas podem divergir do cliente. Validar uma chamada longa e uma falha de provider. +- **Licenca:** GPL/AGPL, EULA e repositorios sem SPDX exigem decisao de distribuicao antes de enviar patch. + +## 7. Riscos de pesquisa e integracao + +1. **Homonomimos e clones:** usar sempre URL canonica, organizacao, release e README do repositorio correto. +2. **Repositorios que mudam rapidamente:** congelar commit/versao no relatorio da task e repetir a consulta no dia da implementacao. +3. **README divergente do codigo:** procurar schema, parser de config, testes e comando de execucao; README sozinho e evidencia Tier 1. +4. **Clientes fechados:** registrar como `needs-mitm` ou `config-only`, nunca como PR upstream. +5. **Forks com historia de origem controversa:** avaliar politica, licenca e aceite de contribuicoes antes de reproduzir componentes. +6. **Segredos no ambiente:** limpar `OMNIROUTE_API_KEY` e chaves de teste quando a suite assume ambiente sem credencial, como ocorreu no jcode. +7. **Mudancas no checkout:** usar worktree em `.claude/worktrees/` por projeto; nao editar o checkout compartilhado do OmniRoute nem usar `git stash`. + +## 8. Recomendacao + +Executar primeiro os lotes P0/P1 do documento de prioridade. Cada lote pode ter ate tres subagentes, um repositorio por worktree. O agente principal deve revisar a pesquisa, o smoke test e a licenca antes de permitir implementacao. O resultado de cada caso deve atualizar o tracker com commit, PR/issue, validacao e status upstream, sem preencher campos externos por suposicao. + +## 9. Referencias + +- OmniRoute CLI catalogo: `src/shared/constants/cliTools.ts` +- OmniRoute CLI reference: `docs/reference/CLI-TOOLS.md` +- OmniRoute setup guide: `docs/guides/CLI-INTEGRATIONS.md` +- Handoff jcode: `_tasks/hands-off/2026-08-01_release-v3.8.50_v3.8.50_sess-e1846bc2/handoff.md` +- Inventario curado: `https://github.com/bradAGI/awesome-cli-coding-agents` +- GitHub Search API: `https://api.github.com/search/repositories` diff --git a/_references/_sistemas_cli/02-prioridade-integracoes-clis.md b/_references/_sistemas_cli/02-prioridade-integracoes-clis.md new file mode 100644 index 0000000000..9db4ca246c --- /dev/null +++ b/_references/_sistemas_cli/02-prioridade-integracoes-clis.md @@ -0,0 +1,167 @@ +# Prioridade de integracoes de CLIs com OmniRoute + +> **Status final (2026-08-03):** esta é a priorização inicial que orientou a execução. Todos os `104/104` casos já foram pesquisados. A classificação final está no tracker `04`; a estratégia revisada de contribuição está no relatório `06`. + +**Snapshot:** 2026-08-01 +**Objetivo:** ordenar do melhor para o pior todos os projetos tecnicamente candidatos a consumir OmniRoute, sem remover projetos pequenos. A ordem e uma fila de pesquisa/execucao; ela nao e promessa de que todo upstream aceitara um PR. + +## Como ler a prioridade + +- **P0:** ja esta no catalogo OmniRoute ou tem evidencia muito forte de endpoint customizavel; executar/consolidar primeiro. +- **P1:** forte candidato novo, com provider/base URL evidente e bom retorno para o ecossistema. +- **P2:** tecnicamente promissor, mas requer confirmacao de protocolo, config, maturidade ou licenca. +- **P3:** possivel via ACP/MCP/wrapper/launcher, ou com menor adocao; pesquisar depois dos P0-P2. +- **P4:** cliente fechado, EULA, MITM ou pesquisa exploratoria; manter no inventario, mas nao bloquear os demais. + +Os fatores usados foram: evidencia de endpoint arbitrario, adocao/atividade, facilidade de teste, compatibilidade OpenAI/Anthropic/Gemini, maturidade, licenca, chance de PR upstream, valor para usuarios OmniRoute e risco de protocolo. + +## A. Catalogo OmniRoute ja existente + +Estas entradas ja aparecem no registro local. A prioridade aqui significa consolidar documentacao, smoke tests, detector/configurador e eventual upstream nominal; nao significa recriar uma integracao que ja existe. + +| Ordem | Projeto | Repositorio/documentacao | Estado local | Proximo foco | +|---:|---|---|---|---| +| A1 | Claude Code | `anthropics/claude-code` | catalogado; Anthropic base URL | manter compatibilidade Anthropic, streaming e tools | +| A2 | Codex CLI | `openai/codex` | catalogado; OpenAI-compatible | Responses, profiles e `/v1` | +| A3 | OpenCode | `anomalyco/opencode` | catalogado; provider | provider nativo/plugin e model discovery | +| A4 | Cline | `cline/cline` | catalogado; base URL | validar CLI/extension e append de `/v1` | +| A5 | Goose | `aaif-goose/goose` | catalogado; `OPENAI_HOST` | validar schema atual e ACP | +| A6 | Aider | `Aider-AI/aider` | catalogado; `OPENAI_API_BASE` | LiteLLM path, tools e custo | +| A7 | Continue | `continuedev/continue` | catalogado; provider OpenAI | CLI e config YAML atual | +| A8 | Kilo Code | `Kilo-Org/kilocode` | catalogado; custom URL | CLI, extension e auth | +| A9 | Roo Code | `RooCodeInc/Roo-Code` | catalogado; custom URL | CLI/headless e provider | +| A10 | Qwen Code | `QwenLM/qwen-code` | catalogado; `modelProviders` | V4 schema, Responses e env | +| A11 | Open Interpreter | `OpenInterpreter/open-interpreter` | catalogado; `--api_base` | streaming e tool execution | +| A12 | OpenClaw | `openclaw/openclaw` | catalogado; gateway/provider | config atual e segurança | +| A13 | Hermes Agent | `NousResearch/hermes-agent` | catalogado; provider/gateway | endpoint custom e modelos | +| A14 | Hermes | `NousResearch/hermes-agent` | catalogado/dual entry | distinguir CLI e agente | +| A15 | Oh My Pi | `can1357/oh-my-pi` | catalogado; YAML provider | auto-discovery e tool calling | +| A16 | Pi | `badlogic/pi-mono` | catalogado; provider | confirmar repositorio/CLI atual | +| A17 | Crush | `charmbracelet/crush` | catalogado; `base_url` | config TOML/JSON atual | +| A18 | Smelt | `leonardcser/smelt` | catalogado; OpenAI-compatible | headless e subagents | +| A19 | ForgeCode | `antinomyhq/forge` | catalogado; multi-provider | base URL e custom agents | +| A20 | jcode | `1jehuang/jcode` | integrado e proposto upstream | aguardar issue #704; manter README OmniRoute | +| A21 | DeepSeek TUI | `hunterbown/deepseek-tui` | catalogado legado | confirmar sucessor CodeWhale | +| A22 | CodeWhale | `Hmbown/CodeWhale` | catalogado | config primaria e legado | +| A23 | Grok Build | `xai-org/grok-build` | catalogado; `~/.grok/config.toml` | provider OmniRoute e modelos | +| A24 | Cursor Agent CLI | `cursor.com/cli` | catalogado parcial | confirmar limites de endpoint | +| A25 | Factory Droid | `Factory-AI/factory` | catalogado parcial | BYOK e endpoint suportado | +| A26 | GitHub Copilot CLI | `github/copilot-cli` | catalogado | provider base URL atual | +| A27 | Letta CLI | `letta-ai/letta-code` | catalogado | config pi-ai/local mode | +| A28 | Warp AI | `warpdotdev/Warp` | catalogado parcial | somente BYOK/desktop | +| A29 | Agent Deck | `asheshgoplani/agent-deck` | catalogado | agentes filhos e ACP | +| A30 | Antigravity | produto Google | MITM backlog | nao tratar como endpoint direto | +| A31 | Kiro AI | produto AWS | MITM backlog | auth/SSO e MITM | +| A32 | Cursor desktop | produto Anysphere | cloud/MITM | manter separado do Cursor CLI | + +## B. Novos candidatos em ordem de execucao + +| Ordem | Prioridade | Projeto | Repositorio | Evidencia inicial | Rota esperada | +|---:|:---:|---|---|---|---| +| 1 | P0 | Gemini CLI | `google-gemini/gemini-cli` | `GOOGLE_GEMINI_BASE_URL` | config direta/Gemini | +| 2 | P0 | Claw Code | `ultraworkers/claw-code` | `OPENAI_BASE_URL`, provider | OpenAI-compatible | +| 3 | P0 | Plandex | `plandex-ai/plandex` | provider com `baseUrl` | preset/provider | +| 4 | P0 | MiMo Code | `XiaomiMiMo/MiMo-Code` | `@ai-sdk/openai-compatible`, `baseURL` | provider | +| 5 | P0 | Trae Agent | `bytedance/trae-agent` | `model_providers`, `base_url` | provider/config | +| 6 | P0 | Kimi CLI | `MoonshotAI/kimi-cli` | OpenAI legacy/Responses/Anthropic, `base_url` | provider nativo | +| 7 | P0 | Every Code | `just-every/code` | fork Codex, OpenAI/Claude/Gemini | profile/provider | +| 8 | P0 | Open Codex | `ymichael/open-codex` | OpenAI/Gemini/OpenRouter/Ollama | profile/provider | +| 9 | P0 | VT Code | `vinhnx/vtcode` | `custom_providers[].base_url` | provider/failover | +| 10 | P0 | OpenHands CLI | `OpenHands/OpenHands-CLI` | `LLM_BASE_URL` | config direta | +| 11 | P0 | gptme | `gptme/gptme` | `OPENAI_BASE_URL` | config direta | +| 12 | P0 | Nanocoder | `Nano-Collective/nanocoder` | qualquer OpenAI-compatible | config direta | +| 13 | P0 | RA.Aid | `ai-christianson/RA.Aid` | `OPENAI_API_BASE` | config direta | +| 14 | P0 | CoreCoder | `he-yufeng/CoreCoder` | `OPENAI_BASE_URL` | config direta | +| 15 | P1 | Grok CLI | `superagent-ai/grok-cli` | `GROK_BASE_URL`/`baseURL` | config direta | +| 16 | P1 | Gitlawb Zero | `Gitlawb/zero` | `custom-openai-compatible`, `--base-url` | provider/flag | +| 17 | P1 | DeepSeek Reasonix | `esengine/DeepSeek-Reasonix` | endpoint/provider compativel | provider | +| 18 | P1 | KlaatCode | `KlaatAI/klaatcode` | `customModels` OpenAI-compatible | config | +| 19 | P1 | CodeMini CLI | `havingautism/Codemini-CLI` | `gateway.base_url` | gateway | +| 20 | P1 | Zot | `patriceckhart/zot` | `--base-url`, `models.json` | flag/config | +| 21 | P1 | Octomind | `Muvon/octomind` | provider URL envs | provider/env | +| 22 | P1 | DvalinCode | `arthurpanhku/dvalincode` | qualquer OpenAI-compatible | config direta | +| 23 | P1 | Coro Code | `Blushyes/coro-code` | `OPENAI_BASE_URL` | env | +| 24 | P1 | Mini-Kode | `minmaxflow/mini-kode` | `MINIKODE_BASE_URL` | env | +| 25 | P1 | Late CLI | `mlhher/late-cli` | `OPENAI_BASE_URL`, `api-url` | env/flag | +| 26 | P1 | Agentty | `1ay1/agentty` | provider-agnostic, ACP | config/ACP | +| 27 | P1 | Aizen | `aizen-stack/aizen` | Rust OpenAI-compatible, `AIZEN_BASE_URL` | config | +| 28 | P1 | Clif-Code | `DLhugly/Clif-Code` | OpenAI/Anthropic/Ollama | provider | +| 29 | P1 | Minacode | `hit9/minacode` | provider/compatibilidade | confirmar URL | +| 30 | P1 | YottaCode | `yottadynamics/yottacode` | modelo escolhido/gateway | provider | +| 31 | P1 | aichat | `sigoden/aichat` | OpenAI/Claude/Gemini | models YAML | +| 32 | P1 | ShellGPT | `TheR1D/shell_gpt` | `API_BASE_URL` | env | +| 33 | P1 | Mistral Vibe | `mistralai/mistral-vibe` | `base_url`, API base | config | +| 34 | P1 | OpenSquilla | `opensquilla/opensquilla` | gateway, 20+ providers | provider | +| 35 | P1 | Kode CLI | `shareAI-lab/Kode-cli` | endpoint/Anthropic/OpenAI/Gemini | config | +| 36 | P1 | Neovate Code | `neovateai/neovate-code` | plugin/multi-provider | plugin/provider | +| 37 | P1 | Deep Agents Code | `langchain-ai/deepagents` | qualquer tool-calling LLM | provider SDK | +| 38 | P1 | Kode fork/variants | `shareAI-lab/Kode-cli` | multi-provider | confirmar upstream | +| 39 | P1 | OpenHands principal | `All-Hands-AI/OpenHands` | CLI/web; pesquisar LLM base | config/CLI | +| 40 | P1 | SWE-agent | `SWE-agent/SWE-agent` | agente de issues | backend/provider | +| 41 | P1 | AutoCodeRover | `AutoCodeRoverSG/auto-code-rover` | agente de patches | backend/provider | +| 42 | P2 | Claurst | `Kuberwastaken/claurst` | provider/Anthropic | config; licenca GPL | +| 43 | P2 | Codebuff | `CodebuffAI/codebuff` | multi-agent CLI | provider | +| 44 | P2 | Devon | `entropy-research/Devon` | TUI pair programmer | backend | +| 45 | P2 | Letta Code | `letta-ai/letta-code` | model-agnostic | provider | +| 46 | P2 | CodeMachine CLI | `moazbuilds/CodeMachine-CLI` | multi-agent local | provider | +| 47 | P2 | Groq Code CLI | `build-with-groq/groq-code-cli` | multi-model | endpoint | +| 48 | P2 | Dexto | `truffle-ai/dexto` | CLI/web/API | provider | +| 49 | P2 | claw-code-agent | `HarnessLab/claw-code-agent` | endpoint/gateway | provider | +| 50 | P2 | g3 | `dhanji/g3` | Rust provider abstraction | provider | +| 51 | P2 | San | `genai-io/san` | provider-neutral | provider | +| 52 | P2 | Waveloom | `Menfre01/waveloom` | DeepSeek/provider | endpoint | +| 53 | P2 | picocode | `jondot/picocode` | multi-LLM | config | +| 54 | P2 | QQCode | `qnguyen3/qqcode` | skills, Rust | config | +| 55 | P2 | Keen Code | `mochow13/keen-code` | 9+ providers | config | +| 56 | P2 | Grinta | `josephsenior/Grinta-Coding-Agent` | provider-agnostic | config | +| 57 | P2 | Zap | `zap-coding-agent/zap-coding-agent` | Claude/Gemini/OpenAI/LM Studio | provider | +| 58 | P2 | Binharic | `CogitatorTech/binharic-cli` | multi-provider | config | +| 59 | P2 | Darce | `AmerSarhan/darce-cli` | multi-model/streaming | config | +| 60 | P2 | CLAII | `agencyswarm/CLAII` | multi-agent/MCP | provider | +| 61 | P2 | nori-cli | `tilework-tech/nori-cli` | multi-provider sobre Codex | config | +| 62 | P2 | cursor-agent clone | `civai-technologies/cursor-agent` | Claude/OpenAI/Ollama | provider | +| 63 | P2 | Free Code | `paoloanzn/free-code` | fork Claude Code | licenca/config | +| 64 | P2 | Claude Engineer | `Doriandarko/claude-engineer` | CLI Claude | provider | +| 65 | P2 | Smol Developer | `smol-ai/developer` | agent embutivel | SDK/adaptador | +| 66 | P2 | Agentless | `OpenAutoCoder/Agentless` | workflow sem loop | entrada de modelo | +| 67 | P2 | Amazon Q Developer CLI | `aws/amazon-q-developer-cli` | CLI AWS | auth/provider | +| 68 | P2 | nanobot | `HKUDS/nanobot` | OpenClaw rewrite | provider | +| 69 | P2 | ZeroClaw | `zeroclaw-labs/zeroclaw` | providers pluggable | provider | +| 70 | P2 | NanoClaw | `gavrielc/nanoclaw` | Anthropic SDK | base URL | +| 71 | P2 | PicoClaw | `sipeed/picoclaw` | provider/config | provider | +| 72 | P2 | IronClaw | `nearai/ironclaw` | provider Rust | provider | +| 73 | P2 | NullClaw | `nullclaw/nullclaw` | 23+ providers | provider | +| 74 | P2 | Moltis | `moltis-org/moltis` | Rust agent | provider | +| 75 | P2 | GitClaw | `open-gitagent/gitclaw` | Git-native agent | provider | +| 76 | P2 | LionClaw | `moshthepitt/lionclaw` | CLI local | provider | +| 77 | P3 | VibePod | `VibePod/vibepod-cli` | wrapper Docker | launcher | +| 78 | P3 | zeroshot | `the-open-engine/zeroshot` | worktrees/orchestration | launcher | +| 79 | P3 | Fractal | `plasma-ai/fractal` | orquestra CLIs | launcher | +| 80 | P3 | Bernstein | `chernistry/bernstein` | executa/verifica agentes | launcher | +| 81 | P3 | Traycer | `traycerai/traycer` | agentes paralelos | launcher | +| 82 | P3 | h5i | `h5i-dev/h5i` | sandbox e peer review | launcher | +| 83 | P3 | OMK | `dmae97/open-multi-agent-kit` | control plane | ACP/MCP | +| 84 | P3 | kodo | `ikamensh/kodo` | orquestrador | launcher | +| 85 | P3 | ORCH | `oxgeneral/ORCH` | fila de tarefas | launcher | +| 86 | P3 | LoopTroop | `LoopTroop-ai/LoopTroop` | orquestrador OpenCode | launcher | +| 87 | P3 | Galley | `shinpr/galley` | worktree/PR | launcher | +| 88 | P3 | Relay | `jcast90/relay` | MCP/orquestracao | MCP | +| 89 | P3 | SageCLI | `youwangd/SageCLI` | runtime-agnostic | launcher/ACP | +| 90 | P3 | 5dive | `5dive-ai/5dive` | agentes em servidor | launcher | +| 91 | P3 | agx | `ramarlina/agx` | checkpoints | launcher | +| 92 | P3 | claude-code-router | `musistudio/claude-code-router` | proxy multi-provider | integrar como consumidor/proxy | +| 93 | P3 | cc-router | `finch-xu/cc-router` | proxy Anthropic | interoperabilidade | +| 94 | P3 | OneCLI | `onecli/onecli` | broker de credenciais | seguranca/integ. adjacente | +| 95 | P3 | agent-browser | `vercel-labs/agent-browser` | ferramenta para agentes | MCP/plugin | +| 96 | P3 | OpenWork | `different-ai/openwork` | desktop sobre OpenCode | config do agente filho | +| 97 | P4 | Pool | `poolsideai/pool` | `POOLSIDE_STANDALONE_BASE_URL`; EULA | config sem PR presumido | +| 98 | P4 | Junie CLI | `junie.jetbrains.com` | fechado/EAP | BYOK/endpoint a confirmar | +| 99 | P4 | Cursor desktop | `Anysphere` | cloud endpoint | MITM/guide | +| 100 | P4 | Windsurf | produto Codeium | sem base URL geral | MITM | +| 101 | P4 | Amp | `sourcegraph.com/amp` | fechado | MITM/sem PR | +| 102 | P4 | Amazon Q/Kiro CLI | AWS | SSO/ecossistema AWS | MITM/adapter | +| 103 | P4 | Cowork | produto Anthropic | endpoint opaco | MITM | + +## C. Regra de promocao/rebaixamento + +Um projeto sobe de prioridade quando a pesquisa individual confirma: configuracao documentada, teste local com OmniRoute, licenca permissiva e contribuicao aceita. Desce quando: a URL e fixa, o endpoint e somente SaaS, o README nao corresponde ao codigo, a autenticacao e inseparavel do provedor, ou a licenca/EULA impede redistribuicao. Nenhum projeto e marcado como impossivel sem registrar a evidencia no tracker. diff --git a/_references/_sistemas_cli/03-plano-integracao-em-lotes.md b/_references/_sistemas_cli/03-plano-integracao-em-lotes.md new file mode 100644 index 0000000000..80d4a02c97 --- /dev/null +++ b/_references/_sistemas_cli/03-plano-integracao-em-lotes.md @@ -0,0 +1,314 @@ +# Plano executavel de integracao de CLIs + +> **Status final (2026-08-03):** a fase de pesquisa foi concluída em lotes de até três worktrees/agentes, cobrindo `104/104` casos. Este documento continua válido como processo operacional para implementação/publicação. Consulte `06-relatorio-final-104-clis-e-estrategia-prs.md` para o resultado final. + +**Data:** 2026-08-01 +**Objetivo:** pesquisar, integrar, validar e publicar suporte ao OmniRoute em todos os projetos tecnicamente possiveis, mantendo uma fila que permite ate tres subagentes simultaneos. + +O ciclo especifico de preparacao, revisao, envio e acompanhamento das contribuicoes upstream esta +em `05-plano-publicacao-prs-upstream.md`. + +## 1. Principios operacionais + +- Um repositorio por subagente e por worktree. +- No maximo tres tasks de repositorios em execucao ao mesmo tempo. +- Cada task pesquisa o upstream novamente antes de editar; o relatorio inicial e somente contexto. +- O agente principal revisa licenca, arquitetura, smoke test e diff antes do proximo lote. +- Nao usar checkout compartilhado para desenvolvimento e nao usar `git stash`/`git pop`. +- Usar worktrees em `.claude/worktrees/` e branches especificas. +- Nao inventar PR, issue, commit ou aceite de mantenedor. +- Nao adicionar trailers ou rodapes de IA em commits/PRs. + +## 2. Fases obrigatorias por projeto + +### Fase 0 - Preparacao da task + +Criar uma task com nome do projeto, URL canonica, prioridade, evidencia inicial, estado no catalogo OmniRoute e objetivo de integrar. Definir a worktree e o agente responsavel. + +### Fase 1 - Pesquisa individual fresca + +O agente deve verificar no upstream atual: + +- arquitetura de providers e ponto de entrada do CLI; +- arquivo/schema de configuracao e suporte a `base_url`, `baseURL`, `OPENAI_BASE_URL`, `OPENAI_API_BASE`, `LLM_BASE_URL` ou equivalente; +- protocolo real (Chat Completions, Responses, Anthropic Messages, Gemini, ACP, MCP ou outro); +- descoberta de modelos e necessidade de `/v1/models`; +- autenticacao, keyring, OAuth e variaveis de ambiente; +- streaming, tool calling, reasoning e limites conhecidos; +- politica de contribuicao, licenca e se PR de fork externo e aceito; +- atividade, releases, issues/PRs sobre providers customizados ou endpoints locais; +- comandos de build, lint, teste e smoke test; +- possibilidade de fork/PR, issue de proposta, documentacao ou apenas wrapper/MITM. + +Registrar commit/release pesquisado e links de evidencia. + +### Fase 2 - Gate de viabilidade + +Classificar exatamente um caminho inicial: + +`viable-direct` (somente configuracao), `viable-upstream` (mudanca no upstream), `viable-acp`, `viable-mcp`, `needs-wrapper`, `needs-mitm`, `config-only`, `blocked` ou `research-more`. + +Nao implementar antes de haver uma conclusao de viabilidade e uma razao verificavel. + +### Fase 3 - Baseline e TDD + +- Executar a suite recomendada pelo upstream antes das mudancas. +- Registrar falhas preexistentes, dependencias ausentes e comandos exatos. +- Limpar `OMNIROUTE_API_KEY` e demais credenciais quando os testes pressupuserem ambiente sem chaves. +- Adicionar primeiro um teste de configuracao, endpoint e selecao de modelo que falhe sem a integracao. + +### Fase 4 - Implementacao minima + +Implementar apenas o necessario para o caso pesquisado: + +- perfil/preset `omniroute` ou provider custom; +- base URL correta (raiz, `/v1` ou `/v1beta` conforme o cliente); +- chave via ambiente ou mecanismo seguro do cliente; +- modelo fixo ou descoberta de modelos; +- selecao/login/report se o CLI tiver esses fluxos; +- documentacao de uso e limites; +- testes de config e chamada. + +Se o upstream nao aceitar mudanca, preparar wrapper/launcher ou documentacao local e registrar a limitacao. + +### Fase 5 - Validacao funcional + +Executar, conforme o protocolo: + +- build, lint, typecheck e testes do upstream; +- smoke request com OmniRoute; +- streaming SSE e encerramento por abort; +- tool calling e JSON de argumentos; +- `/v1/models` ou equivalente; +- Chat Completions, Responses, Anthropic Messages e Gemini `generateContent` quando aplicavel; +- fallback/erro, timeout, retry e modelo inexistente; +- teste com chave limpa e teste com `OMNIROUTE_API_KEY` real fora dos logs. + +### Fase 6 - Publicacao upstream + +- Criar fork somente quando permitido e branch especifica. +- Abrir PR upstream se contribuicoes externas forem aceitas. +- Se PR externo for bloqueado, abrir issue com proposta, patch/referencia e smoke test. +- Se o projeto for fechado/EULA, registrar config manual ou issue de produto; nao criar PR ficticio. +- Atualizar o tracker com URL, commit, estado e resposta do mantenedor. + +### Fase 7 - Catalogo e integracao OmniRoute + +Quando houver valor para usuarios OmniRoute: + +- criar worktree propria do OmniRoute; +- atualizar `src/shared/constants/cliTools.ts` ou `src/shared/constants/cliToolsGrokBuild.ts`; +- atualizar detector em `src/lib/cli-helper/tool-detector.ts` se necessario; +- adicionar gerador/configurador e rota de settings somente se o caso exigir; +- adicionar testes do catalogo, detector, settings, `baseUrlSupport` e `/v1`; +- atualizar `docs/reference/CLI-TOOLS.md`, `docs/guides/CLI-INTEGRATIONS.md` e README quando apropriado; +- atualizar o tracker com a integracao local e evidencias. + +### Fase 8 - Fechamento + +Registrar commit, branch, PR/issue, testes, limitacoes, status do upstream, status do catalogo OmniRoute e proximo passo. O agente principal faz uma revisao final de seguranca, licenca e factualidade. + +## 3. Lotes de ate tres subagentes + +O lote e uma unidade operacional. A fila abaixo e ordenada pelo documento `02-prioridade-integracoes-clis.md`; cada linha representa uma task individual. + +### Lote 0 - consolidacao do caso de referencia + +- `CLI-000` - jcode - manter a issue #704, validar resposta do mantenedor e concluir a secao do README OmniRoute. + +### Lote P0.1 + +- `CLI-001` - Gemini CLI - integrar provider/base URL Gemini. +- `CLI-002` - Claw Code - integrar `OPENAI_BASE_URL`/provider OmniRoute. +- `CLI-003` - Plandex - integrar provider custom com `baseUrl`. + +### Lote P0.2 + +- `CLI-004` - MiMo Code - integrar provider OpenAI-compatible. +- `CLI-005` - Trae Agent - integrar `model_providers` e `base_url`. +- `CLI-006` - Kimi CLI - integrar modos OpenAI/Responses/Anthropic. + +### Lote P0.3 + +- `CLI-007` - Every Code - integrar perfil derivado do Codex. +- `CLI-008` - Open Codex - integrar provider multi-modelo. +- `CLI-009` - VT Code - integrar `custom_providers` e failover. + +### Lote P0.4 + +- `CLI-010` - OpenHands CLI - integrar `LLM_BASE_URL`. +- `CLI-011` - gptme - integrar `OPENAI_BASE_URL`. +- `CLI-012` - Nanocoder - integrar API OpenAI-compatible. + +### Lote P0.5 + +- `CLI-013` - RA.Aid - integrar `OPENAI_API_BASE`. +- `CLI-014` - CoreCoder - integrar `OPENAI_BASE_URL`. +- `CLI-015` - Grok CLI - integrar `GROK_BASE_URL`. + +### Lote P1.1 + +- `CLI-016` - Gitlawb Zero - integrar provider custom e `--base-url`. +- `CLI-017` - DeepSeek Reasonix - confirmar e integrar endpoint. +- `CLI-018` - KlaatCode - integrar `customModels`. + +### Lote P1.2 + +- `CLI-019` - CodeMini CLI - integrar `gateway.base_url`. +- `CLI-020` - Zot - integrar flag/config `--base-url`. +- `CLI-021` - Octomind - integrar provider URL envs. + +### Lote P1.3 + +- `CLI-022` - DvalinCode - integrar OpenAI-compatible. +- `CLI-023` - Coro Code - integrar `OPENAI_BASE_URL`. +- `CLI-024` - Mini-Kode - integrar `MINIKODE_BASE_URL`. + +### Lote P1.4 + +- `CLI-025` - Late CLI - integrar `OPENAI_BASE_URL`/`api-url`. +- `CLI-026` - Agentty - integrar provider e/ou ACP. +- `CLI-027` - Aizen - integrar `AIZEN_BASE_URL`. + +### Lote P1.5 + +- `CLI-028` - Clif-Code - integrar providers OpenAI/Anthropic/Ollama. +- `CLI-029` - Minacode - confirmar provider e integrar URL. +- `CLI-030` - YottaCode - integrar gateway/provider. + +### Lote P1.6 + +- `CLI-031` - aichat - integrar models YAML/provider. +- `CLI-032` - ShellGPT - integrar `API_BASE_URL`. +- `CLI-033` - Mistral Vibe - integrar base URL/provider. + +### Lote P1.7 + +- `CLI-034` - OpenSquilla - integrar gateway/provider. +- `CLI-035` - Kode CLI - integrar endpoint multi-provider. +- `CLI-036` - Neovate Code - integrar plugin/provider. + +### Lote P1.8 + +- `CLI-037` - Deep Agents Code - integrar provider do pacote CLI. +- `CLI-038` - OpenHands principal - integrar CLI/config. +- `CLI-039` - SWE-agent - integrar backend/provider. + +### Lote P1.9 + +- `CLI-040` - AutoCodeRover - integrar backend/provider. +- `CLI-041` - Claurst - integrar provider, respeitando GPL. +- `CLI-042` - Codebuff - integrar provider. + +### Lote P2.1 + +- `CLI-043` - Devon - integrar backend. +- `CLI-044` - Letta Code - integrar provider. +- `CLI-045` - CodeMachine CLI - integrar provider. + +### Lote P2.2 + +- `CLI-046` - Groq Code CLI - integrar endpoint. +- `CLI-047` - Dexto - integrar provider. +- `CLI-048` - claw-code-agent - integrar endpoint. + +### Lote P2.3 + +- `CLI-049` - g3 - integrar provider Rust. +- `CLI-050` - San - integrar provider-neutral. +- `CLI-051` - Waveloom - integrar provider/endpoint. + +### Lote P2.4 + +- `CLI-052` - picocode - integrar multi-LLM. +- `CLI-053` - QQCode - integrar config. +- `CLI-054` - Keen Code - integrar provider. + +### Lote P2.5 + +- `CLI-055` - Grinta - integrar provider. +- `CLI-056` - Zap - integrar Claude/Gemini/OpenAI. +- `CLI-057` - Binharic - integrar multi-provider. + +### Lote P2.6 + +- `CLI-058` - Darce - integrar multi-modelo. +- `CLI-059` - CLAII - integrar provider/MCP. +- `CLI-060` - nori-cli - integrar provider baseado em Codex. + +### Lote P2.7 + +- `CLI-061` - cursor-agent clone - integrar provider. +- `CLI-062` - Free Code - pesquisar licenca e integrar se viavel. +- `CLI-063` - Claude Engineer - integrar provider. + +### Lote P2.8 + +- `CLI-064` - Smol Developer - integrar SDK/adaptador. +- `CLI-065` - Agentless - integrar entrada de modelo. +- `CLI-066` - Amazon Q Developer CLI - pesquisar auth/provider. + +### Lote P2.9 + +- `CLI-067` - nanobot - integrar provider OpenClaw-compatible. +- `CLI-068` - ZeroClaw - integrar trait de provider. +- `CLI-069` - NanoClaw - confirmar base Anthropic. + +### Lote P2.10 + +- `CLI-070` - PicoClaw - integrar provider/config. +- `CLI-071` - IronClaw - integrar provider Rust. +- `CLI-072` - NullClaw - integrar provider. + +### Lote P2.11 + +- `CLI-073` - Moltis - integrar provider Rust. +- `CLI-074` - GitClaw - integrar provider Git-native. +- `CLI-075` - LionClaw - integrar provider CLI. + +### Lote P3.1 - wrappers e orquestradores + +- `CLI-076` - VibePod; `CLI-077` - zeroshot; `CLI-078` - Fractal. + +### Lote P3.2 + +- `CLI-079` - Bernstein; `CLI-080` - Traycer; `CLI-081` - h5i. + +### Lote P3.3 + +- `CLI-082` - OMK; `CLI-083` - kodo; `CLI-084` - ORCH. + +### Lote P3.4 + +- `CLI-085` - LoopTroop; `CLI-086` - Galley; `CLI-087` - Relay. + +### Lote P3.5 + +- `CLI-088` - SageCLI; `CLI-089` - 5dive; `CLI-090` - agx. + +### Lote P3.6 + +- `CLI-091` - claude-code-router; `CLI-092` - cc-router; `CLI-093` - OneCLI. + +### Lote P3.7 + +- `CLI-094` - agent-browser; `CLI-095` - OpenWork; `CLI-096` - Agent Deck (revisao de agente filho). + +### Lote P4 - fechados/MITM + +- `CLI-097` - Pool; `CLI-098` - Junie CLI; `CLI-099` - Cursor desktop. +- `CLI-100` - Windsurf; `CLI-101` - Amp; `CLI-102` - Amazon Q/Kiro CLI; `CLI-103` - Cowork. + +## 4. Criterio para iniciar o lote seguinte + +O lote seguinte pode iniciar quando os tres agentes do lote atual tiverem: pesquisa upstream anexada, gate de viabilidade preenchido, baseline registrado, resultado de smoke test ou bloqueio reproduzivel, e tracker atualizado. Uma falha de um agente nao deve paralisar os outros dois; o agente principal deve marcar `blocked` ou `research-more` com evidencia e seguir a fila. + +## 5. Entregaveis de cada task + +1. Nota de pesquisa fresca com commit/release e links. +2. Classificacao de viabilidade. +3. Diff minimo ou conclusao documentada de que nao ha diff necessario. +4. Testes e comandos executados, incluindo falhas preexistentes. +5. PR/issue upstream ou justificativa de config-only/MITM. +6. Entrada no catalogo OmniRoute quando aplicavel. +7. Atualizacao do tracker `04-tracker-integracoes-clis.md`. diff --git a/_references/_sistemas_cli/04-tracker-integracoes-clis.md b/_references/_sistemas_cli/04-tracker-integracoes-clis.md new file mode 100644 index 0000000000..1b253d1ca8 --- /dev/null +++ b/_references/_sistemas_cli/04-tracker-integracoes-clis.md @@ -0,0 +1,144 @@ +# Tracker de integracoes de CLIs com OmniRoute + +**Status final da pesquisa:** `104/104` concluídos (`100%`), `0` casos `not-started`. Este é o registro individual autoritativo. O relatório executivo está em `06-relatorio-final-104-clis-e-estrategia-prs.md`. + +**Snapshot inicial:** 2026-08-01 +**Legenda de status:** `not-started`, `researching`, `research-more`, `viable-direct`, `viable-upstream`, `viable-acp`, `viable-mcp`, `needs-wrapper`, `needs-mitm`, `blocked`, `implementing`, `validating`, `published-pr`, `published-issue`, `awaiting-maintainer`, `accepted`, `rejected`, `integrated`. + +Os campos externos (`branch`, `commit`, `PR`, `issue`) ficam como `—` ate haver evidencia real. “Catalogo OmniRoute” significa entrada local, nao necessariamente suporte upstream publicado. + +| ID | Prio | Projeto | Repositorio | Pesquisa | Tipo | Upstream | Branch | Commit | PR | Issue | Catalogo OmniRoute | Observacoes/proximo passo | +|---|:---:|---|---|---|---|---|---|---|---|---|---|---| +| CLI-000 | P0 | jcode | `1jehuang/jcode` | concluida | `viable-upstream` | `awaiting-maintainer` | `feat/omniroute-provider` | `ee4f904e6` | [fork PR](https://github.com/diegosouzapw/jcode/pull/1) | [upstream #704](https://github.com/1jehuang/jcode/issues/704) | integrated | acompanhar mantenedor e concluir secao do README | + +## Caso publicado: jcode + +| Campo | Valor | +|---|---| +| Projeto | jcode | +| Repositorio | `https://github.com/1jehuang/jcode` | +| Status geral | `awaiting-maintainer` | +| Tipo | `viable-upstream`; perfil OpenAI-compatible dirigido por metadados | +| Branch | `feat/omniroute-provider` | +| Commit | `ee4f904e6` | +| PR | `https://github.com/diegosouzapw/jcode/pull/1` (fork de referencia) | +| Issue | `https://github.com/1jehuang/jcode/issues/704` | +| Catalogo OmniRoute | `integrated` / entrada existente | +| Validacao | `cargo check --workspace` limpo; 205 testes passaram; 1 falha preexistente/ambiental | +| Diff | 6 arquivos, `+56/-3` | +| Proximo passo | acompanhar issue #704 e criar secao de README do OmniRoute | + +## Tabela principal + +| ID | Prio | Projeto | Repositorio | Pesquisa | Tipo | Upstream | Branch | Commit | PR | Issue | Catalogo OmniRoute | Observacoes/proximo passo | +|---|:---:|---|---|---|---|---|---|---|---|---|---|---| +| CLI-001 | P0 | Gemini CLI | `google-gemini/gemini-cli` | concluida | `pr-generic` | `published-issue` | `fix/omniroute-gateway-auth` | `8138105c38cc1637fe9e8a9bd520eb835f1620e6` | — | [upstream #27550](https://github.com/google-gemini/gemini-cli/issues/27550#issuecomment-5152312278) | not-in-catalog | regression `AuthType.GATEWAY`; patch +26; auth 10/10, non-interactive 17/17, content generator 55/55, Gemini `/v1beta` stream/tools smoke verde; aguardar `help wanted` antes de terceira PR | +| CLI-002 | P0 | Claw Code | `ultraworkers/claw-code` | concluida | `pr-docs` | `published-issue` | `docs/omniroute-setup` | `de857038b2f9ff9b319132e2241549e86215c351` | — | [upstream #3283](https://github.com/ultraworkers/claw-code/issues/3283) | not-in-catalog | generic OpenAI Chat Completions; docs +37; 1.415 testes, fmt, docs/release checks e clippy oficial verdes; fork bloqueado pelo GitHub, issue-first; smoke OmniRoute parcial/timeout; chave do smoke deve ser rotacionada | +| CLI-003 | P0 | Plandex | `plandex-ai/plandex` | concluida | `pr-docs` | `published-pr` | `feat/omniroute-provider-docs` | `f8f0694bdf7d1cb6e65a1f1c5bc39f84921a4507` | [upstream #359](https://github.com/plandex-ai/plandex/pull/359) | — | not-in-catalog | custom provider OpenAI-compatible ja existia; docs com `/v1`, `OMNIROUTE_API_KEY`, Docker reachability e model mapping; Go indisponivel; Docusaurus build verde; acompanhar mantenedor | +| CLI-004 | P0 | MiMo Code | `XiaomiMiMo/MiMo-Code` | concluida | `config-only` | not-applicable | `research/omniroute-mimo-code` | — | — | — | not-in-catalog | SHA `ce124cb`; provider customizado `@ai-sdk/openai-compatible` já suporta `baseURL`, `apiKey` e modelo; 116 testes focados + typecheck verdes; smoke CLI inconclusivo por travamento ambiental; sem PR artificial | +| CLI-005 | P0 | Trae Agent | `bytedance/trae-agent` | concluida | `pr-docs` | `published-pr` | `research/omniroute-trae-agent` | `4801e48b69d7583300eb86ec5c69235506d7f205` | [upstream #449](https://github.com/bytedance/trae-agent/pull/449) | — | not-in-catalog | README +39; `provider: openai` + mapping `base_url=/v1`; `/v1/responses`, `/v1/models`, Bearer, tools e limitação sem streaming; 62 testes/17 skips, pre-commit e mocks verdes; CLA pendente | +| CLI-006 | P0 | Kimi CLI | `MoonshotAI/kimi-cli` | concluida | `pr-docs` | `published-issue` | `research/omniroute-kimi-cli` | `a2f62bf6108a6954e798db992411aa06670e224f` | — | [upstream #2576](https://github.com/MoonshotAI/kimi-cli/issues/2576) | not-in-catalog | docs EN/ZH +63; `openai_legacy` `/v1`, chave via `OPENAI_API_KEY`, modelo manual; Responses/Anthropic alternativos; 47 testes e VitePress verdes; aguardar direção do mantenedor antes da PR | +| CLI-007 | P0 | Every Code | `just-every/code` | concluida | `pr-docs` / `config-only` | `published-pr` | `feat/omniroute-integration` | `8fbc8dab5fb76bf05535055801af0c3ccfea6f3b` | [upstream #614](https://github.com/just-every/code/pull/614) | — | not-in-catalog | PR documental aberta e mergeable; release `v0.6.162`; `./build-fast.sh` baseline/pós-patch verdes; smoke mock Responses/SSE/tools verde; acompanhar CI/mantenedor | +| CLI-008 | P0 | Open Codex | `ymichael/open-codex` | concluida | `pr-generic` / `issue-first` | `published-issue` | `feat/omniroute-integration` | `f25de99f991c0e4d9d6ae2811d307cdbff92f869` | — | [upstream #4](https://github.com/ymichael/open-codex/issues/4#issuecomment-5152804104) | not-in-catalog | patch genérico pronto localmente; issue-first por firewall de container e PR #19 fechada; 132 testes, typecheck/build/format verdes; lint bloqueado por ambiente; aguardar mantenedor antes de PR | +| CLI-009 | P0 | VT Code | `vinhnx/vtcode` | concluida | `pr-docs` / `config-only` | `published-pr` | `feat/omniroute-integration` | `256682d10c72f3e6e145d852b6d9d53f5c471988` | [upstream #717](https://github.com/vinhnx/VTCode/pull/717) | — | not-in-catalog | PR documental aberta e mergeable; release `0.141.10`; custom provider `/v1`, Bearer, `auto`, discovery manual, streaming/tools; 10 testes config verdes; nextest/docs checks bloqueados por ambiente; acompanhar CI/mantenedor | +| CLI-010 | P0 | OpenHands CLI | `OpenHands/OpenHands-CLI` | concluida | `config-only` | not-applicable | `feat/omniroute-openhands-cli-integration` | — | — | — | not-in-catalog | SHA `2df8a283`; `LLM_BASE_URL=/v1`, `LLM_API_KEY`, modelo obrigatório `openai/auto`, Chat Completions/SSE/tools; 63 testes focados e mock verdes; sem PR artificial | +| CLI-011 | P0 | gptme | `gptme/gptme` | concluida | `config-only` | not-applicable | `feat/omniroute-gptme-integration` | — | — | — | not-in-catalog | SHA `7fe250529`; provider TOML nomeado, `/v1/chat/completions`, `/v1/models`, Bearer, streaming/tools; compileall verde, pytest bloqueado por deps; docs genericas ja cobrem | +| CLI-012 | P0 | Nanocoder | `Nano-Collective/nanocoder` | concluida | `config-only` | not-applicable | `feat/omniroute-nanocoder-integration` | — | — | — | not-in-catalog | SHA `becae998`; `createOpenAICompatible`, `/v1/models`, streaming/native tools + XML/JSON fallback; types/format/lint/build verdes; suite ampla com falhas preexistentes; sem PR artificial | +| CLI-013 | P0 | RA.Aid | `ai-christianson/RA.Aid` | concluida | `config-only` | not-applicable | `feat/omniroute-ra-aid-integration` | — | — | — | not-in-catalog | SHA `e71bb83`; provider `openai-compatible`, `/v1/chat/completions`, Bearer, modelo explicito/`auto`, function tools; 762 testes + 62 focados e smoke verdes; sem Responses/stream HTTP garantido; Aider exige config separada; sem PR artificial | +| CLI-014 | P0 | CoreCoder | `he-yufeng/CoreCoder` | concluida | `pr-docs` / `config-only` | `published-pr` | `feat/omniroute-integration` | `f4d2851649e5dda20738c313a8a94337b24eeb9d` | [upstream #20](https://github.com/he-yufeng/CoreCoder/pull/20) | — | not-in-catalog | PR documental aberta, nao draft e mergeable; `/v1/chat/completions`, Bearer, `auto`, streaming/native tools; 86 testes, compileall, build, twine e smoke verdes; Ruff mantem 41 falhas preexistentes; acompanhar CI/mantenedor | +| CLI-015 | P1 | Grok CLI | `superagent-ai/grok-cli` | concluida | `config-only` | not-applicable | `feat/omniroute-grok-cli-integration` | — | — | — | not-in-catalog | SHA `fb97af8`; `GROK_BASE_URL`/`--base-url`, Chat Completions/SSE, Bearer, `auto` e tools confirmados; 47/48 suites e 246 testes no gate isolado, 6 arquivos/39 testes focados verdes; Node não carrega `bun:sqlite`; Responses/search/STT/Batch/midia não garantidos; monitorar PRs #290/#349 | +| CLI-016 | P1 | Gitlawb Zero | `Gitlawb/zero` | concluida | `config-only` | not-applicable | `feat/omniroute-gitlawb-zero-integration` | — | — | — | not-in-catalog | SHA `8e266797`; release `v0.6.0`; provider custom `/v1`, Bearer, `auto`, Chat/SSE/tools, usage e `/v1/models` confirmados; Go test/vet/fmt e smoke verdes; release build bloqueado por falta de espaco; politica exige issue aprovada; sem contribuicao nominal artificial | +| CLI-017 | P1 | DeepSeek Reasonix | `esengine/DeepSeek-Reasonix` | concluida | `config-only` | not-applicable | `feat/omniroute-deepseek-reasonix-integration` | — | — | — | not-in-catalog | SHA `1c62489d`; release `v1.19.1`; `kind=openai`, `/v1/chat/completions`, Bearer, `auto`, SSE/tools, `/v1/models` e reasoning confirmados; suite completa, vet, fmt, build e smoke verdes apos remover env SSH do runner; sem PR/issue redundante | +| CLI-018 | P1 | KlaatCode | `KlaatAI/klaatcode` | concluida | `config-only` | not-applicable | `feat/omniroute-klaatcode-integration` | — | — | — | not-in-catalog | SHA `0d20f24a`; release `V2.4.0`; `customModels` com `/v1`, Bearer, `auto`, Chat/SSE/tools confirmados; 316 testes, 33 fixtures e build verdes; typecheck local divergiu do CI verde; custom endpoint e apenas TUI; divergencia de metadata de licenca registrada; sem contribuicao nominal artificial | +| CLI-019 | P1 | CodeMini CLI | `havingautism/Codemini-CLI` | concluida | `config-only` | not-applicable | `feat/omniroute-codemini-cli-integration` | — | — | — | not-in-catalog | SHA `a3764b21`; package `0.8.3`; gateway `/v1`, Bearer persistido, `auto`, Chat/SSE/usage/tools e tool round trip confirmados; `/models` e probe, nao picker; 122/123 testes, 10 focados e pack-imports verdes; sem PR nominal redundante | +| CLI-020 | P1 | Zot | `patriceckhart/zot` | concluida | `config-only` | not-applicable | `feat/omniroute-zot-integration` | — | — | — | not-in-catalog | SHA `f3d8eb66`; release `v0.3.29`; custom provider `omniroute` em `models.json`, `/v1`, Bearer, `auto`, Chat/SSE/tools/reasoning opt-in e cache usage confirmados; `--base-url` e so override; PR #36 ja cita OmniRoute; race suite/build/vet/fmt verdes | +| CLI-021 | P1 | Octomind | `Muvon/octomind` | concluida | `config-only` | not-applicable | `feat/omniroute-octomind-integration` | — | — | — | not-in-catalog | SHA `65ab1db1`; release `0.39.0`; provider `local:auto` usa endpoint completo `/v1/chat/completions`, Bearer opcional, Chat JSON buffered, tools/reasoning/usage; sem SSE/Responses/discovery; fmt/fetch e smokes com/sem auth verdes; suite ampla nao executada por disco/contencao | +| CLI-022 | P1 | DvalinCode | `arthurpanhku/dvalincode` | concluida | `config-only` | not-applicable | `feat/omniroute-dvalincode-integration` | — | — | — | not-in-catalog | SHA `7d42664a`; release `v0.14.1`; provider OpenAI-compatible custom com `/v1`, Bearer via env, `auto`, Chat/SSE/usage/tools e tool round trip confirmados; `provider test` bloqueado por trusted presets; issues #109/#118/#135 ja cobrem melhorias genericas; sem PR nominal | +| CLI-023 | P1 | Coro Code | `Blushyes/coro-code` | concluida | `config-only` | not-applicable | `feat/omniroute-coro-code-integration` | — | — | — | not-in-catalog | SHA `679c57af`; release `v0.0.8`; `OPENAI_BASE_URL=/v1`, Bearer, `auto`, Chat JSON e function tools/tool loop confirmados; streaming existe mas nao e usado pelo agente; sem Responses/discovery; `cargo check`/fmt bloqueados por drift preexistente; risco de LICENSE ausente; sem PR nominal | +| CLI-024 | P1 | Mini-Kode | `minmaxflow/mini-kode` | concluida | `config-only` | not-applicable | `feat/omniroute-mini-kode-integration` | — | — | — | not-in-catalog | SHA `4e7f9767`; release/tag npm `0.2.3`; provider custom por `MINIKODE_BASE_URL=/v1`, Bearer, `auto`, Chat/SSE e tools/tool loop confirmados; sem Responses/discovery/reasoning dedicado; sem PR nominal redundante | +| CLI-025 | P1 | Late CLI | `mlhher/late-cli` | concluida | `config-only` | not-applicable | `feat/omniroute-late-cli-integration` | — | — | — | not-in-catalog | SHA `26814e62`; release `v1.4.2`; `OPENAI_BASE_URL=/v1`, Bearer, `auto`, Chat/SSE/usage/reasoning_content/tools e tool round trip confirmados; probes `/props`/`/v1/models` nao sao picker; BSL 1.1/CLA; sem PR nominal | +| CLI-026 | P1 | Agentty | `1ay1/agentty` | concluida | `config-only` | not-applicable | `feat/omniroute-agentty-integration` | — | — | — | not-in-catalog | SHA `e947b26c`; release `v0.2.10`; custom host `127.0.0.1:20128`, Bearer, Chat/SSE/tools e `/v1/models` confirmados; Responses/reasoning/tool round trip dinamico nao confirmados; MIT; sem PR nominal | +| CLI-027 | P1 | Aizen | `aizen-stack/aizen` | concluida | `config-only` | not-applicable | `feat/omniroute-aizen-integration` | — | — | — | not-in-catalog | SHA `3d8ae0f6`; release `v0.5.4`; `AIZEN_BASE_URL=/v1`, Bearer, `auto`/modelo literal, Chat/SSE/reasoning_content e `/v1/models`; tools confirmadas estaticamente, sem smoke dinamico; PolyForm Noncommercial/CLA; sem PR nominal | +| CLI-028 | P1 | Clif-Code | `DLhugly/Clif-Code` | concluida | `config-only` | not-applicable | `feat/omniroute-clif-code-integration` | — | — | — | not-in-catalog | SHA `282a787a`; release `v1.72.0`; `CLIFCODE_API_URL=/v1`, Bearer, `auto`, Chat/SSE/usage/tools e tool loop confirmados por fonte; smoke bloqueado por binario ausente; sem Responses/reasoning; licença proprietária conflitante com FSL declarada exige revisão jurídica; sem PR nominal | +| CLI-029 | P1 | Minacode | `hit9/minacode` | concluida | `config-only` | not-applicable | `feat/omniroute-minacode-integration` | — | — | — | not-in-catalog | SHA `d4ea4a97`; release `v0.18.1`; TOML custom `/v1`, key obrigatória, `auto`, Chat/Responses/Anthropic, SSE/tools/reasoning/discovery confirmados; smoke de protocolo Chat+Responses+models e compileall verdes; CI remoto verde; sem PR nominal | +| CLI-030 | P1 | YottaCode | `yottadynamics/yottacode` | concluida | `config-only` | not-applicable | `feat/omniroute-yottacode-integration` | — | — | — | not-in-catalog | SHA `039f61ce`; release `v0.3.1`; provider `openai-compatible`, `/v1`, Bearer, `/v1/models`, Chat/SSE/tools/reasoning parsing confirmados; smoke oficial com mock passou; Go 1.26 nao instalado e gates completos nao executados por espaco; sem PR nominal | +| CLI-031 | P1 | aichat | `sigoden/aichat` | concluida | `config-only` | not-applicable | `feat/omniroute-aichat-integration` | — | — | — | not-in-catalog | SHA `82976d3`; package/release `v0.30.0`; provider `openai-compatible` com base `/v1`, Bearer opcional e modelo `auto`; Chat stream/JSON, reasoning e tool round-trip confirmados; Responses ausente (#1431); limites de tool SSE ja cobertos por #1454/#1495 e PR #1496; sem publicacao nominal | +| CLI-032 | P1 | ShellGPT | `TheR1D/shell_gpt` | concluida | `config-only` | not-applicable | `feat/omniroute-shellgpt-integration` | — | — | — | not-in-catalog | SHA `a082bd53`; release `1.5.1`; `API_BASE_URL=/v1`, `OPENAI_API_KEY`, `DEFAULT_MODEL=auto` e `USE_LITELLM=false`; smoke real confirmou env e `.sgptrc`, Chat/SSE e Bearer; issue #718 nao reproduz no HEAD; CI baseline vermelho por temperatura default independente; sem publicacao nominal | +| CLI-033 | P1 | Mistral Vibe | `mistralai/mistral-vibe` | concluida | `config-only` | not-applicable | `feat/omniroute-mistral-vibe-integration` | — | — | — | not-in-catalog | SHA/release `99a6efa9` / `v2.23.2`; `GenericBackend` custom com base `/v1`, Bearer, Chat/SSE, usage, tools e reasoning; smoke do binario oficial verde; #790 cobre somente discovery `/v1/models`; upstream nao aceita contribuicoes de codigo no momento; sem publicacao | +| CLI-034 | P1 | OpenSquilla | `opensquilla/opensquilla` | concluida | `config-only` | not-applicable | `feat/omniroute-opensquilla-integration` | — | — | — | not-in-catalog | `custom` com `/v1`, Bearer opcional, Chat/SSE, tools, reasoning recebido, usage e `/v1/models`; smoke provider-level verde; monitorar issue #912 do probe custom; sem publicacao nominal | +| CLI-035 | P1 | Kode CLI | `shareAI-lab/Kode-cli` | concluida | `config-only` | not-applicable | `feat/omniroute-kode-cli-integration` | — | — | — | not-in-catalog | `custom-openai` com `/v1`, discovery `/v1/models`, fallback manual, Bearer, Chat/SSE, tools/tool round-trip e persistencia; smoke runtime bloqueado por Bun/artefato ausente; CI baseline vermelho por formatacao; sem publicacao nominal | +| CLI-036 | P1 | Neovate Code | `neovateai/neovate-code` | concluida | `config-only` | not-applicable | `feat/omniroute-neovate-code-integration` | — | — | — | not-in-catalog | provider JSON custom normalizado para OpenAI-compatible, `/v1`, Bearer, Chat/SSE, tools/tool round-trip; model catalog declarado (sem discovery); smoke do pacote publicado verde; sem publicacao nominal | +| CLI-037 | P1 | Deep Agents Code | `langchain-ai/deepagents` | concluida | `config-only` | not-applicable | `feat/omniroute-deepagents-code-integration` | — | — | — | not-in-catalog | SHA `46ee772b4`; `deepagents-code==0.1.51`; provider `openai`, base OmniRoute `/v1`, model `openai:auto`; Responses e default, Chat usa `use_responses_api=false`; smoke de config verde, sem HTTP/runtime por deps e disco; #3973/#3287 ja cobrem os pontos genericos; sem publicacao nominal | +| CLI-038 | P1 | OpenHands principal | `OpenHands/OpenHands` | concluida | `config-only` | not-applicable | `feat/omniroute-openhands-main-integration` | — | — | — | not-in-catalog | SHA `1708efc44`; Agent Canvas `1.8.0`; `openai/auto` + base `/v1` + API key + `api_mode=chat`; LiteLLM envia `model=auto`, Chat/SSE/tools estruturais; sem discovery generico `/v1/models`; PRs OmniRoute [#15189](https://github.com/OpenHands/OpenHands/pull/15189)/[#15211](https://github.com/OpenHands/OpenHands/pull/15211) fechadas sem merge; sem nova publicacao | +| CLI-039 | P1 | SWE-agent | `SWE-agent/SWE-agent` | concluida | `config-only` | not-applicable | `feat/omniroute-swe-agent-integration` | — | — | — | not-in-catalog | SHA `3ea751c08`; release `v1.1.0`; LiteLLM com `openai/`, `api_base=/v1` e chave por env; Chat/tools/tool round-trip e batch confirmados por fonte; reasoning parcial; smoke HTTP bloqueado por deps ausentes; sem publicacao nominal | +| CLI-040 | P1 | AutoCodeRover | `AutoCodeRoverSG/auto-code-rover` | concluida | `pr-generic` | `validating` | `feat/omniroute-auto-code-rover-integration` | — | — | — | not-in-catalog | SHA `585d3e639`; patch local sem commit em 4 arquivos corrige `litellm-generic-openai/auto`, base `/v1`, precedencia da chave e pricing desconhecido; 9 testes focados com stubs, tracer source-only, compileall e diff-check verdes; sem HTTP real; licenca SONAR Source-Available exige gate juridico antes de publicar | +| CLI-041 | P2 | Claurst | `Kuberwastaken/claurst` | concluida | `config-only` | not-applicable | `feat/omniroute-claurst-integration` | — | — | — | not-in-catalog | SHA `595b0ebe3`; `custom-openai` com settings persistidos, base `/v1`, `CUSTOM_OPENAI_API_KEY`, modelo `auto`, Chat/SSE/tools e `/v1/models`; CI upstream verde; sem build/smoke local e sem publicacao nominal; monitorar PR #365 sem duplicar | +| CLI-042 | P2 | Codebuff | `CodebuffAI/codebuff` | concluida | `blocked` / `issue-first` | `blocked` | `feat/omniroute-codebuff-integration` | — | — | — | not-in-catalog | SHA `195b9bef6`; main nao expoe base/chave/provider custom na CLI/SDK; PR upstream existente [#693](https://github.com/CodebuffAI/codebuff/pull/693) cobre a lacuna, observada OPEN/CONFLICTING/DIRTY; nao criar patch concorrente; acompanhar #693 e validar apos merge/port | +| CLI-043 | P2 | Devon | `entropy-research/Devon` | concluida | `pr-generic` | validating | `feat/omniroute-devon-integration` | — | — | [upstream #100](https://github.com/entropy-research/Devon/issues/100) | not-in-catalog | SHA `8f68f1d74`; diff local genérico em 5 arquivos, sem commit; reprodução literal DeepSeek/OpenRouter e resume corrigidos; 9 testes focados, compileall e diff-check verdes; Standards/Spec aprovados; aguardar autorização antes de fork/push/PR | +| CLI-044 | P2 | Letta Code | `letta-ai/letta-code` | concluida | `config-only` | not-applicable | `feat/omniroute-letta-code-integration` | — | — | — | integrated | SHA `09aff1bb4`; já coberta pelo provider local `lmstudio` (`lmstudio_openai`), discovery `/api/v0/models`→`/v1/models`, Chat/SSE/tools; 8 testes OmniRoute verdes; sem PR nominal | +| CLI-045 | P2 | CodeMachine CLI | `moazbuilds/CodeMachine-CLI` | concluida | `config-only` | not-applicable | `feat/omniroute-codemachine-cli-integration` | — | — | — | not-in-catalog | SHA `572def63e`; integração indireta por OpenCode custom `@ai-sdk/openai-compatible`, base `/v1`, chave por env e `omniroute/auto`; provider/model reconhecidos no smoke de config; alternativa Claude Code; sem PR nominal | +| CLI-046 | P2 | Groq Code CLI | `build-with-groq/groq-code-cli` | concluida | `pr-generic` | `awaiting-maintainer` | `feat/omniroute-groq-code-cli-integration` | — | — | — | not-in-catalog | SHA `a303eb4be`; `groq-sdk@0.27.0` fixa `/openai/v1/chat/completions`, logo não há config-only para OmniRoute; mock confirmou path/Bearer; PR existente [#7](https://github.com/build-with-groq/groq-code-cli/pull/7) é a duplicata natural, mas precisa distinguir Groq-compatible de OpenAI-compatible; 17 testes oficiais + 5 testes de contexto, build e mock verdes; clone limpo, sem patch/publicação | +| CLI-047 | P2 | Dexto | `truffle-ai/dexto` | concluida | `config-only` | `not-applicable` | `feat/omniroute-dexto-integration` | — | — | — | not-in-catalog | SHA `4108a9c73`; provider `openai-compatible` nativo exige `baseURL`, aceita modelo arbitrário, Bearer opcional, Chat/SSE/tools e reasoning effort; receita `/v1` + `auto`; 175 testes focados e builds llm/core verdes; TS2741 em chatgpt-oauth é baseline; ELv2; sem PR/issue nominal | +| CLI-048 | P2 | claw-code-agent | `HarnessLab/claw-code-agent` | concluida | `config-only` | `not-applicable` | `feat/omniroute-claw-code-agent-integration` | — | — | — | not-in-catalog | SHA `167571da8`; `OPENAI_BASE_URL=http://127.0.0.1:20128/v1`, Bearer, model manual/`auto`, Chat/SSE/tools/usage confirmados; smoke `MOCK_SMOKE_OK`, 80 testes focados; sem discovery/Responses API; licença não identificada (`license: null`); sem PR/issue | +| CLI-049 | P2 | g3 | `dhanji/g3` | concluida | `pr-generic` | `validating` | `feat/omniroute-g3-integration` | — | — | [upstream #70](https://github.com/dhanji/g3/issues/70) | not-in-catalog | SHA `0ddb052d2`; diff local provider-neutral em `provider_registration.rs`, 1 arquivo `+25/-1`, corrige registro `custom`→`custom.default`; `cargo check -p g3-config`, 6 testes config e diff-check verdes; teste focal escrito mas build bloqueado em `x11.pc`; manifesto declara MIT sem arquivo LICENSE; Standards/Spec centrais aprovados; sem publicação | +| CLI-050 | P2 | San | `genai-io/san` | concluida | `config-only` | `not-applicable` | `feat/omniroute-san-integration` | — | — | — | not-in-catalog | SHA `e45ec0ef7`; Apache-2.0/release v1.22.1; provider Custom com base `/v1`, Bearer, `/models`, Chat/SSE/tools/tool result e reasoning best-effort; smoke HTTP de dois turnos e gates Go focados verdes; sem provider nominal ou publicação | +| CLI-051 | P2 | Waveloom | `Menfre01/waveloom` | concluida | `config-only` | `not-applicable` | `feat/omniroute-waveloom-integration` | — | — | — | not-in-catalog | SHA `293d5cd11`; Apache-2.0/release v0.5.1; adapter OpenAI com `/v1`, Bearer, `/models`, SSE, 14 tools, tool-result round-trip e sessões; smoke do binário oficial verde e CI remoto do HEAD verde; reasoning/cache avançados não são projetados; sem publicação | +| CLI-052 | P2 | picocode | `jondot/picocode` | concluida | `config-only` | `not-applicable` | `feat/omniroute-picocode-integration` | — | — | — | not-in-catalog | SHA `064a2a6ea`; MIT/release v0.6.0; Rig 0.28 lê `OPENAI_BASE_URL` e usa Responses `/v1/responses`; smoke confirmou Bearer, `auto`, 11 tools e function_call_output; 7 testes/doc-tests verdes; fmt/clippy só baseline; sem PR/issue | +| CLI-053 | P2 | QQCode | `qnguyen3/qqcode` | concluida | `config-only` | `not-applicable` | `feat/omniroute-qqcode-integration` | — | — | — | not-in-catalog | SHA `be6a96ce7`; Apache-2.0/release v1.2.0; provider arbitrário + `GENERIC`/OpenAI com base `/v1`; smoke confirmou JSON/SSE, Bearer, extra_body, reasoning e tool-result; backend 20/20, ACP 13+1 skip, observer 11/11, compileall/helps verdes; sem PR/issue | +| CLI-054 | P2 | Keen Code | `mochow13/keen-code` | concluida | `config-only` | `not-applicable` | `feat/omniroute-keen-code-integration` | — | — | — | not-in-catalog | SHA `ee2eaf0f4`; MIT/release v0.40.0; receita manual `openai-compatible` + `/v1` + Bearer + model arbitrário; smoke oficial confirmou Chat/SSE, tools/tool-result, usage e reasoning replay; provider oculto apenas no picker; CI remoto verde; sem PR/issue | +| CLI-055 | P2 | Grinta | `josephsenior/Grinta-Coding-Agent` | concluida | `config-only` | `not-applicable` | `feat/omniroute-grinta-integration` | — | — | — | not-in-catalog | SHA `df7437524`; provider OpenAI-compatible com `LLM_API_KEY`, model `auto`, base `/v1`; smoke Chat/SSE/tools/tool-result/reasoning/usage/cache verde; 183 testes focados, compileall e Ruff verdes; sem PR/issue nominal | +| CLI-056 | P2 | Zap | `zap-coding-agent/zap-coding-agent` | concluida | `config-only` | `not-applicable` | `feat/omniroute-zap-integration` | — | — | — | not-in-catalog | SHA `f0203f872`; provider arbitrário `kind=openai`, base `/v1`, Bearer, discovery `/models`, Chat JSON/SSE, tools/tool-result, reasoning e usage confirmados; cargo check + 16 testes/gates focados verdes; issue #2 confirma arquitetura; sem PR nominal | +| CLI-057 | P2 | Binharic | `CogitatorTech/binharic-cli` | concluida | `pr-generic` | `validating` | `feat/omniroute-binharic-integration` | — | — | — | not-in-catalog | SHA `52ccca70b`; patch sem commit em `provider.ts` + teste: aplica `baseURL` ao OpenAI/Anthropic e usa Chat Completions para base customizada; RED→GREEN, 14 focal, 88 arquivos/774 testes, typecheck/build e smoke wire verdes; lint upstream bloqueado; sem publicação | +| CLI-058 | P2 | Darce | `AmerSarhan/darce-cli` | concluida | `config-only` | `not-applicable` | `feat/omniroute-darce-integration` | — | — | — | not-in-catalog | SHA `1b90c379a`; MIT declarada no package/npm sem arquivo LICENSE; `DARCE_API_BASE` raiz sem `/v1`, `DARCE_API_KEY`, `DARCE_MODEL=auto`; smoke PTY do binário confirmou 2 Chat/SSE, 7 tools, tool-result e Bearer; 106 testes/build verdes; sem MCP/ACP/A2A; sem PR/issue | +| CLI-059 | P2 | CLAII | `agencyswarm/CLAII` | concluida | `pr-generic` | `blocked` | `feat/omniroute-claii-integration` | — | — | — | not-in-catalog | SHA `89d42311b`; patch sem commit em README/config/providers/test: `CLAII_API_KEY`, `CLAII_BASE_URL` origem sem `/v1beta`, model runtime e reject explícito; 4 wire/loop + 10 calculator + pip install + smoke CLI verdes; unittest discover falha só baseline `calculator`/`pkg`; sem MCP/ACP/A2A; **All Rights Reserved**, não publicar sem autorização jurídica | +| CLI-060 | P2 | nori-cli | `tilework-tech/nori-cli` | concluida | `config-only` | `not-applicable` | `feat/omniroute-nori-cli-integration` | — | — | — | not-in-catalog | SHA `829ecf3fd`; Apache-2.0/v0.24.0; Nori custom ACP → OpenCode `opencode-ai@1.18.11` → OmniRoute `/v1`; MCP separado por `/api/mcp/stream` ou stdio; 5 testes focados, cargo build nori e smoke ACP Nori→OpenCode verdes; sem patch/publicação | +| CLI-061 | P2 | cursor-agent clone | `civai-technologies/cursor-agent` | concluida | `config-only` | `not-applicable` | `feat/omniroute-cursor-agent-clone-integration` | — | — | — | not-in-catalog | SHA `d21a8f3d4`; MIT/v0.1.39; SDK OpenAI usa base `/v1`, Anthropic usa raiz; smokes de 2 turnos/tools verdes; factory rejeita `auto` puro; 23 testes, mypy/build verdes; sem patch/publicação | +| CLI-062 | P2 | Free Code | `freecodexyz/free-code` | concluida | `config-only` | `blocked` | `feat/omniroute-free-code-integration` | — | — | [upstream #20](https://github.com/freecodexyz/free-code/issues/20) | not-in-catalog | SHA `6b25ab68b`; URL antiga `paoloanzn/free-code` redireciona; base Anthropic raiz, `model=auto`, stream/tools/MCP; build verde; sem LICENSE/campo license e código atribuído à Anthropic, não publicar | +| CLI-063 | P2 | Claude Engineer | `Doriandarko/claude-engineer` | concluida | `config-only` / `pr-generic` | `blocked` | `feat/omniroute-claude-engineer-integration` | — | [upstream #250](https://github.com/Doriandarko/claude-engineer/pull/250) | [upstream #116](https://github.com/Doriandarko/claude-engineer/issues/116) | not-in-catalog | SHA `0a9e4b309`; v3 funciona por base Anthropic raiz com modelo fixo; #250 já adiciona `ANTHROPIC_MODEL`; arquivo LICENSE ausente apesar de declaração MIT; sem patch concorrente/publicação | +| CLI-064 | P2 | Smol Developer | `smol-ai/developer` | concluida | `config-only` | `not-applicable` | `feat/omniroute-smol-developer-integration` | — | — | — | not-in-catalog | SHA `a6747d1a6`; `OPENAI_API_BASE=/v1`, `auto`, 3 Chat calls, SSE/function calling e Agent Protocol validados; gates de runtime verdes, build metadata preexistente; sem patch/publicação | +| CLI-065 | P2 | Agentless | `OpenAutoCoder/Agentless` | concluida | `config-only` | `not-applicable` | `feat/omniroute-agentless-integration` | — | — | — | not-in-catalog | SHA `5ce5888b9`; OpenAI chat + embeddings funcionam com bases distintas; Anthropic normal/cache histórico validados; DeepSeek fixa host; pre-commit/compileall verdes; sem patch/publicação | +| CLI-066 | P2 | Amazon Q Developer CLI | `aws/amazon-q-developer-cli` | concluida | `viable-mcp` / `needs-wrapper` | `not-applicable` | `feat/omniroute-amazon-q-developer-cli-integration` | — | — | — | not-in-catalog | SHA `15cc8f3cd`; modelo usa AWS JSON/EventStream Bearer/SigV4 e não `/v1`; MCP stdio imediato, HTTP legado com ressalva; upstream issue-first/manutenção crítica; sem patch/publicação | +| CLI-067 | P2 | nanobot | `HKUDS/nanobot` | concluida | `config-only` | `not-applicable` | `feat/omniroute-nanobot-integration` | — | — | — | not-in-catalog | HEAD `44b7e1bf4`; provider dinâmico OpenAI-compatible com base `/api/v1` e modelo `omniroute/auto`; Chat/SSE/tools/reasoning/usage/images/discovery e retry validados; 424 testes + Ruff; sem PR nominal | +| CLI-068 | P2 | ZeroClaw | `zeroclaw-labs/zeroclaw` | concluida | `config-only` | `not-applicable` | `feat/omniroute-zeroclaw-integration` | — | — | — | not-in-catalog | HEAD `4770420ab`; `custom.omniroute`, base `/v1`, Bearer, `auto`, Chat/Responses e tools nativas opt-in; 1.173 unit + 1 integração, fmt/config/smoke verdes; sem PR nominal | +| CLI-069 | P2 | NanoClaw | `gavrielc/nanoclaw` | concluida | `config-only` | `not-applicable` | `feat/omniroute-nanoclaw-integration` | — | — | — | not-in-catalog | HEAD `dfac7e0af`; provider Claude existente aponta para raiz Anthropic OmniRoute e OneCLI guarda a chave; baseline e 49 testes OmniRoute verdes; Codex #3155/#1984 e OpenCode #2985 ficam como follow-ups; sem PR | +| CLI-070 | P2 | PicoClaw | `sipeed/picoclaw` | concluida | `config-only` | `not-applicable` | `feat/omniroute-picoclaw-integration` | — | — | — | not-in-catalog | HEAD `49183d7`, `/api/v1`, `openai/auto` → `auto`; Chat/SSE/tools/usage/images/discovery; Go ausente, testes locais não executados; issue router #3298; sem publicação | +| CLI-071 | P2 | IronClaw | `nearai/ironclaw` | concluida | `config-only` | `not-applicable` | `feat/omniroute-ironclaw-integration` | — | — | — | not-in-catalog | HEAD `4b71aaae`; `openai_compatible` `/api/v1`, Chat/SSE/tools/images/discovery; 889+5 testes e fmt verdes; reasoning #3673; sem publicação | +| CLI-072 | P2 | NullClaw | `nullclaw/nullclaw` | concluida | `config-only` | `not-applicable` | `feat/omniroute-nullclaw-integration` | — | — | — | not-in-catalog | HEAD `d8a802fd`; custom `/api/v1`, Chat/Responses/Anthropic, tools/streaming/usage/images; Zig ausente, CI run 30788444193 verde; sem publicação | +| CLI-073 | P2 | Moltis | `moltis-org/moltis` | concluida | `config-only` | `not-applicable` | `feat/omniroute-moltis-integration` | — | — | — | not-in-catalog | HEAD `678d407`; `custom-omniroute`, `/api/v1`, `auto`, Chat/SSE/tools/reasoning/usage/images; 401 testes + fmt verdes; MCP/ACP separados; sem publicação | +| CLI-074 | P2 | GitClaw | `open-gitagent/gitclaw` | concluida | `config-only` | `not-applicable` | `feat/omniroute-gitclaw-integration` | — | — | — | not-in-catalog | GitAgent HEAD `d3e25d7`; base `/api/v1`, `omniroute:auto`, Chat/SSE/tools/images; build + 65 testes + smoke verdes; reasoning=false no descriptor; sem publicação | +| CLI-075 | P2 | LionClaw | `moshthepitt/lionclaw` | concluida | `patch-required` / `issue-first` | `awaiting-maintainer` | `feat/omniroute-lionclaw-integration` | — | — | — | not-in-catalog | HEAD `cb59b23d`; Codex app-server não projeta config.toml/secret para runtime confinado; patch seguro necessário, alinhado à #157; gates locais bloqueados por uv/podman; CI verde; sem publicação | +| CLI-076 | P3 | VibePod | `VibePod/vibepod-cli` | concluida | `config-only` | `not-applicable` | `feat/omniroute-vibepod-integration` | — | — | — | not-in-catalog | Claude Code via `/api`, container usa `host.docker.internal`; Codex não injeta chave; compileall verde, pytest bloqueado por typer; sem publicação | +| CLI-077 | P3 | zeroshot | `the-open-engine/zeroshot` | concluida | `config-only` | `not-applicable` | `feat/omniroute-zeroshot-integration` | — | — | — | not-in-catalog | Gateway OpenAI `/api/v1`, `auto`, tools fail-closed; 22 testes + build verdes; sem streaming JSON/reasoning/MCP no gateway; sem publicação | +| CLI-078 | P3 | Fractal | `plasma-ai/fractal` | concluida | `config-only` / `needs-wrapper` | `awaiting-maintainer` | `feat/omniroute-fractal-integration` | — | — | — | not-in-catalog | Codex Responses por node `CODEX_HOME`; caveat tmux quente não encaminha `OMNIROUTE_API_KEY`; fix genérico recomendado, sem PR | +| CLI-079 | P3 | Bernstein | `chernistry/bernstein` | concluida | `config-only` | `not-applicable` | `feat/omniroute-bernstein-integration` | — | — | — | not-in-catalog | Canonical `sipyourdrink-ltd/bernstein`; openai_agents `/api/v1`, auto, api_key_env allowlisted; testes bloqueados por openai ausente; sem publicação | +| CLI-080 | P3 | Traycer | `traycerai/traycer` | concluida | `config-only` indireto | `not-applicable` | `feat/omniroute-traycer-integration` | — | — | — | not-in-catalog | Harness OpenCode + provider `@ai-sdk/openai-compatible`, `/api/v1`, `omniroute/auto`; host central fechado; sem publicação | +| CLI-081 | P3 | h5i | `h5i-dev/h5i` | concluida | `patch-required` | `awaiting-maintainer` | `feat/omniroute-h5i-integration` | — | — | — | not-in-catalog | Auth proxy/egress Codex fixos em OpenAI anulam base custom; patch seguro/policy-pinned necessário; CI externa verde; sem publicação | +| CLI-082 | P3 | OMK | `dmae97/open-multi-agent-kit` | concluida | `viable-mcp` | `not-applicable` | `feat/omniroute-omk-integration` | — | — | — | not-in-catalog | pesquisa concluída neste lote; controle multiagente, MCP é caminho primário; sem provider nominal | +| CLI-083 | P3 | kodo | `ikamensh/kodo` | concluida | `config-only` indireto | `not-applicable` | `feat/omniroute-kodo-integration` | — | — | — | not-in-catalog | pesquisa concluída neste lote; orquestrador/agent child, propagar env/base/model ao agente filho | +| CLI-084 | P3 | ORCH | `oxgeneral/ORCH` | concluida | `needs-wrapper` | `awaiting-maintainer` | `feat/omniroute-orch-integration` | — | — | — | not-in-catalog | pesquisa concluída neste lote; fila/controle sem provider LLM direto, wrapper/adaptador necessário | +| CLI-085 | P3 | LoopTroop | `LoopTroop-ai/LoopTroop` | concluida | `config-only` indireto | `not-applicable` | `feat/omniroute-looptroop-integration` | — | — | — | not-in-catalog | HEAD `cbfc81c5`; OpenCode recebe provider `@ai-sdk/openai-compatible`, `/api/v1`, `omniroute/auto`; 16 testes verdes; sem publicação | +| CLI-086 | P3 | Galley | `shinpr/galley` | concluida | `patch-required` | `awaiting-maintainer` | `feat/omniroute-galley-integration` | — | — | — | not-in-catalog | HEAD `6bcc593d`; registry/transports fechados, requer transport OpenAI-compatible para executor e supervisor; Go ausente; sem publicação | +| CLI-087 | P3 | Relay | `jcast90/relay` | concluida | `config-only` | `not-applicable` | `feat/omniroute-relay-integration` | — | — | — | not-in-catalog | HEAD `7bd5a2f6`; provider profile Codex com `OPENAI_BASE_URL`, key ref e modelo; smoke Responses obrigatório; MCP separado; sem publicação | +| CLI-088 | P3 | SageCLI | `youwangd/SageCLI` | concluida | `config-only` indireto | `not-applicable` | `feat/omniroute-sagecli-integration` | — | — | — | not-in-catalog | HEAD `c167712d`; Codex runtime, base/key configuradas fora do Sage; env plaintext caveat; 45 testes verdes; sem publicação | +| CLI-089 | P3 | 5dive | `5dive-ai/5dive` | concluida | `patch-required` | `awaiting-maintainer` | `feat/omniroute-5dive-integration` | — | — | — | not-in-catalog | HEAD `b64b6dac`; provider/base maps fechados; patch OpenAI-compatible genérico; 50 testes focados verdes; sem publicação | +| CLI-090 | P3 | agx | `ramarlina/agx` | concluida | `config-only` indireto | `not-applicable` | `feat/omniroute-agx-integration` | — | — | — | not-in-catalog | HEAD `e674cec1`; Codex herda base/key/model; smoke Responses e governança `--full-auto`; Jest ausente; sem publicação | +| CLI-091 | P3 | claude-code-router | `musistudio/claude-code-router` | concluida | `config-only` | `not-applicable` | `feat/omniroute-claude-code-router-integration` | — | — | — | not-in-catalog | HEAD `bc8a8e62`; provider custom OpenAI/Anthropic/Gemini, Chat/Responses; smoke por protocolo; sem publicação | +| CLI-092 | P3 | cc-router | `finch-xu/cc-router` | concluida | `config-only` | `not-applicable` | `feat/omniroute-cc-router-integration` | — | — | — | not-in-catalog | HEAD `c4c7579`; custom Responses/Chat com base/path/header, SSE/tools/reasoning; cargo bloqueado por glib; sem publicação | +| CLI-093 | P3 | OneCLI | `onecli/onecli` | concluida | `config-only` | `not-applicable` | `feat/omniroute-onecli-integration` | — | — | — | not-in-catalog | HEAD `84ccaf74`; MITM credential gateway, generic host injection; MCP separado; sem publicação | +| CLI-094 | P3 | agent-browser | `vercel-labs/agent-browser` | concluida | `config-only` | `not-applicable` | `feat/omniroute-agent-browser-integration` | — | — | — | not-in-catalog | HEAD `01c1147d`; chat usa gateway Chat/SSE/tools com env key/model; base precisa validar sufixo `/v1` para não duplicar path; cargo test exit 0; sem publicação | +| CLI-095 | P3 | OpenWork | `different-ai/openwork` | concluida | `config-only` indireto | `not-applicable` | `feat/omniroute-openwork-integration` | — | — | — | not-in-catalog | HEAD `ecb7a5f0`; OpenCode custom provider `/api/v1`, auth gerenciada; sem testes/deps; sem publicação | +| CLI-096 | P3 | Agent Deck review | `asheshgoplani/agent-deck` | concluida | `config-only` indireto | `not-applicable` | `feat/omniroute-agent-deck-review` | — | — | — | integrated | HEAD `46300807`; env/model propagados a Codex/OpenCode; Go ausente; sem publicação | +| CLI-097 | P4 | Pool | `poolsideai/pool` | concluida | `config-only` | `not-applicable` | `feat/omniroute-pool-integration` | — | — | — | not-in-catalog | HEAD `a6fe0ca1`; `pool exec --api-url` OpenAI-compatible, sandbox required, MCP/ACP separado; EULA; sem publicação | +| CLI-098 | P4 | Junie CLI | `junie.jetbrains.com` | concluida | `config-only` | `not-applicable` | `feat/omniroute-junie-integration` | — | — | — | not-in-catalog | HEAD `d2701be6`; custom profile OpenAICompletion/Responses com baseUrl full e env ref; runtime proprietário/EAP; sem publicação | +| CLI-099 | P4 | Cursor desktop | Anysphere | concluida | `config-only` limitado | `awaiting-maintainer` | `feat/omniroute-cursor-desktop-integration` | — | — | — | integrated | disclosure-only; BYO key/chat panel; Composer/Tab nativos; privado/MITM proibido; sem publicação | +| CLI-100 | P4 | Windsurf | Codeium | concluida | `blocked-closed` / MCP-only | `awaiting-maintainer` | `feat/omniroute-windsurf-integration` | — | — | — | not-in-catalog | sem upstream/base custom; BYOK Anthropic específico; MCP separado; MITM proibido; sem publicação | +| CLI-101 | P4 | Amp | Sourcegraph | concluida | `config-only` parcial / Enterprise-gated | `awaiting-maintainer` | `feat/omniroute-amp-integration` | — | — | — | not-in-catalog | CLI fechada/Amp Server; confirmar provider custom com suporte; MCP viável; sem publicação | +| CLI-102 | P4 | Amazon Q/Kiro CLI | AWS | concluida | `patch-required` legado / `blocked-closed` Kiro | `awaiting-maintainer` | `feat/omniroute-amazon-q-integration` | — | — | — | integrated | Q usa AWS EventStream/SigV4; Kiro fechado sem base custom; MCP-only seguro; sem publicação | +| CLI-103 | P4 | Cowork | Anthropic | concluida | `blocked-closed` / MCP-only | `not-applicable` | — | — | — | — | not-in-catalog | inferência gerida pela Anthropic sem BYOK/base custom; Custom Connector MCP remoto; MITM proibido; sem publicação | + +## Como atualizar + +Ao terminar uma fase, alterar somente os campos comprovados e deixar os demais como `—`. Para uma integracao concluida, registrar: versao/commit pesquisado, mecanismo, arquivos modificados, testes, branch, commit, URL de PR/issue e resposta do mantenedor. Se o caso for apenas configuracao, registrar o comando/config real e marcar `config-only` ou `viable-direct`, sem criar uma PR artificial. + +Antes de publicar uma contribuicao, aplicar o gate e o checklist de +`05-plano-publicacao-prs-upstream.md`. diff --git a/_references/_sistemas_cli/05-plano-publicacao-prs-upstream.md b/_references/_sistemas_cli/05-plano-publicacao-prs-upstream.md new file mode 100644 index 0000000000..44c1715662 --- /dev/null +++ b/_references/_sistemas_cli/05-plano-publicacao-prs-upstream.md @@ -0,0 +1,659 @@ +# Plano de publicacao de integracoes OmniRoute nos repositorios upstream + +> **Status da campanha de pesquisa:** `104/104` casos concluídos. Este plano continua sendo o procedimento de execução e publicação. A matriz final, inclusive os casos em que PR é inadequada ou impossível, está em `06-relatorio-final-104-clis-e-estrategia-prs.md`. + +**Data:** 2026-08-01 +**Escopo:** transformar a fila `CLI-000` a `CLI-103` em contribuicoes upstream verificadas, +publicando PR, issue, guia de configuracao, adaptador ou conclusao de bloqueio conforme o mecanismo +real de cada projeto. +**Documentos-base:** `01-relatorio-pesquisa-clis-omniroute.md`, +`02-prioridade-integracoes-clis.md`, `03-plano-integracao-em-lotes.md` e +`04-tracker-integracoes-clis.md`. + +## 1. Resultado esperado + +Para cada repositorio pesquisado, a campanha deve produzir exatamente um resultado principal: + +1. **PR upstream de integracao nominal:** adiciona provider/preset `omniroute`, configuracao, + documentacao e testes quando isso combina com a arquitetura do projeto. +2. **PR upstream de compatibilidade generica:** melhora suporte a endpoint customizado sem acoplar + o projeto ao nome OmniRoute, acompanhado de documentacao comprovando o uso com OmniRoute. +3. **PR somente de documentacao:** registra uma configuracao funcional quando o codigo ja suporta + OmniRoute e o upstream aceita guias de terceiros. +4. **Issue-first:** solicita decisao de arquitetura ou permissao antes do patch quando a politica do + repositorio, o desenho de providers ou o tamanho da mudanca exigirem alinhamento. +5. **Configuracao sem PR:** documenta no OmniRoute um fluxo que ja funciona e para o qual uma mudanca + upstream seria redundante ou rejeitada pela politica do projeto. +6. **Adaptador ACP/MCP/wrapper:** contribui no ponto de extensao correto quando o projeto nao consome + diretamente APIs de modelos. +7. **MITM, produto fechado ou bloqueado:** registra evidencia e nao fabrica uma contribuicao que o + upstream nao pode receber. + +O objetivo e tentar integrar todos os casos tecnicamente possiveis. O objetivo nao e abrir uma PR em +todo repositorio independentemente da arquitetura, licenca ou politica de contribuicao. + +## 2. Regras da campanha + +- Trabalhar em lotes de no maximo tres repositorios, com um subagente por repositorio. +- Usar uma worktree isolada por repositorio dentro de `.claude/worktrees/`. +- Nao editar implementacoes no checkout compartilhado. +- Nao usar `git stash` ou `git pop`. +- Fazer pesquisa fresca no commit atual do upstream antes de criar branch ou editar arquivos. +- Ler `README`, `CONTRIBUTING`, templates de issue/PR, `SECURITY`, licenca e instrucoes locais de + agentes antes da implementacao. +- Procurar issues e PRs abertas/fechadas sobre custom provider, base URL, OpenAI-compatible, + Anthropic-compatible, Gemini endpoint, proxy, gateway e OmniRoute antes de propor uma mudanca. +- Registrar a base pesquisada por commit SHA ou release. Nao usar apenas `main` como evidencia. +- Executar baseline antes da mudanca e distinguir falhas preexistentes de regressao. +- Nunca expor `OMNIROUTE_API_KEY` ou qualquer outra credencial em comandos publicados, fixtures, + logs, commits, screenshots, PRs ou issues. +- Nao inserir trailers, assinaturas ou rodapes de IA em commits, PRs ou issues. +- Nao afirmar que uma integracao funciona sem um teste reproduzivel ou uma limitacao explicitamente + registrada. +- Nao inventar fork, branch, commit, PR, issue, CI ou resposta de mantenedor. +- Atualizar `04-tracker-integracoes-clis.md` ao concluir cada fase material. + +## 3. Unidade de trabalho por repositorio + +Cada item `CLI-NNN` deve possuir uma task individual. A task e o pacote de contexto entregue ao +subagente e o registro que permite retomar o trabalho sem repetir ou perder evidencias. + +### 3.1 Cabecalho obrigatorio da task + +```md +# CLI-NNN - - integracao OmniRoute upstream + +- Repositorio canonico: +- Prioridade/lote: +- Estado no catalogo OmniRoute: +- Evidencia inicial: +- Worktree: +- Branch planejada: +- Commit/release pesquisado: — +- Responsavel: +- Estado: researching +``` + +### 3.2 Pesquisa obrigatoria dentro da task + +O subagente deve responder, com links e caminhos de codigo: + +1. Qual e o repositorio canonico, commit/release atual, licenca e nivel de atividade? +2. Contribuicoes de forks externos sao aceitas? Ha CLA, DCO, sign-off ou issue previa obrigatoria? +3. Qual e a arquitetura de providers e qual e o menor ponto de extensao? +4. O cliente usa Chat Completions, Responses, Anthropic Messages, Gemini, ACP, MCP ou protocolo + proprietario? +5. A base URL esperada e raiz, `/v1`, `/v1beta` ou uma URL completa por operacao? +6. O cliente acrescenta algum sufixo automaticamente? Pode duplicar `/v1` ou `/v1beta`? +7. Como a autenticacao e resolvida: variavel de ambiente, arquivo, keyring, OAuth ou header custom? +8. Como os modelos sao definidos ou descobertos? O cliente chama um endpoint de modelos? +9. Streaming, tool calling, reasoning, imagens e cancelamento funcionam pelo caminho escolhido? +10. Ja existe issue, PR, discussao ou documentacao para endpoints customizados ou OmniRoute? +11. Quais comandos oficiais executam install, format, lint, typecheck, build e testes? +12. Qual contribuicao agrega valor real: codigo nominal, compatibilidade generica, docs, issue, + wrapper, MCP/ACP, somente configuracao ou nenhum patch? + +### 3.3 Gate de contribuicao + +Antes de editar, preencher uma decisao: + +| Decisao | Quando usar | Saida esperada | +|---|---|---| +| `pr-provider` | O upstream possui catalogo/presets de providers | Provider/preset OmniRoute, docs e testes | +| `pr-generic` | Falta uma capacidade generica necessaria, como base URL customizavel | Patch generico, docs e teste com OmniRoute | +| `pr-docs` | O codigo ja funciona e o upstream aceita guias de integracao | Guia minimo e validado | +| `issue-first` | Mudanca arquitetural, politica incerta ou mantenedor exige proposta | Issue com evidencia e desenho do patch | +| `config-only` | Tudo funciona por configuracao e um PR seria redundante | Guia no OmniRoute e smoke test | +| `adapter-acp` | ACP e o ponto real de integracao | Adaptador/registro ACP e testes | +| `adapter-mcp` | MCP e o ponto real de integracao | Config/servidor MCP e testes | +| `wrapper` | O projeto apenas lanca outro agente | Wrapper/env forwarding e teste do filho | +| `needs-mitm` | Endpoint fechado ou fixo | Pesquisa/guia MITM separado; sem PR artificial | +| `blocked` | Licenca, politica, build ou protocolo impedem progresso | Evidencia reproduzivel e proximo desbloqueio | + +O gate deve incluir a alternativa rejeitada. Exemplo: `pr-provider` escolhido porque o repositorio +mantem presets nomeados; `pr-docs` rejeitado porque a configuracao exigiria cinco campos internos e +nao seria uma experiencia suportada. + +## 4. Ciclo completo da PR + +### Fase PR-0 - Preparar o contexto + +- Reservar o item no tracker e marcar pesquisa em andamento. +- Confirmar que nenhum outro agente esta trabalhando no mesmo repositorio. +- Resolver o repositorio canonico, fork existente e permissao de contribuicao. +- Criar a task individual com a evidencia inicial marcada como hipotese. +- Criar a worktree isolada somente depois de confirmar o upstream correto. + +### Fase PR-1 - Pesquisar upstream e contribuicoes existentes + +- Ler integralmente as regras do repositorio aplicaveis aos arquivos que podem mudar. +- Mapear provider registry, configuracao, transporte HTTP, auth, modelo, streaming e ferramentas. +- Pesquisar issues/PRs por termos de compatibilidade e pelo nome OmniRoute. +- Registrar commit/release, caminhos e links de evidencia na task. +- Escolher o gate de contribuicao da secao 3.3. + +### Fase PR-2 - Baseline reproduzivel + +- Instalar dependencias de acordo com o upstream. +- Rodar format check, lint, typecheck/build e testes relevantes antes do patch. +- Rodar um smoke test do caminho existente, mesmo que ele falhe por falta da integracao. +- Limpar chaves do ambiente nos testes que validem o comportamento sem credenciais. +- Registrar comando, codigo de saida, testes aprovados e falhas preexistentes. +- Se o projeto nao puder ser construido, tentar o ambiente documentado e registrar o bloqueio; nao + declarar regressao nem compatibilidade com base apenas na leitura do README. + +### Fase PR-3 - Desenhar o menor patch aceitavel + +A ordem de preferencia e: + +1. Reusar a abstracao de provider ja existente. +2. Adicionar metadados/preset antes de criar codigo especial. +3. Reusar cliente OpenAI/Anthropic/Gemini ja presente. +4. Adicionar capacidade generica quando ela beneficiar outros gateways e for coerente com o projeto. +5. Criar executor/adapter dedicado somente quando o protocolo realmente divergir. + +O patch normalmente deve cobrir: + +- identificador e nome de exibicao `omniroute`, se presets nomeados forem aceitos; +- base URL correta e sem dupla concatenacao de versao; +- chave obtida de ambiente ou storage seguro; +- configuracao/descoberta de modelo; +- headers estritamente necessarios; +- streaming e tool calling preservados; +- mensagens de erro sem expor segredo; +- documentacao curta e executavel; +- testes unitarios/integracao alinhados ao padrao upstream. + +Nao adicionar telemetria, dependencia, fluxo de login ou codigo de rede novo quando o provider +generico existente ja resolve o caso. + +### Fase PR-4 - Implementar com teste primeiro + +- Criar teste que demonstre a ausencia do preset, config ou comportamento requerido. +- Confirmar a falha pelo motivo esperado. +- Implementar o menor patch. +- Fazer o teste passar e executar testes adjacentes. +- Refatorar apenas o necessario para manter o padrao do upstream. +- Formatar somente os arquivos tocados, salvo exigencia contraria do repositorio. + +Para PR somente de documentacao, substituir o teste vermelho por uma validacao real dos comandos e +do arquivo de configuracao documentado. Nao sintetizar exemplos que nao foram executados. + +### Fase PR-5 - Validar contra OmniRoute + +Escolher a matriz compativel com o cliente: + +| Superficie | Base inicial esperada | Validacoes minimas | +|---|---|---| +| OpenAI Chat Completions | confirmar se o cliente espera raiz ou `/v1` | chamada simples, stream, tool call, erro de modelo | +| OpenAI Responses | confirmar regra de concatenacao do cliente | resposta simples, stream/eventos, tool call | +| Anthropic Messages | normalmente base antes de `/v1/messages`; confirmar no codigo | mensagem, stream, tools, headers de versao | +| Gemini | normalmente base antes das operacoes `v1beta`; confirmar no codigo | generateContent, streamGenerateContent, tools | +| ACP | endpoint/transport definido pelo protocolo | discovery, sessao, request e cancelamento | +| MCP | stdio, SSE ou Streamable HTTP conforme suporte | inicializacao, listagem e invocacao de ferramenta | + +Registrar no resultado quais linhas da matriz foram executadas, omitidas ou bloqueadas. Um smoke +test simples nao deve ser apresentado como prova de tool calling ou streaming. + +### Fase PR-6 - Revisar o diff antes de publicar + +O agente responsavel faz uma auto-revisao e o agente principal verifica: + +- aderencia a `CONTRIBUTING` e instrucoes locais; +- escopo minimo e ausencia de refactor oportunista; +- testes cobrindo config, URL, auth sem segredo e modelo; +- documentacao consistente com o codigo executado; +- ausencia de arquivos gerados, caches, logs ou credenciais; +- licenca e atribuicao preservadas; +- branch baseada no upstream atual; +- commits pequenos e com mensagem no estilo do projeto; +- ausencia de trailers ou texto de IA; +- `git diff --check` e gates oficiais limpos, ou falhas preexistentes documentadas. + +Uma PR nao deve ser publicada enquanto houver alteracao sem explicacao, teste essencial faltando ou +duvida material sobre a politica do upstream. + +### Fase PR-7 - Preparar a publicacao + +- Confirmar fork e remotes sem sobrescrever branches existentes. +- Atualizar a branch sobre o ponto exigido pelo upstream usando operacao nao destrutiva. +- Enviar a branch ao fork somente depois da revisao. +- Criar PR contra a branch correta do repositorio canonico. +- Se a contribuicao externa estiver bloqueada, abrir issue-first e anexar o commit/patch de + referencia somente quando isso for permitido. +- Registrar URLs reais no tracker imediatamente apos a publicacao. + +Convencoes de branch sugeridas, sujeitas ao padrao de cada upstream: + +- `feat/omniroute-provider` para provider/preset nominal; +- `feat/custom-base-url` para capacidade generica; +- `docs/omniroute-setup` para documentacao validada; +- `fix/custom-endpoint-versioning` para correcao de raiz versus `/v1`/`/v1beta`. + +### Fase PR-8 - Corpo da PR + +Usar o template oficial do repositorio quando existir. Na ausencia de template, adaptar: + +```md +## Why + +Explain the user problem and the existing extension point. Avoid marketing claims. + +## What changed + +- Add or enable the smallest provider/configuration path required. +- Document the verified setup. +- Cover URL, authentication and model selection behavior with tests. + +## Verification + +- `` +- `` +- `` + +## Compatibility notes + +- API surface: `` +- Base URL rule: `` +- Streaming: `` +- Tool calling: `` + +## Scope + +No unrelated refactors or credential changes. +``` + +O titulo deve descrever a mudanca, nao a campanha. Exemplos de formato, sujeitos ao estilo do +upstream: `Add OmniRoute provider preset`, `Support configurable OpenAI-compatible base URLs` ou +`Document OmniRoute as a custom endpoint`. + +### Fase PR-9 - Issue-first ou fallback + +Quando uma PR direta nao for apropriada, a issue deve conter: + +- problema reproduzivel e publico afetado; +- ponto de extensao encontrado no codigo; +- proposta minima; +- compatibilidade esperada e protocolo; +- evidencia de teste ou prototipo; +- pergunta objetiva ao mantenedor; +- link para patch de referencia apenas se permitido. + +Nao abrir simultaneamente issue e PR sem necessidade. Se o template exigir issue previa, esperar a +decisao ou seguir a politica declarada. + +### Fase PR-10 - Acompanhar ate a decisao + +Depois da publicacao: + +- observar CI e checks obrigatorios; +- responder perguntas tecnicas com evidencia; +- corrigir somente o escopo da contribuicao ou pedidos claros do mantenedor; +- reexecutar testes depois de cada mudanca; +- registrar novos commits, revisoes e estado no tracker; +- marcar `accepted` somente depois de merge/aceite comprovado; +- marcar `rejected` com o motivo fornecido pelo upstream; +- se a PR ficar inativa, registrar `awaiting-maintainer`, sem declarar abandono prematuramente; +- manter o guia/catalogo OmniRoute coerente com o estado real do upstream. + +O acompanhamento pode usar a skill `babysit` individualmente para uma PR aberta. Como essa skill +acompanha uma unica PR, nunca agrupar tres PRs em uma mesma execucao dela. + +### Fase PR-11 - Fechar a task + +Uma task individual termina com: + +- pesquisa fresca e gate registrados; +- diff, configuracao ou bloqueio documentado; +- baseline e validacao final comparados; +- branch/commit reais, quando criados; +- PR/issue reais, quando publicados; +- status no catalogo OmniRoute; +- limitacoes e proximo passo; +- linha correspondente no tracker atualizada. + +## 5. Estrategia de paralelizacao + +### 5.1 Papeis por lote + +- **Subagente A:** primeiro repositorio do lote; dono exclusivo da worktree e do diff upstream. +- **Subagente B:** segundo repositorio do lote; dono exclusivo da worktree e do diff upstream. +- **Subagente C:** terceiro repositorio do lote; dono exclusivo da worktree e do diff upstream. +- **Agente principal:** coordena o tracker, revisa gates/diffs, impede duplicacao e autoriza a + publicacao depois das evidencias. + +Todos os agentes devem ser avisados de que nao estao sozinhos no workspace e nao podem reverter ou +sobrescrever mudancas de outros agentes. + +### 5.2 Barreira do lote + +O lote seguinte pode comecar quando os tres itens atuais tiverem, no minimo: + +1. commit/release upstream pesquisado; +2. gate de contribuicao definido; +3. baseline registrado; +4. patch validado, configuracao comprovada ou bloqueio reproduzivel; +5. decisao de publicacao tomada; +6. tracker atualizado. + +A espera por resposta de mantenedor nao bloqueia o lote seguinte. Depois de uma PR/issue publicada, +o item passa para acompanhamento e libera o slot de implementacao. + +### 5.3 Limite de trabalho em progresso + +- No maximo tres pesquisas/implementacoes ativas. +- Publicacoes aguardando mantenedor nao contam como slot de implementacao, mas ficam no tracker. +- No maximo uma task ativa por repositorio, inclusive forks ou variantes do mesmo upstream. +- Se dois itens resolverem o mesmo repositorio, consolidar a pesquisa e decidir se ha uma ou duas + contribuicoes antes de abrir branches. + +## 6. Fila de publicacao + +A ordem detalhada continua sendo a do `03-plano-integracao-em-lotes.md`. Esta secao define o objetivo +de publicacao de cada onda; a pesquisa individual pode promover, rebaixar ou mudar o tipo de +contribuicao. + +### Onda 0 - referencia e infraestrutura da campanha + +- `CLI-000` jcode: acompanhar issue upstream e PR de referencia; concluir a secao prometida no + README do OmniRoute. +- Preparar o modelo de task individual e aplicar o mesmo tracker a todos os novos repositorios. + +### Onda 1 - P0.1 a P0.5 + +- `CLI-001` Gemini CLI: confirmar se o endpoint Gemini customizado pede apenas docs/config ou um + preset nominal. +- `CLI-002` Claw Code: confirmar provider OpenAI-compatible e propor preset/docs minimos. +- `CLI-003` Plandex: confirmar o registro de providers customizados e propor provider/preset. +- `CLI-004` MiMo Code: confirmar o adapter OpenAI-compatible e propor configuracao/provider. +- `CLI-005` Trae Agent: confirmar `model_providers` e propor entrada OmniRoute/documentacao. +- `CLI-006` Kimi CLI: escolher uma superficie suportada e evitar um patch que misture tres + protocolos sem testes. +- `CLI-007` Every Code: reutilizar a arquitetura herdada do Codex quando ainda aplicavel. +- `CLI-008` Open Codex: confirmar upstream canonico e propor provider multi-modelo. +- `CLI-009` VT Code: validar provider customizado, modelo e failover. +- `CLI-010` OpenHands CLI: verificar se `LLM_BASE_URL` torna o caso docs/config-only. +- `CLI-011` gptme: verificar se `OPENAI_BASE_URL` torna o caso docs/config-only. +- `CLI-012` Nanocoder: confirmar compatibilidade de tool calling e decidir preset versus docs. +- `CLI-013` RA.Aid: verificar se `OPENAI_API_BASE` torna o caso docs/config-only. +- `CLI-014` CoreCoder: verificar se `OPENAI_BASE_URL` torna o caso docs/config-only. +- `CLI-015` Grok CLI: confirmar se o endpoint e genericamente configuravel ou preso ao protocolo + Grok antes de propor patch. + +### Onda 2 - P1.1 a P1.9 + +- `CLI-016` Gitlawb Zero: provider custom/flag; preferir docs ou preset pequeno. +- `CLI-017` DeepSeek Reasonix: confirmar repositorio, atividade e endpoint antes de qualquer PR. +- `CLI-018` KlaatCode: integrar via `customModels` ou preset se o catalogo aceitar nomes. +- `CLI-019` CodeMini CLI: validar `gateway.base_url` e sua regra de versao. +- `CLI-020` Zot: validar `--base-url` e `models.json`; docs-first se ja suficiente. +- `CLI-021` Octomind: confirmar variaveis de URL por provider e propor configuracao minima. +- `CLI-022` DvalinCode: confirmar o cliente OpenAI-compatible e testes disponiveis. +- `CLI-023` Coro Code: confirmar `OPENAI_BASE_URL`; docs-first se nao houver lacuna de codigo. +- `CLI-024` Mini-Kode: confirmar `MINIKODE_BASE_URL`; docs-first se nao houver lacuna de codigo. +- `CLI-025` Late CLI: testar ambiente e flag `api-url`; corrigir precedencia apenas se necessario. +- `CLI-026` Agentty: escolher entre provider direto e ACP conforme a arquitetura atual. +- `CLI-027` Aizen: validar `AIZEN_BASE_URL` e propor docs/preset. +- `CLI-028` Clif-Code: selecionar um unico protocolo principal para a primeira contribuicao. +- `CLI-029` Minacode: pesquisa confirmatoria antes de definir o tipo de PR. +- `CLI-030` YottaCode: confirmar gateway/provider e selecao de modelo. +- `CLI-031` aichat: integrar via configuracao de modelos ou provider nominal, conforme a politica. +- `CLI-032` ShellGPT: validar `API_BASE_URL` e decidir docs/config-only. +- `CLI-033` Mistral Vibe: confirmar base URL customizada e separar suporte generico de marca. +- `CLI-034` OpenSquilla: localizar o registro de gateways e propor provider/preset. +- `CLI-035` Kode CLI: escolher OpenAI, Anthropic ou Gemini com base na implementacao mais nativa. +- `CLI-036` Neovate Code: preferir plugin/provider oficial ao patch no core, se existir. +- `CLI-037` Deep Agents Code: contribuir no pacote CLI/provider correto, nao apenas no SDK generico. +- `CLI-038` OpenHands principal: evitar duplicar `CLI-010`; consolidar se ambos apontarem para o + mesmo mecanismo e upstream. +- `CLI-039` SWE-agent: confirmar backend de modelos e interface publica suportada. +- `CLI-040` AutoCodeRover: confirmar backend e propor config/provider minimo. +- `CLI-041` Claurst: revisar GPL e politica antes de redistribuir qualquer adaptacao. +- `CLI-042` Codebuff: confirmar se o provider e extensivel e se contribuicoes externas sao aceitas. + +### Onda 3 - P2.1 a P2.11 + +- `CLI-043` Devon, `CLI-044` Letta Code e `CLI-045` CodeMachine CLI: pesquisar backend real; + revisar a entrada local ja existente de Letta antes de nova PR. +- `CLI-046` Groq Code CLI, `CLI-047` Dexto e `CLI-048` claw-code-agent: confirmar endpoints, + protocolos e maturidade antes do patch. +- `CLI-049` g3, `CLI-050` San e `CLI-051` Waveloom: localizar a abstracao de provider e preferir + implementacao generica. +- `CLI-052` picocode, `CLI-053` QQCode e `CLI-054` Keen Code: validar configuracao multi-modelo e + documentar o caminho minimo. +- `CLI-055` Grinta, `CLI-056` Zap e `CLI-057` Binharic: escolher o provider compativel com melhor + cobertura de streaming/tools. +- `CLI-058` Darce, `CLI-059` CLAII e `CLI-060` nori-cli: separar integracao de modelo de MCP e de + codigo herdado do Codex. + +Resultado P2.6: + +- `CLI-058` Darce: `config-only`, sem PR necessária; usar `DARCE_API_BASE` na raiz e `DARCE_MODEL`. +- `CLI-059` CLAII: patch genérico local validado, mas publicação bloqueada pela declaração upstream + `All Rights Reserved`/ausência de licença OSS; só reconsiderar com autorização jurídica explícita. +- `CLI-060` nori-cli: `config-only` via agente ACP customizado OpenCode; não alterar backend Codex; + MCP deve ser configurado uma vez, em Nori ou OpenCode, para evitar duplicação de tools. +- `CLI-061` cursor-agent clone, `CLI-062` Free Code e `CLI-063` Claude Engineer: revisar origem, + licenca e politica do fork antes de publicar. + +Lote P2.7 reservado em 2026-08-02, na branch-base local `release/v3.8.50` em +`35405be6020696a7c66158ea7a25f06d61ff88ff`. Os três upstreams foram clonados em worktrees +separadas, indexados e delegados. Nenhuma publicação está autorizada; patches só podem surgir após +prova RED→GREEN e permanecem sem commit até revisão central. + +Resultado P2.7: + +- `CLI-061` cursor-agent clone: `config-only`; OpenAI usa base com `/v1`, Anthropic usa raiz sem + `/v1`; tools/tool-result foram comprovados nos dois protocolos. O factory rejeita `auto` puro, + mas isso não impede uso com modelos reconhecíveis ou classes diretas. Sem PR. +- `CLI-062` Free Code: `config-only` com `ANTHROPIC_BASE_URL` na raiz e `model=auto`; stream, + tools/tool-result e MCP nativo foram comprovados. O repo canônico agora é `freecodexyz/free-code`, + mas não há licença e o README atribui o código à Anthropic; publicação bloqueada. +- `CLI-063` Claude Engineer: endpoint/chave funcionam como `config-only` com modelo fixo. A lacuna + de `ANTHROPIC_MODEL` já está coberta pela PR #250; não criar patch concorrente. Arquivo de licença + segue ausente apesar da issue #116, portanto publicação permanece bloqueada. +- `CLI-064` Smol Developer, `CLI-065` Agentless e `CLI-066` Amazon Q Developer CLI: decidir entre + SDK/adaptador, config de modelo ou bloqueio por autenticacao. + +Lote P2.8 iniciado em 2026-08-02 na branch-base local `release/v3.8.50`, SHA +`35405be6020696a7c66158ea7a25f06d61ff88ff`, com clones limpos e separados. Smol Developer será +testado primeiro como integração do SDK OpenAI legado; Agentless será avaliado por backend +OpenAI/Anthropic/DeepSeek; Amazon Q Developer CLI será tratado como protocolo AWS próprio, com MCP +avaliado separadamente. Não criar adaptador grande para Amazon Q nem qualquer publicação antes de +issue-first/coordenação exigida por `CONTRIBUTING.md`. Estado inicial: nenhum commit, fork, push, +PR, issue ou Discussion. + +Resultado P2.8: + +- `CLI-064` Smol Developer: `config-only`; `OPENAI_API_BASE` com `/v1` e `model=auto` passaram no + CLI, biblioteca e Agent Protocol histórico. Não há lacuna provider-specific e a PR #134 já cobre + uma expansão LiteLLM. Sem publicação. +- `CLI-065` Agentless: `config-only` pelo backend OpenAI, incluindo embeddings. Anthropic normal + também funciona; cache/tools exige SDK histórico e DeepSeek possui host fixo, mas essas melhorias + não são necessárias para integrar o projeto e propostas LiteLLM anteriores foram fechadas. Sem + publicação. +- `CLI-066` Amazon Q Developer CLI: MCP stdio é a integração direta; o backend de modelo fala AWS + JSON/EventStream e precisa de wrapper/backend novo. O upstream está em manutenção crítica e exige + issue-first; não preparar PR nominal ou adaptador surpresa. Sem publicação. + +Estado final P2.8: commits `0`, pushes `0`, forks `0`, PRs `0`, issues `0`, Discussions `0`. +Próxima fila: P2.9 (`CLI-067` nanobot, `CLI-068` ZeroClaw, `CLI-069` NanoClaw), usando no máximo +três worktrees/agentes e repetindo a pesquisa individual antes de qualquer patch. + +Lote P2.9 iniciado em 2026-08-03 sobre a branch-base local `release/v3.8.50`, SHA +`84b1e5e12f238269e698f400766230f985f4a07b`. O checkout principal já continha uma alteração do +operador em `CLAUDE.md`, preservada fora do escopo. As worktrees foram recriadas e os upstreams +foram clonados nos HEADs `44b7e1bf4` (nanobot), `4770420ab` (ZeroClaw) e `dfac7e0af` (NanoClaw). +Os três índices Codebase Memory moderate estão ready, sem skipped, e a pesquisa foi delegada a um +agente por repositório. Nenhuma publicação está autorizada; o estado inicial continua: commits `0`, +pushes `0`, forks `0`, PRs `0`, issues `0`, Discussions `0`. + +- `CLI-067` nanobot, `CLI-068` ZeroClaw e `CLI-069` NanoClaw: validar providers OpenClaw/Anthropic + e evitar assumir que todos aceitam a mesma base URL. + +Resultado P2.9: + +- `CLI-067` nanobot: `config-only` pelo provider dinâmico OpenAI-compatible. A base correta inclui + `/api/v1`; `omniroute/auto` seleciona o provider custom e envia `auto` no wire. Chat, SSE, tools, + reasoning, usage, imagens, discovery e retry foram validados. Sem publicação upstream. +- `CLI-068` ZeroClaw: `config-only` pela família `custom`, com `uri=/v1`, modelo `auto`, wire Chat e + `native_tools=true`. Responses é opt-in. Suite de provider, config, fmt e smoke HTTP passaram. + Sem provider nominal ou publicação upstream. +- `CLI-069` NanoClaw: `config-only` pelo provider Claude existente, apontando a raiz Anthropic do + OmniRoute sem `/v1/messages` e usando OneCLI para a credencial. Codex e OpenCode têm bloqueios + upstream reproduzidos (#3155/#1984/#2985) e ficam fora do caminho de produção atual. + +Estado final P2.9: commits `0`, pushes `0`, forks `0`, PRs `0`, issues `0`, Discussions `0`. +Progresso da pesquisa: `70/104` (`67,3%`); pendentes: `34/104` (`32,7%`). Próxima fila: P2.10 +(`CLI-070` PicoClaw, `CLI-071` IronClaw, `CLI-072` NullClaw). +- `CLI-070` PicoClaw, `CLI-071` IronClaw e `CLI-072` NullClaw: localizar traits/registries e propor + um provider pequeno com testes. +- `CLI-073` Moltis, `CLI-074` GitClaw e `CLI-075` LionClaw: confirmar atividade, provider e comandos + de validacao antes da publicacao. + +### Onda 4 - P3, integracoes indiretas + +- `CLI-076`, `CLI-077`, `CLI-078`, `CLI-079`, `CLI-080` e `CLI-081`: pesquisar forwarding de + ambiente/configuracao para os agentes filhos; + publicar wrapper ou docs somente quando houver um ponto de extensao real. +- `CLI-082`, `CLI-083`, `CLI-084`, `CLI-085`, `CLI-086`, `CLI-087`, `CLI-088`, `CLI-089` e + `CLI-090`: escolher ACP, MCP, launcher ou integracao do agente filho; nao apresentar uma + integracao de orquestrador como provider de modelo. +- `CLI-091` e `CLI-092`: tratar como interoperabilidade entre proxies; documentar loops, headers, + auth e riscos antes de propor codigo. +- `CLI-093` e `CLI-094`: integrar como broker/ferramenta MCP somente se isso estiver no escopo dos + projetos. +- `CLI-095` e `CLI-096`: configurar o agente filho e revisar a entrada existente de Agent Deck. + +### Onda 5 - P4, fechados, EULA e MITM + +- `CLI-097` Pool: confirmar o que a EULA permite; priorizar configuracao local e nao presumir PR. +- `CLI-098` Junie CLI: pesquisar canal oficial de feedback; sem repositorio publico confirmado, nao + existe fila de PR. +- `CLI-099` Cursor desktop, `CLI-100` Windsurf, `CLI-101` Amp, `CLI-102` Amazon Q/Kiro CLI e + `CLI-103` Cowork: tratar como MITM, configuracao de produto ou pedido oficial de feature. So mover + para PR se um repositorio publico e uma politica de contribuicao forem comprovados. + +## 7. Prompt operacional para cada subagente + +O agente principal deve adaptar e enviar este prompt para cada item: + +```text +Voce e responsavel exclusivamente por CLI-NNN - no repositorio . +Voce nao esta sozinho no workspace: nao reverta, sobrescreva ou reorganize mudancas de outros +agentes. Trabalhe somente na worktree isolada atribuida dentro de .claude/worktrees/ e nunca use +git stash/pop. + +Primeiro pesquise o upstream atual. Leia README, CONTRIBUTING, licenca, templates e instrucoes locais. +Registre commit/release, arquitetura de providers, config/base URL, protocolo, auth, modelos, +streaming, tool calling, issues/PRs existentes e comandos oficiais de build/test. A evidencia inicial +do relatorio e uma hipotese, nao uma conclusao. + +Antes de editar, classifique o caso como pr-provider, pr-generic, pr-docs, issue-first, config-only, +adapter-acp, adapter-mcp, wrapper, needs-mitm ou blocked, com justificativa. Execute o baseline e +registre falhas preexistentes. Se houver patch, trabalhe com teste primeiro e implemente somente a +menor integracao coerente com o upstream. Confirme raiz versus /v1 versus /v1beta, autenticacao, +modelo, streaming e tool calling conforme aplicavel. + +Nao publique nada antes da revisao do agente principal. Entregue: pesquisa com links/caminhos, +gate, baseline, diff, testes, smoke test sanitizado, riscos, branch/commit local se criados e a +atualizacao proposta para 04-tracker-integracoes-clis.md. Nao invente dados e nao exponha chaves. +``` + +## 8. Checklist de autorizacao para enviar uma PR + +O agente principal somente autoriza a publicacao quando todas as respostas forem `sim` ou houver +uma excecao registrada: + +- [ ] O repositorio canonico e a branch-alvo foram confirmados. +- [ ] A politica aceita o tipo de contribuicao planejado. +- [ ] Issues/PRs duplicadas foram pesquisadas. +- [ ] O commit/release de base esta registrado. +- [ ] O gate de contribuicao esta justificado. +- [ ] O baseline foi executado e falhas preexistentes estao separadas. +- [ ] O patch e o menor necessario e segue a arquitetura upstream. +- [ ] A base URL e sua regra de versao foram verificadas no codigo e em runtime. +- [ ] Auth/modelos foram testados sem vazar segredo. +- [ ] Streaming/tool calling foram testados ou marcados explicitamente como nao aplicaveis. +- [ ] Testes, lint, format, typecheck/build relevantes foram executados. +- [ ] A documentacao foi executada e corresponde ao codigo. +- [ ] O diff nao contem caches, builds, logs, credenciais ou refactors sem relacao. +- [ ] O titulo e o corpo seguem o template upstream e nao contêm marketing ou texto de IA. +- [ ] O tracker esta pronto para receber branch, commit e URL reais. + +## 9. Campos adicionais recomendados no tracker + +O tracker atual deve continuar como fonte principal. Durante a execucao, registrar nas observacoes ou +em uma nota individual: + +- commit/release pesquisado; +- decisao `pr-provider`, `pr-generic`, `pr-docs`, `issue-first`, `config-only`, adapter, wrapper, + MITM ou bloqueio; +- protocolo e regra da base URL; +- comandos de baseline e resultado; +- comandos finais e resultado; +- smoke tests realizados; +- arquivos modificados; +- fork, branch e commit; +- PR/issue e estado de CI/review; +- limitacoes e proximo passo. + +Campos ainda nao comprovados permanecem `—`. + +## 10. Inicio recomendado + +O primeiro ciclo de publicacao deve usar o lote P0.1: + +1. `CLI-001` - Gemini CLI (`google-gemini/gemini-cli`) +2. `CLI-002` - Claw Code (`ultraworkers/claw-code`) +3. `CLI-003` - Plandex (`plandex-ai/plandex`) + +Os tres subagentes fazem pesquisa fresca e implementacao em paralelo, mas nenhuma PR e enviada antes +da revisao individual do agente principal. Ao publicar ou concluir config-only/bloqueio, atualizar o +tracker e liberar os mesmos tres slots para o lote P0.2. + +## Lote P2.10 iniciado em 2026-08-03 + +Base local: `release/v3.8.50` em `84b1e5e12f238269e698f400766230f985f4a07b`. Worktrees isoladas e um agente por upstream foram criadas para `CLI-070` PicoClaw, `CLI-071` IronClaw e `CLI-072` NullClaw. Nenhuma publicação está autorizada; os agentes devem pesquisar o HEAD atual, provar `config-only` ou RED→GREEN e registrar governança, gates, smoke e estado limpo. + +Resultado P2.10: + +- `CLI-070` PicoClaw: `config-only`, `openai/auto` com base `/api/v1`; Chat/SSE/tools/usage/images/discovery. Go ausente impediu execução local; monitorar #3298, sem PR. +- `CLI-071` IronClaw: `config-only`, `openai_compatible` com `/api/v1` e `auto`; 889 testes do crate LLM, 5 de resolução e fmt passaram. Sem PR; reasoning proprietário segue limitado por #3673. +- `CLI-072` NullClaw: `config-only`, provider custom com Chat Completions recomendado e Responses/Anthropic como alternativas. Zig ausente; CI do mesmo HEAD verde. Sem PR. + +Estado final P2.10: commits `0`, pushes `0`, forks `0`, PRs `0`, issues `0`, Discussions `0`. +Pesquisa acumulada: `73/104` (`70,2%`); pendentes: `31/104` (`29,8%`). Próxima fila: P2.11 (`CLI-073` Moltis, `CLI-074` GitClaw, `CLI-075` LionClaw). + +Resultado P3.1: + +- `CLI-076` VibePod: `config-only` pelo agente Claude Code com raiz Anthropic `/api`; wrapper injeta env no container. Codex sem chave automática permanece não comprovado. +- `CLI-077` zeroshot: `config-only` pelo gateway OpenAI `/api/v1`; 22 testes focados verdes; limitações de streaming JSON, reasoning e MCP registradas. +- `CLI-078` Fractal: `config-only` por Codex Responses em `CODEX_HOME` por node; servidores tmux quentes podem perder `OMNIROUTE_API_KEY`, recomendando fix genérico upstream. + +Estado final P3.1: commits `0`, pushes `0`, forks `0`, PRs `0`, issues `0`, Discussions `0`. Pesquisa acumulada: `79/104` (`76,0%`); pendentes: `25/104` (`24,0%`). + +Resultado P3.2: Bernstein `config-only` por openai_agents; Traycer `config-only` indireto pelo harness OpenCode; h5i `patch-required` porque auth proxy/egress são fixados em OpenAI. Nenhuma publicação externa. Pesquisa acumulada `82/104` (`78,8%`), pendentes `22/104` (`21,2%`). + +Resultado P2.11: + +- `CLI-073` Moltis: `config-only`, provider `custom-omniroute`, `/api/v1`, `auto`, Chat/SSE/tools e capacidades multimodais. 401 testes e fmt passaram. Sem publicação. +- `CLI-074` GitClaw/GitAgent: `config-only`, loader OpenAI-compatible com `GITAGENT_MODEL_BASE_URL`, `OPENAI_API_KEY` e `omniroute:auto`. Build, 65 testes e smoke passaram. Sem publicação. +- `CLI-075` LionClaw: `patch-required`/`issue-first`. O runtime Codex confinado não recebe `config.toml`/provider secret; preparar proposta genérica alinhada à [#157](https://github.com/moshthepitt/lionclaw/issues/157), sem PR até revisão do mantenedor. + +Estado final P2.11: commits `0`, pushes `0`, forks `0`, PRs `0`, issues `0`, Discussions `0`. Pesquisa acumulada: `76/104` (`73,1%`); pendentes: `28/104` (`26,9%`). +Resultado P3.3: OMK `viable-mcp`; kodo `config-only` indireto; ORCH `needs-wrapper`. Pesquisa acumulada `85/104` (`81,7%`), pendentes `19/104` (`18,3%`). Nenhuma publicação externa. + +Resultado P3.4: LoopTroop `config-only` indireto via provider OpenCode; Galley `patch-required` por não possuir transport OpenAI-compatible configurável; Relay `config-only` via provider profile/Codex, condicionado a smoke da Responses API e controles sobre ferramentas nativas. Nenhuma publicação externa. Pesquisa acumulada `88/104` (`84,6%`), pendentes `16/104` (`15,4%`). + +Resultado P3.5: SageCLI `config-only` indireto via Codex, com caveat de env plaintext; 5dive `patch-required` por mapas fechados de provider/base; agx `config-only` indireto via Codex e com gates de Responses/sandbox. Pesquisa acumulada `91/104` (`87,5%`), pendentes `13/104` (`12,5%`). Nenhuma publicação externa. + +Resultado P3.6: claude-code-router, cc-router e OneCLI são config-only; os dois primeiros oferecem endpoints custom OpenAI-compatible e OneCLI injeta credenciais por proxy MITM. Pesquisa acumulada `94/104` (`90,4%`), pendentes `10/104` (`9,6%`). Nenhuma publicação externa. + +Resultado P3.7: agent-browser `config-only` direto por Chat Completions; OpenWork `config-only` via OpenCode custom; Agent Deck `config-only` via CLIs filhos. Pesquisa acumulada `97/104` (`93,3%`), pendentes `7/104` (`6,7%`). Nenhuma publicação externa. + +Resultado P4.1: Pool e Junie são `config-only` OpenAI-compatible; Cursor é `config-only` limitado ao BYO chat panel, sem MITM/protocolo privado. Pesquisa acumulada `100/104` (`96,2%`), pendentes `4/104` (`3,8%`). Nenhuma publicação externa. + +Resultado P4.2: Windsurf está bloqueado para inferência e permite apenas MCP; Amp depende de confirmação Enterprise; Amazon Q legado requer patch substancial e Kiro atual é MCP-only seguro. Pesquisa acumulada `103/104` (`99,0%`), pendente `1/104` (`1,0%`). Nenhuma publicação externa. + +Resultado P4.3: Cowork não permite substituir oficialmente a inferência; Custom Connector MCP remoto é o único caminho suportado e permanece separado do modelo. Pesquisa concluída `104/104` (`100%`), pendentes `0/104` (`0%`). Nenhuma publicação externa nesta fase de pesquisa. diff --git a/_references/_sistemas_cli/06-relatorio-final-104-clis-e-estrategia-prs.md b/_references/_sistemas_cli/06-relatorio-final-104-clis-e-estrategia-prs.md new file mode 100644 index 0000000000..e1929db328 --- /dev/null +++ b/_references/_sistemas_cli/06-relatorio-final-104-clis-e-estrategia-prs.md @@ -0,0 +1,131 @@ +# Relatório final — campanha de 104 integrações CLI OmniRoute + +**Data de fechamento:** 2026-08-03 +**Escopo:** `CLI-000` a `CLI-103` +**Resultado:** `104/104` pesquisados (`100%`), `0` pendentes de pesquisa. + +## Como consultar o resultado individual + +O documento autoritativo, com uma linha para cada caso, é o [tracker completo](./04-tracker-integracoes-clis.md). Ele contém para cada ID: + +- prioridade; +- projeto e repositório; +- classificação de integração; +- estado de contribuição upstream; +- branch e commit quando existentes; +- URL de PR e/ou issue quando publicados; +- estado no catálogo OmniRoute; +- observações, limitações, testes e próximo passo. + +Além do tracker, existem fichas técnicas individuais em `_tasks/cli-integrations/`. A cobertura foi auditada e agora há uma ficha para cada ID `CLI-000`–`CLI-103`; o caso `CLI-000` jcode foi adicionado como ficha de referência nesta revisão. + +## Resumo quantitativo + +| Grupo operacional | Quantidade | Tratamento | +|---|---:|---| +| Configuração direta ou indireta | 76 | Documentar receita, validar smoke e só abrir PR se houver melhoria upstream real | +| Contribuição upstream (PR/issue/docs/patch) | 17 | Preparar diff mínimo, validar, revisar e publicar conforme política do repositório | +| Patch obrigatório | 4 | Implementar genericamente, com RED→GREEN/TDD e revisão do mantenedor | +| Bloqueados/fechados | 4 | Registrar bloqueio; usar apenas MCP ou canal oficial, sem MITM | +| MCP/wrapper/ACP como caminho principal | 2 | Integrar a camada de ferramentas/orquestração, sem falsificar provider de inferência | +| Outros casos híbridos | 1 | Seguir a combinação específica descrita no tracker | + +Os números são derivados do campo `Tipo` do tracker; categorias podem se sobrepor em casos híbridos. Atualmente há **7 PRs reais** e **9 issues reais** registrados no tracker, além de cinco entradas locais marcadas como integradas ao catálogo OmniRoute. Nenhum link foi inventado para os 97 casos sem publicação externa. + +## O que foi feito na campanha + +1. Inventário inicial e busca extensa de CLIs, runtimes, harnesses e control-planes. +2. Priorização P0–P4 considerando compatibilidade de protocolo, adoção, licença, maturidade e risco. +3. Pesquisa fresca, uma a uma, em worktrees isoladas, em lotes de no máximo três agentes. +4. Uso de Codebase Memory para índices upstream e verificação de cobertura; faixas parciais foram lidas diretamente quando aplicável. +5. Classificação por configuração, patch, PR documental, issue-first, MCP, wrapper ou bloqueio. +6. Registro de comandos, base URL, autenticação, modelos, streaming, tools, reasoning, imagens, MCP/ACP/A2A, testes e limitações. +7. Consolidação de cada lote com commit separado no OmniRoute e no repositório `_tasks`. +8. Atualização final do tracker, plano de integração, plano de publicação e handoff. +9. Nenhuma credencial real, publicação externa ou técnica de interceptação não autorizada foi utilizada. + +## Estratégia para abrir PRs em 100% dos casos + +“Abrir PR para 100%” deve ser interpretado como **dar um destino upstream apropriado a 100% dos casos**, e não criar 104 PRs artificiais. Há quatro trilhas: + +### Trilha A — PR de código ou documentação + +Aplicar aos casos `viable-upstream`, `pr-generic`, `pr-docs`, `patch-required` e híbridos que tenham superfície pública e política de contribuição compatível. + +Processo por caso: + +1. Reconfirmar HEAD, licença, branch default, política de contribuição e duplicatas. +2. Criar worktree/branch baseada na versão local vigente. +3. Executar baseline upstream e registrar falhas preexistentes. +4. Escrever teste RED que demonstre a lacuna. +5. Implementar o menor patch genérico possível — preferir `openai-compatible`, `base_url` ou provider abstrato a um provider nominal OmniRoute. +6. Executar GREEN: testes focados, suite upstream, lint, format, typecheck/build e smoke com fake server ou OmniRoute local usando placeholder. +7. Revisar segurança: nenhuma chave em argv, logs, fixtures, URL ou artefato; erros sanitizados; streaming/tools/cancelamento cobertos. +8. Abrir PR somente se contribuições externas forem aceitas. O corpo deve explicar problema, solução genérica, compatibilidade, testes, limitações e não conter marketing/texto de IA. +9. Se o repositório bloquear fork/PR ou pedir discussão prévia, abrir issue de proposta com o mesmo patch/reprodução, sem enviar PR prematuramente. +10. Atualizar tracker com branch, commit, URL, CI, revisão e resposta do mantenedor; acompanhar até `accepted`, `merged`, `rejected` ou `awaiting-maintainer`. + +### Trilha B — Issue-first, discussão ou suporte ao mantenedor + +Aplicar quando a arquitetura é adequada, mas há bloqueio de governança, firewall, CLA, fork fechado, dúvida de protocolo ou necessidade de decisão do autor. A issue deve conter: + +- caso de uso OmniRoute; +- configuração atualmente possível; +- lacuna reproduzível; +- proposta genérica; +- impacto de segurança; +- testes/fake server; +- disposição para enviar PR após aprovação. + +Não abrir uma PR paralela enquanto a política exigir issue-first. + +### Trilha C — Config-only documentado + +Aplicar aos casos em que o upstream já suporta a integração e uma mudança de código seria redundante. O entregável é: + +- ficha individual; +- receita validada; +- smoke test e limitações; +- eventual documentação externa/local do OmniRoute; +- issue somente se houver pedido de documentação ou descoberta de bug real. + +Não criar provider nominal ou PR apenas para adicionar a palavra “OmniRoute”. + +### Trilha D — MCP, wrapper ou bloqueio seguro + +Aplicar a control-planes, produtos fechados e CLIs sem rota de inferência substituível. O resultado pode ser: + +- MCP remoto/stdio do OmniRoute; +- wrapper local claramente identificado como wrapper; +- solicitação oficial de custom provider; +- registro de bloqueio e gate legal/ToS. + +Nunca mascarar OmniRoute como Claude/Codex, falsificar executável, interceptar TLS ou reutilizar tokens privados para fabricar uma PR upstream. + +## Ordem recomendada de execução + +1. **Primeiro:** PRs e issues já preparadas ou com alto retorno e baixo risco — jcode, Gemini CLI, Claw Code, Plandex, Trae Agent, Every Code, VT Code e CoreCoder. +2. **Segundo:** patches genéricos com boa superfície OSS — AutoCodeRover, Galley, 5dive e demais casos `pr-generic`/`patch-required`. +3. **Terceiro:** issues aguardando decisão — Open Codex, Kimi CLI, Devon, g3, Free Code, Claude Engineer e casos com `awaiting-maintainer`. +4. **Quarto:** documentação e receitas config-only agrupadas por ecossistema — OpenCode, Codex, LiteLLM, AI SDK, OpenAI-compatible e Anthropic-compatible. +5. **Quinto:** MCP/plugins para produtos fechados — Windsurf, Amp, Kiro, Cowork e Cursor, sempre pela superfície oficial. + +Cada rodada deve manter no máximo três agentes ativos. O agente principal revisa o resultado do trio antes de liberar o próximo. + +## Critério de encerramento por caso + +Um caso só pode ser marcado como finalizado quando possui: pesquisa, classificação, evidência de protocolo, baseline ou limitação reproduzível, receita/patch/bloqueio, validação proporcional, estado de publicação e próximo passo. Para produtos fechados, `blocked-closed` ou `MCP-only` é um resultado válido e preferível a uma PR não autorizada. + +## Estado de publicação atual + +Os únicos links de publicação comprovados devem continuar sendo os registrados no tracker. O fato de existir uma branch local de pesquisa não significa que exista PR upstream. A matriz de verdade é: + +- PR/issue preenchida: publicação real; +- campo `—`: nenhuma publicação externa comprovada; +- `not-applicable`: configuração ou bloqueio sem contribuição upstream; +- `awaiting-maintainer`: contato feito, aguardando decisão; +- `published-pr`/`published-issue`: URL real presente no tracker. + +## Próxima fase + +A pesquisa está encerrada. A próxima fase é execução controlada da Trilha A/B/C/D, começando pelos casos com maior retorno e menor risco, com revisão central antes de qualquer push, PR, issue ou contato externo. diff --git a/bin/cli/commands/doctor.mjs b/bin/cli/commands/doctor.mjs index 087101b50d..f61f9d60c0 100644 --- a/bin/cli/commands/doctor.mjs +++ b/bin/cli/commands/doctor.mjs @@ -299,6 +299,7 @@ async function checkNativeBinary(rootDir) { "Release", "better_sqlite3.node" ), + path.join(rootDir, "dist", "node_modules", "better-sqlite3", "build", "Release", "better_sqlite3.node"), path.join(rootDir, "node_modules", "better-sqlite3", "build", "Release", "better_sqlite3.node"), ]; const binaryPath = candidates.find((candidate) => fs.existsSync(candidate)); diff --git a/bin/cli/commands/launch-codex.mjs b/bin/cli/commands/launch-codex.mjs index f00cae7d2b..88e678c56a 100644 --- a/bin/cli/commands/launch-codex.mjs +++ b/bin/cli/commands/launch-codex.mjs @@ -1,8 +1,37 @@ -import { spawn } from "node:child_process"; +import { spawn, execFileSync } from "node:child_process"; import { t } from "../i18n.mjs"; import { resolveActiveContext } from "../contexts.mjs"; import { quoteShellArgs } from "../utils/winShellArgs.mjs"; +/** + * Probe PATH for a Windows executable via `where.exe`, preferring a `.exe` over + * a `.cmd`/`.bat` shim. Returns the absolute path to the preferred binary, or + * `null` when `where.exe` finds nothing (or cannot run). Mirrors the same probe + * in launch.mjs and `locateCommand()` in `src/shared/services/cliRuntime.ts`. + * + * @param {string} command bare command name to look up + * @returns {Promise} absolute path to the preferred match, or null + */ +function probeWindowsBinary(command) { + try { + const out = execFileSync("where.exe", [command], { + stdio: ["ignore", "pipe", "ignore"], + encoding: "utf8", + timeout: 3000, + windowsHide: true, + }); + const lines = out + .split(/\r?\n/) + .map((l) => l.trim()) + .filter(Boolean); + if (lines.length === 0) return null; + const winExt = /\.(exe|cmd|bat|com)$/i; + return lines.find((l) => winExt.test(l)) || null; + } catch { + return null; + } +} + /** OpenAI/Codex env keys stripped from the child so a stale OpenAI key/base-url * in the shell can't shadow the omniroute provider (defense-in-depth). Mirrors * free-claude-code's codex adapter. NOTE: this does NOT silence codex's @@ -23,11 +52,25 @@ const NO_AUTH_SENTINEL = "omniroute-no-auth"; // On Windows the `codex` binary is an npm `.cmd` shim that `spawn` cannot resolve // without a shell (bare "codex" → ENOENT). Mirror the qodercli Windows fix (#6263): // spawn `codex.cmd` through a shell on win32, and the bare binary elsewhere. -export function resolveCodexSpawn(platform) { - if (platform === "win32") { - return { command: "codex.cmd", shell: true }; +// +// #9454: the native codex installer may ship a real `codex.exe` instead of the +// npm `.cmd` shim. Probe PATH for `codex` first: when `where.exe` resolves a +// `.exe`, spawn it directly (no shell — cmd.exe would split an absolute path +// with spaces); otherwise fall back to `codex.cmd` + shell. Off Windows the bare +// binary is spawned unchanged (no shell, no probe). +/** + * @param {NodeJS.Platform|string} platform + * @param {{ probe?: (command: string) => Promise }} [opts] injectable probe for tests + * @returns {Promise<{ command: string, shell: true|undefined }>} + */ +export async function resolveCodexSpawn(platform, opts = {}) { + if (platform !== "win32") return { command: "codex", shell: undefined }; + const probe = opts.probe ?? probeWindowsBinary; + const located = await probe("codex"); + if (located && /\.exe$/i.test(located)) { + return { command: located, shell: undefined }; } - return { command: "codex", shell: undefined }; + return { command: "codex.cmd", shell: true }; } /** @@ -169,8 +212,9 @@ export async function runLaunchCodexCommand(opts = {}, codexArgs = []) { const extraArgs = [...providerArgs, ...profileArgs, ...codexArgs]; const env = buildCodexEnv(process.env, authToken); + const { command: codexLaunch, shell: shellValue } = await resolveCodexSpawn(process.platform); + return await new Promise((resolve) => { - const { command: codexLaunch, shell: shellValue } = resolveCodexSpawn(process.platform); const child = spawn(codexLaunch, quoteCodexArgs(extraArgs, process.platform), { env, stdio: "inherit", diff --git a/bin/cli/commands/launch.mjs b/bin/cli/commands/launch.mjs index 78016257f1..e1b7aca47d 100644 --- a/bin/cli/commands/launch.mjs +++ b/bin/cli/commands/launch.mjs @@ -1,4 +1,4 @@ -import { spawn } from "node:child_process"; +import { spawn, execFileSync } from "node:child_process"; import { join } from "node:path"; import os from "node:os"; import { t } from "../i18n.mjs"; @@ -92,17 +92,61 @@ export function resolveLaunchTarget(opts = {}) { } /** - * #8246: on Windows, npm installs claude as a `.cmd` shim — spawn() without a - * shell cannot resolve PATHEXT shims (and Node refuses to exec `.cmd` directly - * since CVE-2024-27980), so the Windows path must go through cmd.exe. + * Probe PATH for a Windows executable via `where.exe`, preferring a `.exe` over + * a `.cmd`/`.bat` shim. Returns the absolute path to the preferred binary, or + * `null` when `where.exe` finds nothing (or cannot run). + * + * The native Anthropic installer (#9454) creates only `claude.exe` (no npm + * `.cmd` shim), so the launcher must look for the real PE and spawn it without + * a shell. Mirrors the existing `locateCommand()` probe in + * `src/shared/services/cliRuntime.ts`. + * + * @param {string} command bare command name to look up + * @returns {Promise} absolute path to the preferred match, or null + */ +function probeWindowsBinary(command) { + try { + const out = execFileSync("where.exe", [command], { + stdio: ["ignore", "pipe", "ignore"], + encoding: "utf8", + timeout: 3000, + windowsHide: true, + }); + const lines = out + .split(/\r?\n/) + .map((l) => l.trim()) + .filter(Boolean); + if (lines.length === 0) return null; + const winExt = /\.(exe|cmd|bat|com)$/i; + return lines.find((l) => winExt.test(l)) || null; + } catch { + return null; + } +} + +/** + * #8246 / #9454: on Windows, npm installs claude as a `.cmd` shim — spawn() + * without a shell cannot resolve PATHEXT shims (and Node refuses to exec `.cmd` + * directly since CVE-2024-27980), so the npm-shim path must go through cmd.exe. + * But the native installer creates only `claude.exe`, which is a real PE that + * must NOT go through a shell (cmd.exe would split an absolute path with spaces). + * + * So probe PATH for `claude` first: when `where.exe` resolves a `.exe`, spawn it + * directly (no shell); otherwise fall back to the npm `claude.cmd` + shell. Off + * Windows the bare binary is spawned unchanged (no shell, no probe). * * @param {NodeJS.Platform|string} platform - * @returns {{ command: string, shell: true|undefined }} + * @param {{ probe?: (command: string) => Promise }} [opts] injectable probe for tests + * @returns {Promise<{ command: string, shell: true|undefined }>} */ -export function resolveClaudeSpawn(platform) { - return platform === "win32" - ? { command: "claude.cmd", shell: true } - : { command: "claude", shell: undefined }; +export async function resolveClaudeSpawn(platform, opts = {}) { + if (platform !== "win32") return { command: "claude", shell: undefined }; + const probe = opts.probe ?? probeWindowsBinary; + const located = await probe("claude"); + if (located && /\.exe$/i.test(located)) { + return { command: located, shell: undefined }; + } + return { command: "claude.cmd", shell: true }; } /** @@ -148,8 +192,9 @@ export async function runLaunchCommand(opts = {}, claudeArgs = []) { : undefined; const env = buildClaudeEnv(process.env, baseUrl, authToken, { configDir }); + const { command, shell } = await resolveClaudeSpawn(process.platform); + return await new Promise((resolve) => { - const { command, shell } = resolveClaudeSpawn(process.platform); const child = spawn(command, quoteClaudeArgs(claudeArgs, process.platform), { env, stdio: "inherit", diff --git a/bin/cli/commands/login.mjs b/bin/cli/commands/login.mjs index 506f4e28f9..ef98c9d42d 100644 --- a/bin/cli/commands/login.mjs +++ b/bin/cli/commands/login.mjs @@ -19,6 +19,19 @@ import { randomUUID } from "node:crypto"; * * It talks ONLY to Google (no OmniRoute server needed locally), so it works even * if the remote VPS is firewalled from the user's machine. + * + * Push mode: when an active remote context exists (`omniroute connect `), the + * blob is POSTed straight to that install instead of being printed for a manual + * copy-paste — every piece was already in place: + * + * - the context carries an admin-scoped token, and `apiFetch()` injects it; + * - `/api/oauth` requires admin scope (src/server/authz/accessScopes.ts) and stays + * remote-reachable — routeGuard.ts loopback-gates only `/api/oauth/cursor/auto-import`; + * - `/api/oauth//paste-credentials` already decodes the blob and persists. + * + * The push NEVER becomes a hard requirement: this helper exists precisely because it + * needs no route to the VPS, so a failed push falls back to printing the blob rather + * than losing an authorization the operator just completed in their browser. */ const PROVIDER = "antigravity"; @@ -54,7 +67,7 @@ function defaultStartServer(preferredPort) { res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }); res.end( "OmniRoute" + - "" + + '' + "

✅ Authorization received

" + "

Return to your terminal — you can close this tab.

" ); @@ -73,6 +86,51 @@ function defaultStartServer(preferredPort) { }); } +/** + * Is this context pointing at another machine? Loopback (and an unresolvable value) + * counts as local, so we never auto-push somewhere we cannot reason about. + */ +export function isRemoteBaseUrl(baseUrl) { + if (!baseUrl) return false; + try { + const { hostname } = new URL(baseUrl); + const host = hostname.replace(/^\[|\]$/g, ""); // strip IPv6 brackets + return host !== "localhost" && host !== "127.0.0.1" && host !== "::1"; + } catch { + return false; + } +} + +/** + * POST a credential blob to the active context's install. Never throws: the caller + * decides whether a failure is fatal (it is not — it falls back to printing). + */ +export async function pushCredentialBlob(provider, blob, deps = {}) { + try { + const fetchImpl = deps.fetchImpl ?? (await import("../api.mjs")).apiFetch; + const res = await fetchImpl(`/api/oauth/${provider}/paste-credentials`, { + method: "POST", + body: { blob }, + }); + const data = await res.json().catch(() => ({})); + if (!res.ok || data?.success === false) { + const message = + (typeof data?.error === "string" ? data.error : data?.error?.message) || + `HTTP ${res.status}`; + return { ok: false, error: message }; + } + return { ok: true, connectionId: data?.connection?.id }; + } catch (err) { + return { ok: false, error: err?.message || String(err) }; + } +} + +/** Read the active CLI context (baseUrl + scoped token) written by `omniroute connect`. */ +async function defaultResolveContext(overrideName) { + const { resolveActiveContext } = await import("../contexts.mjs"); + return resolveActiveContext(overrideName); +} + /** Lazy-load the antigravity provider + blob codec (TS source via tsx). */ async function loadDeps() { const { antigravity } = await import("../../../src/lib/oauth/providers/antigravity.ts"); @@ -153,10 +211,41 @@ export async function runAntigravityLogin(opts = {}, deps = {}) { const tokens = await exchange(params.code, redirectUri); const blob = encodeCredentialBlob({ provider: PROVIDER, tokens }); + // Push when the operator explicitly asked, or when the active context already points + // at another machine — that is exactly the situation this helper was built for. + const resolveContext = deps.resolveContext ?? defaultResolveContext; + const push = deps.push ?? pushCredentialBlob; + let context = null; + try { + context = await resolveContext(opts.context); + } catch { + // No usable context store — fall through to printing. + } + const wantsPush = + opts.push === true || (opts.push !== false && isRemoteBaseUrl(context?.baseUrl)); + + if (wantsPush) { + log(`\nSending the credential to ${context?.baseUrl || "the active context"}...\n`); + const result = await push(PROVIDER, blob, { context }); + if (result?.ok) { + log( + `Antigravity connected on ${context?.baseUrl || "the remote install"}` + + `${result.connectionId ? ` (connection ${result.connectionId})` : ""}.\n` + + "Nothing to paste — you can close this terminal.\n" + ); + // Deliberately NOT printed: the blob wraps a refresh token and it already landed. + return blob; + } + log( + `\nCould not deliver the credential automatically: ${result?.error || "unknown error"}\n` + + "Falling back to manual paste — the authorization itself is still valid.\n" + ); + } + print( "\n" + "Antigravity authorized. Copy the line below and paste it into your remote\n" + - "OmniRoute dashboard: Providers → Antigravity → Connect → \"Paste credentials\".\n" + + 'OmniRoute dashboard: Providers → Antigravity → Connect → "Paste credentials".\n' + "(This contains a refresh token — treat it like a password.)\n\n" + blob + "\n\n" @@ -170,6 +259,8 @@ async function runLoginAntigravity(opts) { browser: opts.browser, timeout: opts.timeout, port: opts.port, + push: opts.push, + context: opts.context, }); } catch (err) { process.stderr.write(`\nLogin failed: ${err?.message || err}\n`); @@ -188,5 +279,11 @@ export function registerLogin(program) { .option("--no-browser", "Do not auto-open the browser; print the URL instead") .option("--port ", "Fixed loopback port (default: OS-assigned)", (v) => parseInt(v, 10)) .option("--timeout ", "How long to wait for the callback", (v) => parseInt(v, 10), 300000) + .option( + "--push", + "Send the credential to the active context instead of printing it (default when that context is remote)" + ) + .option("--no-push", "Always print the blob, never contact the server") + .option("--context ", "Push to this context instead of the active one") .action(runLoginAntigravity); } diff --git a/bin/cli/commands/oauth.mjs b/bin/cli/commands/oauth.mjs index 9bcbc92d6c..d1d2fd3b40 100644 --- a/bin/cli/commands/oauth.mjs +++ b/bin/cli/commands/oauth.mjs @@ -10,11 +10,28 @@ const PROVIDERS_WITH_OAUTH = [ { id: "cursor", name: "Cursor", flow: "import" }, { id: "zed", name: "Zed", flow: "import" }, { id: "kiro", name: "Amazon Kiro", flow: "social" }, - { id: "claude-code", name: "Claude Code (OAuth)", flow: "device" }, + { id: "claude-code", name: "Claude Code (OAuth)", flow: "browser" }, { id: "codex", name: "OpenAI Codex (OAuth)", flow: "device" }, { id: "copilot", name: "GitHub Copilot", flow: "device" }, ]; +// The user-facing provider id (the one shown by `omniroute oauth providers`) +// is NOT always the backend OAuth provider key the server's /api/oauth/[provider]/... +// route expects. `claude-code` is the CLI-facing alias for Anthropic's Claude +// OAuth, which the server registers under the key `claude` (see +// src/lib/oauth/providers/index.ts). Routing `claude-code` to the unrelated +// `command-code` (CommandCode.ai) provider — as the previous code did — sent +// the device-flow request to /api/providers/command-code/auth/start, which is +// gated by requireManagementAuth and returned 401 for a fresh CLI context +// (issue #9474). Map the alias to the real backend key instead. +const BACKEND_OAUTH_KEY = { + "claude-code": "claude", +}; + +function resolveBackendKey(id) { + return BACKEND_OAUTH_KEY[id] ?? id; +} + const oauthProviderSchema = [ { key: "id", header: "Provider ID", width: 16 }, { key: "name", header: "Name", width: 28 }, @@ -56,34 +73,111 @@ async function pollStatus(endpoint, timeoutMs) { } async function runBrowserFlow(def, opts) { - const startRes = await apiFetch(`/api/oauth/${def.id}/start`, { method: "POST" }); + // The user-facing id (`def.id`, e.g. "claude-code") must be translated to the + // backend OAuth provider key the server's /api/oauth/[provider]/... route + // expects (e.g. "claude"). The previous implementation called a non-existent + // `/api/oauth/${def.id}/start` action — no such action exists on the server + // (src/app/api/oauth/[provider]/[action]/route.ts), so the browser flow was + // broken for every browser-flow provider. Use the real `authorize` action and + // complete the PKCE (authorization_code / authorization_code_pkce) flow with a + // manual code paste, mirroring the dashboard's manual "input" step. + const backendKey = resolveBackendKey(def.id); + const redirectUri = opts.redirectUri ?? null; + const authorizeUrl = `/api/oauth/${backendKey}/authorize${ + redirectUri ? `?redirect_uri=${encodeURIComponent(redirectUri)}` : "" + }`; + const startRes = await apiFetch(authorizeUrl, { method: "GET" }); if (!startRes.ok) { - process.stderr.write(`Failed to start OAuth for ${def.id}: ${startRes.status}\n`); + const detail = await safeErrorBody(startRes); + process.stderr.write(`Failed to start OAuth for ${def.id}: ${startRes.status}${detail}\n`); process.exit(1); } const start = await startRes.json(); - const url = start.authorizeUrl ?? start.url; + const url = start.authUrl ?? start.authorizeUrl ?? start.url; + if (!url) { + const hint = start.error ?? "no authUrl returned by the server"; + process.stderr.write(`OAuth unavailable for ${def.id}: ${hint}\n`); + process.exit(1); + } + const { codeVerifier, state, redirectUri: returnedRedirectUri } = start; + const finalRedirectUri = returnedRedirectUri || redirectUri; - if (process.stdout.isTTY && opts.browser !== false) { - const { startOAuthTui } = await import("../tui/OAuthFlow.jsx"); - await openBrowser(url); - const tuiResult = await startOAuthTui({ provider: def.name ?? def.id, url }); - if (tuiResult.status === "cancelled") return; - } else { - process.stdout.write(`\nOpen this URL to authorize:\n ${url}\n\n`); - if (opts.browser !== false) await openBrowser(url); - process.stderr.write("Waiting for authorization... (Ctrl+C to cancel)\n"); + process.stdout.write(`\nOpen this URL to authorize:\n ${url}\n\n`); + if (opts.browser !== false) await openBrowser(url); + process.stdout.write( + "After authorizing, paste the callback URL (or the Authentication Code\n" + + "shown on the confirmation page) here:\n" + ); + + const { createPrompt } = await import("../io.mjs"); + const prompt = createPrompt(); + const input = await prompt.ask("Callback URL or code"); + prompt.close(); + + const trimmed = input.trim(); + if (!trimmed) { + process.stderr.write("No authorization code provided.\n"); + process.exit(1); } - const result = await pollStatus( - `/api/oauth/${def.id}/status?state=${encodeURIComponent(start.state ?? "")}`, - opts.timeout ?? 300000 - ); + // The Anthropic Claude confirmation page (platform.claude.com/oauth/code/callback) + // shows a raw "Authentication Code" like `code#state` rather than a full URL. + // The dashboard's manual submit (src/shared/components/OAuthModal.tsx) parses + // both forms; mirror that here. + let code = null; + let codeState = state || null; + try { + const cbUrl = new URL(trimmed); + code = cbUrl.searchParams.get("code"); + const stateParam = cbUrl.searchParams.get("state") || cbUrl.hash.replace(/^#/, ""); + if (stateParam) codeState = stateParam; + } catch { + const [rawCode, rawState] = trimmed.split("#", 2); + code = rawCode || null; + if (rawState) codeState = rawState; + } + if (!code) { + process.stderr.write( + "No authorization code found. Paste the callback URL or the Authentication Code.\n" + ); + process.exit(1); + } + + const exchangeRes = await apiFetch(`/api/oauth/${backendKey}/exchange`, { + method: "POST", + body: { + code, + redirectUri: finalRedirectUri, + codeVerifier, + ...(codeState ? { state: codeState } : {}), + }, + }); + if (!exchangeRes.ok) { + const detail = await safeErrorBody(exchangeRes); + process.stderr.write(`Token exchange failed: ${exchangeRes.status}${detail}\n`); + process.exit(1); + } + const result = await exchangeRes.json(); + const conn = result.connection ?? {}; process.stdout.write( - `Authorized: ${result.email ?? result.userId ?? result.account ?? "connected"}\n` + `Authorized: ${conn.email ?? conn.displayName ?? conn.id ?? "connected"}\n` ); } +async function safeErrorBody(res) { + try { + const data = await res.json(); + if (data?.error) { + const msg = typeof data.error === "string" ? data.error : data.error?.message; + if (msg) return `: ${msg}`; + } + if (data?.message) return `: ${data.message}`; + } catch { + /* ignore */ + } + return ""; +} + async function runImportFlow(def, opts) { const endpoint = opts.importFromSystem ? `/api/oauth/${def.id}/auto-import` @@ -124,7 +218,7 @@ async function runSocialFlow(def, opts) { } async function runDeviceFlow(def, opts) { - const providerKey = def.id === "claude-code" ? "command-code" : def.id; + const providerKey = resolveBackendKey(def.id); const startRes = await apiFetch(`/api/providers/${providerKey}/auth/start`, { method: "POST" }); if (!startRes.ok) { process.stderr.write(`Failed to start device flow: ${startRes.status}\n`); diff --git a/bin/cli/commands/redis.mjs b/bin/cli/commands/redis.mjs index e841abf00b..dd593d9628 100644 --- a/bin/cli/commands/redis.mjs +++ b/bin/cli/commands/redis.mjs @@ -10,9 +10,25 @@ const DEFAULT_IMAGE = "docker.io/redis:7-alpine"; const DEFAULT_NAME = "omniroute-redis"; const DEFAULT_PORT = "6379"; const DEFAULT_VOLUME = "omniroute-redis-data"; +// The launcher starts Redis without AUTH unless --password is given, so the +// published port stays on loopback. `-p 6379:6379` would bind 0.0.0.0 and hand +// the whole LAN an unauthenticated Redis. +const DEFAULT_BIND = "127.0.0.1"; const RUNTIME_PREFERENCE = ["podman", "docker"]; +/** + * Build the `-p` publish spec for the Redis container. + * Always host-qualified so the runtime never falls back to 0.0.0.0. + */ +export function buildRedisPublishSpec(bind = DEFAULT_BIND, port = DEFAULT_PORT) { + const host = String(bind || DEFAULT_BIND).trim() || DEFAULT_BIND; + const hostPort = String(port || DEFAULT_PORT).trim() || DEFAULT_PORT; + // Bracket IPv6 literals (e.g. ::1) so `host:port:port` stays unambiguous. + const normalizedHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host; + return `${normalizedHost}:${hostPort}:6379`; +} + async function detectRuntime() { for (const candidate of RUNTIME_PREFERENCE) { try { @@ -27,7 +43,14 @@ async function detectRuntime() { async function containerExists(runtime, name) { try { - const { stdout } = await execFile(runtime, ["ps", "-a", "--filter", `name=^${name}$`, "--format", "{{.Names}}"]); + const { stdout } = await execFile(runtime, [ + "ps", + "-a", + "--filter", + `name=^${name}$`, + "--format", + "{{.Names}}", + ]); return stdout.trim() === name; } catch { return false; @@ -36,7 +59,13 @@ async function containerExists(runtime, name) { async function containerRunning(runtime, name) { try { - const { stdout } = await execFile(runtime, ["ps", "--filter", `name=^${name}$`, "--format", "{{.Names}}"]); + const { stdout } = await execFile(runtime, [ + "ps", + "--filter", + `name=^${name}$`, + "--format", + "{{.Names}}", + ]); return stdout.trim() === name; } catch { return false; @@ -100,6 +129,11 @@ export function registerRedis(program) { .command("up") .description("Start the local Redis container") .option("-p, --port ", "Host port to expose", DEFAULT_PORT) + .option( + "-b, --bind ", + "Host interface to publish on (use 0.0.0.0 only together with --password)", + DEFAULT_BIND + ) .option("-n, --name ", "Container name", DEFAULT_NAME) .option("-i, --image ", "Container image", DEFAULT_IMAGE) .option("--no-pull", "Skip pulling the image if it is missing") @@ -160,6 +194,7 @@ export async function runRedisUpCommand(opts = {}) { const name = opts.name || DEFAULT_NAME; const port = opts.port || DEFAULT_PORT; + const bind = opts.bind || DEFAULT_BIND; const image = opts.image || DEFAULT_IMAGE; const exists = await containerExists(runtime, name); @@ -186,7 +221,11 @@ export async function runRedisUpCommand(opts = {}) { info(`Checking if image '${image}' is present locally…`); let present = false; try { - const { stdout } = await execFile(runtime, ["images", "--format", "{{.Repository}}:{{.Tag}}"]); + const { stdout } = await execFile(runtime, [ + "images", + "--format", + "{{.Repository}}:{{.Tag}}", + ]); present = stdout.split("\n").some((line) => line.trim() === image); } catch { // ignore — fall through to pull @@ -205,10 +244,14 @@ export async function runRedisUpCommand(opts = {}) { const args = [ "run", "-d", - "--name", name, - "--restart", "unless-stopped", - "-p", `${port}:6379`, - "-v", `${DEFAULT_VOLUME}:/data`, + "--name", + name, + "--restart", + "unless-stopped", + "-p", + buildRedisPublishSpec(bind, port), + "-v", + `${DEFAULT_VOLUME}:/data`, ]; if (opts.password) { args.push("-e", `REDIS_PASSWORD=${opts.password}`); @@ -219,8 +262,13 @@ export async function runRedisUpCommand(opts = {}) { info(`Launching ${runtime} run ${args.join(" ")}`); try { await execFile(runtime, args); - success(`Container '${name}' is now running on redis://127.0.0.1:${port}`); - info(`Set OMNIROUTE_REDIS_URL=redis://127.0.0.1:${port} in your .env to wire OmniRoute to it.`); + success(`Container '${name}' is now running on redis://${bind}:${port}`); + info(`Set OMNIROUTE_REDIS_URL=redis://${bind}:${port} in your .env to wire OmniRoute to it.`); + if (bind !== DEFAULT_BIND && !opts.password) { + info( + `Warning: '${bind}' publishes Redis beyond loopback without AUTH. Re-run with --password .` + ); + } return 0; } catch (err) { fail(`Failed to launch container: ${err.message}`); @@ -267,7 +315,13 @@ export async function runRedisStatusCommand(opts = {}) { const exists = await containerExists(runtime, name); if (!exists) { - console.log(JSON.stringify({ runtime, name, port, exists: false, running: false, reachable: false }, null, 2)); + console.log( + JSON.stringify( + { runtime, name, port, exists: false, running: false, reachable: false }, + null, + 2 + ) + ); return 0; } @@ -285,10 +339,12 @@ export async function runRedisStatusCommand(opts = {}) { console.log(` Running: ${running ? "yes" : "no"}`); console.log(` Reachable: ${reachable ? "yes" : "no"} (port ${port})`); if (running && !reachable) { - warn("Container is running but the port is not reachable. Is REDIS_PASSWORD set or another process bound?"); + warn( + "Container is running but the port is not reachable. Is REDIS_PASSWORD set or another process bound?" + ); } if (!running) { info(`Run 'omniroute redis up' to launch it.`); } return 0; -} \ No newline at end of file +} diff --git a/bin/cli/commands/runtime.mjs b/bin/cli/commands/runtime.mjs index ffd8c0dac0..ed41bca352 100644 --- a/bin/cli/commands/runtime.mjs +++ b/bin/cli/commands/runtime.mjs @@ -34,7 +34,14 @@ async function runRepairAction(opts, cmd) { if (ok) { process.stdout.write("✓ better-sqlite3 repaired OK\n"); } else { - process.stderr.write("✗ Repair failed — check npm availability\n"); + process.stderr.write("✗ Repair failed\n"); + process.stderr.write( + " Possible causes:\n" + + " • npm not available — check that Node.js/npm are on your PATH\n" + + " • npm install scripts are blocked — run: npm install-scripts approve better-sqlite3\n" + + " • Network issue — check your internet connection\n" + + " Try: npm install-scripts ls (to see if better-sqlite3 is blocked)\n" + ); process.exit(1); } } diff --git a/bin/cli/commands/serve.mjs b/bin/cli/commands/serve.mjs index 8e819895d6..4ed5ac55cf 100644 --- a/bin/cli/commands/serve.mjs +++ b/bin/cli/commands/serve.mjs @@ -16,7 +16,7 @@ import { resolveMaxOldSpaceMb, calibrateHeapFallbackMb, buildServerNodeOptions, - buildNodeHeapArgs, + buildNodeRuntimeArgs, } from "../../../scripts/build/runtime-env.mjs"; import { resolveTlsOptions } from "../../../scripts/dev/tls-options.mjs"; @@ -269,7 +269,7 @@ function runDaemon(serverJs, env, memoryLimit, dashboardPort, apiPort) { // heap via NODE_OPTIONS (a CLI arg would shadow/override their value). const server = spawn( process.versions.bun ? process.execPath : "node", - [...(process.versions.bun ? [] : buildNodeHeapArgs(process.env, memoryLimit)), serverJs], + process.versions.bun ? [serverJs] : buildNodeRuntimeArgs(process.env, memoryLimit, serverJs), { cwd: APP_DIR, env, @@ -289,7 +289,7 @@ function runWithoutRecovery(serverJs, env, memoryLimit, dashboardPort, apiPort, // heap via NODE_OPTIONS (a CLI arg would shadow/override their value). const server = spawn( process.versions.bun ? process.execPath : "node", - [...(process.versions.bun ? [] : buildNodeHeapArgs(process.env, memoryLimit)), serverJs], + process.versions.bun ? [serverJs] : buildNodeRuntimeArgs(process.env, memoryLimit, serverJs), { cwd: APP_DIR, env, @@ -387,12 +387,19 @@ async function runWithSupervisor( supervisor.start(); + // #9455: persist the supervisor's own PID so `omniroute stop` can SIGTERM it + // before the child — the supervisor's SIGTERM handler sets isShuttingDown=true, + // kills the child, and exits cleanly, so the child is never respawned after stop. + writePidFile("supervisor", process.pid); + process.on("SIGINT", () => { killTrayIfActive(); + cleanupPidFile("supervisor"); supervisor.stop(); }); process.on("SIGTERM", () => { killTrayIfActive(); + cleanupPidFile("supervisor"); supervisor.stop(); }); diff --git a/bin/cli/commands/setup-claude.mjs b/bin/cli/commands/setup-claude.mjs index fbb95d5ff8..6ccc668257 100644 --- a/bin/cli/commands/setup-claude.mjs +++ b/bin/cli/commands/setup-claude.mjs @@ -156,7 +156,16 @@ export async function runSetupClaudeCommand(opts = {}) { headers, signal: AbortSignal.timeout(10000), }); - if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`); + if (!res.ok) { + let detail = `HTTP ${res.status}`; + try { + const errorBody = await res.json(); + const serverMsg = + errorBody?.error?.message || errorBody?.error || errorBody?.message || ""; + if (serverMsg) detail += ` — ${serverMsg}`; + } catch {} + throw new Error(detail); + } const body = await res.json(); models = body.data ?? body.models ?? []; } catch (err) { diff --git a/bin/cli/commands/stop.mjs b/bin/cli/commands/stop.mjs index b3dbf64b40..8eb989d18c 100644 --- a/bin/cli/commands/stop.mjs +++ b/bin/cli/commands/stop.mjs @@ -24,18 +24,35 @@ export function registerStop(program) { export async function runStopCommand(opts = {}) { const pid = readPidFile("server"); + // #9455: when the server was started with a supervisor (the default), killing only + // the child lets the supervisor respawn it immediately. The supervisor's PID is + // persisted separately by serve.mjs; SIGTERM it FIRST so its handler sets + // isShuttingDown=true and stops the child cleanly without respawning. + const supervisorPid = readPidFile("supervisor"); if (pid && isPidRunning(pid)) { console.log(t("stop.stopping", { pid })); try { + if (supervisorPid && isPidRunning(supervisorPid)) { + try { + process.kill(supervisorPid, "SIGTERM"); + } catch {} + // Give the supervisor a moment to cascade the shutdown to its child so we + // don't race the child kill against the supervisor's own child stop. + await sleep(300); + } + // #8045: on win32, process.kill(pid, "SIGTERM") unconditionally force-terminates // the target instead of delivering an interceptable signal, racing (and beating) // the server's own async graceful shutdown / WAL checkpoint. stopProcessGracefully // skips the immediate SIGTERM on win32 and just polls before escalating to SIGKILL. - await stopProcessGracefully({ pid, timeoutMs: 5000, isPidRunning, sleep }); + if (isPidRunning(pid)) { + await stopProcessGracefully({ pid, timeoutMs: 5000, isPidRunning, sleep }); + } killAllSubprocesses(); cleanupPidFile("server"); + cleanupPidFile("supervisor"); console.log(t("stop.stopped")); return 0; } catch (err) { @@ -49,10 +66,24 @@ export async function runStopCommand(opts = {}) { const port = opts.port ? parseInt(String(opts.port), 10) : 20128; if (pid === null) { console.log(t("stop.portFallback")); - await killByPort(port); + // #9455: a stale supervisor PID file would let the port-fallback stop also + // leave the supervisor running and respawning. Stop it first. + if (supervisorPid && isPidRunning(supervisorPid)) { + try { + process.kill(supervisorPid, "SIGTERM"); + } catch {} + } + const portFreed = await killByPort(port); killAllSubprocesses(); cleanupPidFile("server"); - console.log(t("stop.stopped")); + cleanupPidFile("supervisor"); + // #9455: only report success when the port is actually free — previously stop + // printed "Server stopped." even when killByPort was a no-op (win32). + if (portFreed) { + console.log(t("stop.stopped")); + } else { + console.log(t("stop.notRunning")); + } return 0; } @@ -60,31 +91,84 @@ export async function runStopCommand(opts = {}) { return 0; } -async function killByPort(port) { - if (process.platform === "win32") return; +/** + * Kill the process listening on `port`. Returns true once the port is free + * (or no listener was found), false if it could not be freed. + * + * #9455: previously this was a no-op on win32 (`if (win32) return;`) yet the + * caller still reported "Server stopped." — a lie. The win32 branch now uses + * `netstat -ano` to find LISTENING PIDs and `process.kill()` (SIGTERM then + * SIGKILL), mirroring the POSIX `lsof` path. + */ +export async function killByPort(port, deps = {}) { + const exec = deps.execFileAsync || execFileAsync; + const kill = deps.processKill || ((p, sig) => process.kill(p, sig)); + const running = deps.isPidRunning || isPidRunning; + const wait = deps.sleep || sleep; + const platform = deps.platform || process.platform; + + if (platform === "win32") { + return killByPortWin32(port, { exec, kill, running, wait }); + } + return killByPortPosix(port, { exec, kill, running, wait }); +} + +async function killByPortPosix(port, { exec, kill, running, wait }) { + let pids = []; try { - const { stdout } = await execFileAsync("lsof", ["-ti", `:${port}`]); - const pids = stdout + const { stdout } = await exec("lsof", ["-ti", `:${port}`]); + pids = stdout .trim() .split("\n") .map((p) => parseInt(p, 10)) .filter((p) => Number.isFinite(p) && p > 0); - - for (const p of pids) { - try { - process.kill(p, "SIGTERM"); - } catch {} - } - - if (pids.length > 0) { - await sleep(1000); - for (const p of pids) { - try { - if (isPidRunning(p)) process.kill(p, "SIGKILL"); - } catch {} - } - } } catch { // lsof not available or no process on port } + return terminatePids(pids, { kill, running, wait }); +} + +async function killByPortWin32(port, { exec, kill, running, wait }) { + let pids = []; + try { + const { stdout } = await exec("netstat", ["-ano"]); + pids = parseNetstatPids(stdout, port); + } catch { + // netstat not available or empty + } + return terminatePids(pids, { kill, running, wait }); +} + +function parseNetstatPids(stdout, port) { + const portCol = `:${port}`; + const pids = []; + for (const line of stdout.split(/\r?\n/)) { + const cols = line.trim().split(/\s+/); + // Expected columns: Proto LocalAddress ForeignAddress State PID + if (cols.length < 5) continue; + if (cols[0] !== "TCP" && cols[0] !== "TCPv6") continue; + const local = cols[1] || ""; + if (!local.endsWith(portCol)) continue; + if ((cols[cols.length - 2] || "").toUpperCase() !== "LISTENING") continue; + const pid = parseInt(cols[cols.length - 1], 10); + if (Number.isFinite(pid) && pid > 0 && !pids.includes(pid)) pids.push(pid); + } + return pids; +} + +async function terminatePids(pids, { kill, running, wait }) { + if (pids.length === 0) return true; + for (const p of pids) { + try { + kill(p, "SIGTERM"); + } catch {} + } + await wait(1000); + for (const p of pids) { + try { + if (running(p)) kill(p, "SIGKILL"); + } catch {} + } + // Confirm the port is free: any PID still alive means we failed. + return pids.every((p) => !running(p)); } diff --git a/bin/cli/commands/update.mjs b/bin/cli/commands/update.mjs index 443f9a498b..75f829107d 100644 --- a/bin/cli/commands/update.mjs +++ b/bin/cli/commands/update.mjs @@ -181,6 +181,26 @@ export async function runUpdateCommand(opts = {}) { // --include=optional keeps the optionalDependencies (better-sqlite3, keytar, // tls-client, llmlingua SLM stack) on update so an omit=optional config can't drop them. execSync("npm install -g omniroute@latest --include=optional", { stdio: "inherit" }); + // Trust-but-verify: `npm install -g` exits 0 even when a shadowing local install + // (e.g. ~/node_modules/omniroute ahead of the global prefix on PATH) means the + // binary the user actually runs was not touched. Re-read the running binary's + // version and warn instead of lying about success (#9475). + const afterVersion = await getCurrentVersion(); + if (afterVersion && compareVersions(afterVersion, latest) < 0) { + printError( + `Global install updated to ${latest}, but the running binary still reports ${afterVersion}.`, + ); + console.log( + " A local `node_modules/omniroute` is likely shadowing the global install on PATH.", + ); + console.log(" Diagnose with:"); + console.log(" which -a omniroute"); + console.log(" command -v omniroute"); + console.log(" npm prefix -g"); + console.log(" Then remove the shadowing local copy (e.g. `npm uninstall omniroute` from its directory)"); + console.log(" or reorder PATH so the global bin comes first."); + return 1; + } printSuccess(`Updated to version ${latest}`); printInfo("Run `omniroute --version` to verify."); return 0; diff --git a/bin/cli/runtime/nativeDeps.mjs b/bin/cli/runtime/nativeDeps.mjs index 1dc442270e..bd053384f9 100644 --- a/bin/cli/runtime/nativeDeps.mjs +++ b/bin/cli/runtime/nativeDeps.mjs @@ -152,9 +152,18 @@ export function ensureBetterSqliteRuntime({ silent = false, force = false } = {} if (!silent) process.stdout.write("[omniroute][runtime] better-sqlite3 OK\n"); return { betterSqlite: true }; } + if (!silent) { + process.stdout.write( + `[omniroute][runtime] Installing better-sqlite3@${BETTER_SQLITE3_VERSION} into runtime...\n` + ); + } const ok = npmInstallRuntime([`better-sqlite3@${BETTER_SQLITE3_VERSION}`], { silent }); if (!ok && !silent) { - process.stderr.write("[omniroute][runtime] better-sqlite3 install failed\n"); + process.stderr.write( + "[omniroute][runtime] better-sqlite3 install failed.\n" + + " This usually means npm install scripts are blocked.\n" + + " Try: npm install-scripts approve better-sqlite3\n" + ); } return { betterSqlite: ok && hasModule("better-sqlite3") && isBetterSqliteBinaryValid() }; } diff --git a/bin/cli/runtime/processSupervisor.mjs b/bin/cli/runtime/processSupervisor.mjs index 3c79bd213c..7277f9de67 100644 --- a/bin/cli/runtime/processSupervisor.mjs +++ b/bin/cli/runtime/processSupervisor.mjs @@ -8,7 +8,7 @@ import { computeRestartDelayMs, waitUntilPortFree, } from "./supervisorPolicy.mjs"; -import { buildNodeHeapArgs } from "../../../scripts/build/runtime-env.mjs"; +import { buildNodeRuntimeArgs } from "../../../scripts/build/runtime-env.mjs"; import { stopProcessGracefully } from "../../../src/shared/platform/windowsProcess.ts"; import { isFatalInstrumentationHookFailure, @@ -47,7 +47,6 @@ export class ServerSupervisor { // #5238: skip the explicit CLI --max-old-space-size when the user pinned the // heap via NODE_OPTIONS (a CLI arg would shadow/override their value). The // calibrated heap is already carried by env.NODE_OPTIONS either way. - const heapArgs = buildNodeHeapArgs(process.env, this.memoryLimit); // #6321: stdout used to be discarded (`"ignore"`) whenever `--log`/OMNIROUTE_SHOW_LOG // wasn't set (the default) — any debug/pino output written to stdout vanished // silently, so a boot that never becomes ready looked like a dead hang with zero @@ -55,7 +54,9 @@ export class ServerSupervisor { // stderr so a readiness timeout can surface what the child actually printed. this.child = spawn( process.versions.bun ? process.execPath : "node", - [...(process.versions.bun ? [] : heapArgs), this.serverPath], + process.versions.bun + ? [this.serverPath] + : buildNodeRuntimeArgs(process.env, this.memoryLimit, this.serverPath), { cwd: dirname(this.serverPath), env: this.env, diff --git a/bin/cli/utils/pid.mjs b/bin/cli/utils/pid.mjs index 1149c67251..ddbbc211a8 100644 --- a/bin/cli/utils/pid.mjs +++ b/bin/cli/utils/pid.mjs @@ -2,7 +2,9 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from " import { join } from "node:path"; import { resolveDataDir } from "../data-dir.mjs"; -const SERVICES = ["server", "mitm", "tunnel/cloudflared", "tunnel/tailscale"]; +// #9455: "supervisor" must be tracked so killAllSubprocesses() can stop the +// supervisor process, not just the child server it spawned (and respawns). +const SERVICES = ["server", "supervisor", "mitm", "tunnel/cloudflared", "tunnel/tailscale"]; function getServicePidPath(service) { return join(resolveDataDir(), service, ".pid"); diff --git a/changelog.d/features/8862-novita-model-catalog.md b/changelog.d/features/8862-novita-model-catalog.md new file mode 100644 index 0000000000..e510b079de --- /dev/null +++ b/changelog.d/features/8862-novita-model-catalog.md @@ -0,0 +1 @@ +- **Providers**: expands the Novita AI catalog from a single Llama 3.1 8B entry to 19 curated serving models (DeepSeek V4, Kimi K3, GLM 5.2, MiniMax M3, Qwen3.7 Max, Qwen3 Coder 480B, MiMo V2.5 Pro, gpt-oss-120b, Gemma 4 31B and more), each carrying its real context window, output cap and reasoning flag from the live `/openai/v1/models` listing, and each vision flag confirmed by an actual image request rather than the listing's self-reported modalities diff --git a/changelog.d/features/8870-node-sqlite-adapter-parity.md b/changelog.d/features/8870-node-sqlite-adapter-parity.md new file mode 100644 index 0000000000..b912939d2e --- /dev/null +++ b/changelog.d/features/8870-node-sqlite-adapter-parity.md @@ -0,0 +1 @@ +- **Database**: The `node:sqlite` fallback now uses SQLite's native backup API and real immediate write transactions, improving backup consistency and concurrent-write behavior when `better-sqlite3` is unavailable diff --git a/changelog.d/features/8908-model-token-limit-overrides.md b/changelog.d/features/8908-model-token-limit-overrides.md new file mode 100644 index 0000000000..8d32a9e1f0 --- /dev/null +++ b/changelog.d/features/8908-model-token-limit-overrides.md @@ -0,0 +1 @@ +- **feat(models):** add exact per-model `context_length`, `max_input_tokens`, and `max_output_tokens` overrides across model discovery and runtime enforcement, with automatic migration from the retired output-only `max_token` key ([#8908](https://github.com/diegosouzapw/OmniRoute/pull/8908)) — thanks @xz-dev diff --git a/changelog.d/features/8964-xai-agent-tools-passthrough.md b/changelog.d/features/8964-xai-agent-tools-passthrough.md new file mode 100644 index 0000000000..62536adb43 --- /dev/null +++ b/changelog.d/features/8964-xai-agent-tools-passthrough.md @@ -0,0 +1 @@ +- **feat(providers):** native xAI Agent Tools passthrough on `/v1/responses` for `xai` / `xai-oauth` (`xao`) — forward `web_search` + `x_search` to `api.x.ai` instead of rewriting or rejecting them ([#8964](https://github.com/diegosouzapw/OmniRoute/issues/8964)) diff --git a/changelog.d/features/8978-unorouter.md b/changelog.d/features/8978-unorouter.md new file mode 100644 index 0000000000..5a4e34839f --- /dev/null +++ b/changelog.d/features/8978-unorouter.md @@ -0,0 +1 @@ +- **feat(providers): add UnoRouter provider** — UnoRouter is an OpenAI-compatible routing gateway supporting hundreds of models. It is now registered as an API-key provider. ([#8978](https://github.com/diegosouzapw/OmniRoute/issues/8978)) diff --git a/changelog.d/features/9208-codex-parenthesized-reasoning.md b/changelog.d/features/9208-codex-parenthesized-reasoning.md new file mode 100644 index 0000000000..3eb2d97e26 --- /dev/null +++ b/changelog.d/features/9208-codex-parenthesized-reasoning.md @@ -0,0 +1 @@ +- **feat(codex):** accept parenthesized GPT-5.6 reasoning overrides. (thanks @seakleangnhak) diff --git a/changelog.d/features/9214-claude-thinking-token-counts.md b/changelog.d/features/9214-claude-thinking-token-counts.md new file mode 100644 index 0000000000..6787c2bd45 --- /dev/null +++ b/changelog.d/features/9214-claude-thinking-token-counts.md @@ -0,0 +1 @@ +- **feat(usage):** surface Claude thinking token counts to clients. (thanks @luoyide) diff --git a/changelog.d/features/9225-ollama-local-embeddings.md b/changelog.d/features/9225-ollama-local-embeddings.md new file mode 100644 index 0000000000..02b606281b --- /dev/null +++ b/changelog.d/features/9225-ollama-local-embeddings.md @@ -0,0 +1 @@ +- **feat(ollama):** add Ollama Local embedding support via /v1/embeddings. (thanks @HaoNgo232) diff --git a/changelog.d/fixes/8072-catalog-provider-grouped-ordering.md b/changelog.d/fixes/8072-catalog-provider-grouped-ordering.md new file mode 100644 index 0000000000..f1b919cd40 --- /dev/null +++ b/changelog.d/fixes/8072-catalog-provider-grouped-ordering.md @@ -0,0 +1 @@ +- **fix(models):** `/v1/models` now publishes one contiguous provider-grouped block per provider instead of interleaved fragments. The catalog is assembled by many independent push loops (auto-combos, named combos, static registry, codex-native, synced, OpenRouter, specialty, custom, alias-backed, connection-fallback), so one provider's models previously landed in several separated blocks. A single stable, provider-grouped sort is applied at serialization, keyed by `owned_by` (canonical owner identity) rather than the model-id prefix — so a single routable public prefix that differs from its owner (e.g. no-auth OpenCode publishing `oc/` while keeping `owned_by: "opencode"`) stays contiguous. Combos are pinned first (preserving #4164); then providers in registry precedence (OAuth → NoAuth → API-key); then unknown providers in locale-independent code-unit order. The sort is stable and pure (reorders rows only, no mutation, no DB/IO), preserving combo `sort_order`, connection priority, custom append-order, and equal-id audio twins. diff --git a/changelog.d/fixes/8858-win32-cmd-shim-einval.md b/changelog.d/fixes/8858-win32-cmd-shim-einval.md new file mode 100644 index 0000000000..86ca5d1099 --- /dev/null +++ b/changelog.d/fixes/8858-win32-cmd-shim-einval.md @@ -0,0 +1 @@ +- **fix(build):** `prepublish` no longer spawns the Windows `.cmd` shims for npm/npx, which Node >= 20 refuses to launch without a shell (`EINVAL`). On Node 24 that silently skipped the MITM utilities, the MCP server bundle, the LLMLingua ONNX worker and `@omniroute/opencode-plugin` while `build:cli` still exited 0 and reported success. Build tools are now resolved to their own JS entry point and run with the current Node binary — no shim, no shell, no unescaped arguments. (thanks @maisdesign) diff --git a/changelog.d/fixes/8901-nightly-compat-stale-fixtures-and-goldens.md b/changelog.d/fixes/8901-nightly-compat-stale-fixtures-and-goldens.md new file mode 100644 index 0000000000..dcf494fd33 --- /dev/null +++ b/changelog.d/fixes/8901-nightly-compat-stale-fixtures-and-goldens.md @@ -0,0 +1 @@ +- fix(tests): update stale nightly compat fixtures and goldens to match current source constants (#8901) diff --git a/changelog.d/fixes/8990-preserve-tools-response-completed.md b/changelog.d/fixes/8990-preserve-tools-response-completed.md new file mode 100644 index 0000000000..50ce426422 --- /dev/null +++ b/changelog.d/fixes/8990-preserve-tools-response-completed.md @@ -0,0 +1 @@ +- **fix(sse):** `stripResponsesLifecycleEcho` no longer strips `tools` from the `response.completed` snapshot — that terminal event is what Codex CLI rebuilds its tool list from, so stripping it left the client with zero tools. `tools` is still stripped from `response.created`/`response.in_progress`, and `instructions` (the >100KB size lever) is still stripped from all three ([#8990](https://github.com/diegosouzapw/OmniRoute/pull/8990)) diff --git a/changelog.d/fixes/9073-batches-list-limit-validation.md b/changelog.d/fixes/9073-batches-list-limit-validation.md new file mode 100644 index 0000000000..18f5538f82 --- /dev/null +++ b/changelog.d/fixes/9073-batches-list-limit-validation.md @@ -0,0 +1 @@ +- **fix(batches):** `GET /v1/batches` now validates the `limit` query param instead of passing `Number.parseInt(limit)` straight to the SQLite `LIMIT` bind. Previously `?limit=abc` threw an unhandled `datatype mismatch` (→ HTTP 500), `?limit=-1`/`0` returned an incoherent `has_more:true` empty page with `last_id:null`, and a large `?limit` read the entire `batches` table into memory. It now returns a `400` for any non-integer or out-of-range value (1–100, default 20), matching the `POST` handler's Zod validation and the OpenAI Batches contract ([#9073](https://github.com/diegosouzapw/OmniRoute/pull/9073)) diff --git a/changelog.d/fixes/9083-a2a-auth-timing-safe.md b/changelog.d/fixes/9083-a2a-auth-timing-safe.md new file mode 100644 index 0000000000..c5a64776c1 --- /dev/null +++ b/changelog.d/fixes/9083-a2a-auth-timing-safe.md @@ -0,0 +1 @@ +- **fix(a2a):** the A2A JSON-RPC router now compares the bearer token against `OMNIROUTE_API_KEY` in constant time (`crypto.timingSafeEqual`) instead of `===`, closing a token-length timing side-channel, and no longer logs the request URL to server logs on every call ([#9083](https://github.com/diegosouzapw/OmniRoute/pull/9083)) diff --git a/changelog.d/fixes/9088-skills-routes-error-sanitization.md b/changelog.d/fixes/9088-skills-routes-error-sanitization.md new file mode 100644 index 0000000000..7962220e6c --- /dev/null +++ b/changelog.d/fixes/9088-skills-routes-error-sanitization.md @@ -0,0 +1 @@ +- **fix(api/skills):** the `/api/skills/**` routes now run caught error messages through `sanitizeErrorMessage` before returning them, so a filesystem failure no longer leaks an absolute path (e.g. `/home//.omniroute/skills/...`) to the client; the `{ error: string }` response shape is preserved for the dashboard ([#9088](https://github.com/diegosouzapw/OmniRoute/pull/9088)) diff --git a/changelog.d/fixes/9103-remove-retired-copilot-gemini-models.md b/changelog.d/fixes/9103-remove-retired-copilot-gemini-models.md new file mode 100644 index 0000000000..73087690c4 --- /dev/null +++ b/changelog.d/fixes/9103-remove-retired-copilot-gemini-models.md @@ -0,0 +1 @@ +- **fix(providers):** GitHub Copilot no longer re-imports or routes cached Gemini 2.5 Pro and Gemini 3 Flash model IDs after their retirement ([#9103](https://github.com/diegosouzapw/OmniRoute/pull/9103)) diff --git a/changelog.d/fixes/9187-enable-request-logs.md b/changelog.d/fixes/9187-enable-request-logs.md new file mode 100644 index 0000000000..9ba8a3ca87 --- /dev/null +++ b/changelog.d/fixes/9187-enable-request-logs.md @@ -0,0 +1 @@ +- **fix(db):** honor the `ENABLE_REQUEST_LOGS` environment override for detailed request persistence. (thanks @RobertsXML) diff --git a/changelog.d/fixes/9193-context-window-suffix.md b/changelog.d/fixes/9193-context-window-suffix.md new file mode 100644 index 0000000000..3cd229937d --- /dev/null +++ b/changelog.d/fixes/9193-context-window-suffix.md @@ -0,0 +1 @@ +- **fix(model):** normalize client context-window suffixes for combo routing. (thanks @b1nhm1nh) diff --git a/changelog.d/fixes/9200-compression-off-reactive-compaction.md b/changelog.d/fixes/9200-compression-off-reactive-compaction.md new file mode 100644 index 0000000000..e4fefaf0f4 --- /dev/null +++ b/changelog.d/fixes/9200-compression-off-reactive-compaction.md @@ -0,0 +1 @@ +- **fix(compression):** honor the global compression-off setting for proactive and last-resort context compaction, preventing disabled compression from rewriting tool-call histories ([#9200](https://github.com/diegosouzapw/OmniRoute/pull/9200)) — thanks @joachimBrindeau diff --git a/changelog.d/fixes/9209-cli-ipv4-first-dns.md b/changelog.d/fixes/9209-cli-ipv4-first-dns.md new file mode 100644 index 0000000000..b0e602eed6 --- /dev/null +++ b/changelog.d/fixes/9209-cli-ipv4-first-dns.md @@ -0,0 +1 @@ +- **fix(cli):** prefer IPv4 DNS for spawned Node servers. (thanks @dsitmilis) diff --git a/changelog.d/fixes/9212-reasoning-cost-double-billing.md b/changelog.d/fixes/9212-reasoning-cost-double-billing.md new file mode 100644 index 0000000000..3c16a3ae8b --- /dev/null +++ b/changelog.d/fixes/9212-reasoning-cost-double-billing.md @@ -0,0 +1 @@ +- **fix(pricing):** stop billing reasoning tokens twice. (thanks @yidecode) diff --git a/changelog.d/fixes/9218-combo-picker-hidden-models.md b/changelog.d/fixes/9218-combo-picker-hidden-models.md new file mode 100644 index 0000000000..aa8270fd40 --- /dev/null +++ b/changelog.d/fixes/9218-combo-picker-hidden-models.md @@ -0,0 +1 @@ +- **fix(combo):** the Combo "Add model" picker now respects hidden-model visibility for every model source — system catalog, fallback, passthrough/node aliases, custom rows and auto-fetched models — instead of drowning the list in 500+ unavailable entries ([#9218](https://github.com/diegosouzapw/OmniRoute/pull/9218)) — thanks @szzhoujiarui diff --git a/changelog.d/fixes/9219-codex-additional-tools-normalization.md b/changelog.d/fixes/9219-codex-additional-tools-normalization.md new file mode 100644 index 0000000000..02ee481136 --- /dev/null +++ b/changelog.d/fixes/9219-codex-additional-tools-normalization.md @@ -0,0 +1 @@ +- **fix(codex):** normalize additional_tools passthrough items. (thanks @SalyyS1) diff --git a/changelog.d/fixes/9222-codex-quota-window-duration.md b/changelog.d/fixes/9222-codex-quota-window-duration.md new file mode 100644 index 0000000000..2f2e7dd2b7 --- /dev/null +++ b/changelog.d/fixes/9222-codex-quota-window-duration.md @@ -0,0 +1 @@ +- **fix(codex):** preserve quota window duration in usage shape. (thanks @HectorBernstorff) diff --git a/changelog.d/fixes/9223-azure-gpt5-chat-parameters.md b/changelog.d/fixes/9223-azure-gpt5-chat-parameters.md new file mode 100644 index 0000000000..6f4bb43afb --- /dev/null +++ b/changelog.d/fixes/9223-azure-gpt5-chat-parameters.md @@ -0,0 +1 @@ +- **fix(azure):** normalize GPT-5 chat completion parameters. (thanks @royanrosyad85) diff --git a/changelog.d/fixes/9228-codex-orphaned-tool-outputs.md b/changelog.d/fixes/9228-codex-orphaned-tool-outputs.md new file mode 100644 index 0000000000..46897c0a4f --- /dev/null +++ b/changelog.d/fixes/9228-codex-orphaned-tool-outputs.md @@ -0,0 +1 @@ +- **fix(codex):** strip orphaned tool outputs from compacted conversations. (thanks @raflyazf) diff --git a/changelog.d/fixes/9235-french-ui-catalog.md b/changelog.d/fixes/9235-french-ui-catalog.md new file mode 100644 index 0000000000..77731166ac --- /dev/null +++ b/changelog.d/fixes/9235-french-ui-catalog.md @@ -0,0 +1 @@ +- **fix(i18n):** completed the French UI catalog by adding all missing keys and replacing every placeholder translation ([#9235](https://github.com/diegosouzapw/OmniRoute/pull/9235)) — thanks @alex-jordan547 diff --git a/changelog.d/fixes/9236-nvidia-tool-compatibility.md b/changelog.d/fixes/9236-nvidia-tool-compatibility.md new file mode 100644 index 0000000000..b97bd98faf --- /dev/null +++ b/changelog.d/fixes/9236-nvidia-tool-compatibility.md @@ -0,0 +1 @@ +- **fix(nvidia):** normalize tool names and call ids for NVIDIA compatibility. (thanks @minhnhat166) diff --git a/changelog.d/fixes/9241-registered-keys-window-reset.md b/changelog.d/fixes/9241-registered-keys-window-reset.md new file mode 100644 index 0000000000..deeb1e4baa --- /dev/null +++ b/changelog.d/fixes/9241-registered-keys-window-reset.md @@ -0,0 +1 @@ +- **fix(db):** `validateRegisteredKey` no longer rejects the first request of a fresh budget window when the previous window's usage already met the daily/hourly budget — the reset `UPDATE` zeroed the counters in the DB but the budget check still read the stale pre-reset snapshot, so the reset is now mirrored into the row before checking ([#9241](https://github.com/diegosouzapw/OmniRoute/pull/9241)) diff --git a/changelog.d/fixes/9246-purge-orphan-proxy-assignments.md b/changelog.d/fixes/9246-purge-orphan-proxy-assignments.md new file mode 100644 index 0000000000..ee460f8ca4 --- /dev/null +++ b/changelog.d/fixes/9246-purge-orphan-proxy-assignments.md @@ -0,0 +1 @@ +- **fix(db):** deleting a provider connection (single, batch, or provider-scoped) now purges its account-scoped `proxy_assignments` rows inside an atomic transaction — no more orphan assignments pointing at deleted connections ([#9246](https://github.com/diegosouzapw/OmniRoute/pull/9246)) — thanks @maxmad64bis diff --git a/changelog.d/fixes/9256-minimax-thinking-signature.md b/changelog.d/fixes/9256-minimax-thinking-signature.md new file mode 100644 index 0000000000..d25edee6f0 --- /dev/null +++ b/changelog.d/fixes/9256-minimax-thinking-signature.md @@ -0,0 +1 @@ +- **fix(minimax):** add the required empty signature placeholder to unsigned thinking block starts. (thanks @rixzkiye) diff --git a/changelog.d/fixes/9286-redis-loopback-bind.md b/changelog.d/fixes/9286-redis-loopback-bind.md new file mode 100644 index 0000000000..dbd6448bf5 --- /dev/null +++ b/changelog.d/fixes/9286-redis-loopback-bind.md @@ -0,0 +1 @@ +- **fix(docker):** the bundled Redis sidecar no longer publishes on `0.0.0.0`. `docker-compose.yml`, `omniroute redis up` and the dashboard's 1-click launcher all built an unqualified `-p :6379` spec, which the container runtime expands to every interface — and none of them sets `requirepass`, so any host on the LAN could reach the rate-limiter/cache store. All three now default to `127.0.0.1`, with exposure opt-in via `REDIS_BIND_HOST` (compose), `--bind` (CLI) and `OMNIROUTE_REDIS_BIND_HOST` (launcher); the CLI warns when a non-loopback bind is requested without `--password` ([#9286](https://github.com/diegosouzapw/OmniRoute/pull/9286)) diff --git a/changelog.d/fixes/9308-claude-tool-result-pairing.md b/changelog.d/fixes/9308-claude-tool-result-pairing.md new file mode 100644 index 0000000000..9e6bee8aa9 --- /dev/null +++ b/changelog.d/fixes/9308-claude-tool-result-pairing.md @@ -0,0 +1 @@ +- **fix(claude):** reconcile compacted tool results against the preceding tool use. (thanks @ryanngit) diff --git a/changelog.d/fixes/9314-kiro-nested-tool-call-validation.md b/changelog.d/fixes/9314-kiro-nested-tool-call-validation.md new file mode 100644 index 0000000000..22c6ef5665 --- /dev/null +++ b/changelog.d/fixes/9314-kiro-nested-tool-call-validation.md @@ -0,0 +1 @@ +- **fix(kiro):** validate completed nested tool-call payloads before forwarding them. (thanks @SemonCat) diff --git a/changelog.d/fixes/9332-port-2649-claude-server-tool-models.md b/changelog.d/fixes/9332-port-2649-claude-server-tool-models.md new file mode 100644 index 0000000000..a1d0d8bd59 --- /dev/null +++ b/changelog.d/fixes/9332-port-2649-claude-server-tool-models.md @@ -0,0 +1 @@ +- **fix(claude):** normalize nested Claude server tool model ids (`cc/` and `claude/` prefixes) on native passthrough, covering non-versioned server tools (Task/subagent). (thanks @AlanSyue) diff --git a/changelog.d/fixes/9364-models-pricing-gap.md b/changelog.d/fixes/9364-models-pricing-gap.md new file mode 100644 index 0000000000..182fc0061f --- /dev/null +++ b/changelog.d/fixes/9364-models-pricing-gap.md @@ -0,0 +1 @@ +- fix(api): consult LiteLLM pricing_synced layer in resolveCatalogPricing so deployed models absent from models.dev and defaults get pricing in /v1/models (#9364) diff --git a/changelog.d/fixes/9442-mitm-ca-umask.md b/changelog.d/fixes/9442-mitm-ca-umask.md new file mode 100644 index 0000000000..e0a27abab3 --- /dev/null +++ b/changelog.d/fixes/9442-mitm-ca-umask.md @@ -0,0 +1 @@ +- fix(backend): force system MITM CA cert to 0644 on Linux regardless of umask and repair on re-install (#9442) diff --git a/changelog.d/fixes/9451-selfsigned-docker-dep.md b/changelog.d/fixes/9451-selfsigned-docker-dep.md new file mode 100644 index 0000000000..a2f525665d --- /dev/null +++ b/changelog.d/fixes/9451-selfsigned-docker-dep.md @@ -0,0 +1 @@ +- fix(docker): ship MITM `_internal/` shims and `selfsigned` package in standalone bundle (#9451) diff --git a/changelog.d/fixes/9454-launch-claude-exe-windows.md b/changelog.d/fixes/9454-launch-claude-exe-windows.md new file mode 100644 index 0000000000..c4abdf25ab --- /dev/null +++ b/changelog.d/fixes/9454-launch-claude-exe-windows.md @@ -0,0 +1 @@ +- fix(cli): probe PATH for claude.exe/codex.exe on Windows before falling back to the .cmd shim (#9454) diff --git a/changelog.d/fixes/9455-stop-supervisor-respawn.md b/changelog.d/fixes/9455-stop-supervisor-respawn.md new file mode 100644 index 0000000000..b4571ce88f --- /dev/null +++ b/changelog.d/fixes/9455-stop-supervisor-respawn.md @@ -0,0 +1 @@ +- fix(cli): stop the supervisor before the child so omniroute stop no longer reports success while the supervisor respawns the server (#9455) diff --git a/changelog.d/fixes/9474-claude-code-oauth-mismap.md b/changelog.d/fixes/9474-claude-code-oauth-mismap.md new file mode 100644 index 0000000000..4a7df44a69 --- /dev/null +++ b/changelog.d/fixes/9474-claude-code-oauth-mismap.md @@ -0,0 +1 @@ +- fix(cli): route claude-code OAuth to the Anthropic `claude` browser-PKCE flow instead of the unrelated command-code provider (#9474) diff --git a/changelog.d/fixes/9475-update-lies-shadowing.md b/changelog.d/fixes/9475-update-lies-shadowing.md new file mode 100644 index 0000000000..969d9b4aee --- /dev/null +++ b/changelog.d/fixes/9475-update-lies-shadowing.md @@ -0,0 +1 @@ +- fix(cli): re-verify running binary version after `omniroute update` install and warn instead of lying about success when a local install shadows the global one (#9475) diff --git a/changelog.d/fixes/9500-reasoning-summary-separator.md b/changelog.d/fixes/9500-reasoning-summary-separator.md new file mode 100644 index 0000000000..95f5565a72 --- /dev/null +++ b/changelog.d/fixes/9500-reasoning-summary-separator.md @@ -0,0 +1 @@ +- fix(translator): join reasoning summary segments with newline separators (#9500) diff --git a/changelog.d/fixes/9502-muse-ecto1-auth-token.md b/changelog.d/fixes/9502-muse-ecto1-auth-token.md new file mode 100644 index 0000000000..5962deb307 --- /dev/null +++ b/changelog.d/fixes/9502-muse-ecto1-auth-token.md @@ -0,0 +1 @@ +- fix(muse-spark-web): document the ecto1: WS auth token requirement in the credential hint, spec, and error message (#9502) diff --git a/changelog.d/fixes/9505-atu-effort-beta-allowlist.md b/changelog.d/fixes/9505-atu-effort-beta-allowlist.md new file mode 100644 index 0000000000..e580e1cb6b --- /dev/null +++ b/changelog.d/fixes/9505-atu-effort-beta-allowlist.md @@ -0,0 +1 @@ +- fix(sse): stop force-injecting advanced-tool-use beta via the effort-2025-11-24 gate; forward client-negotiated effort through the allowlist (#9505) diff --git a/changelog.d/fixes/9507-maxtokens-upward-rewrite.md b/changelog.d/fixes/9507-maxtokens-upward-rewrite.md new file mode 100644 index 0000000000..ef43480699 --- /dev/null +++ b/changelog.d/fixes/9507-maxtokens-upward-rewrite.md @@ -0,0 +1 @@ +- fix(sse): stop the reasoning-token buffer from enlarging a client's explicit max_tokens upward (x1.5) (#9507) diff --git a/changelog.d/maintenance/8484-client-usage-format-contract.md b/changelog.d/maintenance/8484-client-usage-format-contract.md new file mode 100644 index 0000000000..c459a8eda8 --- /dev/null +++ b/changelog.d/maintenance/8484-client-usage-format-contract.md @@ -0,0 +1 @@ +- **fix(types):** preserve the client response format contract while estimating usage for non-streaming responses diff --git a/changelog.d/maintenance/8484-responses-transform-options-type.md b/changelog.d/maintenance/8484-responses-transform-options-type.md new file mode 100644 index 0000000000..7c27623665 --- /dev/null +++ b/changelog.d/maintenance/8484-responses-transform-options-type.md @@ -0,0 +1 @@ +- Preserve the Responses API transform options contract under TypeScript 7. diff --git a/changelog.d/maintenance/8484-thinking-signature-recovery-types.md b/changelog.d/maintenance/8484-thinking-signature-recovery-types.md new file mode 100644 index 0000000000..94c32a5b6e --- /dev/null +++ b/changelog.d/maintenance/8484-thinking-signature-recovery-types.md @@ -0,0 +1 @@ +- **fix(types):** preserved the known first-failure record while reading Anthropic thinking-signature recovery details so TypeScript 7 keeps the retry result union narrow ([#8484](https://github.com/diegosouzapw/OmniRoute/issues/8484)) diff --git a/changelog.d/maintenance/8484-validation-failure-narrowing.md b/changelog.d/maintenance/8484-validation-failure-narrowing.md new file mode 100644 index 0000000000..d5a5c7a5c2 --- /dev/null +++ b/changelog.d/maintenance/8484-validation-failure-narrowing.md @@ -0,0 +1 @@ +- **fix(types):** reuse the validation failure predicate when building malformed-body responses so the existing error envelope remains type-safe and unchanged. diff --git a/changelog.d/maintenance/8484-vision-capability-literal.md b/changelog.d/maintenance/8484-vision-capability-literal.md new file mode 100644 index 0000000000..b155ef82e6 --- /dev/null +++ b/changelog.d/maintenance/8484-vision-capability-literal.md @@ -0,0 +1 @@ +- **fix(types):** preserve the literal `capabilities.vision: true` contract for catalog vision fields so custom-model capability composition remains type-safe under TypeScript 7 ([#9121](https://github.com/diegosouzapw/OmniRoute/pull/9121)) diff --git a/changelog.d/maintenance/9063-cover-specificity-rules.md b/changelog.d/maintenance/9063-cover-specificity-rules.md new file mode 100644 index 0000000000..f4e0ef5ce6 --- /dev/null +++ b/changelog.d/maintenance/9063-cover-specificity-rules.md @@ -0,0 +1,7 @@ +- **test(sse):** added the first test suite for `open-sse/services/specificityRules.ts` — the + module was hotspot #7 in the coverage plan at 11.28% lines with no dedicated test; the 14 pure + detectors are now pinned edge-to-edge (token ladders, per-domain max-not-sum scoring, and the + min/max clamps), taking the file to ~100% line coverage. The suite also documents two quirks + left unchanged: `detectReasoningDepth` scores above 0 on marker-free input via its + always-applied message-depth bonus, and `detectErrorContext` returns non-integer scores because + it never rounds ([#9063](https://github.com/diegosouzapw/OmniRoute/pull/9063)) diff --git a/changelog.d/maintenance/9104-veoaifree-polling-delay-type.md b/changelog.d/maintenance/9104-veoaifree-polling-delay-type.md new file mode 100644 index 0000000000..5da0e8337c --- /dev/null +++ b/changelog.d/maintenance/9104-veoaifree-polling-delay-type.md @@ -0,0 +1 @@ +- **fix(types):** preserved the Veo polling delay promise result as `void` for TypeScript 7 compatibility without changing runtime polling behavior ([#9104](https://github.com/diegosouzapw/OmniRoute/pull/9104)) diff --git a/changelog.d/maintenance/9105-compression-stats-type-import.md b/changelog.d/maintenance/9105-compression-stats-type-import.md new file mode 100644 index 0000000000..714536d96b --- /dev/null +++ b/changelog.d/maintenance/9105-compression-stats-type-import.md @@ -0,0 +1 @@ +- **fix(types):** imported compression analytics statistics from their defining module so TypeScript 7 resolves the existing interface correctly ([#9105](https://github.com/diegosouzapw/OmniRoute/pull/9105)) diff --git a/changelog.d/maintenance/9117-ts7-semantic-cache-signature-inputs.md b/changelog.d/maintenance/9117-ts7-semantic-cache-signature-inputs.md new file mode 100644 index 0000000000..c49c326950 --- /dev/null +++ b/changelog.d/maintenance/9117-ts7-semantic-cache-signature-inputs.md @@ -0,0 +1 @@ +- **chore(types):** align semantic cache signature inputs with the numeric request contract so both cache-write paths remain runtime-equivalent while TypeScript 7 checks them safely ([#9117](https://github.com/diegosouzapw/OmniRoute/pull/9117)) diff --git a/changelog.d/maintenance/9118-ts7-response-meta-header-inputs.md b/changelog.d/maintenance/9118-ts7-response-meta-header-inputs.md new file mode 100644 index 0000000000..983269b392 --- /dev/null +++ b/changelog.d/maintenance/9118-ts7-response-meta-header-inputs.md @@ -0,0 +1 @@ +- **fix(types):** narrowed non-streaming chat response metadata inputs to the shared header contract without changing emitted metadata headers ([#9118](https://github.com/diegosouzapw/OmniRoute/pull/9118)) diff --git a/changelog.d/maintenance/9229-zoo-code-branding.md b/changelog.d/maintenance/9229-zoo-code-branding.md new file mode 100644 index 0000000000..7bb2c48803 --- /dev/null +++ b/changelog.d/maintenance/9229-zoo-code-branding.md @@ -0,0 +1 @@ +- **docs(readme):** replace Roo Code branding with Zoo Code. (thanks @taltas) diff --git a/changelog.d/maintenance/rtl-physical-class-ratchet.md b/changelog.d/maintenance/rtl-physical-class-ratchet.md new file mode 100644 index 0000000000..16432ea051 --- /dev/null +++ b/changelog.d/maintenance/rtl-physical-class-ratchet.md @@ -0,0 +1 @@ +- chore(quality): add an RTL layout ratchet — counts physical directional Tailwind classes (ml/mr/pl/pr/left/right/text-left/border-l/rounded-l) that do not mirror under `dir=rtl`, seeded at 1011 so the backlog behind `tests/unit/ui/rtl-logical-classes.test.tsx` ("#3541, partial, core layout") cannot grow while it is worked through diff --git a/config/quality/file-size-baseline.json b/config/quality/file-size-baseline.json index e3c570b3e3..7c3c6022ef 100644 --- a/config/quality/file-size-baseline.json +++ b/config/quality/file-size-baseline.json @@ -161,6 +161,7 @@ "_rebaseline_2026_08_04_9439_agentic_conversation_tracking": "PR #9439 (hartmark, feat/agentic-conversation-tracking) own growth: adds agentic multi-turn conversation tracking (X-ConversationId, fingerprint+prefix-hash continuation detection) plus a full dashboard surface for it. src/sse/handlers/chat.ts 1845->1868 (+23, conversationId resolution + X-ConversationId header wiring at the existing chat-request chokepoint, threaded to executeChatWithBreaker). open-sse/handlers/chatCore.ts 5020->5024 (+4, sessionTag passthrough on the trackPendingRequest() call so an in-flight/streaming request's conversation transcript can be reconstructed live — see #9315 fix in the same PR). src/shared/components/RequestLoggerV2.tsx 1629->1643 (+14, onNavigateToLog wiring so a turn/next-message click in the new conversation panel can open another request's detail without leaving the logs list). Two files cross the 1000-line new-file cap because they gained the actual UI feature body, not incidental wiring: src/shared/components/RequestLoggerDetail.tsx (new cap, 1241->1256 after a follow-up +15: a 'Conversation' field added to the metadata grid, last after 'Combo', showing the request's sessionTag/conversation id; then 1256->1260 after lint-staged's prettier auto-reformatted a pre-existing multi-line ternary past the 100-char print width while staging that same commit) gained the 'Full Conversation' transcript section (Markdown rendering, per-turn timestamps, turn-relative view, click-to-navigate, live auto-refresh/auto-follow fed from the in-flight SSE buffer, mobile-responsive header) and src/shared/components/RequestTimeline.tsx (new cap, 1037) gained conversation-aware lane grouping/connector-arrow rendering, mobile responsiveness, and configurable poll-interval controls; both are the dashboard-side half of this PR's actual feature, not extractable without splitting an existing single-modal/single-canvas component mid-feature. open-sse/executors/base.ts 1578->1623 (+45) is NOT this PR's change — confirmed via `git diff upstream/release/v3.8.50 HEAD -- open-sse/executors/base.ts` (empty) — it is release/v3.8.50's own pre-existing drift past its frozen cap, inherited via this branch's rebase onto the current release tip; rebaselined here only because check:file-size runs against the full merged tree and this PR's rebase is what surfaced it. Covered by tests/unit/conversationTracker.test.ts, agenticConversations.test.ts, request-timeline-lane-allocation.test.ts, stream-payload-collector.test.ts. Structural shrink of RequestLoggerDetail.tsx/RequestTimeline.tsx tracked in #3501. Follow-up v3 redesign (per-turn hash-chain continuation detection replacing the whole-history prefix hash, so an edit/duplicate mid-history forks a branch instead of never reconnecting — real OpenClaw traffic pattern): src/sse/handlers/chat.ts 1868->1869 (+1, threading the request's existing correlationId into resolveConversationId() so new turn-chain nodes can be tagged with a request identifier that exists before the call_logs row itself does). RequestLoggerDetail.tsx's conversation panel was simplified in the same pass (1260->1080, -180): dropped the cross-row multi-row reconstruction/next-turn navigation/auto-follow/reuse-window spinner entirely in favor of rendering only the currently-viewed request's own context, per operator request — src/mitm/inspector/multiRowConversation.ts (and its test) deleted, no longer needed. New migration 136_conversation_turn_nodes.sql + src/lib/db/agenticConversations.ts turn-node CRUD additions covered by their own tests in agenticConversations.test.ts.", "_rebaseline_2026_08_05_9439_fold_9183_responses_api_fixes": "PR #9183 (hartmark, fix/responses-api-index-collision) folded into #9439 at the operator's request, closing #9183 in favor of this branch. Fixes output_index collisions between reasoning/message/tool-call items, a race that dropped tool calls and finish signals sharing a chunk with reasoning/text, multi-choice truncation, and DeepSeek/big-pickle reasoning_content replay across turns. open-sse/handlers/chatCore.ts 5024->5032 (+8, messageIndex now keyed off the real position in the next turn's replayed `messages` array — both the non-stream and stream reasoning-cache capture call sites — instead of a hardcoded 0). open-sse/translator/response/openai-responses.ts 1174->1180 (+6, turn-grouping fix so reasoning/content/tool_calls land in one assistant turn for strict OpenAI-compatible upstreams). Both are cohesive fixes at existing chokepoints, not extractable without splitting response translation mid-turn. tests/unit/reasoning-cache.test.ts crosses the 1000-line new-file test cap (976->1035, +59, entirely this fold's diff — cache-index regression coverage for the fixed messageIndex behavior). Covered by the PR's own 82 passing tests across reasoning-cache.test.ts, translator-helper-branches.test.ts, translator-request-openai-responses.test.ts, responses-api-truncation.test.ts (new), responses-replay-fixes.test.ts (new), responses-request-translation.test.ts (new).", "_rebaseline_2026_08_06_9439_no_forking_redesign_and_fixes": "PR #9439 (hartmark) own growth, superseding the prior entry's 'forks a branch' description: live traffic showed the fork/tree model indenting one level per edited/duplicated turn until no room was left for content, and forking never actually reconnected — every candidate reconnect anchor for a repeated turn (a tool-polling loop's identical output, one real conversation had 28 copies of a single turn) returned whichever occurrence was tried first (the oldest, stalest), which almost always looked like a divergence. Redesigned so an edit mints its own independent conversation instead of a branch (findReconnectMatch in conversationTracker.ts now evaluates every candidate anchor and keeps the one that verifiably extends furthest, ties breaking toward the anchor with no recorded child), and the dashboard lists/paginates flat per-conversation transcripts (last 20 turns + 'Load more') instead of rendering a tree. src/sse/handlers/chat.ts 1869->1875 (+6, no material change here — drift absorbed while reconciling this rebase). open-sse/translator/response/openai-responses.ts 1180->1227 (+47): persists per-tool-call JSON-escape state (inString/pendingEscape) across SSE delta chunks instead of resetting it per call — a raw or already-escaped newline byte split across two chunks was getting corrupted in transit, a real OmniRoute bug previously mistaken for model-generation quality. src/shared/components/RequestLoggerV2.tsx 1643->1687 (+44): Previous/Next navigation resyncs the in-memory list once at the array boundary before closing the modal — list polling intentionally pauses while a detail modal is open, so hitting the boundary didn't mean there was nothing newer, only that the client hadn't fetched it yet. src/shared/components/RequestTimeline.tsx 1037->1044 (+7, drops the now-nonexistent onNavigateToLog prop passed into RequestLoggerDetail, whose cross-row next-turn navigation was removed in the same pass detailed in the prior rebaseline entry). Covered by tests/unit/conversationTracker.test.ts (duplicate-content reconnect-anchor regression test), tests/unit/translator-resp-openai-responses.test.ts (cross-chunk escape-state regression tests), tests/unit/agenticConversations.test.ts, tests/unit/inspector-conversation-normalizer.test.ts, tests/unit/request-logger-bounded-clone.test.ts, tests/unit/conversations-tree-route-seq-param.test.ts (new). Structural shrink of RequestLoggerV2.tsx/RequestTimeline.tsx tracked in #3501.", + "_rebaseline_2026_08_06_9439_merge_release_v3850_tip": "Merging the current upstream/release/v3.8.50 tip into #9439 (134 commits ahead of this branch's last sync) surfaced a migration-number collision: upstream independently added 135_migrate_model_capability_max_token.sql at the same version 135 this PR's 135_agentic_conversations.sql already occupied (this PR's tables were themselves already bumped once before, 134->135, for the identical reason per the '[Migration] CRITICAL: renumbered' warning in migrationRunner.ts — a recurring cost of a long-lived branch rebasing against a moving release target). Renumbered this PR's own two migrations upward (135_agentic_conversations.sql->137, 136_conversation_turn_nodes.sql->138) rather than touch upstream's file, leaving every other branch/PR based on the same release number unaffected. All internal comment references (agenticConversations.ts, the migration files themselves) updated to match; verified via agenticConversations.test.ts/conversationTracker.test.ts/conversations-tree-route-seq-param.test.ts (35/35) plus the newly-unblocked catalog-order-contract.test.ts (2/2, upstream's own file, was colliding on the same version number so never got to run against this tree before). Remaining file-size baseline changes in this entry are release/v3.8.50's own pre-existing drift, inherited via the merge and unrelated to this PR's commits — confirmed none of src/app/(dashboard)/dashboard/HomePageClient.tsx (1381->1388), providers/page.tsx (1923->1928), usage/components/ProviderLimits/index.tsx (1109->1119), open-sse/executors/{base,codex,default,kiro}.ts, open-sse/mcp-server/server.ts (1407->1411), or the 4 rebaselined test files (chatcore-translation-paths, combo-routing-engine, sse-auth, translator-openai-to-kiro) appear in any commit this PR authored; rebaselined here only because check:file-size runs against the full merged tree and this merge is what surfaced it, same precedent as open-sse/executors/base.ts in the first rebaseline entry above.", "cap": 1000, "testCap": 1000, "testFrozen": { @@ -175,14 +176,14 @@ "_rebaseline_2026_07_25_8510_adobe_firefly_reference_images_tests": "#8510 (artickc, feat/adobe-firefly-reference-images) own test growth: tests/unit/adobe-firefly.test.ts 711->871 (+159, entirely this PR's diff — new referenceBlobs upload/dispatch coverage for handleAdobeFireflyImageGeneration, resolveAdobeSourceImageIds, and the storage-upload wire contract). Route-level /v1/images/edits coverage (credentials/rate-limit/4-ref-cap branches added to route.ts) lives in the new tests/unit/8510-adobe-firefly-edits-route.test.ts instead of growing this file further.", "_rebaseline_basered_codebuddy_cn": "Base-red fix (#4664 CodeBuddy CN): oauth-providers-config.test.ts 867->870 (+3) to align the EXPECTED provider list/config with the codebuddy-cn provider that #4664 added to the registry without updating this test (it asserts 'exactly once').", "_rebaseline_pr4613_compatible_provider_groups": "Reconcile #4613 already-merged growth: providers-page-utils.test.ts 1004->1052 (+48, buildCompatibleProviderGroups partition unit test). Fast-gate PR->release does not run check:file-size, so this surfaced post-merge.", - "tests/integration/chat-pipeline.test.ts": 1592, + "tests/integration/chat-pipeline.test.ts": 1598, "tests/integration/chatcore-compression-integration.test.ts": 1114, "tests/unit/account-fallback-service.test.ts": 1563, "tests/unit/batch_api.test.ts": 1324, "tests/unit/cc-compatible-provider.test.ts": 1217, - "tests/unit/chatcore-translation-paths.test.ts": 2776, + "tests/unit/chatcore-translation-paths.test.ts": 2876, "tests/unit/chatgpt-web.test.ts": 3148, - "tests/unit/combo-routing-engine.test.ts": 3449, + "tests/unit/combo-routing-engine.test.ts": 3457, "tests/unit/db-migration-runner.test.ts": 1499, "tests/unit/deepseek-web.test.ts": 1092, "tests/unit/executor-codex.test.ts": 1339, @@ -193,17 +194,17 @@ "tests/unit/models-catalog-route.test.ts": 1636, "tests/unit/perplexity-web.test.ts": 1355, "tests/unit/provider-models-route.test.ts": 1784, - "tests/unit/provider-validation-specialty.test.ts": 2980, + "tests/unit/provider-validation-specialty.test.ts": 2985, "tests/unit/providers-page-utils.test.ts": 1106, "tests/unit/response-sanitizer.test.ts": 1063, "tests/unit/route-edge-coverage.test.ts": 1241, "tests/unit/search-handler-extended.test.ts": 1071, - "tests/unit/sse-auth.test.ts": 1600, + "tests/unit/sse-auth.test.ts": 1610, "tests/unit/stream-utils.test.ts": 2445, "tests/unit/token-refresh-service.test.ts": 1378, "tests/unit/translator-openai-responses-req.test.ts": 1194, "tests/unit/translator-openai-to-gemini.test.ts": 1616, - "tests/unit/translator-openai-to-kiro.test.ts": 1250, + "tests/unit/translator-openai-to-kiro.test.ts": 1275, "tests/unit/translator-resp-gemini-to-openai.test.ts": 1234, "tests/unit/usage-service-hardening.test.ts": 1483, "tests/unit/vscode-token-routes.test.ts": 1256, @@ -347,31 +348,31 @@ "_rebaseline_pr1043_minimax_tts": "Upstream port decolua/9router#1043 (toanalien) own growth: audioSpeech.ts 965->1061 (+96). Adds MiniMax T2A v2 TTS dispatch (handleMinimaxSpeech + hexToBytes helper) — provider entry was already in audioRegistry (format: minimax-tts) but no handler existed, falling through to the OpenAI-compatible default that fails (T2A has custom shape + hex-encoded audio + base_resp envelope). New branch sits next to the other inline provider branches (xiaomi-mimo, coqui, tortoise, aws-polly) — extracting would just create indirection. Covered by tests/unit/minimax-tts-1043.test.ts (3 tests, GREEN: success, base_resp error, invalid-hex).", "_rebaseline_pr4592_exclude_exhausted_auto": "Reconcile #4592 already-merged growth: combo.ts 2991->3036 (+45, terminal-status quota-cutoff exclusion in buildAutoCandidates + opt-in gate). Fast-gate PR->release does not run check:file-size.", "open-sse/executors/antigravity.ts": 1528, - "open-sse/executors/base.ts": 1623, + "open-sse/executors/base.ts": 1635, "open-sse/executors/chatgpt-web.ts": 3241, - "open-sse/executors/codex.ts": 1534, + "open-sse/executors/codex.ts": 1562, "open-sse/executors/cursor.ts": 1560, "open-sse/executors/deepseek-web.ts": 1148, "open-sse/executors/grok-web.ts": 1044, "open-sse/executors/muse-spark-web.ts": 1405, - "open-sse/handlers/chatCore.ts": 5032, + "open-sse/handlers/chatCore.ts": 5034, "open-sse/handlers/imageGeneration.ts": 3101, - "open-sse/handlers/responseSanitizer.ts": 1115, + "open-sse/handlers/responseSanitizer.ts": 1128, "open-sse/handlers/search.ts": 1536, "open-sse/handlers/videoGeneration.ts": 1063, "open-sse/mcp-server/schemas/tools.ts": 1505, - "open-sse/mcp-server/server.ts": 1407, + "open-sse/mcp-server/server.ts": 1411, "open-sse/mcp-server/tools/advancedTools.ts": 1120, "open-sse/services/accountFallback.ts": 1966, - "open-sse/services/adobeFireflyClient.ts": 2322, + "open-sse/services/adobeFireflyClient.ts": 2385, "open-sse/services/claudeCodeCompatible.ts": 1202, "open-sse/services/combo.ts": 3648, "open-sse/services/compression/strategySelector.ts": 1060, - "open-sse/services/rateLimitManager.ts": 1060, - "open-sse/translator/response/openai-responses.ts": 1227, + "open-sse/services/rateLimitManager.ts": 1105, + "open-sse/translator/response/openai-responses.ts": 1257, "open-sse/utils/cursorAgentProtobuf.ts": 1505, "open-sse/utils/stream.ts": 2889, - "src/app/(dashboard)/dashboard/HomePageClient.tsx": 1381, + "src/app/(dashboard)/dashboard/HomePageClient.tsx": 1388, "src/app/(dashboard)/dashboard/analytics/ComboHealthTab.tsx": 1031, "src/app/(dashboard)/dashboard/api-manager/ApiManagerPageClient.tsx": 3117, "src/app/(dashboard)/dashboard/cache/media/MediaPageClient.tsx": 1067, @@ -381,7 +382,7 @@ "src/app/(dashboard)/dashboard/endpoint/EndpointPageClient.tsx": 2615, "src/app/(dashboard)/dashboard/health/page.tsx": 1165, "src/app/(dashboard)/dashboard/providers/[id]/components/modals/EditConnectionModal.tsx": 1316, - "src/app/(dashboard)/dashboard/providers/page.tsx": 1923, + "src/app/(dashboard)/dashboard/providers/page.tsx": 1928, "src/app/(dashboard)/dashboard/runtime/RuntimePageClient.tsx": 1201, "src/app/(dashboard)/dashboard/settings/components/PricingTab.tsx": 1019, "src/app/(dashboard)/dashboard/settings/components/ProxyRegistryManager.tsx": 1464, @@ -390,7 +391,7 @@ "src/app/(dashboard)/dashboard/settings/components/SystemStorageTab.tsx": 1573, "src/app/(dashboard)/dashboard/usage/components/BudgetTab.tsx": 1028, "src/app/(dashboard)/dashboard/usage/components/EvalsTab.tsx": 2148, - "src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.tsx": 1109, + "src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.tsx": 1119, "src/app/api/providers/[id]/models/route.ts": 2250, "src/app/api/v1/models/catalog.ts": 1549, "src/lib/tokenHealthCheck.ts": 1021, @@ -406,13 +407,15 @@ "src/shared/components/RequestLoggerV2.tsx": 1687, "src/shared/components/analytics/charts.tsx": 1035, "src/shared/services/cliRuntime.ts": 1122, - "src/sse/handlers/chat.ts": 1875, + "src/sse/handlers/chat.ts": 1906, "src/shared/components/RequestLoggerDetail.tsx": 1260, "src/shared/components/RequestTimeline.tsx": 1044, "src/sse/services/auth.ts": 2508, "tests/unit/account-fallback-service.test.ts": 1572, - "tests/unit/provider-validation-specialty.test.ts": 2980, - "open-sse/executors/hyperagent.ts": 1026 + "tests/unit/provider-validation-specialty.test.ts": 2985, + "open-sse/executors/hyperagent.ts": 1026, + "open-sse/executors/default.ts": 1042, + "open-sse/executors/kiro.ts": 1069 }, "_rebaseline_2026_07_27_v3849_train2": "Merge-train 2 (7 PRs) — owner-approved 2026-07-27. Single entry: chatCore.ts 4955->5006 (#8595, Responses multi-turn image compaction before the context hard-reject). Genuine irreducible growth at the existing compaction chokepoint in handleChatCore — the PR adds a last-resort retry against the concrete budget plus the estimateFinalInputTokens helper, both wired at the pre-existing call site rather than a new branch. Covered by tests/unit/8560-responses-image-compaction.test.ts (4 tests).", "_rebaseline_2026_07_27_v3849_train3": "Merge-train 3 (13 PRs) — owner-approved 2026-07-27. Both entries are genuine irreducible growth at existing chokepoints, not new branches: src/lib/db/apiKeys.ts 1518->1529 (#8805 cx/* ≡ codex/* API-key model permissions); open-sse/handlers/chatCore.ts 5006->5020 (#8806 real response payload into plugin onResponse hooks). Covered by tests/unit/db-apiKeys-crud.test.ts (4 new cases) and the two plugin-hook test files updated in #8806 respectively.", @@ -421,6 +424,11 @@ "_rebaseline_2026_07_28_8860_tokenrefresh_projectid": "PR #8860 (fix/antigravity-projectid-centralized) own test growth: tests/unit/token-refresh-service.test.ts 1311->1378 (+67 = 4 cases covering projectId discovery on the tokenRefresh.ts path — the Dashboard/health-check refresh route, which #8842 did not reach since that fixed the executor path). Covered by the same file.", "_rebaseline_2026_07_28_8861_xiaomi_token_plan": "PR #8861 (feat/xiaomi-token-plan-protocol-selector) own growth: EditConnectionModal.tsx 1283->1316 (+33 = the per-connection API-protocol selector field) and open-sse/executors/base.ts 1540->1562 (+22 = alternate-format resolution at the existing buildUrl/headers chokepoint). Both are irreducible wiring at existing call sites.", "_rebaseline_2026_07_28_8863_firefly_detail_level": "PR #8863 (fix/adobe-firefly-gpt-detail-level-max) own growth: adobeFireflyClient.ts 2317->2322 (+5 = gpt-image detailLevel defaulting to maximal at the existing payload-build site). Covered by tests/unit/adobe-firefly.test.ts.", + "_rebaseline_2026_07_28_8870_firefly_ref_cap_timeout": "PR #8870 (fix/adobe-firefly-gpt-ref-cap-timeout) own growth: adobeFireflyClient.ts 2322->2385 (+63 = gpt-image subject-ref hard cap at 2 + adaptive poll timeout budget (base 300s + 60s/ref, max 600s) + defensive .slice on referenceBlobs for gpt/nano/generic families). Fixes live 504s on multi-screenshot listing jobs (Featured Promo / Box Art) where 3–4+ subject refs stall colligo until the old 180s poll budget expires. Helpers adobeFireflyMaxImageRefs/adobeFireflyImageTimeoutMs live next to the existing payload/poll chokepoint (not extractable without splitting the wire recipe mid-PR). Covered by tests/unit/adobe-firefly.test.ts (ref-cap + timeout cases). Structural shrink tracked in #3501.", "_rebaseline_2026_07_29_8281_home_quickstart_prefetch": "Release v3.8.49 base-red fix (no PR — captain sweep): src/app/(dashboard)/dashboard/HomePageClient.tsx 1377->1381 (+4). #8292 added prefetch={false} to the sidebar but left /home's five quick-start Links prefetching, so first paint still fired 12 speculative RSC requests — caught by navigation.spec.ts only after the e2e helper bug (APP_ROUTE_PATTERN missing /home) was repaired in the same cycle. Growth is the five prefetch attributes; it was offset first by extracting the repeated className literals (INLINE_LINK x4, DOCS_LINK x1), which collapsed five wrapped blocks back to one line each — a naive fix measured 1391. Guard: tests/unit/sidebar-prefetch-policy-8281.test.ts.", - "_rebaseline_2026_08_02_v3850_agentrouter_responses": "Release v3.8.50 AgentRouter/Codex compatibility reconciliation. open-sse/executors/base.ts 1562->1578: #9190 wires AgentRouter's selected Claude/OpenAI/Responses protocol through the existing executor URL, auth, identity-header and fingerprint chokepoints; the reusable alternate resolver remains outside base.ts. open-sse/utils/stream.ts 2887->2889: #9213 evaluates Responses ID and usage normalization independently so response.completed always receives finite usage.total_tokens instead of short-circuiting after an ID rewrite. tests/unit/chatcore-translation-paths.test.ts 2769->2776: #9191 updates the existing Claude-Code bridge assertions for the dynamic AgentRouter wire image. PR #9224 offsets its own chatCore growth by extracting the AgentRouter protocol decisions into chatCore/agentRouterProtocol.ts, leaving chatCore below its frozen ceiling. Covered by agentrouter executor/chatCore protocol tests, chatcore translation-path tests, and responses-commentary-passthrough tests." + "_rebaseline_2026_08_01_8964_xai_agent_tools": "PR #8964 own growth: chatCore.ts 5020->5034 at the existing native-passthrough chokepoint. Adds xAI Agent Tools passthrough for /v1/responses (xai/xai-oauth/xao): resolve nativeXaiResponsesPassthrough, force openai-responses targetFormat, stamp body marker, and OR into the existing nativeCodexPassthrough sites (web-search bypass + requestEndpointPath). Leaf logic in passthroughHelpers, responsesEndpoint, targetFormat, xai executor, responseSanitizer, usageTracking. Cohesive wiring at the Codex passthrough boundary.", + "_rebaseline_2026_08_01_8964_response_sanitizer": "PR #8964 own growth: responseSanitizer.ts 1115->1128. Keep cost_in_usd_ticks / server_side_tool_usage(_details) through sanitizeResponsesApiResponse allowlists so native xAI tool responses retain usage.", + "_rebaseline_2026_08_02_v3850_agentrouter_responses": "Release v3.8.50 AgentRouter/Codex compatibility reconciliation. open-sse/executors/base.ts 1562->1578: #9190 wires AgentRouter's selected Claude/OpenAI/Responses protocol through the existing executor URL, auth, identity-header and fingerprint chokepoints; the reusable alternate resolver remains outside base.ts. open-sse/utils/stream.ts 2887->2889: #9213 evaluates Responses ID and usage normalization independently so response.completed always receives finite usage.total_tokens instead of short-circuiting after an ID rewrite. tests/unit/chatcore-translation-paths.test.ts 2769->2776: #9191 updates the existing Claude-Code bridge assertions for the dynamic AgentRouter wire image. PR #9224 offsets its own chatCore growth by extracting the AgentRouter protocol decisions into chatCore/agentRouterProtocol.ts, leaving chatCore below its frozen ceiling. Covered by agentrouter executor/chatCore protocol tests, chatcore translation-path tests, and responses-commentary-passthrough tests.", + "_rebaseline_2026_08_05_9323_agentrouter_waf_retry": "PR #9323 (fix(agentrouter): retry on 400 content-blocked + burst guard) own growth: open-sse/executors/base.ts 1578->1623 (check-file-size.mjs conta via split(\"\\n\").length; wc -l ve 1622). As +45 linhas sao o WAF_RETRY_CONFIG + o burst guard via gateOutboundRequest() para o WAF do agentrouter.org, com comentarios explicando o porque de cada mitigacao e cobertos por tests/unit/base-executor-waf-retry.test.ts e tests/unit/wafRateLimit.test.ts. Crescimento funcional legitimo, nao inchaco.", + "_rebaseline_2026_08_05_9529_own_growth": "PR #9529 own growth (base release/v3.8.50 medida EXATAMENTE nos frozen antigos, entao o modo base-relative #8522 nao cobre): open-sse/services/rateLimitManager.ts 1060->1105 (+45: helper applyLimiterSettings() que re-arma o heartbeat do reservoir apos updateSettings — fix do bug Bottleneck 2.19.5 que congelava a fila weighted; TDD em tests/unit/ratelimit-reservoir-refresh.test.ts); tests/integration/chat-pipeline.test.ts 1592->1598 (+6: User-Agent do codex derivado de getCodexClientVersion() em vez de literal pinado — teste-irmao alinhado ao contrato); tests/unit/provider-validation-specialty.test.ts 2980->2985 (+5: cobertura NOVA claude-web 429 -> valid:false, alinhamento #9406); open-sse/translator/response/openai-responses.ts 1174->1204 (+30: buildResponsesReasoningSummaryDelta MOVIDA do leaf pureHelpers.ts para o host — a funcao do #9500 muta stream state e violava o contrato do leaf puro; o LOC total do par host+leaf nao cresceu, o pureHelpers encolheu o mesmo tanto). Crescimento por fix de producao + cobertura adicional + realocacao arquitetural, nao inchaco." } diff --git a/config/quality/quality-baseline.json b/config/quality/quality-baseline.json index fb903da1e6..5b13635fe3 100644 --- a/config/quality/quality-baseline.json +++ b/config/quality/quality-baseline.json @@ -341,6 +341,12 @@ "value": 83.18, "direction": "up", "dedicatedGate": true + }, + "rtlPhysicalClasses": { + "value": 1011, + "direction": "down", + "eps": 0, + "_seeded_2026_07_28": "Measured by scripts/check/check-rtl-ratchet.mjs. tests/unit/ui/rtl-logical-classes.test.tsx pins four components and states it is partial (#3541); this bounds the remainder." } }, "_coverage_note": "Pisos anti-flake ~2pt abaixo do real do CI mergeado MEDIDO COM os 135 testes religados (run 27247237268: statements 78.4 / lines 78.4 / functions 83.84 / branches 75.73). O religamento da 6A.1 HONESTIFICOU a regua: os ~82.5 anteriores eram inflados porque modulos nunca importados ficavam fora do denominador do c8. Apertar via --require-tighten na Fase 6A (2026-06-16).", diff --git a/config/quality/test-masking-allowlist.json b/config/quality/test-masking-allowlist.json index e01abf42cc..e15040cb47 100644 --- a/config/quality/test-masking-allowlist.json +++ b/config/quality/test-masking-allowlist.json @@ -109,5 +109,7 @@ "tests/unit/usage-service-hardening.test.ts": "v3.8.49 #7866/#8565/#8013: qwen removido (−3 asserts); o Kimi/Kiro builder-id (uso profileless) passou a ter SUCESSO real em vez de erro de ARN — supportsProfilelessKiroUsage(\"builder-id\") retorna true —, trocando 1 assert de regex de erro por 3 asserts de valor; e os ids de bucket de quota do Antigravity foram atualizados para o catálogo atual. Rodado no HEAD: 23/23 passam. Net 210→209. Verificado legítimo. Prune após v3.8.49 mergear para main.", "tests/unit/virtual-auto-combo.test.ts": "v3.8.49 #7928/#8183: o pooling de contas passou a agrupar conexões web-session do mesmo provider numa entrada lógica com allowedConnectionIds (campo confirmado em open-sse/services/autoCombo/virtualFactory.ts), e o pool no-auth virou uma allowlist fixa (AUTO_COMBO_NOAUTH_ALLOWLIST = opencode, felo-web) — os testes antigos esperavam duplicatas e a inclusão de duckduckgo-web/theoldllm/chipotle, que hoje são corretamente excluídos. Guard dedicado em noauth-autocombo-allowlist.test.ts. Rodado no HEAD: 10/10 passam. Net 39→31. Verificado legítimo. Prune após v3.8.49 mergear para main.", "open-sse/services/__tests__/tierResolver.test.ts": "v3.8.49 #7866: refactor(qwen) remove o provider OAuth legado — o teste \"classifies Qwen as free\" e a entrada de qwen na lista do batch saíram junto com o provider, e os índices do batch desceram de 10 para 9 elementos (net 61→59). Superfície extinta, não enfraquecimento. Verificado legítimo. Prune após v3.8.49 mergear para main.", - "tests/unit/plugins-welcome-banner-e2e.test.ts": "v3.8.50 #9126 (commit 8fac6bcd48): o teste único 'BUILTIN_EVENTS has all 14 events' (13 asserts .ok/.equal) foi reestruturado em 3 testes mais específicos — 'contains only emitted/public events' (assert.deepEqual da lista completa), 'does not advertise dead events' (7 asserts .equal(false) para eventos sem emissor real: onModelSelect/onComboResolve/onRateLimit/onQuotaExhaust/onProviderError/onStreamStart/onStreamEnd) e 'lifecycle events remain represented' (4 asserts .ok). Contrato mais forte (agora também nega presença dos eventos mortos), não mais fraco — a contagem líquida cai (73→61) porque o assert.deepEqual único substitui múltiplos assert.ok redundantes com a mesma cobertura. Asserts restruturados, não removidos sem substituição. Verificado legítimo." + "tests/unit/plugins-welcome-banner-e2e.test.ts": "v3.8.50 #9126 (commit 8fac6bcd48): o teste único 'BUILTIN_EVENTS has all 14 events' (13 asserts .ok/.equal) foi reestruturado em 3 testes mais específicos — 'contains only emitted/public events' (assert.deepEqual da lista completa), 'does not advertise dead events' (7 asserts .equal(false) para eventos sem emissor real: onModelSelect/onComboResolve/onRateLimit/onQuotaExhaust/onProviderError/onStreamStart/onStreamEnd) e 'lifecycle events remain represented' (4 asserts .ok). Contrato mais forte (agora também nega presença dos eventos mortos), não mais fraco — a contagem líquida cai (73→61) porque o assert.deepEqual único substitui múltiplos assert.ok redundantes com a mesma cobertura. Asserts restruturados, não removidos sem substituição. Verificado legítimo.", + "tests/unit/web-tools-translation-2820.test.ts": "v3.8.50 #9343 (commit d969555417): fix(security) exige envelope explicito — JSON puro NAO deve mais ser promovido a tool_calls. Os 5 testes foram REESCRITOS para o contrato oposto (antes: 'promove e valida name/arguments'; agora: 'toolCalls === null e content preservado'), o que naturalmente usa menos asserts: verificar a NAO-promocao custa 2 asserts, verificar o objeto promovido custava 4. Contrato mais restritivo, nao mais fraco (39->35). Verificado legitimo — a inversao esta explicita nos proprios nomes dos testes ('does NOT promote ... (#9343)').", + "tests/unit/deepseek-web-tools-execute-2820.test.ts": "v3.8.50 ed661f2126 (alinhamento ao #9343): o teste 'parses bare JSON reply into OpenAI tool_calls' foi reescrito para o contrato INVERTIDO do fix de seguranca #9343 — JSON puro sem envelope NAO deve mais ser promovido. Verificar a nao-promocao custa 3 asserts (finish_reason stop, sem tool_calls, content preservado verbatim) onde validar o objeto promovido custava 5 (23->21). Mesma classe da entrada web-tools-translation-2820 acima. Contrato mais restritivo, nao mais fraco." } diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml index f65c2b1335..b40b36e8f8 100644 --- a/docker-compose.prod.yml +++ b/docker-compose.prod.yml @@ -29,7 +29,7 @@ services: # ── Redis (Rate Limiter Backend) ────────────────────────────────── redis: - image: redis:8.6.2-alpine + image: redis:8.6.5-alpine container_name: omniroute-redis-prod restart: unless-stopped volumes: diff --git a/docker-compose.yml b/docker-compose.yml index b20b067788..870f73ec9b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -54,11 +54,17 @@ x-common: &common services: # ── Redis (Rate Limiter Backend) ────────────────────────────────── redis: - image: docker.io/library/redis:7-alpine + image: docker.io/library/redis:8.6.5-alpine container_name: omniroute-redis restart: unless-stopped ports: - - "${REDIS_PORT:-6379}:6379" + # Loopback-only by default: this Redis has no `requirepass`, and the app + # containers reach it over the compose network (redis:6379), so the + # published port exists purely for host-side tooling (redis-cli, a local + # `npm run dev`). A bare "6379:6379" binds 0.0.0.0 — that puts an + # unauthenticated Redis on every LAN interface. Override REDIS_BIND_HOST + # only together with a password (`--requirepass`). + - "${REDIS_BIND_HOST:-127.0.0.1}:${REDIS_PORT:-6379}:6379" volumes: - redis-data:/data command: redis-server --save 60 1 --loglevel warning diff --git a/docs/compression/COMPRESSION_LANGUAGE_PACKS.md b/docs/compression/COMPRESSION_LANGUAGE_PACKS.md index eb727dad0b..fad4de2ed0 100644 --- a/docs/compression/COMPRESSION_LANGUAGE_PACKS.md +++ b/docs/compression/COMPRESSION_LANGUAGE_PACKS.md @@ -7,7 +7,7 @@ lastUpdated: 2026-06-28 # Compression Language Packs Caveman compression can load language-specific rule packs in addition to the built-in English rules. -This keeps the core engine stable while allowing Portuguese, Spanish, German, French, Japanese, and +This keeps the core engine stable while allowing Portuguese, Spanish, German, French, Italian, Japanese, and future language packs to evolve independently. ## Location @@ -26,11 +26,12 @@ Current shipped packs (verified against `rules/` directory contents): | Spanish | `rules/es/` | `context`, `dedup`, `filler`, `structural`, `ultra` | | Portuguese (Brazil) | `rules/pt-BR/` | `context`, `dedup`, `filler`, `structural`, `ultra` | | Indonesian | `rules/id/` | `context`, `dedup`, `filler`, `structural`, `ultra` | +| Italian | `rules/it/` | `context`, `dedup`, `filler`, `structural`, `ultra` | | German | `rules/de/` | `context`, `filler`, `structural` | | French | `rules/fr/` | `context`, `filler`, `structural` | | Japanese | `rules/ja/` | `context`, `filler`, `structural` | -> **Parity note:** `en`, `es`, `pt-BR`, and `id` packs have the full 5 categories; `de`, `fr`, `ja` ship 3 categories. The missing `dedup` and `ultra` categories silently fall back to the English built-ins. Contributions welcome to add `dedup.json` and `ultra.json` for the smaller packs. +> **Parity note:** `en`, `es`, `pt-BR`, `id`, and `it` packs have the full 5 categories; `de`, `fr`, `ja` ship 3 categories. The missing `dedup` and `ultra` categories silently fall back to the English built-ins. Contributions welcome to add `dedup.json` and `ultra.json` for the smaller packs. > > The `pt-BR` pack is based on **[Troglodita](https://github.com/leninejunior/troglodita)** by Lenine Júnior — a compression system designed from scratch for Brazilian Portuguese grammar (pleonasm reduction, PT-BR filler removal, technical abbreviations for the dev BR community). > diff --git a/docs/guides/DOCKER_GUIDE.md b/docs/guides/DOCKER_GUIDE.md index 242c215ae6..5233889912 100644 --- a/docs/guides/DOCKER_GUIDE.md +++ b/docs/guides/DOCKER_GUIDE.md @@ -86,19 +86,27 @@ OmniRoute ships four Compose profiles. Pick the one that matches your environmen OmniRoute relies on Redis to back the distributed rate limiter and shared cache. The `redis` service is **always defined** in `docker-compose.yml` (it has no profile gate) and starts alongside any other profile. -| Detail | Value | -| -------------------- | --------------------------------- | -| Image | `redis:7-alpine` | -| Container name | `omniroute-redis` | -| Internal port | `6379` | -| Host port (override) | `REDIS_PORT` (defaults to `6379`) | -| Volume | `omniroute-redis-data` → `/data` | -| Healthcheck | `redis-cli ping` (10s interval) | +| Detail | Value | +| -------------------- | ------------------------------------------- | +| Image | `redis:7-alpine` | +| Container name | `omniroute-redis` | +| Internal port | `6379` | +| Host port (override) | `REDIS_PORT` (defaults to `6379`) | +| Host bind (override) | `REDIS_BIND_HOST` (defaults to `127.0.0.1`) | +| Volume | `omniroute-redis-data` → `/data` | +| Healthcheck | `redis-cli ping` (10s interval) | Related environment variables: - `REDIS_URL` — connection string injected into the app (`redis://redis:6379` by default). - `REDIS_PORT` — host-side port mapping for the Redis container. +- `REDIS_BIND_HOST` — host interface the port is published on. Defaults to `127.0.0.1`. + +> **Why loopback by default:** the sidecar runs without `requirepass`, and the app +> containers reach it over the compose network (`redis:6379`) — the published port is +> only there for host-side tooling (`redis-cli`, a local `npm run dev`). Publishing on +> `0.0.0.0` would expose an unauthenticated Redis to every host on your LAN. If you set +> `REDIS_BIND_HOST=0.0.0.0`, add `--requirepass` to the service `command:` as well. **Disabling Redis** is not recommended (rate limiter will degrade to in-memory fallback). If you must, either remove/comment the `redis:` service block in `docker-compose.yml` or scale it to zero: @@ -170,6 +178,7 @@ Beyond the defaults documented in [ENVIRONMENT.md](../reference/ENVIRONMENT.md), | `OMNIROUTE_WS_BRIDGE_SECRET` | Shared secret for the WebSocket bridge. **Required in production** — set to a strong random string. | unset (must be provided) | | `REDIS_URL` | Connection string for the rate limiter / cache backend | `redis://redis:6379` | | `REDIS_PORT` | Host-side port for the bundled Redis container | `6379` | +| `REDIS_BIND_HOST` | Host interface the bundled Redis port is published on (loopback unless you add AUTH) | `127.0.0.1` | | `AUTO_UPDATE_HOST_REPO_DIR` | Host path mounted into `cli` profile at `/workspace/omniroute` for self-update workflows | `.` (current directory) | | `OMNIROUTE_MEMORY_MB` | Runtime Node heap ceiling for the Docker standalone server; overrides the image fallback above | `512` | | `DASHBOARD_PORT` / `API_PORT` | Override exposed ports for dashboard (20128) and API (20129) | `20128` / `20129` | diff --git a/docs/guides/DOCKER_RELEASE_CHANNELS.md b/docs/guides/DOCKER_RELEASE_CHANNELS.md new file mode 100644 index 0000000000..46b4e44406 --- /dev/null +++ b/docs/guides/DOCKER_RELEASE_CHANNELS.md @@ -0,0 +1,52 @@ +# Docker Release Channels + +OmniRoute publishes separate Docker channels for stable releases, active release-branch testing, and development builds. + +## Channel summary + +| Channel | Source | Mutability | Recommended use | +| --- | --- | --- | --- | +| `:` / `:-web` | Signed/versioned release | Immutable | Production deployments that pin an exact release | +| `:latest` / `:latest-web` | Highest stable release | Mutable stable pointer | Production deployments that intentionally follow stable releases | +| `:next` / `:next-web` | Current default `release/v*` branch | Mutable pre-release pointer | Testing fixes that have landed on the active release branch but are not yet in a stable release | +| `:main` / `:main-web` | `main` branch | Mutable development pointer | Development and integration testing only | + +## Using the pre-release channel + +The `next` channel is rebuilt on every push to the current default `release/v*` branch and is published for both AMD64 and ARM64. Older maintenance branches cannot overwrite it. The channel provides a pullable image for fixes that have merged into the active release branch before the next stable tag is cut. + +```bash +docker pull diegosouzapw/omniroute:next +docker pull diegosouzapw/omniroute:next-web +``` + +For Docker Compose, override the image tag used by the selected profile, then pull and recreate the service: + +```yaml +services: + omniroute: + image: diegosouzapw/omniroute:next +``` + +```bash +docker compose pull +docker compose up -d +``` + +## Safety and rollback + +`next` is a floating pre-release channel. It may change on any push to the active release branch and is **not supported for production use**. Pin the image digest while evaluating a specific build: + +```bash +docker pull diegosouzapw/omniroute:next +docker image inspect diegosouzapw/omniroute:next --format '{{index .RepoDigests 0}}' +``` + +Before testing, back up the OmniRoute data volume or bind-mounted data directory. To roll back, restore the previously used stable version or digest and recreate the container: + +```bash +docker pull diegosouzapw/omniroute: +docker compose up -d +``` + +A release-branch build can never move `latest`; only an eligible stable semantic version may promote the stable pointer. The `next` images retain the release image inspection and blocking CRITICAL-vulnerability gate. diff --git a/docs/guides/REMOTE-MODE.md b/docs/guides/REMOTE-MODE.md index 2a43f03977..2e0e202227 100644 --- a/docs/guides/REMOTE-MODE.md +++ b/docs/guides/REMOTE-MODE.md @@ -121,29 +121,51 @@ There are two supported ways to connect Antigravity to a remote OmniRoute. ### Option A — local login helper (recommended) -Run the OAuth on **your own computer**, where `127.0.0.1` is reachable, and paste -the result into the remote dashboard. The helper talks only to Google — it does -**not** need network access to your VPS, so it works even behind firewalls. +Run the OAuth on **your own computer**, where `127.0.0.1` is reachable. The helper +talks to Google directly, so the consent completes where the dashboard's version +cannot. + +**If you are already connected** (`omniroute connect `), there is nothing to +copy — the helper delivers the credential to that install for you: ```bash # On your LOCAL machine (needs Node.js + a browser): +omniroute connect 192.168.0.15 # once — mints an admin-scoped context token npx omniroute login antigravity -# ↳ opens the Google consent in your browser, captures the callback on a local -# loopback port, exchanges it, and prints a one-line credential blob: +# ↳ opens the Google consent, captures the callback on a local loopback port, +# exchanges it, and POSTs the credential to the active context: # +# Antigravity connected on http://192.168.0.15:20128 (connection abc123). +# Nothing to paste — you can close this terminal. +``` + +The push happens automatically whenever the active context points at another +machine. Force it either way with `--push` / `--no-push`, or aim at a specific +context with `--context `. + +**If your machine cannot reach the VPS** (firewalled, no SSH, air-gapped desk), the +helper still works — it only ever _needs_ Google. Use `--no-push`, or just let the +push fail: it falls back to printing the blob rather than discarding an +authorization you already completed. + +```bash +npx omniroute login antigravity --no-push # omniroute-cred-v1.eyJ2IjoxLCJ... ``` -Then, in the **remote** dashboard: **Providers → Antigravity → Connect**, and -paste the `omniroute-cred-v1.…` blob into the **Step 2** field (it accepts either -a callback URL or a credential blob). OmniRoute decodes it, runs the Cloud Code +Then, in the **remote** dashboard: **Providers → Antigravity → Connect**, and paste +the `omniroute-cred-v1.…` blob into the **Step 2** field (it accepts either a +callback URL or a credential blob). OmniRoute decodes it, runs the Cloud Code onboarding server-side, and persists the connection. -> The blob contains a refresh token — treat it like a password. It is sent once -> over your dashboard connection and stored encrypted at rest. +> The blob contains a refresh token — treat it like a password. On the push path it +> is sent once over your context's authenticated connection; on the paste path, over +> your dashboard connection. Either way it is stored encrypted at rest, and a +> successful push never prints it to your terminal. Flags: `--no-browser` (print the URL instead of auto-opening), `--port ` -(pin the loopback port), `--timeout `. +(pin the loopback port), `--timeout `, `--push` / `--no-push` (override the +automatic delivery), `--context ` (target a specific context). ### Option B — SSH local-forward tunnel diff --git a/docs/guides/TROUBLESHOOTING.md b/docs/guides/TROUBLESHOOTING.md index 801cdbb7e1..ddbc6f0a83 100644 --- a/docs/guides/TROUBLESHOOTING.md +++ b/docs/guides/TROUBLESHOOTING.md @@ -40,19 +40,19 @@ Common problems and solutions for OmniRoute. ## Quick Fixes -| Problem | Solution | -| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No logs written to disk | Set `APP_LOG_TO_FILE=true` and verify call log capture is enabled | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to the latest v3.x release (Zod schema fix for settings persistence shipped in earlier versions) | -| Login crash / blank page | Check Node.js version — see [Node.js Compatibility](#nodejs-compatibility) below | -| `dlopen` / `slice is not valid mach-o file` (macOS) | Run `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — see [macOS native module rebuild](#macos-native-module-rebuild) below | -| Proxy "fetch failed" | Ensure proxy config is set at the correct level — see [Proxy Issues](#proxy-issues) below | +| Problem | Solution | +| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No logs written to disk | Set `APP_LOG_TO_FILE=true` and verify call log capture is enabled | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to the latest v3.x release (Zod schema fix for settings persistence shipped in earlier versions) | +| Login crash / blank page | Check Node.js version — see [Node.js Compatibility](#nodejs-compatibility) below | +| `dlopen` / `slice is not valid mach-o file` (macOS) | Run `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — see [macOS native module rebuild](#macos-native-module-rebuild) below | +| Proxy "fetch failed" | Ensure proxy config is set at the correct level — see [Proxy Issues](#proxy-issues) below | | Docker `curl: (56) Recv failure: Connection reset by peer` | Your Docker port bind may be landing on IPv6. Use `-p 127.0.0.1:20128:20128` to force IPv4, or test with `curl -4`. See [Docker IPv6](#docker-ipv6) below | -| Antivirus quarantines `README.md` | False positive — see [Antivirus false positives](#antivirus-false-positives) below | -| Kaspersky flags the Desktop app as a Trojan | Behavioral false positive on the unsigned installer — see [Antivirus false positives](#antivirus-false-positives) below | +| Antivirus quarantines `README.md` | False positive — see [Antivirus false positives](#antivirus-false-positives) below | +| Kaspersky flags the Desktop app as a Trojan | Behavioral false positive on the unsigned installer — see [Antivirus false positives](#antivirus-false-positives) below | --- @@ -95,7 +95,7 @@ dodge one vendor's heuristic would hurt every reader to satisfy a scanner bug. **This is a false positive from a behavioral heuristic. Nothing is infected.** Kaspersky's `PDM:` prefix means the verdict comes from its Proactive Defense Module (System Watcher), -which judges what the installer *does* rather than matching it against known malware. When +which judges what the installer _does_ rather than matching it against known malware. When it fires, Kaspersky "rolls back" the whole installation — deleting files it had already written — so the app ends up broken or missing. @@ -163,6 +163,36 @@ until it lands, new releases can repeat this. > **Supported secure versions:** `>=22.22.2 <23` or `>=24.0.0 <27`. Node.js 24.x LTS (Krypton) and Node.js 26 are fully supported. +### npm v11+: `better-sqlite3` not installed (Cannot find module) + + + +**Cause:** npm v11 (shipped with Node.js 24+) blocks install scripts for optional +dependencies by default. Since `better-sqlite3` is listed in `optionalDependencies` +and requires native compilation (`node-gyp rebuild`), npm silently skips it. + +**Symptoms:** + +- Server crashes on startup with `Cannot find module 'better-sqlite3'` +- `ls node_modules/better-sqlite3` shows "No such file or directory" +- `npm ls better-sqlite3` shows `(empty)` + +**Fix:** + +1. Approve the install scripts and reinstall: + ```bash + npm approve-scripts better-sqlite3 + npm install + ``` +2. Or install the prebuilt manually: + ```bash + npm pack better-sqlite3@13.0.1 + tar -xzf better-sqlite3-*.tgz -C node_modules + mv node_modules/package node_modules/better-sqlite3 + rm better-sqlite3-*.tgz + ``` +3. Verify it works: `node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"` + ### macOS: `dlopen` / "slice is not valid mach-o file" @@ -306,6 +336,7 @@ see [`docs/guides/KIRO_SETUP.md`](./KIRO_SETUP.md). **Cause:** `docker run -p 20128:20128` publishes on both `0.0.0.0` (IPv4) and `::` (IPv6), but the process inside the container listens on IPv4 only. On hosts where `localhost` resolves to `::1` first, the connection lands on the IPv6 published port with no listener behind it → connection reset. **Fix:** + 1. **Quick diagnostic:** Run `curl -4 http://localhost:20128/v1/models`. If it works with `-4` but fails without, you have an IPv6 bind mismatch. 2. **Permanent fix:** Bind to IPv4 explicitly by using `-p 127.0.0.1:20128:20128` in your `docker run` command: ```bash diff --git a/docs/reference/ENVIRONMENT.md b/docs/reference/ENVIRONMENT.md index 765b34aecb..262f69b6c5 100644 --- a/docs/reference/ENVIRONMENT.md +++ b/docs/reference/ENVIRONMENT.md @@ -201,6 +201,7 @@ OmniRoute uses **SQLite** (via `better-sqlite3`) for all persistence. These vari | `OUTBOUND_SSRF_GUARD_ENABLED` | `true` | `src/shared/network/outboundUrlGuard.ts` | Block provider calls targeting private/loopback/link-local IP ranges. Disable only in isolated test envs. | | `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS` | `false` | `src/shared/network/outboundUrlGuard.ts` | Allow provider URLs pointing to private/local networks (localhost, 192.168.x.x, 10.x.x.x, etc.). **REQUIRED for self-hosted providers** (LM Studio, Ollama, vLLM, Llamafile, Triton, SearXNG). When `false`, the dashboard rejects validation of local URLs. | | `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` | `true` | `src/shared/network/outboundUrlGuard.ts` | Allow adding/validating providers on local/private addresses (127.0.0.1, localhost, LAN, private ranges) — scoped to the provider validation path. **Default `true`** (local-first); set `false` to enforce strict public-only blocking. Cloud-metadata endpoints (169.254.169.254, metadata.google.internal) stay blocked regardless. (#5066) | +| `AUDIO_REMOTE_PROVIDER_NODES` | `false` | `src/app/api/v1/_shared/audioProviderNodes.ts` | Let the `/v1/audio/*` routes (transcriptions, speech, translations) use an OpenAI-compatible provider node hosted outside localhost. Off by default — routing audio to a remote host changes egress identity and must be an explicit operator decision. Loopback/private nodes (localhost, 127.0.0.1, 172.16-31.x) are always allowed and unaffected. (#3963) | ### Hardening Checklist @@ -264,6 +265,7 @@ OmniRoute provides a two-layer defense: request-side injection scanning and resp | `OMNIROUTE_PAYLOAD_RULES_PATH` | `./config/payloadRules.json` | `open-sse/services/payloadRules.ts` | Path to payload manipulation rules JSON file (per-model/protocol upstream tweaks). | | `OMNIROUTE_PAYLOAD_RULES_RELOAD_MS` | `5000` | `open-sse/services/payloadRules.ts` | Reload interval (ms) for hot-reloading the payload rules file. Minimum `1000`. | | `OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS` | `false` | `open-sse/services/model.ts` | Opt-in: route bare `claude-*` model IDs from Claude Code clients through the Claude Code OAuth account instead of requiring a provider prefix. Explicit provider prefixes still win. Also configurable via a dashboard toggle on the Claude provider page. | +| `COMBO_CONCURRENCY_PER_MODEL` | `3` | `open-sse/services/comboConfig.ts` | Per-model concurrency cap for round-robin combos (#9100). The round-robin combo semaphore was hard-capped at 3 concurrent requests per model with no override, serializing higher-concurrency traffic behind that cap. Validated to `>= 1`, clamped to `<= 32`. | --- @@ -505,7 +507,7 @@ Built-in credentials for **localhost development**. For remote deployments, regi | `OMNIROUTE_QODER_WORKSPACE` | Qoder | Alias for `QODER_CLI_WORKSPACE`. | | `QODER_CLI_CONFIG_DIR` | Qoder | Override the Qoder CLI config dir (isolated PAT session, avoids clobbering a browser login). | | `BLACKBOX_WEB_VALIDATED_TOKEN` | Blackbox Web | Frontend `tk` token to send as `validated` on `/api/chat`. Required when Blackbox enforces token matching; otherwise OmniRoute falls back to a random UUID. See issue #2252. | -| `VISION_BRIDGE_BASE_URL` | Vision Bridge guardrail | OpenAI-compatible base URL for non-Anthropic vision-bridge calls. Defaults to the legacy OpenAI URL env or api.openai.com. Point at OmniRoute's `/v1` self-loop or any OpenAI-compat endpoint (Gemini OpenAI-compat, OpenRouter). Issue #2232. | +| `VISION_BRIDGE_BASE_URL` | Vision Bridge guardrail | OpenAI-compatible base URL for non-Anthropic vision-bridge calls. Defaults to the legacy OpenAI URL env or api.openai.com. Point at OmniRoute's `/v1` self-loop or any OpenAI-compat endpoint (Gemini OpenAI-compat, OpenRouter). Issue #2232. When the URL is OmniRoute's own `/v1`, the describe sub-request sends `x-omniroute-admission-bypass: internal` and authenticates with the resolved self-loop credential (`sk_omniroute` sentinel in local mode, or `OMNIROUTE_API_KEY` / `ROUTER_API_KEY` — #1350) so `REQUIRE_API_KEY=true` deployments work. | | `VISION_BRIDGE_API_KEY` | Vision Bridge guardrail | API key for the URL above. Overrides per-provider OpenAI / Google env vars for non-Anthropic vision-bridge calls. Anthropic models keep their dedicated Anthropic key path. Issue #2232. | > [!WARNING] @@ -654,6 +656,8 @@ REQUEST_TIMEOUT_MS (global override) | `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Raw socket timeout (0 = disabled). | | `SHUTDOWN_TIMEOUT_MS` | `30000` | Grace period on SIGTERM/SIGINT before force-exit. | | `OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS` | `120000` | Fallback used by `src/shared/utils/fetchTimeout.ts` when `FETCH_TIMEOUT_MS` is unset. | +| `OMNIROUTE_RELAY_FETCH_TIMEOUT_MS` | `25000` | Relay-specific fetch timeout in `open-sse/utils/proxyFetch.ts` (#9158). A hung relay must fail before the client/agent timeout (~30s) so callers see a relay-specific failure instead of a generic upstream timeout. Capped at `29000` so it always fires first. | +| `OMNIROUTE_RETRY_BACKOFF_MS` | `10` | Shared retry backoff for the direct/relay/proxy retry-once paths in `open-sse/utils/proxyFetch.ts` (#9158). `0` = retry immediately. | | `OMNIROUTE_CHATGPT_TLS_TIMEOUT_MS` | `60000` | Wire-level timeout for the bogdanfinn/tls-client koffi binding (`chatgptTlsClient.ts`). | | `OMNIROUTE_CHATGPT_TLS_GRACE_MS` | `10000` | JS-side grace added on top of the wire timeout when the native binding is wedged. | | `OMNIROUTE_CHATGPT_STREAM_FIRST_BYTE_TIMEOUT_MS` | `30000` (30s) | Max wait for the first streamed byte from the ChatGPT TLS sidecar (`chatgptTlsClient.ts`) before aborting a dead stream. Raise if upstream cold-starts exceed the window. | @@ -667,6 +671,7 @@ REQUEST_TIMEOUT_MS (global override) | `OMNIROUTE_NOTION_TLS_GRACE_MS` | `10000` | JS-side grace added on top of the wire timeout when the native binding is wedged. | | `OMNIROUTE_BROWSER_POOL` | `on` | Shared Playwright browser pool for browser-backed web-cookie chat (`browserPool.ts`); set `off` to disable. | | `WEB_COOKIE_USE_BROWSER` | `0` | Opt a web-cookie chat request into the browser-backed path (`browserBackedChat.ts`); `1` to enable. | +| `OMNIROUTE_LOGIN_BROWSER_PATH` | _(auto-detected)_ | Path to a system Chrome/Edge executable for the Adobe Firefly interactive browser sign-in (`adobeFireflyBrowserLogin.ts`); overrides per-OS auto-detection. | Combo target attempts inherit the resolved upstream request timeout (`FETCH_TIMEOUT_MS`, or `REQUEST_TIMEOUT_MS` when it supplies the fetch default). Set `targetTimeoutMs` in a combo, @@ -714,6 +719,7 @@ The logging system writes to both stdout and rotated log files. All configuratio | `CALL_LOG_RETENTION_DAYS` | `7` | Days to keep request/call log entries in the database. | | `CALL_LOG_MAX_ENTRIES` | `10000` | Max call log entries in the in-memory buffer. | | `CALL_LOGS_TABLE_MAX_ROWS` | `100000` | Max rows in the `call_logs` SQLite table before pruning. | +| `ENABLE_REQUEST_LOGS` | _(unset)_ | Force detailed request logging on or off, overriding the dashboard setting. | | `MAX_PENDING_REQUEST_AGE_MS` | `3600000` (1 hour) | Max age for orphaned active request log entries before in-memory cleanup. | | `CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS` | `true` | Store stream chunks in pipeline artifacts when `call_log_pipeline_enabled=true`. | | `CALL_LOG_PIPELINE_MAX_SIZE_KB` | `512` | Max pipeline call log artifact size in KB when `call_log_pipeline_enabled=true`. | diff --git a/docs/reference/PROVIDER_REFERENCE.md b/docs/reference/PROVIDER_REFERENCE.md index f8b776e976..257f55690a 100644 --- a/docs/reference/PROVIDER_REFERENCE.md +++ b/docs/reference/PROVIDER_REFERENCE.md @@ -1,16 +1,16 @@ --- title: "Provider Reference" version: 3.8.50 -lastUpdated: 2026-07-30 +lastUpdated: 2026-08-05 --- # Provider Reference > **Auto-generated** from `src/shared/constants/providers.ts` — do not edit by hand. > Regenerate with: `npm run gen:provider-reference` -> **Last generated:** 2026-07-30 +> **Last generated:** 2026-08-05 -Total providers: **290**. See category breakdown below. +Total providers: **291**. See category breakdown below. ## Categories @@ -84,7 +84,7 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each | `kimi-web` | `kimi-web` | Kimi Web | Web cookie | [link](https://www.kimi.com/code?aff=omniroute) | Paste access_token from www.kimi.com DevTools → Application → Local Storage. A legacy kimi-auth cookie is also accepted. | — | | `lmarena` | `lma` | Arena (Free) | Web cookie | [link](https://arena.ai) | Paste the full Cookie header from arena.ai (DevTools → Network → request → Cookie). Include arena-auth-prod-v1.0/.1… and cf_clearance/__cf_bm when present. OmniRoute uses Chrome TLS impersonation; if Arena still 403s, set providerSpecificData.recaptchaV3Token from a live browser session. | — | | `microsoft-designer-web` | `msdesigner` | Microsoft Designer (Image Generation) | Web cookie | [link](https://designer.microsoft.com) | Sign in at designer.microsoft.com, then open DevTools → Network, generate an image, and find the request to DallE.ashx?action=GetDallEImagesCogSci. Copy the value of its Authorization: Bearer header (the access_token — no 'Bearer ' prefix). The token is short-lived; this is an unofficial, reverse-engineered integration. | — | -| `muse-spark-web` | `ms-web` | Muse Spark Web (Meta AI) | Web cookie | [link](https://www.meta.ai) | Paste your ecto_1_sess value or full cookie header from meta.ai | emulated | +| `muse-spark-web` | `ms-web` | Muse Spark Web (Meta AI) | Web cookie | [link](https://www.meta.ai) | Paste your ecto_1_sess cookie AND the ecto1:... WS auth token from meta.ai. Capture the ecto1: token in DevTools → Network → WS → the clippy request's Authorization query param. Example: ecto_1_sess=4240a308...NVDg0; ecto1:ABCD... | emulated | | `notion-web` | `nw` | Notion AI Web (Unofficial/Experimental) | Web cookie | [link](https://www.notion.so) | Paste only the token_v2 cookie VALUE from app.notion.com (DevTools → Application → Cookies → token_v2). Do not paste token_v2= or the full Cookie header. Workspace is auto-detected; space_id / notion_user_id are optional. | — | | `perplexity-web` | `pplx-web` | Perplexity Web (Pro/Max) | Web cookie | [link](https://www.perplexity.ai) | Paste your __Secure-next-auth.session-token cookie value from perplexity.ai | emulated | | `poe-web` | `poe` | Poe Web (Subscription) | Web cookie | [link](https://poe.com) | Paste your p-b cookie value from poe.com (DevTools → Application → Cookies → p-b) | — | @@ -97,7 +97,7 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each | `zai-web` | `zw` | Z.ai Web (Free) | Web cookie | [link](https://chat.z.ai) | Paste the full Cookie header from chat.z.ai (must include the token= cookie) | — | | `zenmux-free` | `zmf` | ZenMux Free (Web) | Web cookie | [link](https://zenmux.ai) | Login at zenmux.ai, then export all cookies using EditThisCookie or Cookie-Editor and paste the full Cookie header string here. Refresh every ~30 days. | — | -## API Key Providers (paid / paid-with-free-credits) (195) +## API Key Providers (paid / paid-with-free-credits) (196) | ID | Alias | Name | Tags | Website | Notes | |----|-------|------|------|---------|-------| @@ -117,7 +117,7 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each | `azure-ai` | `azure-ai` | Azure AI Foundry | API key, enterprise | [link](https://learn.microsoft.com/azure/ai-foundry) | Use your Azure AI Foundry key. Base URL can be https://.services.ai.azure.com/openai/v1/ or https://.openai.azure.com/openai/v1/. | | `azure-openai` | `azure` | Azure OpenAI | API key, enterprise | [link](https://azure.microsoft.com/products/ai-services/openai-service) | Use your Azure OpenAI API key. Base URL should be your resource endpoint, for example https://my-resource.openai.azure.com. | | `bai` | `bai` | b.ai | API key | [link](https://b.ai) | Bearer API key for the b.ai OpenAI-compatible LLM gateway (distinct from TheB.AI). Create a key at https://docs.b.ai, then use https://api.b.ai/v1 as the OpenAI-compatible base URL. | -| `baichuan` | `baichuan` | Baichuan | API key | [link](https://baichuan.com) | Get API key at platform.baichuan-ai.com | +| `baichuan` | `baichuan` | Baichuan | API key | [link](https://www.baichuan-ai.com/) | Get API key at platform.baichuan-ai.com | | `baidu` | `baidu` | Baidu (ERNIE) | API key | [link](https://ernie.baidu.com/) | Get API key at console.bce.baidu.com | | `bailian-coding-plan` | `bcp` | Alibaba Token Plan | API key | [link](https://www.alibabacloud.com/help/en/model-studio/token-plan-overview) | — | | `baseten` | `baseten` | Baseten | API key | [link](https://baseten.co) | $30 free trial credits for GPU inference | @@ -130,6 +130,7 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each | `bytez` | `bytez` | Bytez | API key | [link](https://bytez.com) | $1 free credits, refreshes every 4 weeks | | `cerebras` | `cerebras` | Cerebras | API key | [link](https://inference.cerebras.ai) | Free Trial: 1M tokens/day, 30K TPM, 5 RPM — no credit card. | | `charm-hyper` | `charm-hyper` | Charm Hyper | API key | [link](https://hyper.charm.land) | 100 free monthly Hypercredits on signup | +| `cheaperinference` | `cinf` | Cheaper Inference | API key | [link](https://cheaperinference.com/?utm_source=omniroute) | — | | `chenzk` | `chenzk` | Chenzk API | API key | [link](https://chenzk.top) | — | | `chutes` | `chutes` | Chutes.ai | API key, aggregator | [link](https://chutes.ai) | Bearer API key for the Chutes OpenAI-compatible gateway. | | `clarifai` | `clarifai` | Clarifai | API key, enterprise | [link](https://docs.clarifai.com) | Use your Clarifai PAT or app-specific API key. OmniRoute targets the OpenAI-compatible endpoint at https://api.clarifai.com/v2/ext/openai/v1 and authenticates with Authorization: Key . | diff --git a/docs/security/GUARDRAILS.md b/docs/security/GUARDRAILS.md index 68252680c4..8b900359db 100644 --- a/docs/security/GUARDRAILS.md +++ b/docs/security/GUARDRAILS.md @@ -23,12 +23,12 @@ request. Blocking is an explicit decision (`block: true`), never an accident. The registry auto-loads four guardrails in priority order on import (see `registry.ts` → `registerDefaultGuardrails()`): -| Priority | Name | Stage(s) | File | -| -------- | -------------------- | -------------- | --------------------- | -| `5` | `vision-bridge` | `preCall` | `visionBridge.ts` | -| `10` | `pii-masker` | `pre` + `post` | `piiMasker.ts` | -| `20` | `prompt-injection` | `preCall` | `promptInjection.ts` | -| `95` | `credential-masker` | `pre` + `post` | `credentialMasker.ts` | +| Priority | Name | Stage(s) | File | +| -------- | ------------------- | -------------- | --------------------- | +| `5` | `vision-bridge` | `preCall` | `visionBridge.ts` | +| `10` | `pii-masker` | `pre` + `post` | `piiMasker.ts` | +| `20` | `prompt-injection` | `preCall` | `promptInjection.ts` | +| `95` | `credential-masker` | `pre` + `post` | `credentialMasker.ts` | Lower priority numbers run **first**. @@ -44,6 +44,11 @@ Flow: 1. Skip if the target model already supports vision (unless it appears in the forced-bridge list `isVisionBridgeForcedModel`). 2. Extract image parts via `extractImageParts(messages)`. Skip if none. + `extractImageParts` recognizes all three image shapes: OpenAI `image_url`, + Anthropic base64 `source.type:"base64"`, and Anthropic URL + `source.type:"url"` — so Claude-Code-compatible clients (e.g. Zoo Code) + sending `{ type: "image", source: { type: "url", url } }` are described + instead of silently dropped. 3. Load runtime config from `getSettings()` (`visionBridgeEnabled`, `visionBridgeModel`, `visionBridgePrompt`, `visionBridgeTimeout`, `visionBridgeMaxImages`). @@ -53,6 +58,15 @@ Flow: 5. Return `modifiedPayload` + meta (`imagesProcessed`, `processingTimeMs`, `visionModel`). +**Self-loop admission bypass:** when the describe call routes through OmniRoute's +own `/v1` self-loop (non-standard provider model), the sub-request sends +`x-omniroute-admission-bypass: internal` and is authenticated with the resolved +self-loop credential — the local `sk_omniroute` sentinel in local mode, or the +operator-configured `OMNIROUTE_API_KEY` / `ROUTER_API_KEY` env key (#1350) so +`REQUIRE_API_KEY=true` deployments can still run the describe call. The bypass +is only honored for those exact credentials, so external clients cannot use the +header to skip admission. + Defaults live in `src/shared/constants/visionBridgeDefaults.ts`. The guardrail exposes a `deps` constructor option so tests can inject fake `getSettings` and `callVisionModel` implementations. @@ -82,11 +96,11 @@ Detects adversarial structures in user-supplied content and enforces the configured policy. Behavior is driven by environment variables and constructor options: -| Setting | Env var | Default | Effect | -| --------------- | ----------------------------------------------- | ------- | --------------------------------------- | -| Enabled | `INPUT_SANITIZER_ENABLED` | `true` | When `false`, guardrail short-circuits. | -| Mode | `INJECTION_GUARD_MODE` / `INPUT_SANITIZER_MODE` | `warn` | Injection policy: `block`, `warn`, or `log`. (`redact` is accepted for back-compat but does **not** strip injection text; request PII rewrite is controlled by `PII_REDACTION_ENABLED`.) | -| Block threshold | `blockThreshold` option / `INPUT_SANITIZER_BLOCK_THRESHOLD` (alias `INJECTION_GUARD_BLOCK_THRESHOLD`) | `high` | Minimum severity required to block. Medium is observe-only at default. | +| Setting | Env var | Default | Effect | +| --------------- | ----------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Enabled | `INPUT_SANITIZER_ENABLED` | `true` | When `false`, guardrail short-circuits. | +| Mode | `INJECTION_GUARD_MODE` / `INPUT_SANITIZER_MODE` | `warn` | Injection policy: `block`, `warn`, or `log`. (`redact` is accepted for back-compat but does **not** strip injection text; request PII rewrite is controlled by `PII_REDACTION_ENABLED`.) | +| Block threshold | `blockThreshold` option / `INPUT_SANITIZER_BLOCK_THRESHOLD` (alias `INJECTION_GUARD_BLOCK_THRESHOLD`) | `high` | Minimum severity required to block. Medium is observe-only at default. | **Mode precedence** (`getMode`): caller `options.mode` → `INJECTION_GUARD_MODE` **DB feature-flag override** (Dashboard → Settings → @@ -252,15 +266,15 @@ Guardrails that throw are recorded with `error: ` and logged via Environment variables read by the built-in guardrails: -| Variable | Used by | Effect | -| ------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------ | -| `INPUT_SANITIZER_ENABLED` | `prompt-injection` | Set `false` to disable detection entirely. | -| `INPUT_SANITIZER_MODE` | `prompt-injection` | Injection policy: `warn`, `block`, or `log`. Legacy value `redact` does not rewrite injection text. | -| `INJECTION_GUARD_MODE` | `prompt-injection` | Mode for the injection guard; also a DB feature flag that **overrides** the env vars (DB > ENV). | -| `INPUT_SANITIZER_BLOCK_THRESHOLD` | `prompt-injection` | Minimum severity that `MODE=block` rejects: `high` (default), `medium`, or `low`. | -| `INJECTION_GUARD_BLOCK_THRESHOLD` | `prompt-injection` | Legacy alias for `INPUT_SANITIZER_BLOCK_THRESHOLD`. | -| `PII_REDACTION_ENABLED` | `pii-masker` | When `true`, request PII is redacted (independent of injection mode). | -| `PII_RESPONSE_SANITIZATION` / `_MODE` | `pii-masker` (downstream) | Controls response-side masker behavior. | +| Variable | Used by | Effect | +| ------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- | +| `INPUT_SANITIZER_ENABLED` | `prompt-injection` | Set `false` to disable detection entirely. | +| `INPUT_SANITIZER_MODE` | `prompt-injection` | Injection policy: `warn`, `block`, or `log`. Legacy value `redact` does not rewrite injection text. | +| `INJECTION_GUARD_MODE` | `prompt-injection` | Mode for the injection guard; also a DB feature flag that **overrides** the env vars (DB > ENV). | +| `INPUT_SANITIZER_BLOCK_THRESHOLD` | `prompt-injection` | Minimum severity that `MODE=block` rejects: `high` (default), `medium`, or `low`. | +| `INJECTION_GUARD_BLOCK_THRESHOLD` | `prompt-injection` | Legacy alias for `INPUT_SANITIZER_BLOCK_THRESHOLD`. | +| `PII_REDACTION_ENABLED` | `pii-masker` | When `true`, request PII is redacted (independent of injection mode). | +| `PII_RESPONSE_SANITIZATION` / `_MODE` | `pii-masker` (downstream) | Controls response-side masker behavior. | The Vision Bridge reads runtime config from the DB-backed settings store (`getSettings()`), not env vars: `visionBridgeEnabled`, `visionBridgeModel`, diff --git a/electron/package.json b/electron/package.json index 60a0ada9bf..a2bb7614b5 100644 --- a/electron/package.json +++ b/electron/package.json @@ -43,7 +43,8 @@ "appId": "online.omniroute.desktop", "productName": "OmniRoute", "copyright": "Copyright © 2025 OmniRoute", - "buildDependenciesFromSource": true, + "buildDependenciesFromSource": false, + "npmRebuild": false, "directories": { "output": "dist-electron", "buildResources": "assets" diff --git a/next.config.mjs b/next.config.mjs index 8eccf141e3..e1c2e7cc1a 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -173,6 +173,10 @@ const nextConfig = { serverActions: { bodySizeLimit: process.env.OMNIROUTE_SERVER_ACTIONS_BODY_LIMIT || "50mb", }, + // Reduce peak heap during production builds (Next.js 15+). + webpackMemoryOptimizations: true, + // Run webpack in a separate Node worker, lowering main-process memory. + webpackBuildWorker: true, // Next.js proxy (middleware) has a default 10MB body clone limit. File // uploads (OpenAI-compatible /v1/files) routinely exceed this. Match the // 512 MB server-side cap; tune via env if needed. diff --git a/open-sse/config/anthropicHeaders.ts b/open-sse/config/anthropicHeaders.ts index 2edc489d1e..cf6710c4fe 100644 --- a/open-sse/config/anthropicHeaders.ts +++ b/open-sse/config/anthropicHeaders.ts @@ -57,6 +57,11 @@ export const FORWARDABLE_CLIENT_BETAS = Object.freeze([ "context-1m-2025-08-07", "code-execution-2025-08-25", "skills-2025-10-02", + // effort-2025-11-24 is a client-negotiated beta (Claude Code sends it on every + // request). selectBetaFlags no longer force-adds it as a side-effect of the ATU + // gate (#9505), so a client that sent it must keep it through the merge — + // otherwise its effort negotiation is silently dropped. + "effort-2025-11-24", ]); /** diff --git a/open-sse/config/antigravityUpstream.ts b/open-sse/config/antigravityUpstream.ts index 1ed328d7f3..aa015ef3ae 100644 --- a/open-sse/config/antigravityUpstream.ts +++ b/open-sse/config/antigravityUpstream.ts @@ -12,6 +12,12 @@ export const ANTIGRAVITY_BOOTSTRAP_BASE_URLS = Object.freeze([ "https://cloudcode-pa.googleapis.com", ]); +export const ANTIGRAVITY_ONBOARD_PATH = "/v1internal:onboardUser"; + +export function getAntigravityOnboardUrls(): string[] { + return ANTIGRAVITY_BOOTSTRAP_BASE_URLS.map((base) => `${base}${ANTIGRAVITY_ONBOARD_PATH}`); +} + const ANTIGRAVITY_MODELS_PATH = "/v1internal:models"; const ANTIGRAVITY_FETCH_AVAILABLE_MODELS_PATH = "/v1internal:fetchAvailableModels"; diff --git a/open-sse/config/audioRegistry.ts b/open-sse/config/audioRegistry.ts index 0419622f36..6ee45169fd 100644 --- a/open-sse/config/audioRegistry.ts +++ b/open-sse/config/audioRegistry.ts @@ -14,6 +14,14 @@ interface AudioModel { export interface AudioProvider { id: string; + /** + * Provider key to look credentials up under. Dynamic provider nodes are exposed + * to callers under their `prefix` (that is what appears in `provider/model`), + * but their connections are stored under the node **id** — without this the + * credential lookup silently misses. Absent for hardcoded providers, where the + * id already is the credential key. + */ + credentialProviderId?: string; baseUrl: string; authType: string; authHeader: string; @@ -564,27 +572,49 @@ export function getSpeechProvider(providerId: string): AudioProvider | null { } export interface ProviderNodeRow { + /** provider_node row id — the key its connections (and credentials) are stored under. */ + id?: string; prefix: string; name: string; baseUrl: string; apiType?: string; } +/** Hosts reachable only from the operator's machine/Docker network. */ +function isLoopbackNodeHost(baseUrl: string): boolean { + try { + const hostname = new URL(baseUrl).hostname; + return ( + hostname === "localhost" || + hostname === "127.0.0.1" || + /^172\.(1[6-9]|2[0-9]|3[0-1])\.\d{1,3}\.\d{1,3}$/.test(hostname) + ); + } catch { + return false; + } +} + /** * Build a dynamic AudioProvider from a provider_node DB entry. - * Only used for local providers (localhost/127.0.0.1) — remote nodes are - * excluded by the caller to prevent auth bypass and SSRF. + * + * Loopback nodes keep `authType: "none"` — a local Ollama/LM Studio has no key and + * must not be blocked on a missing credential. A remote node is the opposite: it is + * only reachable when the operator opted in, and it must present the credential + * stored on its connection, so it is built as an api-key provider keyed by the node + * id (`credentialProviderId`) rather than by the caller-facing prefix. */ export function buildDynamicAudioProvider(node: ProviderNodeRow, audioPath: string): AudioProvider { if (!node.prefix || !node.baseUrl) { throw new Error(`Invalid provider_node: missing prefix or baseUrl`); } const baseUrl = node.baseUrl.replace(/\/+$/, ""); + const isLocal = isLoopbackNodeHost(node.baseUrl); return { id: node.prefix, + ...(node.id ? { credentialProviderId: node.id } : {}), baseUrl: `${baseUrl}${audioPath}`, - authType: "none", - authHeader: "none", + authType: isLocal ? "none" : "apikey", + authHeader: isLocal ? "none" : "bearer", models: [], }; } diff --git a/open-sse/config/cliFingerprints.ts b/open-sse/config/cliFingerprints.ts index da65fce35b..b219cd1363 100644 --- a/open-sse/config/cliFingerprints.ts +++ b/open-sse/config/cliFingerprints.ts @@ -271,6 +271,7 @@ function stripInternalBodyFields(body: unknown): unknown { const record = body as Record; delete record._claudeCodeRequiresLowercaseToolNames; delete record._nativeCodexPassthrough; + delete record._nativeXaiResponsesPassthrough; delete record._omnirouteResponsesStore; return body; } diff --git a/open-sse/config/embeddingRegistry.ts b/open-sse/config/embeddingRegistry.ts index 4882b5373a..f8de0e18e9 100644 --- a/open-sse/config/embeddingRegistry.ts +++ b/open-sse/config/embeddingRegistry.ts @@ -372,6 +372,21 @@ export const EMBEDDING_PROVIDERS: Record = { models: [], }, + // Ollama Local — OpenAI-compatible embeddings endpoint. Ollama exposes its + // own model catalog, but these common embedding models are useful defaults + // for model selection and validation. + "ollama-local": { + id: "ollama-local", + baseUrl: "http://localhost:11434/v1/embeddings", + authType: "none", + authHeader: "none", + models: [ + { id: "embeddinggemma", name: "EmbeddingGemma" }, + { id: "nomic-embed-text", name: "Nomic Embed Text" }, + { id: "bge-m3", name: "BGE M3" }, + ], + }, + // Issue #6660: Mixedbread AI — OpenAI-compatible /v1/embeddings, free tier // available (API key via signup, no card required). Model ids are the // upstream-qualified "mixedbread-ai/" form, mirroring how `together`/ diff --git a/open-sse/config/freeModelCatalog.data.ts b/open-sse/config/freeModelCatalog.data.ts index 9893a08fd4..42ec705f8c 100644 --- a/open-sse/config/freeModelCatalog.data.ts +++ b/open-sse/config/freeModelCatalog.data.ts @@ -115,10 +115,7 @@ export const FREE_MODEL_BUDGETS: FreeModelBudget[] = [ { provider: "cerebras", modelId: "zai-glm-4.7", displayName: "GLM 4.7", monthlyTokens: 30000000, creditTokens: 0, freeType: "recurring-daily", poolKey: "cerebras", tos: "caution" }, { provider: "cerebras", modelId: "gpt-oss-120b", displayName: "GPT OSS 120B", monthlyTokens: 30000000, creditTokens: 0, freeType: "recurring-daily", poolKey: "cerebras", tos: "caution" }, { provider: "cloudflare-ai", modelId: "@cf/meta/llama-3.3-70b-instruct", displayName: "Llama 3.3 70B (🆓 ~150 resp/day)", monthlyTokens: 30000000, creditTokens: 0, freeType: "recurring-daily", poolKey: "cloudflare-ai", tos: "caution" }, - { provider: "cloudflare-ai", modelId: "@cf/meta/llama-3.1-8b-instruct", displayName: "Llama 3.1 8B (🆓)", monthlyTokens: 0, creditTokens: 0, freeType: "recurring-daily", poolKey: "cloudflare-ai", tos: "caution" }, { provider: "cloudflare-ai", modelId: "@cf/google/gemma-3-12b-it", displayName: "Gemma 3 12B (🆓)", monthlyTokens: 0, creditTokens: 0, freeType: "recurring-daily", poolKey: "cloudflare-ai", tos: "caution" }, - { provider: "cloudflare-ai", modelId: "@cf/mistral/mistral-7b-instruct-v0.2-lora", displayName: "Mistral 7B (🆓)", monthlyTokens: 0, creditTokens: 0, freeType: "recurring-daily", poolKey: "cloudflare-ai", tos: "caution" }, - { provider: "cloudflare-ai", modelId: "@cf/qwen/qwen2.5-coder-15b-instruct", displayName: "Qwen 2.5 Coder 15B (🆓)", monthlyTokens: 0, creditTokens: 0, freeType: "recurring-daily", poolKey: "cloudflare-ai", tos: "caution" }, { provider: "cloudflare-ai", modelId: "@cf/qwen/qwen2.5-coder-32b-instruct", displayName: "Qwen 2.5 Coder 32B (🆓)", monthlyTokens: 0, creditTokens: 0, freeType: "recurring-daily", poolKey: "cloudflare-ai", tos: "caution" }, { provider: "cloudflare-ai", modelId: "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b", displayName: "DeepSeek R1 Distill 32B (🆓)", monthlyTokens: 0, creditTokens: 0, freeType: "recurring-daily", poolKey: "cloudflare-ai", tos: "caution" }, { provider: "cloudflare-ai", modelId: "@cf/meta/llama-3.3-70b-instruct-fp8-fast", displayName: "Llama 3.3 70B (FP8 Fast 🆓)", monthlyTokens: 0, creditTokens: 0, freeType: "recurring-daily", poolKey: "cloudflare-ai", tos: "caution" }, diff --git a/open-sse/config/providers/index.ts b/open-sse/config/providers/index.ts index e586b42301..b12a6963f6 100644 --- a/open-sse/config/providers/index.ts +++ b/open-sse/config/providers/index.ts @@ -1,4 +1,5 @@ import type { RegistryEntry } from "./shared.ts"; +import { unorouterProvider } from "./registry/unorouter/index.ts"; import { aimlapiProvider } from "./registry/aimlapi/index.ts"; import { byteplusProvider } from "./registry/byteplus/index.ts"; @@ -444,4 +445,5 @@ export const REGISTRY: Record = { hcnsec: hcnsecProvider, promptql: promptqlProvider, hyperagent: hyperagentProvider, + unorouter: unorouterProvider, }; diff --git a/open-sse/config/providers/registry/cloudflare-ai/index.ts b/open-sse/config/providers/registry/cloudflare-ai/index.ts index f90d67137a..907138aa48 100644 --- a/open-sse/config/providers/registry/cloudflare-ai/index.ts +++ b/open-sse/config/providers/registry/cloudflare-ai/index.ts @@ -12,10 +12,7 @@ export const cloudflare_aiProvider: RegistryEntry = { // 10K Neurons/day free: ~150 LLM responses or 500s Whisper audio — global edge models: [ { id: "@cf/meta/llama-3.3-70b-instruct", name: "Llama 3.3 70B (🆓 ~150 resp/day)" }, - { id: "@cf/meta/llama-3.1-8b-instruct", name: "Llama 3.1 8B (🆓)" }, { id: "@cf/google/gemma-3-12b-it", name: "Gemma 3 12B (🆓)" }, - { id: "@cf/mistral/mistral-7b-instruct-v0.2-lora", name: "Mistral 7B (🆓)" }, - { id: "@cf/qwen/qwen2.5-coder-15b-instruct", name: "Qwen 2.5 Coder 15B (🆓)" }, { id: "@cf/qwen/qwen2.5-coder-32b-instruct", name: "Qwen 2.5 Coder 32B (🆓)" }, { id: "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b", name: "DeepSeek R1 Distill 32B (🆓)" }, // Sweep 2026-06-19: + current Workers AI catalog ids (developers.cloudflare.com/workers-ai/models). diff --git a/open-sse/config/providers/registry/command-code/index.ts b/open-sse/config/providers/registry/command-code/index.ts index 6bc96c2372..affe935180 100644 --- a/open-sse/config/providers/registry/command-code/index.ts +++ b/open-sse/config/providers/registry/command-code/index.ts @@ -17,6 +17,7 @@ export const command_codeProvider: RegistryEntry = { id: "claude-opus-4-7", name: "Claude Opus 4.7 (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 200000, maxOutputTokens: 32000, }, @@ -24,6 +25,7 @@ export const command_codeProvider: RegistryEntry = { id: "claude-opus-4-6", name: "Claude Opus 4.6 (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 200000, maxOutputTokens: 32000, }, @@ -31,6 +33,7 @@ export const command_codeProvider: RegistryEntry = { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6 (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 200000, maxOutputTokens: 16384, }, @@ -38,6 +41,7 @@ export const command_codeProvider: RegistryEntry = { id: "claude-haiku-4-5-20251001", name: "Claude Haiku 4.5 (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 200000, maxOutputTokens: 8192, }, @@ -45,6 +49,7 @@ export const command_codeProvider: RegistryEntry = { id: "gpt-5.5", name: "GPT-5.5 (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 256000, maxOutputTokens: 128000, }, @@ -52,6 +57,7 @@ export const command_codeProvider: RegistryEntry = { id: "gpt-5.4", name: "GPT-5.4 (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 256000, maxOutputTokens: 128000, }, @@ -59,6 +65,7 @@ export const command_codeProvider: RegistryEntry = { id: "gpt-5.3-codex", name: "GPT-5.3 Codex (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 256000, maxOutputTokens: 128000, }, @@ -66,6 +73,7 @@ export const command_codeProvider: RegistryEntry = { id: "gpt-5.4-mini", name: "GPT-5.4 Mini (CC)", supportsReasoning: false, + supportsVision: true, contextLength: 256000, maxOutputTokens: 128000, }, @@ -87,6 +95,7 @@ export const command_codeProvider: RegistryEntry = { id: "moonshotai/Kimi-K2.6", name: "Kimi K2.6 (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 262144, maxOutputTokens: 65536, }, @@ -94,6 +103,7 @@ export const command_codeProvider: RegistryEntry = { id: "moonshotai/Kimi-K2.5", name: "Kimi K2.5 (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 262144, maxOutputTokens: 65536, }, @@ -136,6 +146,7 @@ export const command_codeProvider: RegistryEntry = { id: "Qwen/Qwen3.6-Plus", name: "Qwen 3.6 Plus (CC)", supportsReasoning: true, + supportsVision: true, contextLength: 1000000, maxOutputTokens: 32768, }, diff --git a/open-sse/config/providers/registry/deepseek/web/index.ts b/open-sse/config/providers/registry/deepseek/web/index.ts index ba20e12e0d..08fc142564 100644 --- a/open-sse/config/providers/registry/deepseek/web/index.ts +++ b/open-sse/config/providers/registry/deepseek/web/index.ts @@ -9,27 +9,49 @@ export const deepseek_webProvider: RegistryEntry = { authType: "apikey", authHeader: "bearer", models: [ - { id: "deepseek-v4-pro", name: "DeepSeek V4 Pro", toolCalling: false }, - { id: "deepseek-v4-pro-think", name: "DeepSeek V4 Pro Think", supportsReasoning: true }, - { id: "deepseek-v4-pro-search", name: "DeepSeek V4 Pro Search", toolCalling: false }, + { id: "deepseek-v4-pro", name: "DeepSeek V4 Pro", toolCalling: true }, + { + id: "deepseek-v4-pro-think", + name: "DeepSeek V4 Pro Think", + toolCalling: true, + supportsReasoning: true, + }, + { id: "deepseek-v4-pro-search", name: "DeepSeek V4 Pro Search", toolCalling: true }, { id: "deepseek-v4-pro-think-search", name: "DeepSeek V4 Pro Think+Search", + toolCalling: true, supportsReasoning: true, }, - { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash", toolCalling: false }, - { id: "deepseek-v4-flash-think", name: "DeepSeek V4 Flash Think", supportsReasoning: true }, - { id: "deepseek-v4-flash-search", name: "DeepSeek V4 Flash Search", toolCalling: false }, + { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash", toolCalling: true }, + { + id: "deepseek-v4-flash-think", + name: "DeepSeek V4 Flash Think", + toolCalling: true, + supportsReasoning: true, + }, + { id: "deepseek-v4-flash-search", name: "DeepSeek V4 Flash Search", toolCalling: true }, { id: "deepseek-v4-flash-think-search", name: "DeepSeek V4 Flash Think+Search", + toolCalling: true, supportsReasoning: true, }, - { id: "deepseek-chat", name: "DeepSeek Chat", toolCalling: false }, - { id: "deepseek-reasoner", name: "DeepSeek Reasoner", supportsReasoning: true }, - { id: "DeepSeek-R1", name: "DeepSeek R1", supportsReasoning: true }, - { id: "DeepSeek-R1-Search", name: "DeepSeek R1 Search", supportsReasoning: true }, - { id: "DeepSeek-V3.2", name: "DeepSeek V3.2", toolCalling: false }, - { id: "DeepSeek-Search", name: "DeepSeek Search", toolCalling: false }, + { id: "deepseek-chat", name: "DeepSeek Chat", toolCalling: true }, + { + id: "deepseek-reasoner", + name: "DeepSeek Reasoner", + toolCalling: true, + supportsReasoning: true, + }, + { id: "DeepSeek-R1", name: "DeepSeek R1", toolCalling: true, supportsReasoning: true }, + { + id: "DeepSeek-R1-Search", + name: "DeepSeek R1 Search", + toolCalling: true, + supportsReasoning: true, + }, + { id: "DeepSeek-V3.2", name: "DeepSeek V3.2", toolCalling: true }, + { id: "DeepSeek-Search", name: "DeepSeek Search", toolCalling: true }, ], }; diff --git a/open-sse/config/providers/registry/github/index.ts b/open-sse/config/providers/registry/github/index.ts index 9513afdc1e..3adda64763 100644 --- a/open-sse/config/providers/registry/github/index.ts +++ b/open-sse/config/providers/registry/github/index.ts @@ -122,9 +122,24 @@ export const githubProvider: RegistryEntry = { contextLength: 1000000, maxOutputTokens: 64000, }, - { id: "gpt-5.6-sol", name: "GPT-5.6 Sol", maxOutputTokens: 128000 }, - { id: "gpt-5.6-terra", name: "GPT-5.6 Terra", maxOutputTokens: 128000 }, - { id: "gpt-5.6-luna", name: "GPT-5.6 Luna", maxOutputTokens: 128000 }, + { + id: "gpt-5.6-sol", + name: "GPT-5.6 Sol", + targetFormat: "openai-responses", + maxOutputTokens: 128000, + }, + { + id: "gpt-5.6-terra", + name: "GPT-5.6 Terra", + targetFormat: "openai-responses", + maxOutputTokens: 128000, + }, + { + id: "gpt-5.6-luna", + name: "GPT-5.6 Luna", + targetFormat: "openai-responses", + maxOutputTokens: 128000, + }, { id: "gpt-5.5", name: "GPT-5.5", ...GPT_5_5_CODEX_CAPABILITIES, maxOutputTokens: 128000 }, { id: "gpt-5.4", diff --git a/open-sse/config/providers/registry/github/retiredModels.ts b/open-sse/config/providers/registry/github/retiredModels.ts new file mode 100644 index 0000000000..cc412401f9 --- /dev/null +++ b/open-sse/config/providers/registry/github/retiredModels.ts @@ -0,0 +1,12 @@ +const RETIRED_GITHUB_COPILOT_MODEL_IDS = new Set([ + "gemini-2.5-pro", + "gemini-3-flash", + "gemini-3-flash-preview", +]); + +export function isRetiredGitHubCopilotModelId(providerId: unknown, modelId: unknown): boolean { + const provider = typeof providerId === "string" ? providerId.trim().toLowerCase() : ""; + if (provider !== "github" && provider !== "gh") return false; + if (typeof modelId !== "string") return false; + return RETIRED_GITHUB_COPILOT_MODEL_IDS.has(modelId.trim().toLowerCase()); +} diff --git a/open-sse/config/providers/registry/minimax/cn/index.ts b/open-sse/config/providers/registry/minimax/cn/index.ts index 2274b01c39..8046b9e9d6 100644 --- a/open-sse/config/providers/registry/minimax/cn/index.ts +++ b/open-sse/config/providers/registry/minimax/cn/index.ts @@ -12,6 +12,7 @@ export const minimax_cnProvider: RegistryEntry = { authType: "apikey", authHeader: "bearer", headers: getAnthropicCompatHeaders(), + ensureThinkingSignature: true, models: [ // Keep parity with minimax to ensure model discovery works for minimax-cn connections. // #3110: MiniMax M3 — frontier coding model with 1M context diff --git a/open-sse/config/providers/registry/minimax/index.ts b/open-sse/config/providers/registry/minimax/index.ts index 3033fccb46..6f1f80f51f 100644 --- a/open-sse/config/providers/registry/minimax/index.ts +++ b/open-sse/config/providers/registry/minimax/index.ts @@ -12,6 +12,7 @@ export const minimaxProvider: RegistryEntry = { authType: "apikey", authHeader: "bearer", headers: getAnthropicCompatHeaders(), + ensureThinkingSignature: true, models: [ // T12/T28: MiniMax default upgraded from M2.5 to M2.7 // #3110: MiniMax M3 — frontier coding model with 1M context diff --git a/open-sse/config/providers/registry/nanogpt/index.ts b/open-sse/config/providers/registry/nanogpt/index.ts index 9bd165deee..9947938ffb 100644 --- a/open-sse/config/providers/registry/nanogpt/index.ts +++ b/open-sse/config/providers/registry/nanogpt/index.ts @@ -7,6 +7,7 @@ export const nanogptProvider: RegistryEntry = { format: "openai", executor: "default", baseUrl: "https://nano-gpt.com/api/v1/chat/completions", + modelsUrl: "https://nano-gpt.com/api/v1/models", authType: "apikey", authHeader: "bearer", models: CHAT_OPENAI_COMPAT_MODELS.nanogpt, diff --git a/open-sse/config/providers/registry/novita/index.ts b/open-sse/config/providers/registry/novita/index.ts index cd57d24523..48227c6a14 100644 --- a/open-sse/config/providers/registry/novita/index.ts +++ b/open-sse/config/providers/registry/novita/index.ts @@ -11,5 +11,175 @@ export const novitaProvider: RegistryEntry = { modelsUrl: "https://api.novita.ai/openai/v1/models", authType: "apikey", authHeader: "bearer", - models: [{ id: "meta-llama/llama-3.1-8b-instruct", name: "Llama 3.1 8B Instruct" }], + // Catalog seeded from a live GET https://api.novita.ai/openai/v1/models, the listing + // `modelsUrl` already points at. Every id below reports `status: 1` (serving) there, and + // `contextLength` / `maxOutputTokens` / `supportsReasoning` mirror that response's + // `context_size`, `max_output_tokens` and `features` fields. + // + // `supportsVision` is the exception: it is set from an actual image request per id, not + // from the listing's `input_modalities`. Those two disagree — `openai/gpt-oss-120b` + // advertises `input_modalities: ["text","image"]`, accepts an image part with HTTP 200, + // and then answers that it cannot see the image, so it is listed here without the flag. + // Models that genuinely lack vision instead fail closed with + // `400 "model features vision not support"`, so a 200 alone does not confirm the + // capability — the reply has to be checked. Each flag below was verified by sending a + // two-colour test image and requiring both colours back. + // + // Curated rather than exhaustive: the listing carries 143 entries unauthenticated and 304 + // with an API key (the former is a subset of the latter), including retired + // generations (`status: 4`, e.g. `meta-llama/llama-3-8b-instruct`) and unnamespaced staging + // ids (`bunny`, `ai_infer_test_2`, `dev/glm46`) that no caller should be offered. This keeps + // one entry per serving family/generation, matching the granularity of the other + // multi-vendor OpenAI-compatible hosts (fireworks, groq, nvidia). `modelsUrl` still drives + // dashboard discovery for anything not listed here. + models: [ + // DeepSeek + { + id: "deepseek/deepseek-v4-pro", + name: "DeepSeek V4 Pro", + supportsReasoning: true, + contextLength: 1048576, + maxOutputTokens: 393216, + }, + { + id: "deepseek/deepseek-v4-flash", + name: "DeepSeek V4 Flash", + supportsReasoning: true, + contextLength: 1048576, + maxOutputTokens: 393216, + }, + { + id: "deepseek/deepseek-v3.2", + name: "DeepSeek V3.2", + supportsReasoning: true, + contextLength: 163840, + maxOutputTokens: 65536, + }, + // Moonshot Kimi + { + id: "moonshotai/kimi-k3", + name: "Kimi K3", + supportsReasoning: true, + supportsVision: true, + contextLength: 1048576, + maxOutputTokens: 1048576, + }, + { + id: "moonshotai/kimi-k2.7-code", + name: "Kimi K2.7 Code", + supportsReasoning: true, + supportsVision: true, + contextLength: 262144, + maxOutputTokens: 262144, + }, + { + id: "moonshotai/kimi-k2.6", + name: "Kimi K2.6", + supportsReasoning: true, + supportsVision: true, + contextLength: 262144, + maxOutputTokens: 262144, + }, + // Z.ai GLM + { + id: "zai-org/glm-5.2", + name: "GLM 5.2", + supportsReasoning: true, + contextLength: 1048576, + maxOutputTokens: 131072, + }, + { + id: "zai-org/glm-5.1", + name: "GLM 5.1", + supportsReasoning: true, + contextLength: 204800, + maxOutputTokens: 131072, + }, + { + id: "zai-org/glm-4.7", + name: "GLM 4.7", + supportsReasoning: true, + contextLength: 204800, + maxOutputTokens: 131072, + }, + // MiniMax + { + id: "minimax/minimax-m3", + name: "MiniMax M3", + supportsReasoning: true, + supportsVision: true, + contextLength: 1000000, + maxOutputTokens: 131072, + }, + { + id: "minimax/minimax-m2.7", + name: "MiniMax M2.7", + supportsReasoning: true, + contextLength: 204800, + maxOutputTokens: 131072, + }, + // Qwen + { + id: "qwen/qwen3.7-max", + name: "Qwen3.7 Max", + supportsReasoning: true, + contextLength: 1000000, + maxOutputTokens: 65536, + }, + { + id: "qwen/qwen3.6-plus", + name: "Qwen3.6 Plus", + supportsReasoning: true, + supportsVision: true, + contextLength: 1000000, + maxOutputTokens: 65536, + }, + { + id: "qwen/qwen3.5-397b-a17b", + name: "Qwen3.5 397B A17B", + supportsReasoning: true, + supportsVision: true, + contextLength: 262144, + maxOutputTokens: 65536, + }, + { + id: "qwen/qwen3-coder-480b-a35b-instruct", + name: "Qwen3 Coder 480B", + contextLength: 262144, + maxOutputTokens: 65536, + }, + // Xiaomi MiMo / OpenAI gpt-oss / Google Gemma + { + id: "xiaomimimo/mimo-v2.5-pro", + name: "MiMo V2.5 Pro", + supportsReasoning: true, + contextLength: 1048576, + maxOutputTokens: 131072, + }, + { + // No `supportsVision`: the listing claims `image` input, but a live image request + // returns 200 and "I cannot see the image" (retried 4x, data-URI and remote URL). + // Matches how groq / fireworks / nvidia / siliconflow / cerebras list this id here. + id: "openai/gpt-oss-120b", + name: "OpenAI gpt-oss-120b", + supportsReasoning: true, + contextLength: 131072, + maxOutputTokens: 32768, + }, + { + id: "google/gemma-4-31b-it", + name: "Gemma 4 31B", + supportsReasoning: true, + supportsVision: true, + contextLength: 262144, + maxOutputTokens: 131072, + }, + // Pre-existing entry — the id verified live in #5455; kept as the endpoint guard's anchor. + { + id: "meta-llama/llama-3.1-8b-instruct", + name: "Llama 3.1 8B Instruct", + contextLength: 16384, + maxOutputTokens: 16384, + }, + ], }; diff --git a/open-sse/config/providers/registry/nvidia/index.ts b/open-sse/config/providers/registry/nvidia/index.ts index fb36561e07..c6e349fce1 100644 --- a/open-sse/config/providers/registry/nvidia/index.ts +++ b/open-sse/config/providers/registry/nvidia/index.ts @@ -8,6 +8,7 @@ export const nvidiaProvider: RegistryEntry = { baseUrl: "https://integrate.api.nvidia.com/v1/chat/completions", authType: "apikey", authHeader: "bearer", + toolNameMaxLength: 64, // #6773: nvidia multiplexes 17 models from 9 different upstream vendors // (z-ai/, minimaxai/, deepseek-ai/, qwen/, mistralai/, stepfun-ai/, // moonshotai/, openai/, nvidia/) behind ONE connection — mark it passthrough diff --git a/open-sse/config/providers/registry/poe/index.ts b/open-sse/config/providers/registry/poe/index.ts index b80d612fa5..85a84d66dc 100644 --- a/open-sse/config/providers/registry/poe/index.ts +++ b/open-sse/config/providers/registry/poe/index.ts @@ -1,4 +1,5 @@ import type { RegistryEntry } from "../../shared.ts"; +import { normalizeBaseUrl } from "../../../../utils/urlSanitize.ts"; // Poe (creator.poe.com) — OpenAI-compatible chat/responses gateway. #8082: the // built-in `poe` provider (NAMED_OPENAI_STYLE_PROVIDERS, passthroughModels:true) @@ -7,19 +8,86 @@ import type { RegistryEntry } from "../../shared.ts"; // for provider" even though credentials/inference worked fine. This base URL is // the single source of truth other Poe code paths should read from (see // src/lib/providers/validation/audioMiscProviders.ts::validatePoeProvider). +// +// #8969: canonical `poe` is the API-key provider (DefaultExecutor → api.poe.com). +// The web-cookie GraphQL transport lives only on `poe-web` / PoeWebExecutor — +// never alias `poe` to that executor (it posts to /api/gql_POST and returns 405). export const POE_DEFAULT_BASE_URL = "https://api.poe.com/v1"; +export const POE_CHAT_COMPLETIONS_URL = `${POE_DEFAULT_BASE_URL}/chat/completions`; +export const POE_RESPONSES_URL = `${POE_DEFAULT_BASE_URL}/responses`; +export const POE_MESSAGES_URL = `${POE_DEFAULT_BASE_URL}/messages`; + +/** Official Claude model ids are the only ones Poe accepts on /v1/messages. */ +export function isPoeMessagesEligibleModel(model: string | null | undefined): boolean { + if (typeof model !== "string" || !model) return false; + return /(?:^|[\/._-])claude(?:[\/._-]|$)/i.test(model); +} + +export type PoeUpstreamProtocol = "chat" | "responses" | "messages"; + +/** + * Normalize an operator-supplied or registry Poe base URL onto one of the three + * documented API surfaces. Accepts bare host, `/v1`, full chat/completions URL, + * and trailing-slash variants. + */ +export function resolvePoeUpstreamUrl(opts: { + protocol: PoeUpstreamProtocol; + configuredBaseUrl?: string | null; + responsesBaseUrl?: string | null; + messagesUrl?: string | null; + defaultChatUrl?: string | null; +}): string { + const defaultChat = opts.defaultChatUrl || POE_CHAT_COMPLETIONS_URL; + const defaultResponses = opts.responsesBaseUrl || POE_RESPONSES_URL; + const defaultMessages = opts.messagesUrl || POE_MESSAGES_URL; + + if (opts.protocol === "responses" && !opts.configuredBaseUrl) { + return defaultResponses; + } + if (opts.protocol === "messages" && !opts.configuredBaseUrl) { + return defaultMessages; + } + if (opts.protocol === "chat" && !opts.configuredBaseUrl) { + return defaultChat; + } + + const raw = normalizeBaseUrl(opts.configuredBaseUrl || defaultChat); + // Strip any known protocol suffix so we can re-append the requested one. + const root = raw + .replace(/\/chat\/completions\/?$/i, "") + .replace(/\/responses\/?$/i, "") + .replace(/\/messages\/?$/i, "") + .replace(/\/$/, ""); + + const withV1 = /\/v1$/i.test(root) ? root : `${root}/v1`; + + if (opts.protocol === "responses") return `${withV1}/responses`; + if (opts.protocol === "messages") return `${withV1}/messages`; + return `${withV1}/chat/completions`; +} + export const poeProvider: RegistryEntry = { id: "poe", alias: "poe", format: "openai", executor: "default", - baseUrl: `${POE_DEFAULT_BASE_URL}/chat/completions`, + baseUrl: POE_CHAT_COMPLETIONS_URL, + responsesBaseUrl: POE_RESPONSES_URL, + // Anthropic-compatible Messages API — official Claude models only + // (https://creator.poe.com/docs/external-applications/anthropic-compatible-api). + // Routed via each claude-* model's targetFormat: "claude" below; GPT/Gemini + // stay on Chat Completions / Responses. + messagesUrl: POE_MESSAGES_URL, authType: "apikey", authHeader: "bearer", models: [ { id: "gpt-5.2", name: "GPT-5.2" }, - { id: "claude-opus-4.8", name: "Claude Opus 4.8" }, + { + id: "claude-opus-4.8", + name: "Claude Opus 4.8", + targetFormat: "claude", + }, { id: "gemini-3.0-pro", name: "Gemini 3.0 Pro" }, ], }; diff --git a/open-sse/config/providers/registry/unorouter/index.ts b/open-sse/config/providers/registry/unorouter/index.ts new file mode 100644 index 0000000000..771bde6a7c --- /dev/null +++ b/open-sse/config/providers/registry/unorouter/index.ts @@ -0,0 +1,14 @@ +import type { RegistryEntry } from "../../shared.ts"; + +export const unorouterProvider: RegistryEntry = { + id: "unorouter", + alias: "unorouter", + format: "openai", + executor: "default", + baseUrl: "https://api.unorouter.ai/v1/chat/completions", + authType: "apikey", + authHeader: "bearer", + defaultContextLength: 128000, + models: [{ id: "auto", name: "Auto (Best Available)" }], + passthroughModels: true, +}; diff --git a/open-sse/config/providers/shared.ts b/open-sse/config/providers/shared.ts index b41d24256e..e8e2e96d75 100644 --- a/open-sse/config/providers/shared.ts +++ b/open-sse/config/providers/shared.ts @@ -141,6 +141,8 @@ export interface RegistryEntry { passthroughModels?: boolean; /** Default context window for all models in this provider (can be overridden per-model) */ defaultContextLength?: number; + /** Maximum OpenAI-compatible function name length accepted by this provider. */ + toolNameMaxLength?: number; /** Optional session pool config for rate limit management */ poolConfig?: Record; /** @@ -177,6 +179,12 @@ export interface RegistryEntry { * standard OpenAI array-shaped content untouched (see openai-responses.ts). */ requiresPlainStringContent?: boolean; + /** + * Anthropic-compatible providers that omit the required `signature` field + * from streamed thinking block starts. The passthrough stream adds only an + * empty placeholder; later provider `signature_delta` events remain intact. + */ + ensureThinkingSignature?: boolean; /** * Protocolos alternativos que este provedor aceita (ex.: um endpoint * Anthropic-compatible alem do OpenAI-compatible padrao). A conexao escolhe diff --git a/open-sse/executors/azure-openai.ts b/open-sse/executors/azure-openai.ts index 01c68cf088..812733ce31 100644 --- a/open-sse/executors/azure-openai.ts +++ b/open-sse/executors/azure-openai.ts @@ -3,6 +3,7 @@ import type { ProviderCredentials } from "./base.ts"; import { stripTrailingSlashes } from "../utils/urlSanitize.ts"; const DEFAULT_API_VERSION = "2024-12-01-preview"; +const GPT5_OR_REASONING_DEPLOYMENT = /(?:^|[/_-])(?:gpt-5|o(?:1|3|4))(?:[._-]|$)/i; function normalizeAzureBaseUrl(rawBaseUrl?: string | null): string { const normalized = stripTrailingSlashes((rawBaseUrl || "").trim()); @@ -45,4 +46,44 @@ export class AzureOpenAIExecutor extends DefaultExecutor { headers.Accept = stream ? "text/event-stream" : "application/json"; return headers; } + + override transformRequest( + model: string, + body: unknown, + stream: boolean, + credentials: ProviderCredentials + ): unknown { + const transformed = super.transformRequest(model, body, stream, credentials); + if (!GPT5_OR_REASONING_DEPLOYMENT.test(model)) return transformed; + if (!transformed || typeof transformed !== "object" || Array.isArray(transformed)) { + return transformed; + } + + const original = + body && typeof body === "object" && !Array.isArray(body) + ? (body as Record) + : null; + const normalized = { ...(transformed as Record) }; + + if (original?.max_completion_tokens !== undefined) { + normalized.max_completion_tokens = original.max_completion_tokens; + } else if ( + normalized.max_completion_tokens === undefined && + original?.max_tokens !== undefined + ) { + normalized.max_completion_tokens = original.max_tokens; + } + delete normalized.max_tokens; + + if (normalized.temperature !== undefined && normalized.temperature !== 1) { + delete normalized.temperature; + } + + const hasTools = Array.isArray(normalized.tools) && normalized.tools.length > 0; + if (hasTools || normalized.reasoning_effort === "none") { + delete normalized.reasoning_effort; + } + + return normalized; + } } diff --git a/open-sse/executors/base.ts b/open-sse/executors/base.ts index d6883bc451..a4312778d9 100644 --- a/open-sse/executors/base.ts +++ b/open-sse/executors/base.ts @@ -301,22 +301,34 @@ function clampNestedThinkingBudget(body: unknown, max: number): boolean { } /** - * Strip the OmniRoute provider prefix from versioned built-in tool model - * fields (e.g. `cc/claude-opus-4-8` → `claude-opus-4-8`). Versioned built-in - * tool types carry an 8-digit date suffix (`advisor_20260301`, `bash_20250124`); - * the real Claude CLI sends a bare model id there, never a prefixed one, so a - * leaked OmniRoute prefix makes Anthropic reject the request. Mutates in place. + * Strip the OmniRoute provider prefix from tool model fields (e.g. + * `cc/claude-opus-4-8` → `claude-opus-4-8`). Versioned built-in tool types carry + * an 8-digit date suffix (`advisor_20260301`, `bash_20250124`); non-versioned + * server tools (Task/subagent, web_search) carry the same prefixed model. The + * real Claude CLI sends a bare model id there, never a prefixed one, so a leaked + * OmniRoute prefix makes Anthropic reject the request. + * + * Two mechanisms, applied to any tool with a string `model`: + * 1. Versioned built-in types (`type` matches `_\d{8}$`): strip the last path + * segment (`model.split("/").pop()`), matching legacy behavior for kiro/ etc. + * 2. Any tool whose model starts with a 9router Claude provider prefix + * (`cc/`, `claude/`): strip exactly that prefix (`slice`), preserving foreign + * providers such as `openrouter/anthropic/...` — mirrors upstream + * normalizeClaudeServerToolModels (9router#2649). + * Mutates in place. */ +const CLAUDE_TOOL_MODEL_PREFIXES = ["cc/", "claude/"] as const; + export function stripVersionedToolModelPrefix(tools: unknown): void { if (!Array.isArray(tools)) return; for (const t of tools as Array>) { - if ( - typeof t.type === "string" && - /^[a-z][a-z0-9_]*_\d{8}$/.test(t.type) && - typeof t.model === "string" && - t.model.includes("/") - ) { - t.model = t.model.split("/").pop(); + if (typeof t.model !== "string") continue; + const model = t.model; + if (typeof t.type === "string" && /^[a-z][a-z0-9_]*_\d{8}$/.test(t.type) && model.includes("/")) { + t.model = model.split("/").pop(); + } else { + const prefix = CLAUDE_TOOL_MODEL_PREFIXES.find((candidate) => model.startsWith(candidate)); + if (prefix) t.model = model.slice(prefix.length); } } } diff --git a/open-sse/executors/chatgpt-web.ts b/open-sse/executors/chatgpt-web.ts index eee1dace6e..15fc3b7355 100644 --- a/open-sse/executors/chatgpt-web.ts +++ b/open-sse/executors/chatgpt-web.ts @@ -44,7 +44,6 @@ const SENTINEL_PREPARE_URL = `${CHATGPT_BASE}/backend-api/sentinel/chat-requirem const SENTINEL_CR_URL = `${CHATGPT_BASE}/backend-api/sentinel/chat-requirements`; const CONV_URL = `${CHATGPT_BASE}/backend-api/f/conversation`; const USER_LAST_USED_MODEL_CONFIG_URL = `${CHATGPT_BASE}/backend-api/settings/user_last_used_model_config`; - const DEFAULT_PRO_POLL_TIMEOUT_MS = 20 * 60_000; const DEFAULT_PRO_POLL_INTERVAL_MS = 4_000; @@ -2263,7 +2262,7 @@ interface ResolverContext { deviceId: string; cookie: string; signal?: AbortSignal | null; - log?: { debug?: (tag: string, msg: string) => void; warn?: (tag: string, msg: string) => void }; + log?: Partial void>>; /** * Absolute base URL that downstream clients should use to fetch cached * images served by /v1/chatgpt-web/image/. Derived from the inbound @@ -2697,9 +2696,10 @@ async function pollForAsyncImage( const message = node?.message; const parts = message?.content?.parts; if (!Array.isArray(parts)) continue; - const pointers = extractImagePointers(parts).map( - (pointer) => ({ pointer, messageId: message?.id }) - ); + const pointers = extractImagePointers(parts).map((pointer) => ({ + pointer, + messageId: message?.id, + })); if (pointers.length === 0) continue; const at = message?.create_time ?? 0; if (!newest || at >= newest.at) newest = { pointers, at }; diff --git a/open-sse/executors/claude-web/stream.ts b/open-sse/executors/claude-web/stream.ts index 82281bb02b..264f8218e8 100644 --- a/open-sse/executors/claude-web/stream.ts +++ b/open-sse/executors/claude-web/stream.ts @@ -148,7 +148,8 @@ async function* decodeSseData( } function safeMetadataValue(value: unknown): string | number | boolean | null | undefined { - if (value === null || typeof value === "boolean") return value; + if (value === null) return null; + if (typeof value === "boolean") return value; if (typeof value === "number" && Number.isFinite(value)) return value; if (typeof value === "string" && value.length <= 128 && /^[A-Za-z0-9._:+/@-]+$/.test(value)) { return value; @@ -715,7 +716,7 @@ async function pullStreamingChunk( while (!state.terminal) { const next = await state.iterator.next(); if (state.control.cancelled) return; - if (next.done) { + if (next.done === true) { throw new ClaudeWebProtocolError("Claude Web stream ended without a terminal event"); } await queueSemanticEvent(state, next.value, options); diff --git a/open-sse/executors/claudeIdentity.ts b/open-sse/executors/claudeIdentity.ts index c9544c6743..68cc708e4a 100644 --- a/open-sse/executors/claudeIdentity.ts +++ b/open-sse/executors/claudeIdentity.ts @@ -323,6 +323,23 @@ function isContext1mModel(model: unknown): boolean { ); } +export function shouldUseMidConversationSystem( + body: Record | null | undefined, + model?: string | null +): boolean { + const payload = body || {}; + const hasSystem = + !!payload.system && + (typeof payload.system === "string" || + (Array.isArray(payload.system) && payload.system.length > 0)); + const hasTools = Array.isArray(payload.tools) && payload.tools.length > 0; + const effectiveModel = model ?? (typeof payload.model === "string" ? payload.model : ""); + + return ( + hasSystem && hasTools && matchesModelPrefix(effectiveModel, CONTEXT_1M_BETA_MODEL_PREFIXES) + ); +} + /** * Pick the anthropic-beta flag set that matches the request shape. Real CLI * uses three patterns: minimal probe, structured-output, and full agent. @@ -357,10 +374,12 @@ export function selectBetaFlags( // betas it actually asked for. Opaque clients (clientBetaSet === null) keep them all. const allowThinking = clientBetaSet === null || clientBetaSet.has("interleaved-thinking-2025-05-14"); + // effort-2025-11-24 must NOT imply advanced-tool-use-2025-11-20 (#9505): Claude + // Code sends effort on every request and never sends ATU, so treating effort as + // a proxy for ATU force-injects the heavy-agent pair the client never negotiated — + // the same class of mutation #3415 closed. Opaque clients keep the full set. const allowHeavy = - clientBetaSet === null || - clientBetaSet.has("advanced-tool-use-2025-11-20") || - clientBetaSet.has("effort-2025-11-24"); + clientBetaSet === null || clientBetaSet.has("advanced-tool-use-2025-11-20"); const hasSystem = !!b.system && (typeof b.system === "string" || (Array.isArray(b.system) && b.system.length > 0)); @@ -373,8 +392,7 @@ export function selectBetaFlags( const isFullAgent = hasTools && hasSystem; const effectiveModel = model ?? (typeof b.model === "string" ? b.model : ""); const isHeavyAgent = isFullAgent && isHeavyAgentModel(effectiveModel); - const isOpusAgent = - isFullAgent && matchesModelPrefix(effectiveModel, CONTEXT_1M_BETA_MODEL_PREFIXES); + const isOpusAgent = shouldUseMidConversationSystem(b, effectiveModel); const isContext1m = isFullAgent && isContext1mModel(effectiveModel); const flags: string[] = []; diff --git a/open-sse/executors/codex.ts b/open-sse/executors/codex.ts index 463a815ca0..fb9336c784 100644 --- a/open-sse/executors/codex.ts +++ b/open-sse/executors/codex.ts @@ -48,6 +48,12 @@ export { getCodexDualWindowCooldownMs, } from "./codex/quota.ts"; import { isCodexFreePlan, normalizeCodexTools } from "./codex/tools.ts"; +import { + CODEX_EFFORT_ORDER as EFFORT_ORDER, + GPT_5_6_ULTRA_ALIAS_MODELS, + splitCodexReasoningSuffix, + type CodexEffortLevel as EffortLevel, +} from "./codex/reasoningSuffix.ts"; // Re-exported for external importers (tests + provider services). export { isCodexFreePlan, normalizeCodexTools } from "./codex/tools.ts"; @@ -117,12 +123,6 @@ function codexWebSocketUnavailableResponse(): Response { // Ref: sub2api PR #1129 (feat(openai): split codex spark rate limiting from codex) export { getCodexModelScope, getCodexRateLimitKey, type CodexQuotaScope }; -// Ordered list of effort levels from lowest to highest -const EFFORT_ORDER = ["none", "low", "medium", "high", "xhigh", "max", "ultra"] as const; -type EffortLevel = (typeof EFFORT_ORDER)[number]; -const STANDARD_EFFORT_SUFFIXES = ["none", "low", "medium", "high", "xhigh"] as const; -const GPT_5_6_MAX_ALIAS_MODELS = new Set(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]); -const GPT_5_6_ULTRA_ALIAS_MODELS = new Set(["gpt-5.6-sol", "gpt-5.6-terra"]); const CODEX_FAST_WIRE_VALUE = "priority"; const CODEX_RESPONSES_WS_URL = "wss://chatgpt.com/backend-api/codex/responses"; const CODEX_RESPONSES_LITE_HEADER = "x-openai-internal-codex-responses-lite"; @@ -185,32 +185,6 @@ function enforceCodexResponsesLiteParallelToolCalls( return { ...body, parallel_tool_calls: false }; } -function splitCodexReasoningSuffix(model: unknown): { - baseModel: string; - effort: EffortLevel | null; -} { - const modelId = typeof model === "string" ? model : ""; - const gpt56AliasMatch = /^(gpt-5\.6-(?:sol|terra|luna))-(max|ultra)$/.exec(modelId); - if (gpt56AliasMatch) { - const [, baseModel, alias] = gpt56AliasMatch; - const supportedModels = - alias === "ultra" ? GPT_5_6_ULTRA_ALIAS_MODELS : GPT_5_6_MAX_ALIAS_MODELS; - if (supportedModels.has(baseModel)) { - return { baseModel, effort: alias as EffortLevel }; - } - } - - for (const level of STANDARD_EFFORT_SUFFIXES) { - if (modelId.endsWith(`-${level}`)) { - return { - baseModel: modelId.slice(0, -`-${level}`.length), - effort: level, - }; - } - } - return { baseModel: modelId, effort: null }; -} - export function getCodexUpstreamModel(model: unknown): string { return splitCodexReasoningSuffix(model).baseModel; } @@ -333,6 +307,59 @@ export function stripStoredItemReferences(body: Record): void { } } +function stripOrphanedCodexFunctionCallOutputs(body: Record): void { + if (!Array.isArray(body.input)) return; + // A previous_response_id delegates history resolution to the upstream + // Responses service, so a matching function_call may legitimately live in + // that remote response rather than in the local input array. + if (typeof body.previous_response_id === "string" && body.previous_response_id.trim()) return; + + const callIds = new Set(); + let outputCount = 0; + + for (const item of body.input) { + if (!item || typeof item !== "object" || Array.isArray(item)) continue; + const record = item as Record; + + if (record.type === "function_call" && typeof record.call_id === "string") { + callIds.add(record.call_id); + } + + if (Array.isArray(record.tool_calls)) { + for (const toolCall of record.tool_calls) { + if (!toolCall || typeof toolCall !== "object" || Array.isArray(toolCall)) continue; + const toolCallId = (toolCall as Record).id; + if (typeof toolCallId === "string") { + callIds.add(toolCallId); + } + } + } + + if (record.type === "function_call_output") { + outputCount++; + } + } + + if (outputCount === 0) return; + + const before = body.input.length; + body.input = body.input.filter((item) => { + if (!item || typeof item !== "object" || Array.isArray(item)) return true; + const record = item as Record; + if (record.type === "function_call_output" && typeof record.call_id === "string") { + return callIds.has(record.call_id); + } + return true; + }); + + const removedCount = before - body.input.length; + if (removedCount > 0) { + console.debug( + `[Codex] stripOrphanedCodexFunctionCallOutputs: removed ${removedCount} orphaned function_call_output item(s)` + ); + } +} + function repairMissingCodexFunctionCallOutputs(body: Record): void { if (!Array.isArray(body.input)) return; @@ -1319,6 +1346,7 @@ export class CodexExecutor extends BaseExecutor { dropInternalAssistantMessages: !nativeCodexPassthrough, }); } + stripOrphanedCodexFunctionCallOutputs(body); repairMissingCodexFunctionCallOutputs(body); // ── Cache-aware system prompt handling (both paths) ── diff --git a/open-sse/executors/codex/reasoningSuffix.ts b/open-sse/executors/codex/reasoningSuffix.ts new file mode 100644 index 0000000000..37cf237f6d --- /dev/null +++ b/open-sse/executors/codex/reasoningSuffix.ts @@ -0,0 +1,41 @@ +export const CODEX_EFFORT_ORDER = [ + "none", + "low", + "medium", + "high", + "xhigh", + "max", + "ultra", +] as const; +export type CodexEffortLevel = (typeof CODEX_EFFORT_ORDER)[number]; +export const GPT_5_6_MAX_ALIAS_MODELS = new Set(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]); +export const GPT_5_6_ULTRA_ALIAS_MODELS = new Set(["gpt-5.6-sol", "gpt-5.6-terra"]); + +export function splitCodexReasoningSuffix(model: unknown): { + baseModel: string; + effort: CodexEffortLevel | null; +} { + const modelId = typeof model === "string" ? model : ""; + const gpt56Match = /^(gpt-5\.6-(?:sol|terra|luna))(?:-(max|ultra)|\((max|ultra)\))$/.exec( + modelId + ); + if (gpt56Match) { + const [, baseModel, hyphenEffort, parenthesizedEffort] = gpt56Match; + const effort = hyphenEffort ?? parenthesizedEffort; + const supportedModels = parenthesizedEffort + ? GPT_5_6_MAX_ALIAS_MODELS + : effort === "ultra" + ? GPT_5_6_ULTRA_ALIAS_MODELS + : GPT_5_6_MAX_ALIAS_MODELS; + if (supportedModels.has(baseModel)) { + return { baseModel, effort: effort as CodexEffortLevel }; + } + } + + for (const effort of ["none", "low", "medium", "high", "xhigh"] as const) { + if (modelId.endsWith(`-${effort}`)) { + return { baseModel: modelId.slice(0, -`-${effort}`.length), effort }; + } + } + return { baseModel: modelId, effort: null }; +} diff --git a/open-sse/executors/commandCode.ts b/open-sse/executors/commandCode.ts index bebe6ebd21..fe056eab8f 100644 --- a/open-sse/executors/commandCode.ts +++ b/open-sse/executors/commandCode.ts @@ -73,7 +73,12 @@ const CC_VISION_MODEL_PATTERNS: readonly RegExp[] = [ // Anthropic /claude-fable/i, // claude-fable-5 (not covered by claude-opus/sonnet/haiku-4) // OpenAI - /gpt-5/i, // gpt-5.6, gpt-5.5, gpt-5.3-codex + /gpt-5/i, // gpt-5.6, gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex + // NOTE: gpt-5.4-mini and gpt-5.3-codex deliberately stay inside the `/gpt-5/` + // family — both accept image input on the OpenAI API, and there is no + // verified Command Code backend data marking them text-only. Excluding them + // without evidence would re-create #4071 (image stripped from a model that + // can see it). Revisit only with per-model CC registry capability data. // Sakana /fugu/i, // sakana/fugu-ultra ]; @@ -105,9 +110,36 @@ function isCommandCodeVisionModel(model?: string | null): boolean { * * OpenAI-compatible: { type: "image_url", image_url: { url: "..." } } * Command Code CLI: { type: "image", image: "..." } + * AI SDK image: { type: "image", image: "data:...;base64,..." } (#1330) + * Anthropic image: { type: "image", source: { type: "base64", media_type, data } } + * or { type: "image", source: { type: "url", url } } + * + * The Anthropic-shaped block is common for Claude-Code-compatible clients + * (e.g. Zoo Code) that send Messages-style content arrays to the + * OpenAI `/v1/chat/completions` surface. Without this branch the image was + * silently dropped before reaching the upstream vision model. */ function extractImageUrl(part: JsonRecord): string | undefined { - if (part.type === "image") return stringValue(part.image); + if (part.type === "image") { + const direct = stringValue(part.image); + if (direct) return direct; + + // Anthropic source block: { source: { type: "base64", media_type, data } } or + // { source: { type: "url", url } }. + const source = isRecord(part.source) ? part.source : null; + if (source) { + if (source.type === "base64") { + const mediaType = stringValue(source.media_type) || "image/png"; + const data = stringValue(source.data); + if (data) return `data:${mediaType};base64,${data}`; + } + if (source.type === "url") { + const url = stringValue(source.url); + if (url) return url; + } + } + return undefined; + } if (part.type === "image_url") { if (isRecord(part.image_url)) return stringValue(part.image_url.url); return stringValue(part.image_url); diff --git a/open-sse/executors/default.ts b/open-sse/executors/default.ts index 1820e48a01..8836b79dfb 100644 --- a/open-sse/executors/default.ts +++ b/open-sse/executors/default.ts @@ -1,3 +1,5 @@ +import { createHash } from "node:crypto"; + import { BaseExecutor, type ExecuteInput } from "./base.ts"; import { mapNvidiaGlm52ReasoningParams } from "./base/reasoningEffort.ts"; import { PROVIDERS, OAUTH_ENDPOINTS } from "../config/constants.ts"; @@ -18,6 +20,7 @@ import { import { isOfficialAnthropicBaseUrl } from "../utils/anthropicHost.ts"; import { applyProviderRequestDefaults } from "../services/providerRequestDefaults.ts"; import { stripUnsupportedParams } from "../translator/paramSupport.ts"; +import { normalizeOpenAIToolNames } from "../translator/helpers/toolCallHelper.ts"; import { injectReasoningContentForThinkingModel, shouldInjectReasoningContentPlaceholder, @@ -28,6 +31,7 @@ import { getTargetFormat, isClaudeCodeCompatible, } from "../services/provider.ts"; +import { ensureToolMessageNames } from "./kimiToolNames.ts"; import { getSapResourceGroup } from "../config/sap.ts"; import { normalizeBailianMessagesUrl, @@ -40,6 +44,10 @@ import { normalizeOpenAIChatUrl, getOpenRouterConnectionPreset, } from "./default/urlNormalizers.ts"; +import { + isPoeMessagesEligibleModel, + resolvePoeUpstreamUrl, +} from "../config/providers/registry/poe/index.ts"; import { buildMaritalkChatUrl } from "../config/maritalk.ts"; import { LOCAL_PROVIDERS } from "@/shared/constants/providers"; import { isForbiddenCustomHeaderName } from "@/shared/constants/upstreamHeaders"; @@ -59,6 +67,38 @@ import { usesCcWireImage } from "../services/ccWireImageBuiltins.ts"; import type { PoolConfig } from "../services/sessionPool/types.ts"; +const NVIDIA_TOOL_CALL_ID_PATTERN = /^[A-Za-z0-9]{9}$/; + +function normalizeNvidiaToolCallId(id: unknown): unknown { + if (id === null || id === undefined) return id; + const value = String(id); + if (NVIDIA_TOOL_CALL_ID_PATTERN.test(value)) return value; + return createHash("sha256").update(value).digest("hex").slice(0, 9); +} + +function normalizeNvidiaToolCallIds(body: unknown): void { + if (!body || typeof body !== "object" || Array.isArray(body)) return; + const messages = (body as Record).messages; + if (!Array.isArray(messages)) return; + + for (const message of messages) { + if (!message || typeof message !== "object" || Array.isArray(message)) continue; + const record = message as Record; + if (Array.isArray(record.tool_calls)) { + for (const toolCall of record.tool_calls) { + if (!toolCall || typeof toolCall !== "object" || Array.isArray(toolCall)) continue; + const call = toolCall as Record; + if (call.id !== null && call.id !== undefined) { + call.id = normalizeNvidiaToolCallId(call.id); + } + } + } + if (record.tool_call_id !== null && record.tool_call_id !== undefined) { + record.tool_call_id = normalizeNvidiaToolCallId(record.tool_call_id); + } + } +} + /** * Apply operator-configured per-provider custom headers onto an outgoing header * map. Defense-in-depth on top of the Zod `customHeadersSchema`: @@ -285,6 +325,36 @@ export class DefaultExecutor extends BaseExecutor { case "glm-coding-apikey": // #7364: format override extracted to zaiFormatOverride.ts (file-size ratchet). return resolveZaiUrl(credentials, (fallback) => this.resolveBaseUrl(credentials, fallback)); + case "poe": { + // #8969: Poe API-key surfaces — Chat Completions, Responses, and + // Claude-only Messages. Prefer the responses marker from + // resolveExecutionCredentials (incoming /v1/responses), then the + // registry Claude targetFormat → messagesUrl, else chat/completions. + // GPT models must never hit /v1/messages (Poe rejects non-Claude there). + const psd = credentials?.providerSpecificData; + const manualBaseUrl = + typeof psd?.baseUrl === "string" && psd.baseUrl.trim() ? psd.baseUrl.trim() : null; + const forceResponses = psd?._omnirouteForceResponsesUpstream === true; + const modelTarget = getModelTargetFormat("poe", model); + const connectionTarget = + typeof psd?.targetFormat === "string" ? (psd.targetFormat as string) : null; + const effectiveTarget = modelTarget || connectionTarget; + + let protocol: "chat" | "responses" | "messages" = "chat"; + if (forceResponses || effectiveTarget === "openai-responses") { + protocol = "responses"; + } else if (effectiveTarget === "claude" && isPoeMessagesEligibleModel(model)) { + protocol = "messages"; + } + + return resolvePoeUpstreamUrl({ + protocol, + configuredBaseUrl: manualBaseUrl, + responsesBaseUrl: this.config.responsesBaseUrl, + messagesUrl: this.config.messagesUrl, + defaultChatUrl: this.config.baseUrl, + }); + } case "claude": case "glm": case "glmt": @@ -601,9 +671,27 @@ export class DefaultExecutor extends BaseExecutor { transformRequest(model, body, stream, credentials) { const cleanedBody = super.transformRequest(model, body, stream, credentials); let withDefaults = applyProviderRequestDefaults(cleanedBody, this.config.requestDefaults); + + // ponytail: backfill missing tool message names for strict OpenAI-compatible providers. + // Kimi K3 and some BYOK endpoints reject tool messages whose `name` field was stripped + // during combo routing or format translation. Build a tool_call_id → function.name + // lookup from assistant messages and restore missing names before forwarding. + if ( + withDefaults && + typeof withDefaults === "object" && + !Array.isArray(withDefaults) && + Array.isArray((withDefaults as Record).messages) + ) { + withDefaults = ensureToolMessageNames(withDefaults as Record); + } + withDefaults = this.applyJsonSchemaFallback(withDefaults); withDefaults = this.defaultResponsesTextFormat(withDefaults); + if (this.provider === "nvidia") { + normalizeNvidiaToolCallIds(withDefaults); + } + // Port of decolua/9router commit d652300e: // Cerebras returns 400 (wrong_api_format), Mistral returns 422 // (extra_forbidden), and NVIDIA's OpenAI-compatible wrapper returns 400 @@ -789,6 +877,34 @@ export class DefaultExecutor extends BaseExecutor { } } + const toolNameMaxLength = getRegistryEntry(this.provider)?.toolNameMaxLength; + if ( + toolNameMaxLength && + withDefaults && + typeof withDefaults === "object" && + !Array.isArray(withDefaults) + ) { + const toolNameMap = normalizeOpenAIToolNames(withDefaults, toolNameMaxLength); + if (toolNameMap.size > 0) { + const existingToolNameMap = + (withDefaults as Record)._toolNameMap instanceof Map + ? ((withDefaults as Record)._toolNameMap as Map) + : null; + const responseToolNameMap = existingToolNameMap + ? new Map(existingToolNameMap) + : new Map(); + for (const [alias, original] of toolNameMap) { + responseToolNameMap.set(alias, original); + } + Object.defineProperty(withDefaults, "_toolNameMap", { + value: responseToolNameMap, + enumerable: false, + configurable: true, + writable: true, + }); + } + } + return withDefaults; } diff --git a/open-sse/executors/duckduckgo-web.ts b/open-sse/executors/duckduckgo-web.ts index f028dee7cd..72abad4f84 100644 --- a/open-sse/executors/duckduckgo-web.ts +++ b/open-sse/executors/duckduckgo-web.ts @@ -1,3 +1,4 @@ +import { Buffer } from "node:buffer"; import { generateKeyPairSync, randomUUID } from "node:crypto"; import vm from "node:vm"; import { solveDuckDuckGoChallenge, makeDuckDuckGoFeSignals } from "./duckduckgo-web/challenge.ts"; @@ -136,11 +137,6 @@ interface DuckDuckGoModelCapabilities { reasoningEffort: string | null; } -type DuckDuckGoChallengeResult = { - client_hashes?: unknown; - [key: string]: unknown; -}; - let durablePublicKey: JsonWebKey | null = null; function extractDuckDuckGoContent(data: unknown): string { @@ -499,7 +495,7 @@ export class DuckDuckGoWebExecutor extends BaseExecutor { // Wrap the captured body as a Response so processResponse // (already a streaming/non-streaming transformer) can be // reused unchanged. - const upstreamResp = new Response(result.body, { + const upstreamResp = new Response(Buffer.from(result.body), { status: result.status, headers: { "Content-Type": result.contentType || "text/event-stream", diff --git a/open-sse/executors/duckduckgo-web/challenge.ts b/open-sse/executors/duckduckgo-web/challenge.ts index 4c3f3a6132..3c0159ba3a 100644 --- a/open-sse/executors/duckduckgo-web/challenge.ts +++ b/open-sse/executors/duckduckgo-web/challenge.ts @@ -102,6 +102,11 @@ export function sha256Base64(value: string): string { return createHash("sha256").update(value, "utf8").digest("base64"); } +type DuckDuckGoChallengeResult = { + client_hashes?: unknown; + [key: string]: unknown; +}; + export async function solveDuckDuckGoChallenge( challenge: string, userAgent: string diff --git a/open-sse/executors/edgeTts.ts b/open-sse/executors/edgeTts.ts index 74a9c7f333..18a9f144e9 100644 --- a/open-sse/executors/edgeTts.ts +++ b/open-sse/executors/edgeTts.ts @@ -58,7 +58,7 @@ export interface EdgeTtsSynthInput { } export interface EdgeTtsSynthResult { - audio: Buffer; + audio: Buffer; contentType: string; } @@ -189,9 +189,7 @@ export function isTurnEndMessage(message: string): boolean { * ASCII headers, then the remaining bytes are audio data. Returns `null` * for a frame too short to contain a valid header-length prefix. */ -export function demuxAudioChunk( - frame: Buffer -): { headers: string; audio: Buffer } | null { +export function demuxAudioChunk(frame: Buffer): { headers: string; audio: Buffer } | null { if (!Buffer.isBuffer(frame) || frame.length < 2) return null; const headerLength = frame.readUInt16BE(0); if (2 + headerLength > frame.length) return null; diff --git a/open-sse/executors/index.ts b/open-sse/executors/index.ts index 49fe28ee6c..767d087927 100644 --- a/open-sse/executors/index.ts +++ b/open-sse/executors/index.ts @@ -152,7 +152,9 @@ const executors = { "yuanbao-web": new YuanbaoWebExecutor(), ybw: new YuanbaoWebExecutor(), // Alias "poe-web": new PoeWebExecutor(), - poe: new PoeWebExecutor(), // Alias + // #8969: do NOT alias canonical `poe` (API-key / api.poe.com) to PoeWebExecutor. + // Registry declares executor:"default"; the hard-coded map previously won and + // routed API-key traffic to GraphQL /api/gql_POST → HTTP 405. "venice-web": new VeniceWebExecutor(), ven: new VeniceWebExecutor(), // Alias "notion-web": new NotionWebExecutor(), diff --git a/open-sse/executors/inner-ai.ts b/open-sse/executors/inner-ai.ts index 27a535daef..261a75468e 100644 --- a/open-sse/executors/inner-ai.ts +++ b/open-sse/executors/inner-ai.ts @@ -23,6 +23,7 @@ interface InnerAiModel { unavailable_api?: boolean; pro_only?: boolean; ultra_only?: boolean; + ai_model_categories?: Array>; } interface CredentialCache { @@ -283,9 +284,7 @@ async function resolveModels( if (m.enable === false || m.unavailable_api) return false; if (m.ultra_only && !isUltra) return false; if (m.pro_only && !isPro) return false; - const cats = Array.isArray((m as Record).ai_model_categories) - ? ((m as Record).ai_model_categories as Array>) - : null; + const cats = Array.isArray(m.ai_model_categories) ? m.ai_model_categories : null; if (cats && cats.length > 0) { return cats.some((c) => String(c.unique_identifier ?? c.name ?? "").toLowerCase() === "text"); } diff --git a/open-sse/executors/kimi.ts b/open-sse/executors/kimi.ts index 8364f0909f..1a3ec3463f 100644 --- a/open-sse/executors/kimi.ts +++ b/open-sse/executors/kimi.ts @@ -7,6 +7,7 @@ import { import { FORMATS } from "../translator/formats.ts"; import { DefaultExecutor } from "./default.ts"; import type { ProviderCredentials } from "./base.ts"; +import { ensureToolMessageNames } from "./kimiToolNames.ts"; type JsonRecord = Record; type KimiProtocol = "openai" | "claude"; @@ -410,11 +411,17 @@ export class KimiExecutor extends DefaultExecutor { const cleanedBody = super.transformRequest(model, body, stream, credentials); const record = asRecord(cleanedBody); if (!record) return cleanedBody; + + // ponytail: backfill missing tool message names before protocol normalization. + // Kimi K3 rejects tool messages whose `name` field was stripped during + // combo routing or format translation. + const withNames = ensureToolMessageNames(record); + const policy = getThinkingPolicy(credentials); const normalized = - resolveKimiProtocol(credentials, record) === "claude" - ? normalizeAnthropicRequest(record, policy) - : normalizeOpenAIRequest(record, stream, policy); + resolveKimiProtocol(credentials, withNames) === "claude" + ? normalizeAnthropicRequest(withNames, policy) + : normalizeOpenAIRequest(withNames, stream, policy); return stream ? { ...normalized, stream: true } : normalized; } } diff --git a/open-sse/executors/kimiToolNames.ts b/open-sse/executors/kimiToolNames.ts new file mode 100644 index 0000000000..664f85c9ff --- /dev/null +++ b/open-sse/executors/kimiToolNames.ts @@ -0,0 +1,42 @@ +type JsonRecord = Record; + +function asRecord(value: unknown): JsonRecord | null { + return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonRecord) : null; +} + +// ponytail: Kimi K3 (Moonshot) enforces a stricter tool-message contract than most +// OpenAI-compatible APIs: every role:"tool" message must carry a `name` field matching +// the function that issued the tool_call_id. When requests arrive through combo routing +// or format translation, the `name` field is frequently stripped, causing a 400. +// This builds a tool_call_id -> function.name lookup from assistant tool_calls and +// backfills missing names. Shared by KimiExecutor and DefaultExecutor (for BYOK providers). +// Upgrade path: if Moonshot relaxes this requirement, this function becomes a no-op. +export function ensureToolMessageNames(record: JsonRecord): JsonRecord { + if (!Array.isArray(record.messages)) return record; + + const callIdToName = new Map(); + for (const msg of record.messages) { + const m = asRecord(msg); + if (!m || m.role !== "assistant" || !Array.isArray(m.tool_calls)) continue; + for (const tc of m.tool_calls as { id?: string; function?: { name?: string } }[]) { + if (tc?.id && typeof tc.function?.name === "string") { + callIdToName.set(String(tc.id), tc.function.name); + } + } + } + + if (callIdToName.size === 0) return record; + + let modified = false; + const messages = record.messages.map((msg: unknown) => { + const m = asRecord(msg); + if (!m || m.role !== "tool" || typeof m.name === "string") return msg; + const callId = String(m.tool_call_id ?? ""); + const resolvedName = callIdToName.get(callId); + if (!resolvedName) return msg; + modified = true; + return { ...m, name: resolvedName }; + }); + + return modified ? { ...record, messages } : record; +} diff --git a/open-sse/executors/kiro.ts b/open-sse/executors/kiro.ts index 3dab64c395..65c4e6186a 100644 --- a/open-sse/executors/kiro.ts +++ b/open-sse/executors/kiro.ts @@ -6,6 +6,7 @@ import { type ProviderCredentials, } from "./base.ts"; import { PROVIDERS } from "../config/constants.ts"; +import { getRegistryEntry } from "../config/providerRegistry.ts"; import { v4 as uuidv4 } from "uuid"; import { refreshKiroToken } from "../services/tokenRefresh.ts"; import { @@ -20,6 +21,18 @@ import { } from "./kiroThinking.ts"; import { ByteQueue, TEXT_ENCODER, parseEventFrame } from "./kiro/eventstream.ts"; import { kiroRuntimeHost, resolveKiroRuntimeRegion } from "../services/kiroRegion.ts"; +import { + KIRO_TOOL_CALL_WRAPPER, + appendBufferedKiroToolInput, + encodeSse, + getBufferedKiroToolInput, + validateKiroToolCallWrapperInput, + validateKiroToolName, + validateKiroToolUse, + type PendingKiroWrapperToolCall, +} from "./kiroToolCallValidation.ts"; + +export { validateKiroToolUse } from "./kiroToolCallValidation.ts"; type JsonRecord = Record; @@ -41,6 +54,9 @@ type KiroStreamState = { seenToolIds: Map; toolArgsEmitted: Map; toolArgsBuffered: Map; + generatedToolIdCounter: number; + pendingWrapperToolCalls: Map; + invalidToolCall?: boolean; totalContentLength?: number; contextUsagePercentage?: number; hasContextUsage?: boolean; @@ -130,7 +146,45 @@ function buildKiroFinishChunk( return finishChunk; } -function ensureKiroUsage(state: KiroStreamState) { +/** + * Kiro's fallback input-token budget when the model is absent from the registry. + * Mirrors the registry's own `defaultContextLength` and kiro-gateway's + * DEFAULT_MAX_INPUT_TOKENS. + */ +const KIRO_DEFAULT_MAX_INPUT_TOKENS = 200000; + +/** + * Input-token budget for a Kiro model, used to turn `contextUsagePercentage` + * into an absolute token count. + * + * Kiro reports only a percentage, so the budget it is a percentage OF decides the + * result. A fixed 200000 undercounts every model with a larger window by the + * ratio of the two windows — claude-sonnet-5 (1M) by 5x, gpt-5.6-* (272k) by + * ~26% — and those numbers land in usage_history and the API-key token-limit + * counters. + */ +function resolveKiroMaxInputTokens(model: string): number { + const entry = getRegistryEntry("kiro"); + const modelEntry = entry?.models?.find((m) => m.id === model); + return modelEntry?.contextLength || entry?.defaultContextLength || KIRO_DEFAULT_MAX_INPUT_TOKENS; +} + +/** + * Synthesize a usage block when Kiro sent no token counts of its own. + * + * Live `generateAssistantResponse` traffic carries no token counts at all — only + * `contextUsageEvent.contextUsagePercentage` and a `meteringEvent` credit figure + * (verified against the live API: frames are assistantResponseEvent / + * metadataEvent / contextUsageEvent / meteringEvent). So these numbers are + * ESTIMATES, derived the same way kiro-gateway derives them: the percentage + * yields the total, the response text yields the completion, and the prompt is + * the remainder. + * + * Subtracting matters: the percentage already covers the whole context, so + * adding a separately-estimated completion on top would double-count it and + * inflate `total_tokens`. + */ +function ensureKiroUsage(state: KiroStreamState, model: string) { if (state.usage) return; const estimatedOutputTokens = @@ -138,17 +192,30 @@ function ensureKiroUsage(state: KiroStreamState) { ? Math.max(1, Math.floor(state.totalContentLength / 4)) : 0; - const estimatedInputTokens = + const estimatedTotalTokens = state.contextUsagePercentage && state.contextUsagePercentage > 0 - ? Math.floor((state.contextUsagePercentage * 200000) / 100) + ? Math.floor((state.contextUsagePercentage * resolveKiroMaxInputTokens(model)) / 100) : 0; - if (estimatedInputTokens <= 0 && estimatedOutputTokens <= 0) return; + if (estimatedTotalTokens <= 0 && estimatedOutputTokens <= 0) return; + + // Without a percentage there is no total to split, so the output estimate is + // all that is known and stands on its own. + if (estimatedTotalTokens <= 0) { + state.usage = { + prompt_tokens: 0, + completion_tokens: estimatedOutputTokens, + total_tokens: estimatedOutputTokens, + }; + return; + } + + const promptTokens = Math.max(0, estimatedTotalTokens - estimatedOutputTokens); state.usage = { - prompt_tokens: estimatedInputTokens, + prompt_tokens: promptTokens, completion_tokens: estimatedOutputTokens, - total_tokens: estimatedInputTokens + estimatedOutputTokens, + total_tokens: promptTokens + estimatedOutputTokens, }; } @@ -344,11 +411,116 @@ export class KiroExecutor extends BaseExecutor { seenToolIds: new Map(), toolArgsEmitted: new Map(), toolArgsBuffered: new Map(), + generatedToolIdCounter: 0, + pendingWrapperToolCalls: new Map(), hasReasoningContent: false, reasoningChunkCount: 0, thinking: thinkingExpected ? { thinkingMode: false, pendingTag: "" } : undefined, }; + const getToolCallId = (toolUse: JsonRecord): string => { + if (typeof toolUse.toolUseId === "string" && toolUse.toolUseId) { + return toolUse.toolUseId; + } + state.generatedToolIdCounter += 1; + return `call_${created}_${state.generatedToolIdCounter}`; + }; + + const emitToolCallStart = ( + controller: TransformStreamDefaultController, + toolCallId: string, + toolName: string, + toolIndex: number + ) => { + const startChunk: JsonRecord = { + id: responseId, + object: "chat.completion.chunk", + created, + model, + choices: [ + { + index: 0, + delta: { + ...(chunkIndex === 0 ? { role: "assistant" } : {}), + tool_calls: [ + { + index: toolIndex, + id: toolCallId, + type: "function", + function: { name: toolName, arguments: "" }, + }, + ], + }, + finish_reason: null, + }, + ], + }; + chunkIndex += 1; + controller.enqueue(encodeSse(`data: ${JSON.stringify(startChunk)}\n\n`)); + }; + + const emitToolCallArguments = ( + controller: TransformStreamDefaultController, + toolIndex: number, + argumentsStr: string + ) => { + const argsChunk: JsonRecord = { + id: responseId, + object: "chat.completion.chunk", + created, + model, + choices: [ + { + index: 0, + delta: { + tool_calls: [{ index: toolIndex, function: { arguments: argumentsStr } }], + }, + finish_reason: null, + }, + ], + }; + chunkIndex += 1; + controller.enqueue(encodeSse(`data: ${JSON.stringify(argsChunk)}\n\n`)); + }; + + const failInvalidToolCall = (controller: TransformStreamDefaultController, message: string) => { + const error = { + error: { + message, + type: "invalid_request_error", + code: "invalid_kiro_tool_call", + }, + }; + state.invalidToolCall = true; + state.finishEmitted = true; + controller.enqueue(encodeSse(`data: ${JSON.stringify(error)}\n\n`)); + controller.enqueue(encodeSse("data: [DONE]\n\n")); + controller.terminate(); + }; + + const flushPendingWrapperToolCalls = ( + controller: TransformStreamDefaultController + ): boolean => { + for (const toolCall of state.pendingWrapperToolCalls.values()) { + const toolInput = getBufferedKiroToolInput(toolCall); + try { + validateKiroToolCallWrapperInput(toolInput); + } catch (error) { + failInvalidToolCall(controller, error instanceof Error ? error.message : String(error)); + return false; + } + + const toolIndex = state.toolCallIndex++; + state.seenToolIds.set(toolCall.toolCallId, toolIndex); + emitToolCallStart(controller, toolCall.toolCallId, toolCall.toolName, toolIndex); + const argumentsStr = + typeof toolInput === "string" ? toolInput : JSON.stringify(toolInput ?? {}); + if (argumentsStr) emitToolCallArguments(controller, toolIndex, argumentsStr); + } + state.pendingWrapperToolCalls.clear(); + return true; + }; + const transformStream = new TransformStream( { async transform(chunk, controller) { @@ -566,50 +738,64 @@ export class KiroExecutor extends BaseExecutor { const toolUse = event.payload; const toolUses = Array.isArray(toolUse) ? toolUse : [toolUse]; - for (const singleToolUse of toolUses) { - const toolCallId = singleToolUse.toolUseId || `call_${Date.now()}`; - const toolName = singleToolUse.name || ""; + for (const rawToolUse of toolUses) { + const singleToolUse = rawToolUse as JsonRecord; + let toolName: string; + try { + toolName = validateKiroToolName(singleToolUse); + } catch (error) { + failInvalidToolCall( + controller, + error instanceof Error ? error.message : String(error) + ); + return; + } + + const toolCallId = getToolCallId(singleToolUse); const toolInput = singleToolUse.input; + if (toolName === KIRO_TOOL_CALL_WRAPPER) { + let pending = state.pendingWrapperToolCalls.get(toolCallId); + if (!pending) { + if (state.seenToolIds.has(toolCallId)) { + failInvalidToolCall( + controller, + "Invalid Kiro tool_call payload: duplicate toolUseId reused by wrapper" + ); + return; + } + pending = { toolCallId, toolName }; + state.pendingWrapperToolCalls.set(toolCallId, pending); + } + try { + appendBufferedKiroToolInput(pending, toolInput); + } catch (error) { + failInvalidToolCall( + controller, + error instanceof Error ? error.message : String(error) + ); + return; + } + continue; + } + + if (state.pendingWrapperToolCalls.has(toolCallId)) { + failInvalidToolCall( + controller, + "Invalid Kiro tool_call payload: mixed wrapper and direct tool fragments" + ); + return; + } + let toolIndex; const isNewTool = !state.seenToolIds.has(toolCallId); if (isNewTool) { toolIndex = state.toolCallIndex++; state.seenToolIds.set(toolCallId, toolIndex); - - const startChunk = { - id: responseId, - object: "chat.completion.chunk", - created, - model, - choices: [ - { - index: 0, - delta: { - ...(chunkIndex === 0 ? { role: "assistant" } : {}), - tool_calls: [ - { - index: toolIndex, - id: toolCallId, - type: "function", - function: { - name: toolName, - arguments: "", - }, - }, - ], - }, - finish_reason: null, - }, - ], - }; - chunkIndex++; - controller.enqueue( - TEXT_ENCODER.encode(`data: ${JSON.stringify(startChunk)}\n\n`) - ); + emitToolCallStart(controller, toolCallId, toolName, toolIndex); } else { - toolIndex = state.seenToolIds.get(toolCallId); + toolIndex = state.seenToolIds.get(toolCallId) as number; } if (toolInput !== undefined) { @@ -662,6 +848,7 @@ export class KiroExecutor extends BaseExecutor { // Handle messageStopEvent if (eventType === "messageStopEvent") { + if (!flushPendingWrapperToolCalls(controller)) return; flushBufferedToolArgs(state, controller, { responseId, created, model }); state.stopSeen = true; } @@ -685,37 +872,74 @@ export class KiroExecutor extends BaseExecutor { state.hasMeteringEvent = true; } - // Handle metricsEvent for token usage - if (eventType === "metricsEvent") { - // Extract usage data from metricsEvent payload - const metrics = event.payload?.metricsEvent || event.payload; + // Handle token usage. Kiro reports it under more than one frame: the + // `metricsEvent` shape covered by unit tests, and a `metadataEvent` + // carrying a nested `usage` object — the shape observed on live + // API-key traffic (see tests/unit/executor-kiro.test.ts, the + // "live API-key event shape" case, whose frames are + // assistantResponseEvent / metadataEvent / contextUsageEvent / + // meteringEvent with no metricsEvent at all). Reading only + // `metricsEvent` meant cache tokens were never picked up in + // production even after their field names were corrected, because + // the branch holding that code never ran. + if (eventType === "metricsEvent" || eventType === "metadataEvent") { + const metrics = + event.payload?.metricsEvent || + event.payload?.usage || + (event.payload?.metadataEvent as JsonRecord)?.usage || + event.payload; if (metrics && typeof metrics === "object") { + const readNumber = (...candidates: unknown[]) => + candidates.find((value) => typeof value === "number") as number | undefined; + + // Bedrock-style (`inputTokens`) and OpenAI-style + // (`prompt_tokens`) spellings both appear across Kiro frames. const inputTokens = - typeof (metrics as JsonRecord).inputTokens === "number" - ? ((metrics as JsonRecord).inputTokens as number) - : 0; + readNumber( + (metrics as JsonRecord).inputTokens, + (metrics as JsonRecord).prompt_tokens + ) || 0; const outputTokens = - typeof (metrics as JsonRecord).outputTokens === "number" - ? ((metrics as JsonRecord).outputTokens as number) - : 0; + readNumber( + (metrics as JsonRecord).outputTokens, + (metrics as JsonRecord).completion_tokens + ) || 0; - const cacheReadTokens = - typeof (metrics as JsonRecord).cacheReadTokens === "number" - ? ((metrics as JsonRecord).cacheReadTokens as number) - : 0; + const cacheReadTokens = readNumber( + (metrics as JsonRecord).cacheReadInputTokens, + (metrics as JsonRecord).cacheReadTokens, + (metrics as JsonRecord).cache_read_input_tokens + ); - const cacheCreationTokens = - typeof (metrics as JsonRecord).cacheCreationTokens === "number" - ? ((metrics as JsonRecord).cacheCreationTokens as number) - : 0; + const cacheCreationTokens = readNumber( + (metrics as JsonRecord).cacheWriteInputTokens, + (metrics as JsonRecord).cacheCreationTokens, + (metrics as JsonRecord).cache_creation_input_tokens + ); if (inputTokens > 0 || outputTokens > 0) { state.usage = { prompt_tokens: inputTokens, completion_tokens: outputTokens, total_tokens: inputTokens + outputTokens, - ...(cacheReadTokens > 0 && { cache_read_input_tokens: cacheReadTokens }), - ...(cacheCreationTokens > 0 && { + ...((cacheReadTokens || 0) > 0 && { + cache_read_input_tokens: cacheReadTokens, + }), + ...((cacheCreationTokens || 0) > 0 && { + cache_creation_input_tokens: cacheCreationTokens, + }), + }; + } else if ((cacheReadTokens || 0) > 0 || (cacheCreationTokens || 0) > 0) { + // Cache counts can arrive on a frame that carries no + // input/output totals. Preserve them instead of dropping the + // whole frame, and let ensureKiroUsage() fill the totals from + // contextUsagePercentage. + state.usage = { + ...(state.usage || {}), + ...((cacheReadTokens || 0) > 0 && { + cache_read_input_tokens: cacheReadTokens, + }), + ...((cacheCreationTokens || 0) > 0 && { cache_creation_input_tokens: cacheCreationTokens, }), }; @@ -730,6 +954,8 @@ export class KiroExecutor extends BaseExecutor { }, flush(controller) { + if (!flushPendingWrapperToolCalls(controller)) return; + if (state.invalidToolCall) return; // Flush any buffered tool arguments (partial-object payloads) before finishing — // idempotent against toolArgsEmitted if messageStopEvent already flushed them. flushBufferedToolArgs(state, controller, { responseId, created, model }); @@ -772,7 +998,7 @@ export class KiroExecutor extends BaseExecutor { // Emit finish chunk if not already sent if (!state.finishEmitted) { state.finishEmitted = true; - ensureKiroUsage(state); + ensureKiroUsage(state, model); const finishChunk = buildKiroFinishChunk(state, responseId, created, model, true); controller.enqueue(TEXT_ENCODER.encode(`data: ${JSON.stringify(finishChunk)}\n\n`)); } diff --git a/open-sse/executors/kiroToolCallValidation.ts b/open-sse/executors/kiroToolCallValidation.ts new file mode 100644 index 0000000000..d447a427f0 --- /dev/null +++ b/open-sse/executors/kiroToolCallValidation.ts @@ -0,0 +1,94 @@ +import { TEXT_ENCODER } from "./kiro/eventstream.ts"; + +/** + * Validation + buffering helpers for Kiro's nested `tool_call` wrapper payloads. + * + * Extracted from kiro.ts (file-size gate, #9314) — pure functions, no dependency on + * KiroExecutor instance state. + */ + +export type JsonRecord = Record; + +export const KIRO_TOOL_CALL_WRAPPER = "tool_call"; + +export type PendingKiroWrapperToolCall = { + toolCallId: string; + toolName: string; + inputKind?: "string" | "object"; + inputText?: string; + inputObject?: Record; +}; + +export function parseKiroToolInput(toolInput: unknown): unknown { + if (typeof toolInput !== "string") return toolInput; + try { + return JSON.parse(toolInput); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + throw new Error(`Invalid Kiro tool_call payload: input must be valid JSON (${message})`); + } +} + +export function validateKiroToolName(toolUse: JsonRecord): string { + const toolName = typeof toolUse.name === "string" ? toolUse.name.trim() : ""; + if (!toolName) throw new Error("Invalid Kiro toolUseEvent: missing tool name"); + return toolName; +} + +export function validateKiroToolCallWrapperInput(toolInput: unknown): void { + if (toolInput === undefined) { + throw new Error("Invalid Kiro tool_call payload: missing input"); + } + const input = parseKiroToolInput(toolInput); + if (!input || typeof input !== "object" || Array.isArray(input)) { + throw new Error( + "Invalid Kiro tool_call payload: input must be an object with name and arguments" + ); + } + const record = input as JsonRecord; + if (typeof record.name !== "string" || !record.name.trim()) { + throw new Error("Invalid Kiro tool_call payload: missing nested MCP tool name at input.name"); + } + if (!Object.prototype.hasOwnProperty.call(record, "arguments")) { + throw new Error( + "Invalid Kiro tool_call payload: missing nested MCP tool arguments at input.arguments" + ); + } +} + +export function validateKiroToolUse(toolUse: JsonRecord): void { + const toolName = validateKiroToolName(toolUse); + if (toolName === KIRO_TOOL_CALL_WRAPPER) { + validateKiroToolCallWrapperInput(toolUse.input); + } +} + +export function appendBufferedKiroToolInput( + toolCall: PendingKiroWrapperToolCall, + toolInput: unknown +): void { + if (toolInput === undefined) return; + if (typeof toolInput === "string") { + if (toolCall.inputKind && toolCall.inputKind !== "string") { + throw new Error("Invalid Kiro tool_call payload: mixed input fragment types"); + } + toolCall.inputKind = "string"; + toolCall.inputText = `${toolCall.inputText || ""}${toolInput}`; + return; + } + if (toolInput && typeof toolInput === "object" && !Array.isArray(toolInput)) { + if (toolCall.inputKind && toolCall.inputKind !== "object") { + throw new Error("Invalid Kiro tool_call payload: mixed input fragment types"); + } + toolCall.inputKind = "object"; + toolCall.inputObject = toolInput as Record; + } +} + +export function getBufferedKiroToolInput(toolCall: PendingKiroWrapperToolCall): unknown { + return toolCall.inputKind === "string" ? toolCall.inputText || "" : toolCall.inputObject; +} + +export function encodeSse(value: string): Uint8Array { + return TEXT_ENCODER.encode(value); +} diff --git a/open-sse/executors/muse-spark-web.ts b/open-sse/executors/muse-spark-web.ts index 66a2e819ef..f93191c312 100644 --- a/open-sse/executors/muse-spark-web.ts +++ b/open-sse/executors/muse-spark-web.ts @@ -1287,7 +1287,7 @@ export class MuseSparkWebExecutor extends BaseExecutor { if (!authorization) { return errorResult( 400, - "Missing Authorization for Meta AI WebSocket — your cookie must include an ecto1:... auth token.", + "Missing Authorization for Meta AI WebSocket — paste the ecto1:... WS auth token from meta.ai DevTools (Network → WS → clippy request Authorization param), alongside your ecto_1_sess cookie.", "missing_authorization", {}, body diff --git a/open-sse/executors/veoaifree-web.ts b/open-sse/executors/veoaifree-web.ts index 269da61f31..d08acad4dd 100644 --- a/open-sse/executors/veoaifree-web.ts +++ b/open-sse/executors/veoaifree-web.ts @@ -102,7 +102,7 @@ async function fetchWithTimeout( function waitForDuration(ms: number, signal?: AbortSignal): Promise { throwIfAborted(signal); let abort: (() => void) | undefined; - return new Promise((resolve, reject) => { + return new Promise((resolve, reject) => { const timeout = setTimeout(resolve, ms); abort = () => { clearTimeout(timeout); diff --git a/open-sse/executors/windsurf.ts b/open-sse/executors/windsurf.ts index d87e245149..782e48e4b7 100644 --- a/open-sse/executors/windsurf.ts +++ b/open-sse/executors/windsurf.ts @@ -168,7 +168,7 @@ function encodeVarint(value: number): Uint8Array { return new Uint8Array(bytes); } -function concatBytes(arrays: Uint8Array[]): Uint8Array { +function concatBytes(arrays: Uint8Array[]): Uint8Array { const total = arrays.reduce((n, a) => n + a.length, 0); const out = new Uint8Array(total); let off = 0; @@ -626,7 +626,8 @@ export class WindsurfExecutor extends BaseExecutor { const { done, value } = await reader.read(); if (done) break; if (!value) continue; - pending = pending.length === 0 ? value : concatBytes([pending, value]); + pending = + pending.length === 0 ? Uint8Array.from(value) : concatBytes([pending, value]); drainFrames(); } } finally { diff --git a/open-sse/executors/xai.ts b/open-sse/executors/xai.ts index 5fc6217729..f9b92fa1f6 100644 --- a/open-sse/executors/xai.ts +++ b/open-sse/executors/xai.ts @@ -1,6 +1,7 @@ import { BaseExecutor, type ExecutorLog, type ProviderCredentials } from "./base.ts"; import { PROVIDERS } from "../config/constants.ts"; import { getModelTargetFormat } from "../config/providerModels.ts"; +import { isResponsesEndpointPath } from "../utils/responsesEndpoint.ts"; type JsonRecord = Record; @@ -52,21 +53,18 @@ export class XaiExecutor extends BaseExecutor { super(provider, PROVIDERS[provider]); } - /** - * Port of decolua/9router#2439 (author: @ryanngit): xAI ships a native - * `/v1/responses` endpoint alongside `/v1/chat/completions`. Models tagged - * `targetFormat: "openai-responses"` in the registry (currently - * grok-4.20-multi-agent-0309, per upstream) resolve to that endpoint instead - * of the default chat-completions bridge. The per-model registry tag is the - * single source of truth — it also drives chatCore's body translation — so - * the URL stays in lockstep with the translated body, mirroring the gh - * executor's targetFormat-driven routing (9router#102) and the "openai" - * -pro heuristic in open-sse/executors/default.ts. - */ - buildUrl(model: string, _stream: boolean, _urlIndex = 0) { + buildUrl( + model: string, + _stream: boolean, + _urlIndex = 0, + credentials: ProviderCredentials | null = null + ) { if (getModelTargetFormat(this.provider, model) === "openai-responses") { return this.config.responsesBaseUrl || this.config.baseUrl; } + if (isResponsesEndpointPath(credentials?.requestEndpointPath)) { + return this.config.responsesBaseUrl || this.config.baseUrl; + } return this.config.baseUrl; } @@ -127,6 +125,14 @@ export class XaiExecutor extends BaseExecutor { if (!record) return cleaned; const out: JsonRecord = { ...record }; + const nativeXaiPassthrough = record._nativeXaiResponsesPassthrough === true; + delete out._nativeXaiResponsesPassthrough; + delete out._nativeCodexPassthrough; + + if (nativeXaiPassthrough || getModelTargetFormat(this.provider, model) === "openai-responses") { + return out; + } + let modelId = typeof out.model === "string" ? out.model : model; let suffixEffort: string | null = null; diff --git a/open-sse/handlers/chatCore.ts b/open-sse/handlers/chatCore.ts index 4c650499db..7109aaf898 100644 --- a/open-sse/handlers/chatCore.ts +++ b/open-sse/handlers/chatCore.ts @@ -1,6 +1,7 @@ import { injectMemoryAndSkills } from "./chatCore/memorySkillsInjection.ts"; import { resolveChatCoreRequestSetup } from "./chatCore/requestSetup.ts"; import { buildFailureUsageRecord } from "./chatCore/failureUsage.ts"; +import { estimateFinalInputTokens } from "./chatCore/contextEstimation.ts"; import { extractSystemRoleMessages } from "./chatCore/claudeSystemRole.ts"; export { extractSystemRoleMessages } from "./chatCore/claudeSystemRole.ts"; import { checkIdempotencyCache } from "./chatCore/idempotency.ts"; @@ -38,6 +39,8 @@ import { } from "./chatCore/executorHelpers.ts"; import { shouldUseNativeCodexPassthrough, + shouldUseNativeXaiResponsesPassthrough, + stampNativeResponsesPassthroughBody, redactPassthroughThinkingSignatures, isClaudeCodeSemanticPassthroughRequest, } from "./chatCore/passthroughHelpers.ts"; @@ -56,6 +59,7 @@ import { // symbols from chatCore.ts (tests, sibling modules) keep resolving after the split. export { shouldUseNativeCodexPassthrough, + shouldUseNativeXaiResponsesPassthrough, redactPassthroughThinkingSignatures, isClaudeCodeSemanticPassthroughRequest, buildStreamingResponseHeaders, @@ -79,6 +83,7 @@ import { FORMATS } from "../translator/formats.ts"; import { collectCustomToolNamesForSourceFormat } from "../translator/request/openai-responses/additionalTools.ts"; import { sanitizeKiroTools } from "../utils/kiroSanitizer.ts"; import { splitMisplacedToolResults } from "../translator/helpers/claudeHelper.ts"; +import { ensureCacheControlOnLastUserMessage } from "../services/claudeCodeConstraints.ts"; import { createSSETransformStreamWithLogger, createPassthroughStreamWithLogger, @@ -119,6 +124,7 @@ import { normalizeClaudeAdaptiveThinking, normalizeClaudeDisabledThinkingEffort, } from "../services/claudeAdaptiveThinking.ts"; +import { shouldUseMidConversationSystem } from "../executors/claudeIdentity.ts"; import { normalizeClaudeHaikuConstraints } from "../services/claudeHaikuConstraints.ts"; import { applyDefaultReasoningEffort } from "../services/defaultReasoningEffort.ts"; import { echoModelInObject } from "../services/responseModelEcho.ts"; @@ -133,6 +139,7 @@ import { supportsMaxTokens, getResolvedModelCapabilities, getExplicitModelOutputCap, + resolveInputTokenCapForGate, } from "@/lib/modelCapabilities.ts"; import { toPositiveInteger } from "../services/reasoningTokenBuffer.ts"; import { normalizeThinkingForModel } from "@/shared/constants/modelSpecs.ts"; @@ -216,8 +223,8 @@ import { recordCost } from "@/domain/costRules"; import { calculateCost } from "@/lib/usage/costCalculator"; import { buildClaudePassthroughToolNameMap, - restoreClaudePassthroughToolNames, - mergeResponseToolNameMap, + normalizeOpenAIToolFinishReasons, + restoreNonStreamingToolNames, } from "./chatCore/passthroughToolNames.ts"; import { resolveCompressionSettings } from "./chatCore/compressionSettings.ts"; import { isCompressionExcluded } from "../services/compression/exclusions.ts"; @@ -627,6 +634,7 @@ export async function handleChatCore({ sourceFormat, isResponsesEndpoint, nativeCodexPassthrough, + nativeXaiResponsesPassthrough, isDroidCLI, isOpencodeClient, copilotCompatibleReasoning, @@ -747,7 +755,9 @@ export async function handleChatCore({ sourceFormat, customModelTargetFormat, providerSpecificData: credentials?.providerSpecificData, + nativeXaiResponsesPassthrough, }); + const nativeResponsesPassthrough = nativeCodexPassthrough || nativeXaiResponsesPassthrough; const initialProviderRequest = body && typeof body === "object" && !Array.isArray(body) @@ -788,7 +798,7 @@ export async function handleChatCore({ provider, sourceFormat, targetFormat, - nativeCodexPassthrough, + nativeCodexPassthrough: nativeResponsesPassthrough, interceptSearchOverride, }); if (webSearchFallbackPlan.enabled) { @@ -806,7 +816,7 @@ export async function handleChatCore({ provider, sourceFormat, targetFormat, - nativeCodexPassthrough, + nativeCodexPassthrough: nativeResponsesPassthrough, interceptFetchOverride, }); if (webFetchFallbackPlan.enabled) { @@ -1090,6 +1100,10 @@ export async function handleChatCore({ // settings read below, then threaded to executor.execute() further down. Lives at // function scope because the read happens inside the per-message compression block. let contextEditingEnabled = false; + // The dashboard's global compression switch must also control the built-in + // reactive and last-resort compaction passes. Otherwise an operator selecting + // "off" still has large histories rewritten by trim_tools/purify_history. + let reactiveContextCompactionEnabled = false; // Hoisted to function scope (not just the compression-block scope below) so the // combo-resolved override survives to the final enforceOutputTokenBudget() call // further down — see #8378 (context limit resolved by the combo was silently @@ -1106,6 +1120,7 @@ export async function handleChatCore({ compressionSettings?.exclusions ); let promptCompressionEnabled = compressionSettingsResult.enabled && !compressionExcluded; + reactiveContextCompactionEnabled = compressionSettingsResult.enabled && !compressionExcluded; contextEditingEnabled = compressionSettingsResult.contextEditingEnabled; if (compressionExcluded) { void writeCompressionSkip( @@ -1755,7 +1770,7 @@ export async function handleChatCore({ // engines (Caveman/RTK). Codex Desktop / Responses clients need this path even // when those engines are off, otherwise multi-turn image sessions hard-reject // at the budget check below (#8560). - if (estimatedTokens > threshold) { + if (reactiveContextCompactionEnabled && estimatedTokens > threshold) { log?.info?.( "CONTEXT", `Proactive compression triggered: ${estimatedTokens} tokens > ${threshold} threshold (${contextLimit} limit)` @@ -1815,27 +1830,6 @@ export async function handleChatCore({ // filtering is advisory and may preserve an all-incompatible pool; this is the // hard boundary that prevents a too-large prompt (or a negative token budget) // from reaching an OpenAI-compatible upstream such as NVIDIA NIM. - const estimateFinalInputTokens = (requestBody: Record | null | undefined) => { - const adapted = requestBody - ? adaptBodyForCompression(requestBody as Record).body - : null; - const messages = - adapted?.messages || - requestBody?.contents || - requestBody?.request?.contents || - (Array.isArray(requestBody?.input) - ? requestBody.input - : requestBody?.input && typeof requestBody.input === "object" - ? requestBody.input - : []); - return ( - estimateTokens(messages) + - (Array.isArray(requestBody?.tools) ? estimateTokens(requestBody.tools) : 0) + - estimateTokens(requestBody?.system) + - estimateTokens(requestBody?.instructions) - ); - }; - let finalEstimatedInputTokens = estimateFinalInputTokens(body as Record); // Reuse the already-resolved `contextLimit` (may have been narrowed to the // per-target combo window above, resolveComboContextLimit) instead of a bare @@ -1846,7 +1840,7 @@ export async function handleChatCore({ // Last-resort compaction against the concrete input budget (not the 70% threshold). // Covers cases where the proactive pass was skipped or still left the request oversized (#8560). - if (finalEstimatedInputTokens >= finalContextLimit && body) { + if (reactiveContextCompactionEnabled && finalEstimatedInputTokens >= finalContextLimit && body) { const lastResortTarget = Math.max(1, finalContextLimit - toolsReserve - 1); const lastResortAdapter = adaptBodyForCompression(body as Record); const lastResortResult = compressContext(lastResortAdapter.body, { @@ -1870,11 +1864,6 @@ export async function handleChatCore({ } } - // Key the lookup by { provider, model } — the bare-string form resolves to - // `provider: null`, which skips both the registry cap and the operator's - // `max_token` capability override (#6524), the documented escape hatch for a - // wrong synced `limit_output`. Clamping against a stale spec while the operator - // raised the ceiling would silently truncate output. const modelOutputCap = toPositiveInteger( getExplicitModelOutputCap({ provider, model: effectiveModel }) ); @@ -1883,13 +1872,15 @@ export async function handleChatCore({ finalEstimatedInputTokens, finalContextLimit, targetFormat === FORMATS.CLAUDE && sourceFormat !== FORMATS.CLAUDE ? DEFAULT_MAX_TOKENS : 0, - modelOutputCap + modelOutputCap, + toPositiveInteger(resolveInputTokenCapForGate({ provider, model: effectiveModel }, { isCombo })) ); if (!outputBudget.ok) { + const exceededInputCap = outputBudget.maxInputTokens !== undefined; const message = - `Input exceeds the context window for ${provider}/${effectiveModel}: ` + - `estimated ${outputBudget.estimatedInputTokens} input tokens, limit ${outputBudget.contextLimit}. ` + - "Reduce the prompt or route to a model with a larger context window."; + `Input exceeds ${exceededInputCap ? "maximum input tokens" : "context window"} for ${provider}/${effectiveModel}: ` + + `estimated ${outputBudget.estimatedInputTokens} input tokens, ${exceededInputCap ? `max input ${outputBudget.maxInputTokens}` : `limit ${outputBudget.contextLimit}`}. ` + + `Reduce the prompt or route to a model with a larger ${exceededInputCap ? "input limit" : "context window"}.`; log?.warn?.("CONTEXT", message); trackPendingRequest(model, provider, connectionId, false); return createErrorResult( @@ -1980,9 +1971,17 @@ export async function handleChatCore({ ) => normalizeClaudeUpstreamMessagesFor(payload, options, log); try { - if (nativeCodexPassthrough) { - translatedBody = { ...body, _nativeCodexPassthrough: true }; - log?.debug?.("FORMAT", "native codex passthrough enabled"); + if (nativeResponsesPassthrough) { + translatedBody = stampNativeResponsesPassthroughBody( + body, + nativeCodexPassthrough ? "codex" : "xai" + ); + log?.debug?.( + "FORMAT", + nativeCodexPassthrough + ? "native codex passthrough enabled" + : "native xAI Responses Agent Tools passthrough enabled" + ); } else if (isClaudeCodeCompatible) { let normalizedForCc = { ...body }; @@ -2071,20 +2070,23 @@ export async function handleChatCore({ } } - // Fix #2468: always extract role:"system" → top-level system. - // The semantic passthrough correctly skips the Claude→OpenAI→Claude - // round-trip, but even pure Claude bodies may carry system content as - // role:"system" messages rather than the top-level system field, which - // Anthropic's Messages API now rejects with a 400. + // Legacy models reject role:"system" messages. Opus accepts them behind + // its beta, and hoisting them breaks the prompt cache prefix. if (isClaudeCodeSemanticPassthrough) { - // Only lift system/developer messages — preserves Claude Code's - // native payload structure (documents, tool chains, thinking, etc.) - extractSystemRoleMessages(translatedBody); + if ( + provider !== "claude" || + !shouldUseMidConversationSystem(translatedBody, effectiveModel) + ) { + extractSystemRoleMessages(translatedBody); + } if (Array.isArray(translatedBody.messages)) { translatedBody.messages = splitMisplacedToolResults( translatedBody.messages as ClaudeMessage[] ) as typeof translatedBody.messages; } + if (provider === "claude") { + ensureCacheControlOnLastUserMessage(translatedBody); + } } else { normalizeClaudeUpstreamMessages(translatedBody, { preserveToolResultBlocks: true }); } @@ -2617,7 +2619,7 @@ export async function handleChatCore({ const getExecutionCredentials = () => resolveExecutionCredentialsFor({ credentials, - nativeCodexPassthrough, + nativeCodexPassthrough: nativeResponsesPassthrough, endpointPath, targetFormat, provider, @@ -4197,14 +4199,14 @@ export async function handleChatCore({ } } - const responseToolNameMap = mergeResponseToolNameMap( + const restoreClaudeNames = sourceFormat === FORMATS.CLAUDE && targetFormat === FORMATS.CLAUDE; + let responseToolNameMap: Map | null; + [responseBody, responseToolNameMap] = restoreNonStreamingToolNames( + responseBody, toolNameMap, - (finalBody as Record | null | undefined) ?? null + finalBody, + restoreClaudeNames ); - - if (sourceFormat === FORMATS.CLAUDE && targetFormat === FORMATS.CLAUDE) { - responseBody = restoreClaudePassthroughToolNames(responseBody, responseToolNameMap); - } reqLogger.logProviderResponse( providerResponse.status, providerResponse.statusText, @@ -4300,17 +4302,7 @@ export async function handleChatCore({ } // T18: Normalize finish_reason to 'tool_calls' if tool calls are present - if (translatedResponse?.choices) { - for (const choice of translatedResponse.choices) { - if ( - choice.message?.tool_calls && - choice.message.tool_calls.length > 0 && - choice.finish_reason !== "tool_calls" - ) { - choice.finish_reason = "tool_calls"; - } - } - } + normalizeOpenAIToolFinishReasons(translatedResponse); // Reasoning Replay Cache (#1628): Capture reasoning_content from non-streaming responses // with tool_calls so it can be replayed on subsequent turns (DeepSeek V4, Kimi K2, etc.) diff --git a/open-sse/handlers/chatCore/clientUsageBuffer.ts b/open-sse/handlers/chatCore/clientUsageBuffer.ts index 754c4f0811..a916edc1de 100644 --- a/open-sse/handlers/chatCore/clientUsageBuffer.ts +++ b/open-sse/handlers/chatCore/clientUsageBuffer.ts @@ -24,10 +24,13 @@ import { estimateUsage as defaultEstimateUsage, } from "../../utils/usageTracking.ts"; -type ResponseLike = { - usage?: unknown; - choices?: Array<{ message?: { content?: unknown } }>; -} | null | undefined; +type ResponseLike = + | { + usage?: unknown; + choices?: Array<{ message?: { content?: unknown } }>; + } + | null + | undefined; export interface ClientUsageBufferDeps { addBufferToUsage: typeof defaultAddBuffer; @@ -95,7 +98,7 @@ export interface ApplyClientUsageBufferOptions { export function applyClientUsageBuffer( translatedResponse: ResponseLike, body: unknown, - clientResponseFormat: unknown, + clientResponseFormat: string, options: ApplyClientUsageBufferOptions = {}, deps: ClientUsageBufferDeps = DEFAULT_DEPS ): void { diff --git a/open-sse/handlers/chatCore/clineResponseEnvelope.ts b/open-sse/handlers/chatCore/clineResponseEnvelope.ts index 0882ef3718..75229773b0 100644 --- a/open-sse/handlers/chatCore/clineResponseEnvelope.ts +++ b/open-sse/handlers/chatCore/clineResponseEnvelope.ts @@ -4,7 +4,7 @@ function isRecord(value: unknown): value is JsonRecord { return !!value && typeof value === "object" && !Array.isArray(value); } -function hasOpenAIChoices(value: unknown): boolean { +function hasOpenAIChoices(value: unknown): value is JsonRecord & { choices: unknown[] } { return isRecord(value) && Array.isArray(value.choices); } diff --git a/open-sse/handlers/chatCore/compressionAnalyticsWrite.ts b/open-sse/handlers/chatCore/compressionAnalyticsWrite.ts index ec68aff23c..ecb9f11f6a 100644 --- a/open-sse/handlers/chatCore/compressionAnalyticsWrite.ts +++ b/open-sse/handlers/chatCore/compressionAnalyticsWrite.ts @@ -10,7 +10,7 @@ * stays under the complexity cap. */ -import { type CompressionStats } from "../../services/compression/stats.ts"; +import { type CompressionStats } from "../../services/compression/types.ts"; type LoggerLike = | { diff --git a/open-sse/handlers/chatCore/contextEstimation.ts b/open-sse/handlers/chatCore/contextEstimation.ts new file mode 100644 index 0000000000..f339cffc90 --- /dev/null +++ b/open-sse/handlers/chatCore/contextEstimation.ts @@ -0,0 +1,29 @@ +import { adaptBodyForCompression } from "../../services/compression/bodyAdapter.ts"; +import { estimateTokens } from "../../services/contextManager.ts"; + +type JsonRecord = Record; + +function asJsonRecord(value: unknown): JsonRecord | null { + return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonRecord) : null; +} + +export function estimateFinalInputTokens(requestBody: JsonRecord | null | undefined): number { + const adapted = requestBody ? adaptBodyForCompression(requestBody).body : null; + const nestedRequest = asJsonRecord(requestBody?.request); + const messages = + adapted?.messages || + requestBody?.contents || + nestedRequest?.contents || + (Array.isArray(requestBody?.input) + ? requestBody.input + : requestBody?.input && typeof requestBody.input === "object" + ? requestBody.input + : []); + + return ( + estimateTokens(messages) + + (Array.isArray(requestBody?.tools) ? estimateTokens(requestBody.tools) : 0) + + estimateTokens(requestBody?.system) + + estimateTokens(requestBody?.instructions) + ); +} diff --git a/open-sse/handlers/chatCore/executionCredentials.ts b/open-sse/handlers/chatCore/executionCredentials.ts index 1a96ef92ee..c8e4223774 100644 --- a/open-sse/handlers/chatCore/executionCredentials.ts +++ b/open-sse/handlers/chatCore/executionCredentials.ts @@ -118,6 +118,18 @@ export function resolveExecutionCredentials(opts: { providerSpecificData._omnirouteForceResponsesUpstream = true; } + // #8969: Poe's native /v1/responses surface — DefaultExecutor.buildUrl("poe") + // reads this marker so Responses requests do not land on chat/completions. + if (targetFormat === FORMATS.OPENAI_RESPONSES && provider === "poe") { + providerSpecificData._omnirouteForceResponsesUpstream = true; + } + + // #8969: Claude-tagged Poe models speak Anthropic Messages wire format. Keep + // DefaultExecutor from injecting OpenAI stream_options onto that body. + if (targetFormat === FORMATS.CLAUDE && provider === "poe") { + providerSpecificData.disableStreamOptions = true; + } + // #7364: "zai"/"glm-coding-apikey" default to the Anthropic Messages wire format // (registry format:"claude"), but a per-model targetFormat override (custom-model // dropdown, #2905) can resolve targetFormat to "openai" — e.g. for a vision model diff --git a/open-sse/handlers/chatCore/nonStreamingResponseHeaders.ts b/open-sse/handlers/chatCore/nonStreamingResponseHeaders.ts index 62ad018ccb..1a58391806 100644 --- a/open-sse/handlers/chatCore/nonStreamingResponseHeaders.ts +++ b/open-sse/handlers/chatCore/nonStreamingResponseHeaders.ts @@ -16,9 +16,9 @@ export function buildNonStreamingResponseHeaders( provider: string | null | undefined; model: string | null | undefined; startTime: number; - responseUsage: unknown; + responseUsage: Record | null | undefined; estimatedCost: number; - requestId: unknown; + requestId: string | null | undefined; compressionResponseMeta?: string | null | undefined; comboStrategy?: string | null | undefined; }, diff --git a/open-sse/handlers/chatCore/outputTokenBudget.ts b/open-sse/handlers/chatCore/outputTokenBudget.ts index 62752e42f4..3adb97fd81 100644 --- a/open-sse/handlers/chatCore/outputTokenBudget.ts +++ b/open-sse/handlers/chatCore/outputTokenBudget.ts @@ -15,6 +15,7 @@ export type OutputTokenBudgetResult = ok: false; estimatedInputTokens: number; contextLimit: number; + maxInputTokens?: number | null; }; type OutputTokenAdjustment = { field: string; value?: number; remove?: boolean }; @@ -74,19 +75,43 @@ function adjustOutputTokenFields( * cap limits how much is requested, not whether the request fits. Absent / * null / non-positive cap values leave behavior byte-identical to before this * parameter existed (fail-open). + * + * `maxInputTokenCap` (the model's own input ceiling, `maxInputTokens`) is an + * additional, independent input-only bound enforced on the accept/reject + * decision. The total-window check (`contextLimit - input >= 1`) stays in place + * and remains responsible for reserving output room; the input cap never + * double-counts a requested output. Absent / null / non-positive input caps + * leave behavior byte-identical (fail-open). */ export function enforceOutputTokenBudget( body: Record | null | undefined, estimatedInputTokens: number, contextLimit: number, defaultOutputTokens = 0, - maxOutputTokenCap?: number | null + maxOutputTokenCap?: number | null, + maxInputTokenCap?: number | null ): OutputTokenBudgetResult { const normalizedInputTokens = Math.max(0, Math.ceil(estimatedInputTokens)); const normalizedContextLimit = Math.max(1, Math.floor(contextLimit)); const normalizedDefaultOutputTokens = Math.max(0, Math.floor(defaultOutputTokens)); const availableOutputTokens = normalizedContextLimit - normalizedInputTokens; + // Independent input-only ceiling: reject when the prompt alone exceeds the + // model's declared max input, regardless of remaining output room. + const normalizedInputCap = maxInputTokenCap == null ? null : Math.floor(maxInputTokenCap); + if ( + normalizedInputCap !== null && + normalizedInputCap > 0 && + normalizedInputTokens > normalizedInputCap + ) { + return { + ok: false, + estimatedInputTokens: normalizedInputTokens, + contextLimit: normalizedContextLimit, + maxInputTokens: normalizedInputCap, + }; + } + if (availableOutputTokens < 1) { return { ok: false, diff --git a/open-sse/handlers/chatCore/passthroughHelpers.ts b/open-sse/handlers/chatCore/passthroughHelpers.ts index 3c0731c2b1..e644878329 100644 --- a/open-sse/handlers/chatCore/passthroughHelpers.ts +++ b/open-sse/handlers/chatCore/passthroughHelpers.ts @@ -1,7 +1,12 @@ import { FORMATS } from "../../translator/formats.ts"; import { isClaudeCodeCompatibleProvider } from "../../services/claudeCodeCompatible.ts"; +import { isResponsesEndpointPath } from "../../utils/responsesEndpoint.ts"; import { getHeaderValueCaseInsensitive } from "./headers.ts"; +export { isResponsesEndpointPath }; + +export const XAI_API_PROVIDERS = new Set(["xai", "xai-oauth", "xao"]); + export function shouldUseNativeCodexPassthrough({ provider, sourceFormat, @@ -13,10 +18,29 @@ export function shouldUseNativeCodexPassthrough({ }): boolean { if (provider !== "codex") return false; if (sourceFormat !== FORMATS.OPENAI_RESPONSES) return false; - let normalizedEndpoint = String(endpointPath || ""); - while (normalizedEndpoint.endsWith("/")) normalizedEndpoint = normalizedEndpoint.slice(0, -1); - const segments = normalizedEndpoint.split("/"); - return segments.includes("responses"); + return isResponsesEndpointPath(endpointPath); +} + +export function shouldUseNativeXaiResponsesPassthrough({ + provider, + sourceFormat, + endpointPath, +}: { + provider?: string | null; + sourceFormat?: string | null; + endpointPath?: string | null; +}): boolean { + if (!provider || !XAI_API_PROVIDERS.has(provider)) return false; + if (sourceFormat !== FORMATS.OPENAI_RESPONSES) return false; + return isResponsesEndpointPath(endpointPath); +} + +export function stampNativeResponsesPassthroughBody( + body: Record, + mode: "codex" | "xai" +): Record { + if (mode === "codex") return { ...body, _nativeCodexPassthrough: true }; + return { ...body, _nativeXaiResponsesPassthrough: true }; } /** diff --git a/open-sse/handlers/chatCore/passthroughToolNames.ts b/open-sse/handlers/chatCore/passthroughToolNames.ts index 0ab6b17d4d..87069c7360 100644 --- a/open-sse/handlers/chatCore/passthroughToolNames.ts +++ b/open-sse/handlers/chatCore/passthroughToolNames.ts @@ -1,6 +1,11 @@ import { CLAUDE_OAUTH_TOOL_PREFIX } from "../../translator/request/openai-to-claude.ts"; +import { restoreOpenAIToolNames } from "../../translator/helpers/toolCallHelper.ts"; -export function buildClaudePassthroughToolNameMap(body: Record | null | undefined) { +type JsonRecord = Record; + +export function buildClaudePassthroughToolNameMap( + body: Record | null | undefined +) { if (!body || !Array.isArray(body.tools)) return null; const toolNameMap = new Map(); @@ -47,11 +52,15 @@ export function restoreClaudePassthroughToolNames( export function mergeResponseToolNameMap( baseToolNameMap: Map | null, - transformedBody: Record | null | undefined + transformedBody: unknown ) { + const transformedRecord = + transformedBody && typeof transformedBody === "object" && !Array.isArray(transformedBody) + ? (transformedBody as JsonRecord) + : null; const executorToolNameMap = - transformedBody && transformedBody._toolNameMap instanceof Map - ? (transformedBody._toolNameMap as Map) + transformedRecord?._toolNameMap instanceof Map + ? (transformedRecord._toolNameMap as Map) : null; if (!executorToolNameMap?.size) return baseToolNameMap; @@ -63,3 +72,30 @@ export function mergeResponseToolNameMap( } return merged; } + +export function restoreNonStreamingToolNames( + responseBody: JsonRecord, + baseToolNameMap: Map | null, + transformedBody: unknown, + restoreClaudeNames: boolean +): [JsonRecord, Map | null] { + const responseToolNameMap = mergeResponseToolNameMap(baseToolNameMap, transformedBody); + const restoredBody = restoreClaudeNames + ? restoreClaudePassthroughToolNames(responseBody, responseToolNameMap) + : responseBody; + restoreOpenAIToolNames(restoredBody, responseToolNameMap); + return [restoredBody, responseToolNameMap]; +} + +export function normalizeOpenAIToolFinishReasons(responseBody: unknown): void { + const response = responseBody as { + choices?: Array; + } | null; + if (!response?.choices) return; + + for (const choice of response.choices) { + if (choice.message?.tool_calls?.length > 0 && choice.finish_reason !== "tool_calls") { + choice.finish_reason = "tool_calls"; + } + } +} diff --git a/open-sse/handlers/chatCore/requestFormat.ts b/open-sse/handlers/chatCore/requestFormat.ts index fa9e9194fb..d5ce5ad23b 100644 --- a/open-sse/handlers/chatCore/requestFormat.ts +++ b/open-sse/handlers/chatCore/requestFormat.ts @@ -11,7 +11,10 @@ */ import { detectFormatFromEndpoint } from "../../services/provider.ts"; -import { shouldUseNativeCodexPassthrough } from "./passthroughHelpers.ts"; +import { + shouldUseNativeCodexPassthrough, + shouldUseNativeXaiResponsesPassthrough, +} from "./passthroughHelpers.ts"; import { FORMATS } from "../../translator/formats.ts"; /** True when the request originates from a Copilot client (matched by user-agent or any header). */ @@ -49,13 +52,19 @@ function isOpencodeClient( if (headers instanceof Headers) { for (const [key, value] of headers as unknown as Iterable<[string, string]>) { - if (matchesHeaderKey(key) || (key.toLowerCase() === "user-agent" && matchesUserAgent(value))) { + if ( + matchesHeaderKey(key) || + (key.toLowerCase() === "user-agent" && matchesUserAgent(value)) + ) { return true; } } } else if (headers && typeof headers === "object") { for (const [key, value] of Object.entries(headers)) { - if (matchesHeaderKey(key) || (key.toLowerCase() === "user-agent" && matchesUserAgent(value))) { + if ( + matchesHeaderKey(key) || + (key.toLowerCase() === "user-agent" && matchesUserAgent(value)) + ) { return true; } } @@ -71,9 +80,7 @@ function isOpencodeClient( */ export function resolveChatCoreRequestFormat(opts: { clientRawRequest: - | { endpoint?: unknown; headers?: Headers | Record | null } - | null - | undefined; + { endpoint?: unknown; headers?: Headers | Record | null } | null | undefined; body: unknown; provider: string | null | undefined; userAgent: string | null | undefined; @@ -88,6 +95,11 @@ export function resolveChatCoreRequestFormat(opts: { sourceFormat, endpointPath, }); + const nativeXaiResponsesPassthrough = shouldUseNativeXaiResponsesPassthrough({ + provider, + sourceFormat, + endpointPath, + }); const isDroidCLI = userAgent?.toLowerCase().includes("droid") || userAgent?.toLowerCase().includes("codex-cli"); const copilotCompatibleReasoning = isCopilotClient(clientRawRequest?.headers, userAgent); @@ -101,6 +113,7 @@ export function resolveChatCoreRequestFormat(opts: { sourceFormat, isResponsesEndpoint, nativeCodexPassthrough, + nativeXaiResponsesPassthrough, isDroidCLI, copilotCompatibleReasoning, isOpencodeClient: isOpencodeClientRequest, diff --git a/open-sse/handlers/chatCore/semanticCacheStore.ts b/open-sse/handlers/chatCore/semanticCacheStore.ts index 8d119a863f..ff4e7d590c 100644 --- a/open-sse/handlers/chatCore/semanticCacheStore.ts +++ b/open-sse/handlers/chatCore/semanticCacheStore.ts @@ -20,8 +20,8 @@ type LoggerLike = { debug?: (...args: unknown[]) => void } | null | undefined; type CacheBody = { messages?: unknown; input?: unknown; - temperature?: unknown; - top_p?: unknown; + temperature?: number; + top_p?: number; }; type UsageLike = { prompt_tokens?: number; completion_tokens?: number } | null | undefined; @@ -47,7 +47,7 @@ export function storeSemanticCacheResponse( headers: unknown; translatedResponse: unknown; model: string; - apiKeyId?: string | number; + apiKeyId?: string; usage?: UsageLike; log?: LoggerLike; }, diff --git a/open-sse/handlers/chatCore/streamingPipeline.ts b/open-sse/handlers/chatCore/streamingPipeline.ts index 2a6a7c00bb..bbe0bdcb8b 100644 --- a/open-sse/handlers/chatCore/streamingPipeline.ts +++ b/open-sse/handlers/chatCore/streamingPipeline.ts @@ -61,12 +61,12 @@ const DEFAULT_DEPS: StreamingPipelineDeps = { export function assembleStreamingPipeline( args: { - providerResponse: unknown; - transformStream: unknown; - streamController: { signal: AbortSignal }; + providerResponse: Parameters[0]; + transformStream: Parameters[1]; + streamController: Parameters[2]; createPiiTransform: unknown; clientRawRequestHeaders: HeadersLike; - clientResponseFormat: unknown; + clientResponseFormat: Parameters[0]; echoModel: string | null | undefined; responseHeaders: Record; }, diff --git a/open-sse/handlers/chatCore/streamingSemanticCacheStore.ts b/open-sse/handlers/chatCore/streamingSemanticCacheStore.ts index 3aa16a9781..48bd144a3c 100644 --- a/open-sse/handlers/chatCore/streamingSemanticCacheStore.ts +++ b/open-sse/handlers/chatCore/streamingSemanticCacheStore.ts @@ -21,8 +21,8 @@ type LoggerLike = { debug?: (...args: unknown[]) => void } | null | undefined; type CacheBody = { messages?: unknown; input?: unknown; - temperature?: unknown; - top_p?: unknown; + temperature?: number; + top_p?: number; }; export interface StreamingSemanticCacheStoreDeps { @@ -46,7 +46,7 @@ interface StreamingCacheArgs { body: CacheBody; headers: unknown; model: string; - apiKeyId?: string | number; + apiKeyId?: string; streamUsage?: Record | null; log?: LoggerLike; } @@ -73,7 +73,10 @@ function writeStreamingCacheEntry( ); const tokensSaved = streamTokensSaved(args.streamUsage); deps.setCachedResponse(sig, args.model, cleanBody, tokensSaved); - args.log?.debug?.("CACHE", `Stored streaming response for ${args.model} (${tokensSaved} tokens)`); + args.log?.debug?.( + "CACHE", + `Stored streaming response for ${args.model} (${tokensSaved} tokens)` + ); } catch { // Cache write failed — non-critical } diff --git a/open-sse/handlers/chatCore/targetFormat.ts b/open-sse/handlers/chatCore/targetFormat.ts index 9bb2f0da7a..e5f00eb81a 100644 --- a/open-sse/handlers/chatCore/targetFormat.ts +++ b/open-sse/handlers/chatCore/targetFormat.ts @@ -22,6 +22,7 @@ export function resolveChatCoreTargetFormat(opts: { sourceFormat?: string; customModelTargetFormat: string | undefined; providerSpecificData: unknown; + nativeXaiResponsesPassthrough?: boolean; }) { const { provider, @@ -30,6 +31,7 @@ export function resolveChatCoreTargetFormat(opts: { sourceFormat, customModelTargetFormat, providerSpecificData, + nativeXaiResponsesPassthrough = false, } = opts; const alias = PROVIDER_ID_TO_ALIAS[provider] || provider; const modelTargetFormat = getModelTargetFormat(alias, resolvedModel); @@ -44,13 +46,14 @@ export function resolveChatCoreTargetFormat(opts: { sourceFormat === FORMATS.CLAUDE) ? sourceFormat : undefined; - const targetFormat = + let targetFormat = apiFormat === "responses" ? FORMATS.OPENAI_RESPONSES : modelTargetFormat || customModelTargetFormat || inferredAgentRouterTargetFormat || getTargetFormat(provider, providerSpecificData); + if (nativeXaiResponsesPassthrough) targetFormat = FORMATS.OPENAI_RESPONSES; return { alias, targetFormat }; } diff --git a/open-sse/handlers/chatCore/thinkingSignatureRecovery.ts b/open-sse/handlers/chatCore/thinkingSignatureRecovery.ts index b0f080bd77..ab4fb1d931 100644 --- a/open-sse/handlers/chatCore/thinkingSignatureRecovery.ts +++ b/open-sse/handlers/chatCore/thinkingSignatureRecovery.ts @@ -69,7 +69,9 @@ export async function recoverAnthropicThinkingSignature(args: { return args.execute(requestBody); }, getError: async (result) => { - if (result === firstFailure) return { status: result.status, message: result.message }; + if (result === firstFailure) { + return { status: firstFailure.status, message: firstFailure.message }; + } if (result.response.ok) return null; const details = await args.parseError(result.response.clone()); return { status: details.statusCode, message: details.message }; diff --git a/open-sse/handlers/embeddings.ts b/open-sse/handlers/embeddings.ts index 72d98c3b2d..7846ec3d58 100644 --- a/open-sse/handlers/embeddings.ts +++ b/open-sse/handlers/embeddings.ts @@ -28,6 +28,7 @@ import { getCallLogPipelineCaptureStreamChunks } from "@/lib/logEnv"; import { toJsonErrorPayload } from "@/shared/utils/upstreamError"; import { stripStaleEncodingHeaders } from "../utils/upstreamResponseHeaders.ts"; import { sanitizeErrorMessage } from "../utils/error.ts"; +import { stripTrailingSlashes } from "../utils/urlSanitize.ts"; import { fetchRemoteImage } from "@/shared/network/remoteImageFetch"; import { hasStructuredEmbeddingInput, @@ -41,6 +42,31 @@ interface ClientRawRequest { headers: Record; } +/** + * Flatten a single embedding item's vector to the OpenAI-spec `number[]` shape. + * + * Some OpenAI-compatible embedding backends — notably a llama.cpp + * `llama-server --embedding --pooling ...` instance — return each vector wrapped in one + * extra array level: `[[...floats]]` instead of `[...floats]` for a single input. That + * extra level is silently spec-breaking, since a standard OpenAI-SDK consumer reading + * `response.data[i].embedding` gets a length-1 array holding the real vector instead of + * the vector itself. Unwrap only that single redundant level; vectors that are already + * flat (or genuinely multi-row) are left untouched. See issue #9089. + */ +function flattenSingleRowEmbedding(item: unknown): void { + if (!item || typeof item !== "object" || !("embedding" in item)) return; + const record = item as { embedding: unknown }; + const embedding = record.embedding; + if ( + Array.isArray(embedding) && + embedding.length === 1 && + Array.isArray(embedding[0]) && + typeof embedding[0][0] === "number" + ) { + record.embedding = embedding[0]; + } +} + /** * Handle embedding request. * Supports both hardcoded cloud providers and dynamic local provider_nodes. @@ -59,7 +85,11 @@ export async function handleEmbedding({ connectionId = null, }: { body: Record; - credentials: { apiKey?: string | null; accessToken?: string | null } | null; + credentials: { + apiKey?: string | null; + accessToken?: string | null; + providerSpecificData?: Record | null; + } | null; log?: { info: (...args: unknown[]) => void; error: (...args: unknown[]) => void }; resolvedProvider?: EmbeddingProvider | null; resolvedModel?: string | null; @@ -205,6 +235,23 @@ export async function handleEmbedding({ } let upstreamUrl = providerConfig.baseUrl; + if (provider === "ollama-local") { + const configuredBaseUrl = credentials?.providerSpecificData?.baseUrl; + const rawBaseUrl = + typeof configuredBaseUrl === "string" && configuredBaseUrl.trim().length > 0 + ? configuredBaseUrl + : providerConfig.baseUrl; + // Use the shared O(n) helper instead of `/\/+$/` — that regex is + // vulnerable to polynomial backtracking on adversarial input + // (CodeQL js/polynomial-redos) since baseUrl is operator-configured + // per-connection data. See open-sse/utils/urlSanitize.ts. + const normalizedBaseUrl = stripTrailingSlashes(rawBaseUrl.trim()); + const ollamaHost = normalizedBaseUrl + .replace(/\/v1\/(?:chat\/completions|embeddings)$/i, "") + .replace(/\/api\/chat$/i, "") + .replace(/\/v1$/i, ""); + upstreamUrl = `${ollamaHost}/v1/embeddings`; + } let normalizeProviderResponse: ((data: Record) => Record) | null = null; @@ -359,6 +406,19 @@ export async function handleEmbedding({ // Log provider response reqLogger.logProviderResponse(response.status, "", response.headers, data); + // OpenAI-spec compliance (#9089): each item's `embedding` must be a flat number[]. + // Some OpenAI-compatible backends (e.g. a llama.cpp `llama-server --embedding` + // instance) return the vector wrapped in one extra array level — `[[...floats]]` + // instead of `[...floats]` — for a single input, which silently breaks any standard + // OpenAI-SDK consumer doing `response.data[i].embedding`. Flatten that one redundant + // level without touching providers that already return flat vectors. + const responseItems = data.data || data; + if (Array.isArray(responseItems)) { + for (const item of responseItems) { + flattenSingleRowEmbedding(item); + } + } + // Normalize response to OpenAI format const normalizedResponse = { object: "list", diff --git a/open-sse/handlers/imageGeneration.ts b/open-sse/handlers/imageGeneration.ts index c5d338c0bc..97941262ed 100644 --- a/open-sse/handlers/imageGeneration.ts +++ b/open-sse/handlers/imageGeneration.ts @@ -719,7 +719,7 @@ async function handleKieImageGeneration({ baseUrl = `${providerConfig.baseUrl.replace(/\/$/, "")}/api/v1/jobs/createTask`; const input: Record = { prompt, - aspect_ratio: mapImageSize(size, "1:1"), + aspect_ratio: mapImageSize(size), }; if (imageUrl) { input.image_url = imageUrl; @@ -737,7 +737,7 @@ async function handleKieImageGeneration({ payload = { prompt, - size: mapImageSize(size, "1:1"), + size: mapImageSize(size), nVariants: body.n || 1, }; } diff --git a/open-sse/handlers/imageGeneration/providers/adobeFirefly.ts b/open-sse/handlers/imageGeneration/providers/adobeFirefly.ts index 4270894188..33f6990e51 100644 --- a/open-sse/handlers/imageGeneration/providers/adobeFirefly.ts +++ b/open-sse/handlers/imageGeneration/providers/adobeFirefly.ts @@ -15,16 +15,13 @@ import { saveImageErrorResult, saveImageSuccessResult } from "../../imageGenerat import { AdobeFireflyError, adobeFireflyGenerateImage, + adobeFireflyImageTimeoutMs, + adobeFireflyMaxImageRefs, resolveAdobeAccessToken, resolveAdobeSourceImageIds, resolveAdobeImageModel, } from "../../../services/adobeFireflyClient.ts"; -function normalizePositiveNumber(value: unknown, fallback: number): number { - const n = Number(value); - return Number.isFinite(n) && n > 0 ? n : fallback; -} - export async function handleAdobeFireflyImageGeneration({ model, provider, @@ -69,7 +66,6 @@ export async function handleAdobeFireflyImageGeneration({ try { const accessToken = await resolveAdobeAccessToken(credentials, fetchImpl); - const timeoutMs = normalizePositiveNumber(body.timeout_ms, 180_000); const seed = typeof body.seed === "number" ? body.seed @@ -87,12 +83,10 @@ export async function handleAdobeFireflyImageGeneration({ ? credentials.accessToken : undefined); - // Cap uploads by model family (matches MediaViewModel GetSourceImageLimit). + // Cap uploads by model family. gpt-image: 2 subject refs max (3–4+ stalls colligo → 504). + // nano: 4 general refs for multi-panel composition. const { id: resolvedId } = resolveAdobeImageModel(model); - const maxRefs = - resolvedId.includes("nano-banana") || resolvedId.includes("gpt-image") - ? 4 - : 2; + const maxRefs = adobeFireflyMaxImageRefs(resolvedId); const sourceImageIds = await resolveAdobeSourceImageIds({ accessToken, @@ -104,10 +98,22 @@ export async function handleAdobeFireflyImageGeneration({ log, }); + const explicitTimeout = + typeof body.timeout_ms === "number" + ? body.timeout_ms + : typeof body.timeout_ms === "string" && body.timeout_ms.trim() + ? Number(body.timeout_ms) + : undefined; + const timeoutMs = adobeFireflyImageTimeoutMs({ + timeoutMs: explicitTimeout, + refCount: sourceImageIds.length, + }); + log?.info?.( "IMAGE", `${provider}/${model} (adobe-firefly) | prompt: "${prompt.slice(0, 60)}${prompt.length > 60 ? "..." : ""}"` + - (sourceImageIds.length ? ` | refs: ${sourceImageIds.length}` : "") + (sourceImageIds.length ? ` | refs: ${sourceImageIds.length}/${maxRefs}` : "") + + ` | pollTimeoutMs=${timeoutMs}` ); const result = await adobeFireflyGenerateImage({ diff --git a/open-sse/handlers/responseSanitizer.ts b/open-sse/handlers/responseSanitizer.ts index 140011f64e..77a126ed34 100644 --- a/open-sse/handlers/responseSanitizer.ts +++ b/open-sse/handlers/responseSanitizer.ts @@ -42,8 +42,17 @@ const ALLOWED_RESPONSES_USAGE_FIELDS = new Set([ "input_tokens_details", "output_tokens_details", "estimated", + "cost_in_usd_ticks", + "server_side_tool_usage_details", + "server_side_tool_usage", ]); +const RESPONSES_EXTRA_TOP_LEVEL_FIELDS = [ + "server_side_tool_usage_details", + "server_side_tool_usage", + "cost_in_usd_ticks", +] as const; + type JsonRecord = Record; type ParseOptions = { parseTextualReasoningTags?: boolean }; @@ -355,6 +364,10 @@ export function sanitizeResponsesApiResponse(body: unknown): unknown { sanitized.usage = sanitizeResponsesUsage(responseRoot.usage); } + for (const key of RESPONSES_EXTRA_TOP_LEVEL_FIELDS) { + if (responseRoot[key] !== undefined) sanitized[key] = responseRoot[key]; + } + return sanitized; } diff --git a/open-sse/handlers/responseTranslator.ts b/open-sse/handlers/responseTranslator.ts index 7c03f1f623..35f66e1087 100644 --- a/open-sse/handlers/responseTranslator.ts +++ b/open-sse/handlers/responseTranslator.ts @@ -6,6 +6,7 @@ import { import { normalizeOpenAICompatibleFinishReasonString } from "../utils/finishReason.ts"; import { containsTextualToolCallMarker } from "../utils/textualToolCall.ts"; import { getAnyReasoningValue } from "../utils/reasoningFields.ts"; +import { restoreOpenAIToolNames } from "../translator/helpers/toolCallHelper.ts"; type JsonRecord = Record; @@ -137,11 +138,18 @@ export function translateNonStreamingResponse( ): unknown { // If already in source format, return as-is if (targetFormat === sourceFormat) { + if (targetFormat === FORMATS.OPENAI) { + restoreOpenAIToolNames(responseBody, toolNameMap); + } return responseBody; } let intermediateOpenAI = responseBody; + if (targetFormat === FORMATS.OPENAI) { + restoreOpenAIToolNames(intermediateOpenAI, toolNameMap); + } + // Handle OpenAI Responses API format if (targetFormat === FORMATS.OPENAI_RESPONSES) { const responseRoot = toRecord(responseBody); @@ -166,14 +174,18 @@ export function translateNonStreamingResponse( if (!part || typeof part !== "object") continue; const partObj = toRecord(part); if (partObj.type === "summary_text" && typeof partObj.text === "string") { - reasoningContent += partObj.text; + // #9500 — reasoning summary parts are discrete segments; join with "\n\n" + // (matches extractThinkingFromContent convention) so they don't glue back-to-back. + reasoningContent += reasoningContent ? `\n\n${partObj.text}` : partObj.text; } } } else if (itemObj.type === "reasoning" && Array.isArray(itemObj.summary)) { for (const part of itemObj.summary) { const partObj = toRecord(part); if (partObj.type === "summary_text" && typeof partObj.text === "string") { - reasoningContent += partObj.text; + // #9500 — reasoning summary parts are discrete segments; join with "\n\n" + // (matches extractThinkingFromContent convention) so they don't glue back-to-back. + reasoningContent += reasoningContent ? `\n\n${partObj.text}` : partObj.text; } } } else if (itemObj.type === "function_call") { @@ -328,7 +340,9 @@ export function translateNonStreamingResponse( for (const part of content.parts) { const partObj = toRecord(part); if (partObj.thought === true && typeof partObj.text === "string") { - reasoningContent += partObj.text; + // #9500 — Gemini thinking parts are discrete segments; join with "\n\n" + // (matches extractThinkingFromContent convention) so they don't glue back-to-back. + reasoningContent += reasoningContent ? `\n\n${partObj.text}` : partObj.text; continue; } @@ -547,11 +561,20 @@ export function translateNonStreamingResponse( const cacheCreationTokens = toNumber(usage.cache_creation_input_tokens, 0); const promptTokens = toNumber(usage.input_tokens, 0) + cachedTokens; const completionTokens = toNumber(usage.output_tokens, 0); + const reasoningTokens = firstPositiveNumber( + toRecord(usage.output_tokens_details).thinking_tokens, + toRecord(usage.completion_tokens_details).reasoning_tokens, + usage.reasoning_tokens + ); const usageOut: JsonRecord = { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens, }; + if (reasoningTokens > 0) { + usageOut.reasoning_tokens = reasoningTokens; + usageOut.completion_tokens_details = { reasoning_tokens: reasoningTokens }; + } if (cachedTokens > 0 || cacheCreationTokens > 0) { const details: JsonRecord = {}; if (cachedTokens > 0) details.cached_tokens = cachedTokens; diff --git a/open-sse/handlers/sseParser.ts b/open-sse/handlers/sseParser.ts index d2e634e12a..d75f3a72b8 100644 --- a/open-sse/handlers/sseParser.ts +++ b/open-sse/handlers/sseParser.ts @@ -244,10 +244,8 @@ export function parseSSEToOpenAIResponse(rawSSE, fallbackModel) { existing.index = tc.index; } if (tc?.function?.name && !existing.function?.name) { - existing.function = existing.function || {}; existing.function.name = tc.function.name; } - existing.function = existing.function || {}; existing.function.arguments = appendToolCallArgumentDelta( existing.function.arguments, deltaArgs @@ -711,11 +709,19 @@ export function parseSSEToResponsesOutput(rawSSE, fallbackModel) { toIdString(evt.item_id) ); const summary = Array.isArray(reasoningItem.summary) ? reasoningItem.summary : []; - const firstPart = - summary.length > 0 ? { ...toRecord(summary[0]) } : { type: "summary_text", text: "" }; - firstPart.type = firstPart.type || "summary_text"; - firstPart.text = `${toString(firstPart.text)}${toString(evt.delta)}`; - summary[0] = firstPart; + // #9500 — respect summary_index: each segment is a distinct summary_text + // part. Place deltas at summary[summary_index] (growing the array) so + // segments are preserved for later "\n\n" joining on the non-stream path, + // instead of overwriting summary[0] regardless of index. + const summaryIndex = + typeof evt.summary_index === "number" ? evt.summary_index : 0; + const part = + summary[summaryIndex] && typeof summary[summaryIndex] === "object" + ? { ...toRecord(summary[summaryIndex]) } + : { type: "summary_text", text: "" }; + part.type = part.type || "summary_text"; + part.text = `${toString(part.text)}${toString(evt.delta)}`; + summary[summaryIndex] = part; reasoningItem.summary = summary; } @@ -726,11 +732,16 @@ export function parseSSEToResponsesOutput(rawSSE, fallbackModel) { toIdString(evt.item_id) ); const summary = Array.isArray(reasoningItem.summary) ? reasoningItem.summary : []; - const firstPart = - summary.length > 0 ? { ...toRecord(summary[0]) } : { type: "summary_text", text: "" }; - firstPart.type = firstPart.type || "summary_text"; - firstPart.text = toString(evt.text, toString(firstPart.text)); - summary[0] = firstPart; + // #9500 — respect summary_index on the terminal done event too. + const summaryIndex = + typeof evt.summary_index === "number" ? evt.summary_index : 0; + const part = + summary[summaryIndex] && typeof summary[summaryIndex] === "object" + ? { ...toRecord(summary[summaryIndex]) } + : { type: "summary_text", text: "" }; + part.type = part.type || "summary_text"; + part.text = toString(evt.text, toString(part.text)); + summary[summaryIndex] = part; reasoningItem.summary = summary; } diff --git a/open-sse/handlers/usageExtractor.ts b/open-sse/handlers/usageExtractor.ts index 114ccefa50..3871534646 100644 --- a/open-sse/handlers/usageExtractor.ts +++ b/open-sse/handlers/usageExtractor.ts @@ -63,6 +63,9 @@ export function extractUsageFromResponse(responseBody, provider) { completion_tokens: responseBody.usage.output_tokens || 0, cache_read_input_tokens: cacheRead, cache_creation_input_tokens: cacheCreation, + ...(typeof responseBody.usage.output_tokens_details?.thinking_tokens === "number" + ? { reasoning_tokens: responseBody.usage.output_tokens_details.thinking_tokens } + : {}), }; } @@ -91,10 +94,13 @@ export function extractUsageFromResponse(responseBody, provider) { // Gemini format if (responseBody.usageMetadata && typeof responseBody.usageMetadata === "object") { + // Gemini reports thoughts outside candidates. Fold them into completion so + // every provider keeps reasoning as a subset of completion tokens. + const thoughts = responseBody.usageMetadata.thoughtsTokenCount || 0; return { prompt_tokens: responseBody.usageMetadata.promptTokenCount || 0, - completion_tokens: responseBody.usageMetadata.candidatesTokenCount || 0, - reasoning_tokens: responseBody.usageMetadata.thoughtsTokenCount, + completion_tokens: (responseBody.usageMetadata.candidatesTokenCount || 0) + thoughts, + reasoning_tokens: thoughts, }; } diff --git a/open-sse/handlers/videoGeneration.ts b/open-sse/handlers/videoGeneration.ts index 4ba841c688..0b26f7d673 100644 --- a/open-sse/handlers/videoGeneration.ts +++ b/open-sse/handlers/videoGeneration.ts @@ -655,11 +655,11 @@ async function handleRunwayVideoGeneration({ ); const headers = buildRunwayHeaders(token); - const upstreamBody = { + // prettier-ignore + const upstreamBody: { model: typeof model; promptText: typeof body.prompt; ratio: typeof ratio; duration: typeof duration; promptImage?: typeof promptImage; seed?: number } = { model, promptText: body.prompt, - ratio, - duration, + ratio, duration, }; if (useImageToVideo) upstreamBody.promptImage = promptImage; diff --git a/open-sse/mcp-server/__tests__/advancedTools.test.ts b/open-sse/mcp-server/__tests__/advancedTools.test.ts index 0fedef6aef..c2aaf4d846 100644 --- a/open-sse/mcp-server/__tests__/advancedTools.test.ts +++ b/open-sse/mcp-server/__tests__/advancedTools.test.ts @@ -9,9 +9,15 @@ import { describe, it, expect, vi, beforeEach } from "vitest"; const mockFetch = vi.fn(); vi.stubGlobal("fetch", mockFetch); +const { handleTestCombo } = await import("../tools/advancedTools.ts"); + describe("MCP Advanced Tools", () => { beforeEach(() => { mockFetch.mockReset(); + // Re-assert the stub: importing advancedTools.ts triggers OmniRoute's own + // startup side effects (DB init, global fetch proxy patch) that overwrite + // globalThis.fetch after the top-level vi.stubGlobal() above ran. + vi.stubGlobal("fetch", mockFetch); }); describe("simulate_route", () => { @@ -82,6 +88,32 @@ describe("MCP Advanced Tools", () => { expect(combo).toBeDefined(); expect(combo.models).toHaveLength(2); }); + + it("does not send a non-standard 'x-provider' body field upstream (regression, strict providers like Groq reject it with HTTP 400)", async () => { + mockFetch + .mockResolvedValueOnce({ + ok: true, + json: async () => [ + { + id: "groq-combo", + models: [{ provider: "groq", model: "groq/llama-3.1-8b-instant" }], + }, + ], + }) + .mockResolvedValueOnce({ + ok: true, + json: async () => ({ model: "llama-3.1-8b-instant", cost: 0, usage: {} }), + }); + + await handleTestCombo({ comboId: "groq-combo", testPrompt: "hi" }); + + const chatCompletionsCall = mockFetch.mock.calls.find(([url]) => + String(url).includes("/v1/chat/completions") + ); + expect(chatCompletionsCall).toBeDefined(); + const sentBody = JSON.parse(chatCompletionsCall![1].body); + expect(sentBody).not.toHaveProperty("x-provider"); + }); }); describe("get_provider_metrics", () => { diff --git a/open-sse/mcp-server/audit.ts b/open-sse/mcp-server/audit.ts index 40e023212c..da1e4eaf8f 100644 --- a/open-sse/mcp-server/audit.ts +++ b/open-sse/mcp-server/audit.ts @@ -207,7 +207,10 @@ function toString(value: unknown): string { } async function openBetterSqliteAuditDb(dbPath: string): Promise { - const Database = (await import("better-sqlite3")).default as unknown as new ( + const { createRequire } = await import("node:module"); + const _require = createRequire(import.meta.url); + const mod = _require("better-sqlite3"); + const Database = (mod?.default || mod) as unknown as new ( dbPath: string ) => AuditDatabase; return new Database(dbPath); diff --git a/open-sse/mcp-server/server.ts b/open-sse/mcp-server/server.ts index c584b7a75d..9f8a536744 100644 --- a/open-sse/mcp-server/server.ts +++ b/open-sse/mcp-server/server.ts @@ -46,6 +46,7 @@ import { type McpToolExtraLike, } from "./scopeEnforcement.ts"; import { getMcpHttpAuthHeadersForInternalFetch } from "./httpAuthContext.ts"; +import { getInternalServiceAuthHeaders } from "../../src/lib/api/internalServiceAuth.ts"; import { handleSimulateRoute, handleSetBudgetGuard, @@ -203,6 +204,9 @@ export async function omniRouteFetch(path: string, options: RequestInit = {}): P ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}), ...getMcpHttpAuthHeadersForInternalFetch(), ...((options.headers as Record) || {}), + // Authenticate only the server-to-server hop. This does not replace or + // weaken the caller identity forwarded above. + ...getInternalServiceAuthHeaders(), }; const signal = options.signal || AbortSignal.timeout(10000); diff --git a/open-sse/mcp-server/tools/advancedTools.ts b/open-sse/mcp-server/tools/advancedTools.ts index e9fbdc22b7..fef283d8d2 100644 --- a/open-sse/mcp-server/tools/advancedTools.ts +++ b/open-sse/mcp-server/tools/advancedTools.ts @@ -548,7 +548,6 @@ export async function handleTestCombo(args: { comboId: string; testPrompt: strin messages: [{ role: "user", content: prompt }], max_tokens: 50, stream: false, - "x-provider": model.provider, }), }) ); diff --git a/open-sse/mcp-server/tools/compressionTools.ts b/open-sse/mcp-server/tools/compressionTools.ts index 1958c4736d..51b37a0daa 100644 --- a/open-sse/mcp-server/tools/compressionTools.ts +++ b/open-sse/mcp-server/tools/compressionTools.ts @@ -256,6 +256,7 @@ import { getCcrStoreStats, handleCcrRetrieve, inspectCcrBlock, + isCcrStoreRejection, listCcrBlocks, tryStoreBlock, } from "../../services/compression/engines/ccr/index.ts"; @@ -298,7 +299,7 @@ export async function handleCcrStoreTool( ttlSeconds: args.ttlSeconds, }); const auditInput = buildCcrStoreAuditInput(args); - if (!result.stored) { + if (isCcrStoreRejection(result)) { const output = { stored: false as const, reason: result.reason }; await logToolCall( "omniroute_ccr_store", diff --git a/open-sse/services/adobeFireflyBrowserLogin.ts b/open-sse/services/adobeFireflyBrowserLogin.ts new file mode 100644 index 0000000000..9df37023d3 --- /dev/null +++ b/open-sse/services/adobeFireflyBrowserLogin.ts @@ -0,0 +1,475 @@ +/** + * Adobe Firefly browser login (packaged-backend safe). + * + * Firefly needs an Adobe IMS access_token JWT (Bearer) issued for + * client_id `clio-playground-web`. That JWT is NEVER present in + * cookies/localStorage тАФ the SPA only holds it in memory and attaches it + * as `Authorization: Bearer ` on XHRs to firefly-3p.ff.adobe.io. + * + * IMPORTANT: The VibeProxyServices.exe is a pkg-packaged Node binary. + * Dynamic `import("playwright")` fails there (native bindings / browsers + * are not in the package). This module launches the **system** Chrome or + * Edge with `--remote-debugging-port` and talks pure Chrome DevTools + * Protocol over WebSocket тАФ zero Playwright dependency. + */ +import { spawn, type ChildProcess } from "node:child_process"; +import { existsSync, mkdtempSync, rmSync } from "node:fs"; +import { createServer } from "node:net"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { sanitizeErrorMessage } from "../utils/error.ts"; + +const FIREFLY_HOME_URL = "https://firefly.adobe.com/"; +const FIREFLY_3P_HOST_SUFFIX = "firefly-3p.ff.adobe.io"; +// Bounded quantifiers (Hard Rule: avoid ReDoS on adversarial Authorization headers). +const ADOBE_BEARER_REGEX = + /^Bearer\s+(eyJ[A-Za-z0-9_-]{1,4096}\.[A-Za-z0-9_-]{1,4096}\.[A-Za-z0-9_-]{1,4096})/i; + +const DEFAULT_LOGIN_TIMEOUT_MS = 300_000; +const MIN_LOGIN_TIMEOUT_MS = 15_000; +const MAX_LOGIN_TIMEOUT_MS = 600_000; +const POLL_INTERVAL_MS = 400; +const CDP_READY_TIMEOUT_MS = 30_000; + +export interface AdobeFireflyBrowserLoginResult { + success: boolean; + credentials?: { accessToken?: string; cookie?: string }; + /** Best-effort Adobe account label (email or user id) decoded from the JWT. */ + account?: string; + error?: string; +} + +export function clampAdobeFireflyLoginTimeout(value: unknown): number { + if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_LOGIN_TIMEOUT_MS; + return Math.max(MIN_LOGIN_TIMEOUT_MS, Math.min(MAX_LOGIN_TIMEOUT_MS, Math.trunc(value))); +} + +/** Extract an IMS JWT from an Authorization header value. Exported for unit tests. */ +export function extractAdobeBearerTokenFromAuthorization(authHeader: string): string { + const m = String(authHeader || "").match(ADOBE_BEARER_REGEX); + return m?.[1] || ""; +} + +/** Build a single cookie header from relevant Firefly cookies. Exported for unit tests. */ +export function buildAdobeFireflyCookieHeader( + cookies: Array<{ name: string; value: string; domain?: string }> +): string { + const wanted = ["sherlockToken", "forterToken", "aux_sid", "ff_session_guid"]; + const parts: string[] = []; + for (const wantedName of wanted) { + const c = cookies.find( + (candidate) => + candidate.name === wantedName && + typeof candidate.value === "string" && + candidate.value.length > 0 && + !/[\r\n;]/.test(candidate.value) + ); + if (c) parts.push(`${wantedName}=${c.value}`); + } + return parts.join("; "); +} + +/** Best-effort account label from an IMS JWT payload. Exported for unit tests. */ +export function accountLabelFromAdobeJwt(token: string): string { + try { + const part = String(token || "").split(".")[1]; + if (!part) return ""; + const json = Buffer.from(part.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"); + const obj = JSON.parse(json) as Record; + for (const key of ["email", "preferred_username", "user_id", "sub"]) { + const v = obj[key]; + if (typeof v === "string" && v.trim()) return v.trim(); + } + } catch { + // ignore + } + return ""; +} + +/** Resolve system Chrome/Edge executable. Exported for unit tests. */ +export function resolveSystemBrowserExecutable(): string | null { + const configured = process.env.OMNIROUTE_LOGIN_BROWSER_PATH?.trim(); + if (configured && existsSync(configured)) return configured; + + const pf = process.env.ProgramFiles || "C:\\Program Files"; + const pf86 = process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)"; + const local = process.env.LOCALAPPDATA || ""; + const candidates = [ + join(pf, "Google", "Chrome", "Application", "chrome.exe"), + join(pf86, "Google", "Chrome", "Application", "chrome.exe"), + join(local, "Google", "Chrome", "Application", "chrome.exe"), + join(pf, "Microsoft", "Edge", "Application", "msedge.exe"), + join(pf86, "Microsoft", "Edge", "Application", "msedge.exe"), + join(local, "Microsoft", "Edge", "Application", "msedge.exe"), + "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", + "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge", + "/usr/bin/google-chrome-stable", + "/usr/bin/google-chrome", + "/usr/bin/chromium-browser", + "/usr/bin/chromium", + "/usr/bin/microsoft-edge", + "/usr/bin/microsoft-edge-stable", + ]; + for (const path of candidates) { + if (path && existsSync(path)) return path; + } + return null; +} + +async function getFreeLoopbackPort(): Promise { + return new Promise((resolve, reject) => { + const server = createServer(); + server.once("error", reject); + server.listen(0, "127.0.0.1", () => { + const addr = server.address(); + if (!addr || typeof addr === "string") { + server.close(); + reject(new Error("Could not allocate a free loopback port for Chrome DevTools")); + return; + } + const { port } = addr; + server.close((err) => (err ? reject(err) : resolve(port))); + }); + }); +} + +async function waitForCdpReady( + port: number, + timeoutMs: number +): Promise<{ webSocketDebuggerUrl: string }> { + const deadline = Date.now() + timeoutMs; + let lastError = "CDP endpoint not ready"; + while (Date.now() < deadline) { + try { + const res = await fetch(`http://127.0.0.1:${port}/json/version`, { + signal: AbortSignal.timeout(2000), + }); + if (res.ok) { + const body = (await res.json()) as { webSocketDebuggerUrl?: string }; + if (body.webSocketDebuggerUrl) { + return { webSocketDebuggerUrl: body.webSocketDebuggerUrl }; + } + } + lastError = `CDP /json/version HTTP ${res.status}`; + } catch (err) { + lastError = err instanceof Error ? err.message : String(err); + } + await new Promise((r) => setTimeout(r, 250)); + } + throw new Error(`Chrome DevTools did not become ready: ${lastError}`); +} + +type CdpCookie = { name: string; value: string; domain?: string }; + +class CdpSocket { + private ws: WebSocket; + private nextId = 1; + private pending = new Map< + number, + { resolve: (v: unknown) => void; reject: (e: Error) => void } + >(); + private onEvent: (method: string, params: Record) => void; + + constructor(ws: WebSocket, onEvent: (method: string, params: Record) => void) { + this.ws = ws; + this.onEvent = onEvent; + this.ws.addEventListener("message", (ev) => { + let data: Record; + try { + data = JSON.parse(String(ev.data)) as Record; + } catch { + return; + } + if (typeof data.id === "number" && this.pending.has(data.id)) { + const p = this.pending.get(data.id)!; + this.pending.delete(data.id); + if (data.error) { + const errObj = data.error as { message?: string }; + p.reject(new Error(errObj.message || "CDP error")); + } else { + p.resolve(data.result); + } + return; + } + if (typeof data.method === "string") { + this.onEvent(data.method, (data.params || {}) as Record); + } + }); + } + + send(method: string, params?: Record, sessionId?: string): Promise { + const id = this.nextId++; + const msg: Record = { id, method }; + if (params) msg.params = params; + if (sessionId) msg.sessionId = sessionId; + return new Promise((resolve, reject) => { + this.pending.set(id, { resolve, reject }); + try { + this.ws.send(JSON.stringify(msg)); + } catch (err) { + this.pending.delete(id); + reject(err instanceof Error ? err : new Error(String(err))); + } + }); + } + + close(): void { + try { + this.ws.close(); + } catch { + /* ignore */ + } + } + + get open(): boolean { + return this.ws.readyState === WebSocket.OPEN; + } +} + +async function openCdp(url: string): Promise { + const WebSocketCtor = (globalThis as { WebSocket?: typeof WebSocket }).WebSocket; + if (!WebSocketCtor) { + throw new Error("WebSocket is unavailable in this Node runtime"); + } + return new Promise((resolve, reject) => { + const ws = new WebSocketCtor(url); + const onErr = () => reject(new Error(`Failed to connect CDP: ${url}`)); + ws.addEventListener("error", onErr); + ws.addEventListener("open", () => { + ws.removeEventListener("error", onErr); + resolve(ws); + }); + }); +} + +/** + * Capture Firefly IMS JWT by watching Network.requestWillBeSent on all page targets. + */ +async function captureViaCdp(opts: { + port: number; + browserWsUrl: string; + timeoutMs: number; +}): Promise<{ accessToken: string; cookies: CdpCookie[] }> { + let capturedAccessToken = ""; + const pageSockets = new Map(); + let browserCdp: CdpSocket | null = null; + + const onEvent = (method: string, params: Record) => { + if (method === "Network.requestWillBeSent") { + if (capturedAccessToken) return; + const request = params.request as + { url?: string; headers?: Record } | undefined; + if (!request?.url || !request.url.includes(FIREFLY_3P_HOST_SUFFIX)) return; + const headers = request.headers || {}; + const auth = headers.Authorization || headers.authorization || headers.AUTHORIZATION || ""; + const token = extractAdobeBearerTokenFromAuthorization(auth); + if (token) capturedAccessToken = token; + } else if (method === "Target.attachedToTarget") { + const sessionId = String(params.sessionId || ""); + const targetInfo = params.targetInfo as { type?: string; targetId?: string } | undefined; + if (sessionId && targetInfo?.type === "page" && browserCdp) { + void browserCdp.send("Network.enable", {}, sessionId).catch(() => undefined); + } + } + }; + + try { + const browserWs = await openCdp(opts.browserWsUrl); + browserCdp = new CdpSocket(browserWs, onEvent); + await browserCdp.send("Target.setDiscoverTargets", { discover: true }).catch(() => undefined); + await browserCdp + .send("Target.setAutoAttach", { + autoAttach: true, + waitForDebuggerOnStart: false, + flatten: true, + }) + .catch(() => undefined); + + const deadline = Date.now() + opts.timeoutMs; + while (Date.now() < deadline) { + // Attach to every page target listed by the DevTools HTTP API. + try { + const list = (await fetch(`http://127.0.0.1:${opts.port}/json/list`, { + signal: AbortSignal.timeout(2000), + }).then((r) => r.json())) as Array<{ + id?: string; + type?: string; + url?: string; + webSocketDebuggerUrl?: string; + }>; + for (const t of list) { + if (t.type !== "page" || !t.webSocketDebuggerUrl || !t.id) continue; + if (pageSockets.has(t.id)) continue; + try { + const ws = await openCdp(t.webSocketDebuggerUrl); + const cdp = new CdpSocket(ws, onEvent); + pageSockets.set(t.id, cdp); + await cdp.send("Network.enable"); + if (!t.url || t.url === "about:blank" || t.url.startsWith("chrome://")) { + await cdp.send("Page.enable").catch(() => undefined); + await cdp.send("Page.navigate", { url: FIREFLY_HOME_URL }).catch(() => undefined); + } + } catch { + // page may navigate away mid-connect + } + } + } catch { + // list may fail briefly while Chrome starts + } + + if (capturedAccessToken) { + // Prefer cookies from any live page socket; fall back to empty. + for (const cdp of pageSockets.values()) { + if (!cdp.open) continue; + try { + const result = (await cdp.send("Network.getAllCookies")) as { + cookies?: CdpCookie[]; + }; + return { + accessToken: capturedAccessToken, + cookies: Array.isArray(result?.cookies) ? result.cookies : [], + }; + } catch { + /* try next */ + } + } + return { accessToken: capturedAccessToken, cookies: [] }; + } + + await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS)); + } + + throw new Error( + "Adobe Firefly sign-in timed out. Complete sign-in at firefly.adobe.com and trigger an action " + + "(open Generate) so the browser sends the Firefly request, then try again." + ); + } finally { + for (const cdp of pageSockets.values()) cdp.close(); + browserCdp?.close(); + } +} + +function killProcessTree(child: ChildProcess | null): void { + if (!child?.pid) return; + try { + if (process.platform === "win32") { + spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { + stdio: "ignore", + windowsHide: true, + }); + } else { + child.kill("SIGTERM"); + setTimeout(() => { + try { + child.kill("SIGKILL"); + } catch { + /* ignore */ + } + }, 2000).unref?.(); + } + } catch { + try { + child.kill(); + } catch { + /* ignore */ + } + } +} + +/** + * Launch system Chrome/Edge at firefly.adobe.com, intercept firefly-3p + * Authorization Bearer via CDP, return JWT + useful cookies. + */ +export async function startAdobeFireflyBrowserLogin( + requestedTimeout?: unknown +): Promise { + const timeout = clampAdobeFireflyLoginTimeout(requestedTimeout); + const browserPath = resolveSystemBrowserExecutable(); + if (!browserPath) { + return { + success: false, + error: + "No Chrome or Edge browser found for Adobe Firefly sign-in. " + + "Install Google Chrome or Microsoft Edge, or set OMNIROUTE_LOGIN_BROWSER_PATH, " + + "or paste the IMS Bearer JWT from firefly-3p.ff.adobe.io.", + }; + } + + let userDataDir: string | null = null; + let child: ChildProcess | null = null; + try { + userDataDir = mkdtempSync(join(tmpdir(), "omniroute-firefly-login-")); + const port = await getFreeLoopbackPort(); + + const args = [ + `--remote-debugging-port=${port}`, + `--user-data-dir=${userDataDir}`, + "--no-first-run", + "--no-default-browser-check", + "--disable-sync", + "--disable-background-networking", + "--window-size=1280,800", + FIREFLY_HOME_URL, + ]; + + child = spawn(browserPath, args, { + stdio: "ignore", + windowsHide: false, + detached: false, + }); + + // If Chrome exits immediately, fail fast with a clear message. + const earlyExit = new Promise((_, reject) => { + child?.once("exit", (code) => { + reject(new Error(`Browser exited early (code ${code}). Is the executable runnable?`)); + }); + child?.once("error", (err) => { + reject(new Error(`Failed to launch browser: ${err.message}`)); + }); + }); + + const ready = waitForCdpReady(port, CDP_READY_TIMEOUT_MS); + const { webSocketDebuggerUrl } = await Promise.race([ready, earlyExit]); + + // Detach exit handler so normal user close after capture is fine + child.removeAllListeners("exit"); + child.removeAllListeners("error"); + + const captured = await Promise.race([ + captureViaCdp({ + port, + browserWsUrl: webSocketDebuggerUrl, + timeoutMs: timeout, + }), + earlyExit, + ]); + + const cookie = buildAdobeFireflyCookieHeader(captured.cookies); + const account = accountLabelFromAdobeJwt(captured.accessToken); + return { + success: true, + credentials: { + accessToken: captured.accessToken, + ...(cookie ? { cookie } : {}), + }, + ...(account ? { account } : {}), + }; + } catch (error) { + return { + success: false, + error: sanitizeErrorMessage(error instanceof Error ? error.message : error), + }; + } finally { + killProcessTree(child); + child = null; + if (userDataDir) { + // Give Chrome a moment to release the profile directory. + await new Promise((r) => setTimeout(r, 300)); + try { + rmSync(userDataDir, { recursive: true, force: true }); + } catch { + // Profile may still be locked; temp cleaner will reclaim later. + } + } + } +} diff --git a/open-sse/services/adobeFireflyClient.ts b/open-sse/services/adobeFireflyClient.ts index b9ee9e1589..b3b31cc46a 100644 --- a/open-sse/services/adobeFireflyClient.ts +++ b/open-sse/services/adobeFireflyClient.ts @@ -49,11 +49,57 @@ const DEFAULT_USER_AGENT = const DEFAULT_SEC_CH_UA = '"Not;A=Brand";v="8", "Chromium";v="150", "Google Chrome";v="150"'; const DEFAULT_POLL_INTERVAL_MS = 3000; -const DEFAULT_IMAGE_TIMEOUT_MS = 180_000; +/** + * Poll budget for image generate-async. Multi-ref gpt-image / nano jobs commonly + * exceed 3 minutes (upload + colligo + render at detailLevel 5). 180s was the + * previous default and produced widespread 504s on listing assets with screenshots. + */ +export const DEFAULT_IMAGE_TIMEOUT_MS = 300_000; const DEFAULT_VIDEO_TIMEOUT_MS = 300_000; +/** Extra poll budget per uploaded reference blob (large screenshots + image2image). */ +export const ADOBE_FIREFLY_IMAGE_TIMEOUT_PER_REF_MS = 60_000; +export const ADOBE_FIREFLY_IMAGE_TIMEOUT_MAX_MS = 600_000; +/** + * gpt-image family accepts subject refs, but the live SPA and colligo are reliable + * with 1–2 only. Sending 3–4+ (e.g. Store listing "5 screenshots") often hangs until + * poll timeout. Nano multi-ref composition supports more via usage "general". + */ +export const ADOBE_FIREFLY_GPT_IMAGE_MAX_REFS = 2; +export const ADOBE_FIREFLY_NANO_MAX_REFS = 4; +export const ADOBE_FIREFLY_GENERIC_IMAGE_MAX_REFS = 2; const FIREFLY_ORIGIN = "https://firefly.adobe.com"; const FIREFLY_REFERER = "https://firefly.adobe.com/"; +/** Cap reference uploads by Firefly image model family. */ +export function adobeFireflyMaxImageRefs(model: string): number { + const raw = String(model || "").toLowerCase(); + if (raw.includes("nano-banana") || raw.includes("nanobanana") || raw.includes("gemini-flash")) { + return ADOBE_FIREFLY_NANO_MAX_REFS; + } + if (raw.includes("gpt-image") || raw.includes("gptimage")) { + return ADOBE_FIREFLY_GPT_IMAGE_MAX_REFS; + } + return ADOBE_FIREFLY_GENERIC_IMAGE_MAX_REFS; +} + +/** + * Resolve poll timeout: explicit body.timeout_ms wins; else base + per-ref budget. + * Covers multi-screenshot listing jobs without unbounded waits. + */ +export function adobeFireflyImageTimeoutMs(opts?: { + timeoutMs?: number; + refCount?: number; +}): number { + const explicit = Number(opts?.timeoutMs); + if (Number.isFinite(explicit) && explicit > 0) { + return Math.min(ADOBE_FIREFLY_IMAGE_TIMEOUT_MAX_MS, Math.floor(explicit)); + } + const refs = Math.max(0, Math.floor(Number(opts?.refCount) || 0)); + const budget = + DEFAULT_IMAGE_TIMEOUT_MS + refs * ADOBE_FIREFLY_IMAGE_TIMEOUT_PER_REF_MS; + return Math.min(ADOBE_FIREFLY_IMAGE_TIMEOUT_MAX_MS, budget); +} + export type AdobeFireflyImageModelId = | "nano-banana-pro" | "nano-banana" @@ -716,9 +762,14 @@ export function buildAdobeImagePayload(opts: { }; if (opts.sourceImageIds?.length) { // gpt-image subject references (mask path uses separate mask blob when present). + // Cap to wire-stable count — extra subject blobs stall colligo until poll 504. + const refIds = opts.sourceImageIds + .map((id) => String(id)) + .filter(Boolean) + .slice(0, ADOBE_FIREFLY_GPT_IMAGE_MAX_REFS); payload.generationMetadata = { module: "image2image", submodule: "ff-image-generate" }; - payload.referenceBlobs = opts.sourceImageIds.map((id) => ({ - id: String(id), + payload.referenceBlobs = refIds.map((id) => ({ + id, usage: "subject", })); payload.modelSpecificPayload = {}; @@ -751,8 +802,16 @@ export function buildAdobeImagePayload(opts: { if (Object.keys(genSettings).length) payload.generationSettings = genSettings; if (opts.sourceImageIds?.length) { - payload.referenceBlobs = opts.sourceImageIds.map((id) => ({ - id: String(id), + const maxRefs = + opts.modelSpec.family === "generic" + ? ADOBE_FIREFLY_GENERIC_IMAGE_MAX_REFS + : ADOBE_FIREFLY_NANO_MAX_REFS; + const refIds = opts.sourceImageIds + .map((id) => String(id)) + .filter(Boolean) + .slice(0, maxRefs); + payload.referenceBlobs = refIds.map((id) => ({ + id, usage: "general", })); // Flux / Seedream / Runway image historically used image2image; nano keeps text2image. @@ -2167,11 +2226,15 @@ export async function adobeFireflyGenerateImage(opts: { } pollUrl = normalizeAdobePollUrl(pollUrl); + const pollTimeoutMs = adobeFireflyImageTimeoutMs({ + timeoutMs: opts.timeoutMs, + refCount: opts.sourceImageIds?.length ?? 0, + }); const { mediaUrl, latest } = await pollAdobeJob({ pollUrl, accessToken: opts.accessToken, kind: "image", - timeoutMs: opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_IMAGE_TIMEOUT_MS, + timeoutMs: pollTimeoutMs, fetchImpl, log: opts.log, }); diff --git a/open-sse/services/antigravityProjectBootstrap.ts b/open-sse/services/antigravityProjectBootstrap.ts index 169066d42f..7d69216f1e 100644 --- a/open-sse/services/antigravityProjectBootstrap.ts +++ b/open-sse/services/antigravityProjectBootstrap.ts @@ -1,5 +1,5 @@ /** - * Antigravity project bootstrap — loadCodeAssist. + * Antigravity project bootstrap — loadCodeAssist + onboardUser. * * The Google Cloud Code Assist API (/v1internal:models) requires a prior * /v1internal:loadCodeAssist call to assign a project context to the @@ -10,52 +10,70 @@ * attempt. Results are memoized per-token for the process lifetime to * avoid redundant round-trips. * - * Based on the Antigravity loadCodeAssist flow and the CLIProxyAPI reference - * implementation in internal/runtime/executor/antigravity_executor.go. + * When loadCodeAssist returns no project (account never onboarded), + * the fallback calls onboardUser to create the project, then retries. */ import { getAntigravityContentHeaders, getAntigravityLoadCodeAssistMetadata, } from "./antigravityHeaders.ts"; +import { extractCodeAssistOnboardTierId } from "./codeAssistSubscription.ts"; import type { AntigravityClientProfile } from "./antigravityClientProfile.ts"; -import { ANTIGRAVITY_BOOTSTRAP_BASE_URLS } from "../config/antigravityUpstream.ts"; +import { ANTIGRAVITY_BOOTSTRAP_BASE_URLS, getAntigravityOnboardUrls } from "../config/antigravityUpstream.ts"; const LOAD_CODE_ASSIST_PATH = "/v1internal:loadCodeAssist"; const BOOTSTRAP_TIMEOUT_MS = 8_000; +const ONBOARD_TIMEOUT_MS = 15_000; +const DEFAULT_TIER_ID = "legacy-tier"; -/** Ordered list of loadCodeAssist endpoint URLs (mirrors the models discovery order). */ +/** Ordered list of loadCodeAssist endpoint URLs. */ export function getAntigravityLoadCodeAssistUrls(): string[] { return ANTIGRAVITY_BOOTSTRAP_BASE_URLS.map((base) => `${base}${LOAD_CODE_ASSIST_PATH}`); } +/** Max entries in the per-token caches (prevents unbounded growth). */ +const MAX_CACHE_SIZE = 256; + +/** LRU-style Map: deleting and re-inserting moves the key to the end. */ +function evictOldest(cache: Map): void { + if (cache.size >= MAX_CACHE_SIZE) { + const oldest = cache.keys().next().value; + if (oldest !== undefined) cache.delete(oldest); + } +} + /** Per-token memoization cache (lives for the process lifetime). */ const projectCache = new Map(); +/** Per-key lock to prevent concurrent onboard attempts for the same token. */ +const onboardLocks = new Map>(); + type FetchLike = (url: string, init?: RequestInit) => Promise; function getProjectCacheKey(accessToken: string, clientProfile: AntigravityClientProfile): string { return `${clientProfile}:${accessToken}`; } +type LoadCodeAssistResult = { projectId: string | null; tierId: string }; + /** * Attempt loadCodeAssist against each known base URL in order. - * Returns the discovered project id, or null if all endpoints fail. + * Returns the discovered project id and tier id, or null projectId if all endpoints fail. */ async function tryLoadCodeAssist( accessToken: string, fetchImpl: FetchLike, clientProfile: AntigravityClientProfile, signal?: AbortSignal -): Promise { +): Promise { const urls = getAntigravityLoadCodeAssistUrls(); const headers = getAntigravityContentHeaders(clientProfile, accessToken); - for (const url of urls) { + for (let i = 0; i < urls.length; i++) { + const url = urls[i]; if (signal?.aborted) throw signal.reason; try { - // Combine the caller's cancellation signal (#8098) with the per-attempt - // bootstrap timeout so an aborted request tears down immediately. const timeoutSignal = AbortSignal.timeout(BOOTSTRAP_TIMEOUT_MS); const response = await fetchImpl(url, { method: "POST", @@ -75,7 +93,7 @@ async function tryLoadCodeAssist( // cloudaicompanionProject may be a plain string or an object with an id field. const raw = data.cloudaicompanionProject; - let projectId = + const projectId = typeof raw === "string" ? raw.trim() : raw && @@ -84,16 +102,21 @@ async function tryLoadCodeAssist( ? ((raw as Record).id as string).trim() : ""; + const tierId = extractCodeAssistOnboardTierId(data) || DEFAULT_TIER_ID; + if (projectId) { - return projectId; + return { projectId, tierId }; } + // Continue to next URL if available — a different endpoint might + // have the project. Only return empty when this is the last URL. + if (i === urls.length - 1) { + return { projectId: null, tierId }; + } console.warn( `[models] antigravity loadCodeAssist at ${url} returned no project id — trying next` ); } catch (error) { - // A caller-initiated abort (#8098) must propagate, not be swallowed as a - // "try next URL" transient — otherwise a cancelled request silently proceeds. if (signal?.aborted || (error instanceof Error && error.name === "AbortError")) { throw signal?.reason ?? error; } @@ -101,7 +124,65 @@ async function tryLoadCodeAssist( console.warn(`[models] antigravity loadCodeAssist threw for ${url}: ${msg} — trying next`); } } - return null; + return { projectId: null, tierId: DEFAULT_TIER_ID }; +} + +/** + * Attempt onboardUser to create a Cloud Code project for the account. + * Called when loadCodeAssist returns no project — the account has never + * been onboarded. Returns true if any endpoint reports success. + */ +async function tryOnboardUser( + accessToken: string, + fetchImpl: FetchLike, + clientProfile: AntigravityClientProfile, + tierId: string, + signal?: AbortSignal +): Promise { + const urls = getAntigravityOnboardUrls(); + const headers = getAntigravityContentHeaders(clientProfile, accessToken); + + for (const url of urls) { + if (signal?.aborted) throw signal.reason; + try { + const timeoutSignal = AbortSignal.timeout(ONBOARD_TIMEOUT_MS); + const response = await fetchImpl(url, { + method: "POST", + headers, + body: JSON.stringify({ + tier_id: tierId, + metadata: getAntigravityLoadCodeAssistMetadata(), + }), + signal: signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal, + }); + + if (response.ok) { + return true; + } + + console.warn( + `[models] antigravity onboardUser failed at ${url} (${response.status}) — trying next` + ); + } catch (error) { + if (signal?.aborted || (error instanceof Error && error.name === "AbortError")) { + throw signal?.reason ?? error; + } + const msg = error instanceof Error ? error.message : String(error); + console.warn(`[models] antigravity onboardUser threw for ${url}: ${msg} — trying next`); + } + } + return false; +} + +/** Per-token memoization for accounts we already tried onboarding (avoid repeated calls). */ +const onboardAttemptedCache = new Set(); + +function addToOnboardAttemptedCache(key: string): void { + if (onboardAttemptedCache.size >= MAX_CACHE_SIZE) { + const oldest = onboardAttemptedCache.values().next().value; + if (oldest !== undefined) onboardAttemptedCache.delete(oldest); + } + onboardAttemptedCache.add(key); } /** @@ -123,22 +204,72 @@ export async function ensureAntigravityProjectAssigned( ): Promise { const cacheKey = getProjectCacheKey(accessToken, clientProfile); if (projectCache.has(cacheKey)) { - return projectCache.get(cacheKey); // already bootstrapped for this token + const cached = projectCache.get(cacheKey)!; + // Touch on read: delete+reinsert moves this entry to the end (LRU). + projectCache.delete(cacheKey); + projectCache.set(cacheKey, cached); + return cached; } - const projectId = await tryLoadCodeAssist(accessToken, fetchImpl, clientProfile, signal); + const { projectId: initialProjectId, tierId } = await tryLoadCodeAssist( + accessToken, fetchImpl, clientProfile, signal + ); + + let projectId = initialProjectId; + + // loadCodeAssist is read-only — if the account was never onboarded, it returns + // empty. Call onboardUser to create the project, then retry discovery. + if (!projectId && !onboardAttemptedCache.has(cacheKey)) { + // Per-key lock: concurrent calls for the same token share one onboard attempt. + let lock = onboardLocks.get(cacheKey); + if (!lock) { + lock = (async () => { + let aborted = false; + try { + const onboarded = await tryOnboardUser( + accessToken, fetchImpl, clientProfile, tierId, signal + ); + if (onboarded) { + const retry = await tryLoadCodeAssist( + accessToken, fetchImpl, clientProfile, signal + ); + if (retry.projectId) { + evictOldest(projectCache); + projectCache.set(cacheKey, retry.projectId); + return true; + } + } + return false; + } catch (e) { + aborted = signal?.aborted === true; + return false; + } finally { + onboardLocks.delete(cacheKey); + if (!aborted) addToOnboardAttemptedCache(cacheKey); + } + })(); + onboardLocks.set(cacheKey, lock); + } + const success = await lock; + if (success) { + const cached = projectCache.get(cacheKey); + if (cached) return cached; + } + } if (projectId) { + evictOldest(projectCache); projectCache.set(cacheKey, projectId); return projectId; } - // Non-fatal: if all endpoints failed, we proceed without caching. return undefined; } /** Exported for tests. */ export function clearAntigravityProjectCache(): void { projectCache.clear(); + onboardAttemptedCache.clear(); + onboardLocks.clear(); } /** Exported for tests — inspect cache state. */ diff --git a/open-sse/services/autoCombo/pipelineRouter.ts b/open-sse/services/autoCombo/pipelineRouter.ts index e957fd83f7..5fbc9eea02 100644 --- a/open-sse/services/autoCombo/pipelineRouter.ts +++ b/open-sse/services/autoCombo/pipelineRouter.ts @@ -54,6 +54,7 @@ const INTENT_TO_TASK: Record = { export interface PipelineComboParams { body: Record; combo: Record; + availableModels?: readonly string[]; handleChatCore: (body: Record, modelStr?: string) => Promise; log: { info: (...args: unknown[]) => void; @@ -85,7 +86,7 @@ export interface StageExecutorResult { */ function resolveModelForTier( tier: FitnessTier, - availableModels: string[], + availableModels: readonly string[], taskType: string ): string { // Score each available model for this task type and tier @@ -125,7 +126,7 @@ function createStageExecutor( body: Record, handleChatCore: (body: Record, modelStr?: string) => Promise, log: { info: (...args: unknown[]) => void; warn: (...args: unknown[]) => void }, - availableModels: string[], + availableModels: readonly string[], taskType: string ): (args: StageExecutorArgs & { fitnessTier?: FitnessTier }) => Promise { return async ({ @@ -222,6 +223,7 @@ function estimateTokens(messages: Array<{ role: string; content: unknown }>): nu export async function handlePipelineCombo({ body, combo, + availableModels: routedModels, handleChatCore, log, settings, @@ -291,7 +293,13 @@ export async function handlePipelineCombo({ }) .filter((model): model is string => typeof model === "string" && model.length > 0) : []; - const availableModels = comboModels.length ? comboModels : ["deepseek-chat"]; + const availableModels = + routedModels === undefined + ? comboModels.length + ? comboModels + : ["deepseek-chat"] + : routedModels; + if (availableModels.length === 0) throw new Error("PIPELINE_NO_MODELS"); // ── Create stage executor ───────────────────────────────────────────────── const stageExecutor = createStageExecutor(body, handleChatCore, log, availableModels, taskType); diff --git a/open-sse/services/claudeCodeConstraints.ts b/open-sse/services/claudeCodeConstraints.ts index af17a3657c..ddac177b32 100644 --- a/open-sse/services/claudeCodeConstraints.ts +++ b/open-sse/services/claudeCodeConstraints.ts @@ -128,6 +128,20 @@ export function ensureCacheControlOnLastUserMessage(body: Record> | undefined; if (!Array.isArray(messages) || messages.length === 0) return; + const system = body.system as Array> | undefined; + const systemCacheControlCount = Array.isArray(system) + ? system.filter((block) => block.cache_control).length + : 0; + + for (const message of messages) { + const content = message.content as Array> | undefined; + if (Array.isArray(content) && content.some((block) => block.cache_control)) { + return; + } + } + + if (systemCacheControlCount >= MAX_CACHE_CONTROL_BLOCKS) return; + // Find the last user message for (let i = messages.length - 1; i >= 0; i--) { if (String(messages[i].role) === "user") { diff --git a/open-sse/services/codexUsageQuotas.ts b/open-sse/services/codexUsageQuotas.ts index 4d4ed9c229..e730e9279d 100644 --- a/open-sse/services/codexUsageQuotas.ts +++ b/open-sse/services/codexUsageQuotas.ts @@ -13,6 +13,7 @@ export type CodexUsageQuota = { remaining?: number; resetAt: string | null; unlimited: boolean; + windowSeconds: number | null; displayName?: string; }; @@ -38,6 +39,15 @@ function toNumber(value: unknown, fallback = 0): number { return fallback; } +function toNullableNumber(value: unknown): number | null { + if (typeof value === "number" && Number.isFinite(value)) return value; + if (typeof value === "string" && value.trim().length > 0) { + const parsed = Number(value); + return Number.isFinite(parsed) ? parsed : null; + } + return null; +} + function parseResetTime(resetValue: unknown): string | null { if (!resetValue) return null; try { @@ -81,6 +91,15 @@ function buildPercentageQuota(window: JsonRecord, displayName?: string): CodexUs remaining: 100 - usedPercent, resetAt: parseWindowReset(window), unlimited: false, + windowSeconds: toNullableNumber( + getFieldValue( + window, + "limit_window_seconds", + "limitWindowSeconds", + "window_seconds", + "windowSeconds" + ) + ), ...(displayName ? { displayName } : {}), }; } @@ -105,10 +124,7 @@ function isLatentWindow(window: JsonRecord): boolean { getFieldValue(window, "limit_window_seconds", "limitWindowSeconds"), 0 ); - const resetAfter = toNumber( - getFieldValue(window, "reset_after_seconds", "resetAfterSeconds"), - 0 - ); + const resetAfter = toNumber(getFieldValue(window, "reset_after_seconds", "resetAfterSeconds"), 0); return usedPercent === 0 && limitWindow > 0 && resetAfter >= limitWindow; } @@ -225,7 +241,9 @@ function findCodexReviewRateLimit(data: JsonRecord): JsonRecord { * (issue #5199). */ function parseBankedResetCredits(data: JsonRecord): number | undefined { - const resetCredits = toRecord(getFieldValue(data, "rate_limit_reset_credits", "rateLimitResetCredits")); + const resetCredits = toRecord( + getFieldValue(data, "rate_limit_reset_credits", "rateLimitResetCredits") + ); const availableCount = getFieldValue(resetCredits, "available_count", "availableCount"); const count = toNumber(availableCount, NaN); return Number.isFinite(count) ? count : undefined; diff --git a/open-sse/services/combo.ts b/open-sse/services/combo.ts index 12113422ca..acfb0e81c6 100644 --- a/open-sse/services/combo.ts +++ b/open-sse/services/combo.ts @@ -570,6 +570,7 @@ export async function handleComboChat({ signal, apiKeyAllowedConnections = null, nesting = null, + hiddenModelsByProvider = getHiddenModelsByProvider(), }: HandleComboChatOptions): Promise { const comboCtx = createComboContext({ body, combo, settings, relayOptions, log }); const { @@ -607,6 +608,7 @@ export async function handleComboChat({ clientRequestedStream, handleSingleModelWithTimeout, log, + hiddenModelsByProvider, }); if (pinnedDispatch) return pinnedDispatch; } @@ -628,6 +630,7 @@ export async function handleComboChat({ relayOptions, signal, apiKeyAllowedConnections, + hiddenModelsByProvider, runCombo: handleComboChat, }); if (fusionDispatch) return fusionDispatch; @@ -636,7 +639,12 @@ export async function handleComboChat({ // chaosEngine.ts (dispatchChaosFromCombo), returning null when not chaos-enabled. const chaosDispatch = dispatchChaosFromCombo({ cfg, - comboModels: combo.models || [], + comboModels: resolveComboTargets( + combo, + allCombos, + clampComboDepth(config.maxComboDepth), + hiddenModelsByProvider + ).map((target) => target.modelStr), comboName: combo.name, body, handleSingleModel: handleSingleModelWithTimeout, @@ -649,8 +657,10 @@ export async function handleComboChat({ combo, config, strategy, + allCombos, handleSingleModelWithTimeout, log, + hiddenModelsByProvider, }); if (pipelineDispatch) return pipelineDispatch; @@ -669,6 +679,7 @@ export async function handleComboChat({ relayOptions, signal, apiKeyAllowedConnections, + hiddenModelsByProvider, runCombo: handleComboChat, }); if (runtimeUnitDispatch) return runtimeUnitDispatch; @@ -684,6 +695,7 @@ export async function handleComboChat({ settings, allCombos, signal, + hiddenModelsByProvider, }); } @@ -708,6 +720,7 @@ export async function handleComboChat({ isModelAvailable, handleSingleModelWithTimeout, buildAutoCandidates, + hiddenModelsByProvider, }); if ("earlyResponse" in targetResolution) return targetResolution.earlyResponse; const { stickyWeightedLimit, getWeightedStepKeyForTarget, preScreenMap } = targetResolution; @@ -749,7 +762,7 @@ export async function handleComboChat({ combo, config, body, - resolveShadowTargets(combo, config, allCombos), + resolveShadowTargets(combo, config, allCombos, hiddenModelsByProvider), handleSingleModel, isModelAvailable, strategy, @@ -2184,11 +2197,15 @@ async function handleRoundRobinCombo({ settings, allCombos, signal, + hiddenModelsByProvider = getHiddenModelsByProvider(), }: HandleRoundRobinOptions): Promise { const config = settings ? resolveComboConfig(combo, settings) : { ...getDefaultComboConfig(), ...(combo.config || {}) }; - const concurrency = config.concurrencyPerModel ?? 3; + // #9158: clamp combo-level concurrency to a sane bound — a config carrying a + // huge or negative value would otherwise open an unbounded semaphore and + // flood targets (or deadlock at 0). + const concurrency = Math.min(Math.max(config.concurrencyPerModel ?? 3, 1), 32); // Honor each target connection's own maxConcurrent ceiling (cached per dispatch) // so a low-concurrency subscription account is not flooded; falls back to the // combo-level concurrency when the connection has no positive cap. @@ -2222,7 +2239,8 @@ async function handleRoundRobinCombo({ const orderedTargets = resolveComboTargets( rrExpandedCombo, rrExpandedAllCombos, - clampComboDepth(config.maxComboDepth) + clampComboDepth(config.maxComboDepth), + hiddenModelsByProvider ); const tagFilteredTargets = await applyRequestTagRouting(orderedTargets, body, log); const evalRankedTargets = orderTargetsByEvalScores(tagFilteredTargets, config.evalRouting, log); @@ -2295,7 +2313,7 @@ async function handleRoundRobinCombo({ combo, config, body, - resolveShadowTargets(combo, config, allCombos), + resolveShadowTargets(combo, config, allCombos, hiddenModelsByProvider), handleSingleModel, isModelAvailable, "round-robin", diff --git a/open-sse/services/combo/comboStructure.ts b/open-sse/services/combo/comboStructure.ts index 4bb3aabc33..fa711c6b8c 100644 --- a/open-sse/services/combo/comboStructure.ts +++ b/open-sse/services/combo/comboStructure.ts @@ -12,15 +12,14 @@ */ import { getModelContextLimit } from "../../../src/lib/modelCapabilities"; +import { getHiddenModelsByProvider } from "../../../src/lib/db/models"; import { getComboModelString, normalizeComboStep } from "../../../src/lib/combos/steps.ts"; -import { - getProviderByAlias, - getProviderById, -} from "../../../src/shared/constants/providers.ts"; +import { getProviderByAlias, getProviderById } from "../../../src/shared/constants/providers.ts"; import { estimateTokens } from "../contextManager.ts"; import { getResolvedModelCapabilities } from "../modelCapabilities.ts"; -import { parseModel } from "../model.ts"; +import { parseModel, stripContextWindowSuffix } from "../model.ts"; import { dedupeTargetsByExecutionKey, isRecord } from "./comboData.ts"; +import { isComboModelVisible } from "./comboVisibility.ts"; import { getTargetProvider, MAX_COMBO_DEPTH } from "./comboPredicates.ts"; import { evaluateContextLimit } from "./contextOverrideGate.ts"; import { hasEstimableContent } from "./knownContextOverflow.ts"; @@ -35,6 +34,7 @@ import type { ComboLike, ComboLogger, ComboRuntimeStep, + HiddenModelsByProvider, NestedComboMode, ResolvedComboTarget, ResolvedComboUnit, @@ -135,15 +135,28 @@ function normalizeRuntimeStep( : {}), weight, label, + prompt: step.prompt || null, } satisfies ResolvedComboTarget; } -function getDirectComboTargets(combo: ComboLike): ResolvedComboTarget[] { - return getOrderedTopLevelRuntimeSteps(combo, null).filter( - (entry): entry is ResolvedComboTarget => entry?.kind === "model" +function isComboTargetVisible( + target: ResolvedComboTarget, + hiddenModelsByProvider: HiddenModelsByProvider +): boolean { + return isComboModelVisible( + target.modelStr, + target.providerId || target.provider, + hiddenModelsByProvider ); } +export function filterVisibleComboTargets( + targets: ResolvedComboTarget[], + hiddenModelsByProvider: HiddenModelsByProvider = getHiddenModelsByProvider() +): ResolvedComboTarget[] { + return targets.filter((target) => isComboTargetVisible(target, hiddenModelsByProvider)); +} + function getTopLevelRuntimeSteps( combo: ComboLike, allCombos: ComboCollectionLike, @@ -323,7 +336,8 @@ export function getComboModelsFromData( modelStr: string, combosData: ComboCollectionLike ): string[] | null { - const combo = getComboFromData(modelStr, combosData); + const baseModelStr = stripContextWindowSuffix(modelStr); + const combo = getComboFromData(baseModelStr || modelStr, combosData); if (!combo) return null; return combo.models.map((m) => normalizeModelEntry(m).model); } @@ -834,36 +848,50 @@ export function sortTargetsByContextSize(targets: ResolvedComboTarget[]) { export function resolveComboTargets( combo: ComboLike, allCombos: ComboCollectionLike, - maxDepth: number = MAX_COMBO_DEPTH + maxDepth: number = MAX_COMBO_DEPTH, + hiddenModelsByProvider: HiddenModelsByProvider = getHiddenModelsByProvider() ): ResolvedComboTarget[] { - return allCombos - ? resolveNestedComboTargets(combo, allCombos, new Set(), 0, [], maxDepth) - : getDirectComboTargets(combo); + return filterVisibleComboTargets( + allCombos + ? resolveNestedComboTargets(combo, allCombos, new Set(), 0, [], maxDepth) + : getOrderedTopLevelRuntimeSteps(combo, null).filter( + (entry): entry is ResolvedComboTarget => entry?.kind === "model" + ), + hiddenModelsByProvider + ); } export function resolveComboRuntimeUnits( combo: ComboLike, allCombos: ComboCollectionLike, mode: NestedComboMode, - maxDepth: number = MAX_COMBO_DEPTH + maxDepth: number = MAX_COMBO_DEPTH, + hiddenModelsByProvider: HiddenModelsByProvider = getHiddenModelsByProvider() ): ResolvedComboUnit[] { - if (mode === "flatten" || !allCombos) return resolveComboTargets(combo, allCombos, maxDepth); + if (mode === "flatten" || !allCombos) + return resolveComboTargets(combo, allCombos, maxDepth, hiddenModelsByProvider); validateComboDAG(combo.name, allCombos, new Set(), 0, maxDepth); - return getOrderedTopLevelRuntimeSteps(combo, allCombos); + return getOrderedTopLevelRuntimeSteps(combo, allCombos).filter( + (unit) => unit.kind === "combo-ref" || isComboTargetVisible(unit, hiddenModelsByProvider) + ); } export function resolveWeightedStepGroups( combo: ComboLike, - allCombos: ComboCollectionLike + allCombos: ComboCollectionLike, + hiddenModelsByProvider: HiddenModelsByProvider = getHiddenModelsByProvider() ): Array<{ step: ComboRuntimeStep; targets: ResolvedComboTarget[] }> { return getOrderedTopLevelRuntimeSteps(combo, allCombos) .map((step) => ({ step, - targets: !allCombos - ? step.kind === "model" - ? [step] - : [] - : expandRuntimeStep(step, allCombos, new Set([combo.name])), + targets: filterVisibleComboTargets( + !allCombos + ? step.kind === "model" + ? [step] + : [] + : expandRuntimeStep(step, allCombos, new Set([combo.name])), + hiddenModelsByProvider + ), })) .filter((group) => group.targets.length > 0); } diff --git a/open-sse/services/combo/comboVisibility.ts b/open-sse/services/combo/comboVisibility.ts new file mode 100644 index 0000000000..e3d363ef59 --- /dev/null +++ b/open-sse/services/combo/comboVisibility.ts @@ -0,0 +1,23 @@ +import { getHiddenModelsByProvider } from "../../../src/lib/db/models"; +import { parseModel, resolveCanonicalProviderModel } from "../model.ts"; +import type { HiddenModelsByProvider } from "./types.ts"; + +export function isComboModelVisible( + modelStr: string, + providerId: string | null = null, + hiddenModelsByProvider: HiddenModelsByProvider = getHiddenModelsByProvider() +): boolean { + const parsed = parseModel(modelStr); + const hasExplicitProvider = + providerId && providerId !== parsed.provider && providerId !== parsed.providerAlias; + const rawModel = hasExplicitProvider ? modelStr : parsed.model || modelStr; + const resolved = resolveCanonicalProviderModel( + providerId || parsed.provider || parsed.providerAlias, + rawModel + ); + return ( + !resolved.provider || + !resolved.model || + !hiddenModelsByProvider.get(resolved.provider)?.has(resolved.model) + ); +} diff --git a/open-sse/services/combo/contextOverrideGate.ts b/open-sse/services/combo/contextOverrideGate.ts index 605c27c13f..4f03978a45 100644 --- a/open-sse/services/combo/contextOverrideGate.ts +++ b/open-sse/services/combo/contextOverrideGate.ts @@ -16,14 +16,13 @@ * pool to one provider and producing a hard 503 with no fallback once that * provider's quota is exhausted. An operator-set or auto-discovered override * reflects the real capacity, so it supersedes both catalog limits. Uses the - * raw override (`getModelContextOverride` returns `null` when none is set) — + * resolved exact override (`getResolvedModelContextOverride` returns `null` when none is set) — * NOT `getModelContextLimitForModelString`, which falls back to * `contextWindow` and would therefore bypass the `maxInputTokens` cap for * every model, not just overridden ones. */ -import { getModelContextOverride } from "../../../src/lib/db/modelContextOverrides"; -import { parseModel } from "../model.ts"; +import { getResolvedModelContextOverride } from "../../../src/lib/modelCapabilities"; /** * Resolve the context-fit verdict from a persisted per-model override, if one @@ -36,8 +35,7 @@ function resolveContextOverrideVerdict( requiredContextTokens: number ): boolean | undefined { if (!modelStr) return undefined; - const parsed = parseModel(modelStr); - const override = getModelContextOverride(parsed.provider, parsed.model); + const override = getResolvedModelContextOverride(modelStr); if (override == null) return undefined; return override >= requiredContextTokens; } diff --git a/open-sse/services/combo/dispatchPrelude.ts b/open-sse/services/combo/dispatchPrelude.ts index 69d2576c00..9c30bf8233 100644 --- a/open-sse/services/combo/dispatchPrelude.ts +++ b/open-sse/services/combo/dispatchPrelude.ts @@ -45,6 +45,7 @@ import type { HandleComboChatOptions, HandleSingleModel, IsModelAvailable, + HiddenModelsByProvider, NestedComboMode, ResolvedComboUnit, SingleModelTarget, @@ -68,6 +69,7 @@ type PreludeBaseOptionArgs = { relayOptions?: HandleComboChatOptions["relayOptions"]; signal?: AbortSignal | null; apiKeyAllowedConnections?: string[] | null; + hiddenModelsByProvider?: HiddenModelsByProvider; }; /** Rebuild handleComboChat's option bag verbatim for a recursive dispatch. */ @@ -83,6 +85,7 @@ function buildBaseOptions(a: PreludeBaseOptionArgs): HandleComboChatOptions { relayOptions: a.relayOptions, signal: a.signal, apiKeyAllowedConnections: a.apiKeyAllowedConnections, + hiddenModelsByProvider: a.hiddenModelsByProvider, }; } @@ -232,6 +235,7 @@ export async function tryPinnedModelDispatch(args: { clientRequestedStream: boolean; handleSingleModelWithTimeout: HandleSingleModel; log: ComboLogger; + hiddenModelsByProvider?: HiddenModelsByProvider; }): Promise { const { body, @@ -242,6 +246,7 @@ export async function tryPinnedModelDispatch(args: { clientRequestedStream, handleSingleModelWithTimeout, log, + hiddenModelsByProvider, } = args; // The pin is read from session_model_history (a PRIOR turn) and may name a // model that has since been removed from this combo, or a provider whose @@ -254,11 +259,12 @@ export async function tryPinnedModelDispatch(args: { // when allCombos is authoritative (non-empty) so we can resolve combo-refs; // the auto-combo redirect path passes an empty list and keeps prior behavior. const haveFullCombos = Array.isArray(allCombos) ? allCombos.length > 0 : !!allCombos; - const pinInCombo = - !haveFullCombos || - resolveComboTargets(combo, allCombos, clampComboDepth(config.maxComboDepth)).some( - (t) => t.modelStr === pinnedModel - ); + const pinInCombo = resolveComboTargets( + combo, + haveFullCombos ? allCombos : null, + clampComboDepth(config.maxComboDepth), + hiddenModelsByProvider + ).some((target) => target.modelStr === pinnedModel); // Honor the pin only if it is still a combo target AND its provider is not // DURABLY down. Without the health gate a pin keeps routing a session to a // dead/credits-exhausted/throttled account forever (strategy bypassed, no @@ -330,6 +336,7 @@ export async function tryFusionDispatch(args: { relayOptions?: HandleComboChatOptions["relayOptions"]; signal?: AbortSignal | null; apiKeyAllowedConnections?: string[] | null; + hiddenModelsByProvider?: HiddenModelsByProvider; runCombo: RunCombo; }): Promise { const { cfg, combo, config, strategy, log } = args; @@ -347,9 +354,14 @@ export async function tryFusionDispatch(args: { if (strategy !== "fusion") return null; const { panel: fusionModels, comboRefUnits } = extractFusionPanelSpec( - combo.models || [], + resolveComboTargets( + combo, + args.allCombos, + clampComboDepth(config.maxComboDepth), + args.hiddenModelsByProvider + ).map((target) => target.modelStr), combo.name, - args.allCombos + null ); // Untyped like the existing `nestingContext` further down — `nesting` is // already `ComboNestingContext | null` per HandleComboChatOptions, no new @@ -389,26 +401,28 @@ export async function tryPipelineDispatch(args: { combo: ComboLike; config: ComboSetupConfig; strategy: string; + allCombos?: ComboCollectionLike; handleSingleModelWithTimeout: HandleSingleModel; log: ComboLogger; + hiddenModelsByProvider?: HiddenModelsByProvider; }): Promise { - const { body, combo, config, strategy, handleSingleModelWithTimeout, log } = args; + const { + body, + combo, + config, + strategy, + allCombos, + handleSingleModelWithTimeout, + log, + hiddenModelsByProvider, + } = args; if (strategy !== "pipeline") return null; - const pipelineSteps = (combo.models || []) - .map((m): PipelineStep | null => { - if (typeof m === "string") return { model: m }; - if (m && typeof m === "object") { - const obj = m as Record; - if (typeof obj.model === "string") { - return { - model: obj.model, - prompt: typeof obj.prompt === "string" ? obj.prompt : undefined, - }; - } - } - return null; - }) - .filter((s): s is PipelineStep => Boolean(s)); + const pipelineSteps: PipelineStep[] = resolveComboTargets( + combo, + allCombos, + clampComboDepth(config.maxComboDepth), + hiddenModelsByProvider + ).map((target) => ({ target, prompt: target.prompt })); return handlePipelineChat({ body, steps: pipelineSteps, @@ -523,6 +537,7 @@ export async function tryRuntimeUnitDispatch(args: { relayOptions?: HandleComboChatOptions["relayOptions"]; signal?: AbortSignal | null; apiKeyAllowedConnections?: string[] | null; + hiddenModelsByProvider?: HiddenModelsByProvider; runCombo: RunCombo; }): Promise { const { body, combo, config, strategy, allCombos, log, settings } = args; @@ -531,7 +546,13 @@ export async function tryRuntimeUnitDispatch(args: { const executeModeUnits = nestedComboMode === "execute" && allCombos - ? resolveComboRuntimeUnits(combo, allCombos, "execute", nestingContext.maxDepth) + ? resolveComboRuntimeUnits( + combo, + allCombos, + "execute", + nestingContext.maxDepth, + args.hiddenModelsByProvider + ) : []; const hasExecutableComboRef = executeModeUnits.some((unit) => unit.kind === "combo-ref"); const simpleExecuteStrategies = new Set([ diff --git a/open-sse/services/combo/shadowRouting.ts b/open-sse/services/combo/shadowRouting.ts index 5483b4320d..a04a23687f 100644 --- a/open-sse/services/combo/shadowRouting.ts +++ b/open-sse/services/combo/shadowRouting.ts @@ -16,13 +16,14 @@ import { secureRandomFloat } from "../../../src/shared/utils/secureRandom"; import { recordComboShadowRequest } from "../comboMetrics.ts"; import { isRecord } from "./comboData.ts"; -import { resolveNestedComboTargets } from "./comboStructure.ts"; +import { filterVisibleComboTargets, resolveNestedComboTargets } from "./comboStructure.ts"; import { toRecordedTarget } from "./comboPredicates.ts"; import type { ComboLike, ComboCollectionLike, ComboLogger, HandleSingleModel, + HiddenModelsByProvider, IsModelAvailable, ResolvedComboTarget, ShadowRoutingConfig, @@ -47,7 +48,8 @@ function normalizeShadowRoutingConfig(config: Record): ShadowRo export function resolveShadowTargets( combo: ComboLike, config: Record, - allCombos: ComboCollectionLike + allCombos: ComboCollectionLike, + hiddenModelsByProvider?: HiddenModelsByProvider ): ResolvedComboTarget[] { const shadowConfig = normalizeShadowRoutingConfig(config); if (!shadowConfig.enabled || shadowConfig.targets.length === 0) return []; @@ -58,7 +60,10 @@ export function resolveShadowTargets( name: `${combo.name}:shadow`, models: shadowConfig.targets, }; - return resolveNestedComboTargets(shadowCombo, allCombos, new Set([combo.name]), 0, ["shadow"]) + return filterVisibleComboTargets( + resolveNestedComboTargets(shadowCombo, allCombos, new Set([combo.name]), 0, ["shadow"]), + hiddenModelsByProvider + ) .slice(0, shadowConfig.maxTargets) .map((target) => ({ ...target, diff --git a/open-sse/services/combo/targetResolution.ts b/open-sse/services/combo/targetResolution.ts index 82f23b8c3d..e6b4771239 100644 --- a/open-sse/services/combo/targetResolution.ts +++ b/open-sse/services/combo/targetResolution.ts @@ -88,6 +88,7 @@ import type { ComboRuntimeStep, HandleSingleModel, IsModelAvailable, + HiddenModelsByProvider, ResolvedComboTarget, } from "./types.ts"; @@ -111,6 +112,7 @@ export interface ResolveComboTargetPipelineDeps { * this leaf), so importing it directly would create an import cycle. */ buildAutoCandidates: ResolveAutoStrategyDeps["buildAutoCandidates"]; + hiddenModelsByProvider?: HiddenModelsByProvider; } export interface ResolvedComboTargetPipeline { @@ -204,10 +206,15 @@ async function collectWeightedEligibility( expandedCombo: ComboLike, expandedAllCombos: ComboCollectionLike, resilienceSettings: ResilienceSettings, - isModelAvailable?: IsModelAvailable + isModelAvailable?: IsModelAvailable, + hiddenModelsByProvider?: HiddenModelsByProvider ): Promise<{ stepGroups: WeightedStepGroups; weightedEligibleKeys: Set }> { const weightedEligibleKeys = new Set(); - const stepGroups = resolveWeightedStepGroups(expandedCombo, expandedAllCombos); + const stepGroups = resolveWeightedStepGroups( + expandedCombo, + expandedAllCombos, + hiddenModelsByProvider + ); for (const group of stepGroups) { const availability = await Promise.all( group.targets.map((target) => @@ -260,7 +267,8 @@ async function resolveWeightedSelection( expandedCombo, expandedAllCombos, deps.resilienceSettings, - deps.isModelAvailable + deps.isModelAvailable, + deps.hiddenModelsByProvider ); stepGroups = eligibility.stepGroups; weightedEligibleKeys = eligibility.weightedEligibleKeys; @@ -351,7 +359,8 @@ function logTargetPoolSize( * auto routing (pipeline disabled, below token threshold, or dispatch failure). */ async function dispatchSmartPipeline( - deps: ResolveComboTargetPipelineDeps + deps: ResolveComboTargetPipelineDeps, + availableModels: readonly string[] ): Promise { const { body, combo, strategy, config, settings, signal, log } = deps; if (strategy !== "auto") return null; @@ -362,6 +371,7 @@ async function dispatchSmartPipeline( const pipelineRaw = await handlePipelineCombo({ body, combo, + availableModels, handleChatCore: deps.handleSingleModelWithTimeout, log: { info: log.info, @@ -687,7 +697,8 @@ export async function resolveComboTargetPipeline( : resolveComboTargets( expandedCombo, expandedAllCombos, - clampComboDepth(config.maxComboDepth) + clampComboDepth(config.maxComboDepth), + deps.hiddenModelsByProvider ); orderedTargets = await applyRequestTagRouting(orderedTargets, body, log); @@ -699,7 +710,10 @@ export async function resolveComboTargetPipeline( logTargetPoolSize(strategy, allCombos, orderedTargets, stickyWeightedKey, log); - const pipelineResponse = await dispatchSmartPipeline(deps); + const pipelineResponse = await dispatchSmartPipeline( + deps, + orderedTargets.map((target) => target.modelStr) + ); if (pipelineResponse) return { earlyResponse: pipelineResponse }; const ordering = await orderByStrategy(deps, orderedTargets); diff --git a/open-sse/services/combo/types.ts b/open-sse/services/combo/types.ts index 9371d11529..ca00fedbce 100644 --- a/open-sse/services/combo/types.ts +++ b/open-sse/services/combo/types.ts @@ -95,6 +95,8 @@ export type ComboNestingContext = { attemptBudget: { count: number; limit: number }; }; +export type HiddenModelsByProvider = ReadonlyMap>; + export type HandleComboChatOptions = { body: Record; combo: ComboLike; @@ -107,6 +109,7 @@ export type HandleComboChatOptions = { signal?: AbortSignal | null; apiKeyAllowedConnections?: string[] | null; nesting?: ComboNestingContext | null; + hiddenModelsByProvider?: HiddenModelsByProvider; }; export type HandleRoundRobinOptions = Omit< @@ -167,6 +170,7 @@ export type ResolvedComboTarget = { allowedConnectionIds?: string[] | null; weight: number; label: string | null; + prompt?: string | null; failoverBeforeRetry?: unknown; trafficType?: "production" | "shadow"; /** diff --git a/open-sse/services/comboConfig.ts b/open-sse/services/comboConfig.ts index 30fd959186..9bae96b52e 100644 --- a/open-sse/services/comboConfig.ts +++ b/open-sse/services/comboConfig.ts @@ -98,7 +98,15 @@ const DEFAULT_COMBO_CONFIG = { maxRetries: 1, retryDelayMs: 2000, fallbackDelayMs: 0, - concurrencyPerModel: 3, // max simultaneous requests per model (round-robin) + // #9100: round-robin combo concurrency was hard-capped at 3 concurrent + // requests per model with no override — 5 concurrent requests through a + // round-robin combo serialized behind that cap. Now configurable via + // COMBO_CONCURRENCY_PER_MODEL (validated to >= 1, clamped to <= 32; default + // 3 preserves the historical behavior). + concurrencyPerModel: Math.min( + Math.max(Number(process.env.COMBO_CONCURRENCY_PER_MODEL) || 3, 1), + 32 + ), queueTimeoutMs: 120000, // max wait time in semaphore queue (round-robin); raised from 30s for browser-automation providers like gemini-web (#9407) queueDepth: DEFAULT_COMBO_QUEUE_DEPTH, // pre-cascade semaphore queue depth (round-robin, #3872) handoffThreshold: 0.85, diff --git a/open-sse/services/compression/engines/ccr/index.ts b/open-sse/services/compression/engines/ccr/index.ts index 476d9b37b0..e52755129f 100644 --- a/open-sse/services/compression/engines/ccr/index.ts +++ b/open-sse/services/compression/engines/ccr/index.ts @@ -61,7 +61,12 @@ const RETRIEVAL_THRESHOLD = 3; * ramp (only the >= threshold cliff remains — the legacy binary behavior). */ const RETRIEVAL_RAMP_FACTOR_DEFAULT = 2; -/** Maximum number of entries in the principal-scoped, LRU-ordered store. */ +/** + * Maximum number of entries in the LRU-ordered store, across every principal. The store + * is keyed per principal, but this cap is not: the only per-principal cap is + * `MAX_CCR_PRINCIPAL_BYTES`. Eviction under this cap takes the storing principal's own + * blocks first (see `enforceGlobalBudget`). + */ export const MAX_CCR_ENTRIES = 5_000; export const MAX_CCR_BLOCK_BYTES = 2 * 1024 * 1024; export const MAX_CCR_PRINCIPAL_BYTES = 16 * 1024 * 1024; @@ -105,6 +110,12 @@ export type StoreCcrBlockResult = reason: "block_too_large" | "principal_budget_exceeded" | "global_budget_exceeded"; }; +export function isCcrStoreRejection( + result: StoreCcrBlockResult +): result is Extract { + return result.stored === false; +} + export interface CcrStoreStats { storage: "memory"; entries: number; @@ -257,12 +268,30 @@ function enforcePrincipalBudget(owner: string, bytes: number): boolean { return principalBytes(owner) + bytes <= MAX_CCR_PRINCIPAL_BYTES; } -function enforceGlobalBudget(bytes: number): boolean { - while ( - (ccrStore.size >= MAX_CCR_ENTRIES || ccrTotalBytes + bytes > MAX_CCR_GLOBAL_BYTES) && - evictOldestMatching(() => true) - ) { - // Enforce both entry and global byte caps with LRU eviction. +/** + * Enforce the entry and global byte caps, giving up the storing principal's own + * least-recently-used blocks before anyone else's. + * + * The caps here are global while the only per-principal cap is `MAX_CCR_PRINCIPAL_BYTES`, + * so nothing bounds a principal's entry *count*. Blocks start at `DEFAULT_MIN_CHARS`, so + * 5,000 of them is around 3 MB, under a fifth of one principal's 16 MB byte allowance, + * and enough to exhaust the shared entry budget on its own. Evicting the globally oldest + * entry from there took a block from whoever had been quiet longest, because LRU keeps + * promoting the busy principal's own entries to the tail. + * + * Preferring `owner` keeps the global bound exactly as strict and makes a principal pay + * for its own pressure first. Falling back to any principal preserves the previous + * behaviour for the case that actually needs it: a newcomer storing into a store held + * entirely by others, which would otherwise never fit. + */ +function enforceGlobalBudget(owner: string, bytes: number): boolean { + const overBudget = () => + ccrStore.size >= MAX_CCR_ENTRIES || ccrTotalBytes + bytes > MAX_CCR_GLOBAL_BYTES; + + while (overBudget()) { + if (evictOldestMatching((entry) => entry.principalId === owner)) continue; + if (evictOldestMatching(() => true)) continue; + break; } return ccrTotalBytes + bytes <= MAX_CCR_GLOBAL_BYTES; } @@ -300,7 +329,7 @@ export function tryStoreBlock( return rejectStore(hash, owner, "principal_budget_exceeded"); } - if (!enforceGlobalBudget(bytes)) { + if (!enforceGlobalBudget(owner, bytes)) { return rejectStore(hash, owner, "global_budget_exceeded"); } @@ -330,7 +359,9 @@ export function storeBlock( options: StoreCcrBlockOptions = {} ): string { const result = tryStoreBlock(text, principalId, options); - if (!result.stored) throw new RangeError(`CCR store rejected block: ${result.reason}`); + if (isCcrStoreRejection(result)) { + throw new RangeError(`CCR store rejected block: ${result.reason}`); + } return result.hash; } diff --git a/open-sse/services/compression/languageDetector.ts b/open-sse/services/compression/languageDetector.ts index bbd4a79f83..d44295d225 100644 --- a/open-sse/services/compression/languageDetector.ts +++ b/open-sse/services/compression/languageDetector.ts @@ -1,4 +1,5 @@ const LANGUAGE_HINTS: Record = { + it: [/\b(?:perche|perché|pero|però|cioe|cioè|quindi|potresti|vorrei|adesso|errore|grazie|devo|voglio|questo|quello|anche|sono|molto)\b/i], "pt-BR": [/\b(?:voce|você|preciso|arquivo|codigo|código|erro|falha|obrigado)\b/i], // NOTE: English-ambiguous words are intentionally excluded — "error" (es) and // "configuration" (fr) are identical in English and would misclassify English text. diff --git a/open-sse/services/compression/rules/it/context.json b/open-sse/services/compression/rules/it/context.json new file mode 100644 index 0000000000..745b6d0116 --- /dev/null +++ b/open-sse/services/compression/rules/it/context.json @@ -0,0 +1,70 @@ +{ + "language": "it", + "category": "context", + "rules": [ + { + "name": "it_context_setup", + "pattern": "\\b(?:ecco (?:qui )?il codice|questo è il codice|qui sotto (?:c'è |trovi )?il codice|di seguito il codice|ti allego il codice)\\b\\s*[:.]?\\s*", + "replacement": "Codice:", + "context": "user", + "category": "context", + "minIntensity": "lite" + }, + { + "name": "it_intent", + "pattern": "\\b(?:il mio obiettivo è|quello che (?:mi serve|voglio|devo fare) è|quello che sto cercando di fare è|l'idea è (?:quella di |))\\b\\s*", + "replacement": "Obiettivo:", + "context": "user", + "category": "context", + "minIntensity": "lite" + }, + { + "name": "it_error_report", + "pattern": "\\b(?:mi (?:dà|da) (?:questo |il seguente |)errore|ricevo (?:questo |il seguente |)errore|ottengo (?:questo |il seguente |)errore|l'errore che (?:mi dà|ricevo) è)\\b\\s*[:.]?\\s*", + "replacement": "Errore:", + "context": "user", + "category": "context", + "minIntensity": "lite" + }, + { + "name": "it_expected_behavior", + "pattern": "\\b(?:quello che mi aspetto è|dovrebbe (?:invece |)(?:fare|succedere|restituire)|il comportamento atteso è)\\b\\s*[:.]?\\s*", + "replacement": "Atteso:", + "context": "user", + "category": "context", + "minIntensity": "lite" + }, + { + "name": "it_already_tried", + "pattern": "\\b(?:ho (?:già |)provato a|ho tentato di|ho cercato di)\\b\\s*", + "replacement": "Provato:", + "context": "user", + "category": "context", + "minIntensity": "lite" + }, + { + "name": "it_question_directive", + "pattern": "\\b(?:mi (?:sapresti |sai |puoi |)dire (?:se|come|cosa|quando|perché)|(?:sai|sapresti) (?:dirmi )?(?:se|come|cosa|quando|perché))\\b\\s*", + "replacement": "", + "context": "user", + "category": "context", + "minIntensity": "lite" + }, + { + "name": "it_environment_preamble", + "pattern": "\\b(?:sto (?:lavorando|usando|utilizzando)|nel mio (?:progetto|sistema|ambiente))\\b\\s*", + "replacement": "", + "context": "user", + "category": "context", + "minIntensity": "full" + }, + { + "name": "it_scope_note", + "pattern": "\\b(?:tieni (?:presente|conto) che|considera che|nota che|da notare che)\\b\\s*", + "replacement": "NB:", + "context": "all", + "category": "context", + "minIntensity": "lite" + } + ] +} diff --git a/open-sse/services/compression/rules/it/dedup.json b/open-sse/services/compression/rules/it/dedup.json new file mode 100644 index 0000000000..8513e486d1 --- /dev/null +++ b/open-sse/services/compression/rules/it/dedup.json @@ -0,0 +1,38 @@ +{ + "language": "it", + "category": "dedup", + "rules": [ + { + "name": "it_repeated_context", + "pattern": "\\b(?:come (?:ti )?(?:ho )?(?:già |)(?:detto|accennato|scritto|spiegato) (?:prima|sopra|in precedenza)|come dicevo|come sopra|come menzionato)\\b[,.]?\\s*", + "replacement": "Vedi sopra. ", + "context": "all", + "category": "dedup", + "minIntensity": "lite" + }, + { + "name": "it_repeated_question", + "pattern": "\\b(?:stessa domanda di prima|te l'ho già chiesto|è la stessa domanda|come chiedevo prima)\\b[,.]?\\s*", + "replacement": "[stessa domanda] ", + "context": "user", + "category": "dedup", + "minIntensity": "lite" + }, + { + "name": "it_restating", + "pattern": "\\b(?:in altre parole|detto altrimenti|ovvero|vale a dire|cioè per essere chiari)\\b[,:]?\\s*", + "replacement": "cioè ", + "context": "all", + "category": "dedup", + "minIntensity": "full" + }, + { + "name": "it_recap_preamble", + "pattern": "\\b(?:ricapitolando|per ricapitolare|facciamo il punto|riepilogo)\\b[,:]?\\s*", + "replacement": "", + "context": "assistant", + "category": "dedup", + "minIntensity": "full" + } + ] +} diff --git a/open-sse/services/compression/rules/it/filler.json b/open-sse/services/compression/rules/it/filler.json new file mode 100644 index 0000000000..62649d7663 --- /dev/null +++ b/open-sse/services/compression/rules/it/filler.json @@ -0,0 +1,94 @@ +{ + "language": "it", + "category": "filler", + "rules": [ + { + "name": "it_polite_framing", + "pattern": "\\b(?:per favore|per cortesia|ti (?:pre|)gherei di|potresti|puoi|riusciresti a|ti dispiacerebbe|se puoi|se ti va|quando puoi|gentilmente)\\b\\s*", + "replacement": "", + "context": "all", + "category": "filler", + "minIntensity": "lite" + }, + { + "name": "it_pleasantries", + "pattern": "\\b(?:ciao|buongiorno|buonasera|buon pomeriggio|salve|grazie mille|grazie tante|ti ringrazio|grazie)\\b[,.!?\\s]*", + "replacement": "", + "context": "all", + "category": "filler", + "minIntensity": "lite" + }, + { + "name": "it_hedging", + "pattern": "\\b(?:credo che|penso che|mi sembra che|mi pare che|direi che|secondo me|a mio (?:parere|avviso)|forse|magari|probabilmente|presumibilmente|verosimilmente)\\b\\s*", + "replacement": "", + "context": "all", + "category": "filler", + "minIntensity": "lite" + }, + { + "name": "it_filler_adverbs", + "pattern": "\\b(?:sostanzialmente|essenzialmente|fondamentalmente|praticamente|in realtà|in effetti|letteralmente|semplicemente|diciamo|insomma|comunque|appunto|ovviamente|chiaramente)\\b\\s*", + "replacement": "", + "context": "all", + "category": "filler", + "minIntensity": "lite" + }, + { + "name": "it_self_reference", + "pattern": "^(?:sto cercando di|vorrei|volevo|avrei bisogno di|ho bisogno di|mi servirebbe|mi serve|vorrei sapere se|volevo sapere se|voglio)\\b\\s*", + "replacement": "", + "context": "user", + "category": "filler", + "minIntensity": "lite" + }, + { + "name": "it_verbose_request", + "pattern": "\\b(?:potresti spiegarmi|puoi spiegarmi|mi spieghi|mi puoi spiegare|potresti dettagliare|puoi dettagliare|mi sapresti dire|sapresti dirmi|mi dici)\\b\\s*", + "replacement": "spiega ", + "context": "user", + "category": "filler", + "minIntensity": "lite" + }, + { + "name": "it_assistant_servility", + "pattern": "\\b(?:certamente|assolutamente|volentieri|con piacere|sarei felice di aiutarti|sono felice di aiutarti|ottima domanda|bella domanda|buona domanda)\\b[,.!]?\\s*", + "replacement": "", + "context": "assistant", + "category": "filler", + "minIntensity": "lite" + }, + { + "name": "it_assistant_preamble", + "pattern": "^(?:ecco|ecco qui|ecco a te|allora|dunque|bene)\\b[,:]?\\s*", + "replacement": "", + "context": "assistant", + "category": "filler", + "minIntensity": "lite" + }, + { + "name": "it_closing_offer", + "pattern": "\\b(?:fammi sapere se (?:hai bisogno|ti serve|vuoi)[^.!?]*|se hai (?:altre |ulteriori )?(?:domande|dubbi)[^.!?]*|spero (?:che )?(?:questo )?(?:ti )?(?:sia (?:stato )?d'aiuto|aiuti)[^.!?]*)[.!?]\\s*", + "replacement": "", + "context": "assistant", + "category": "filler", + "minIntensity": "lite" + }, + { + "name": "it_apology", + "pattern": "\\b(?:mi scuso per|scusa per|chiedo scusa per|mi dispiace per)\\b[^.!?]*[.!?]\\s*", + "replacement": "", + "context": "assistant", + "category": "filler", + "minIntensity": "full" + }, + { + "name": "it_softeners", + "pattern": "\\b(?:un attimo|un momento|se non ti dispiace|se non è troppo disturbo|se possibile)\\b[,.]?\\s*", + "replacement": "", + "context": "all", + "category": "filler", + "minIntensity": "lite" + } + ] +} diff --git a/open-sse/services/compression/rules/it/structural.json b/open-sse/services/compression/rules/it/structural.json new file mode 100644 index 0000000000..1c87e76d3d --- /dev/null +++ b/open-sse/services/compression/rules/it/structural.json @@ -0,0 +1,102 @@ +{ + "language": "it", + "category": "structural", + "rules": [ + { + "name": "it_purpose", + "pattern": "\\b(?:al fine di|allo scopo di|con l'obiettivo di|in modo da poter|in modo da|così da|in maniera tale da)\\b\\s*", + "replacement": "per ", + "context": "all", + "category": "structural", + "minIntensity": "lite" + }, + { + "name": "it_causal", + "pattern": "\\b(?:a causa del fatto che|per il fatto che|dal momento che|visto che|dato che|in quanto)\\b\\s*", + "replacement": "perché ", + "context": "all", + "category": "structural", + "minIntensity": "lite" + }, + { + "name": "it_connectors", + "pattern": "\\b(?:inoltre|in aggiunta|per di più|d'altra parte|d'altro canto|oltre a ciò)\\b[,]?\\s*", + "replacement": "anche ", + "context": "all", + "category": "structural", + "minIntensity": "lite" + }, + { + "name": "it_emphasis", + "pattern": "\\b(?:molto|davvero|veramente|estremamente|parecchio|piuttosto|abbastanza|super)\\s+(?=[a-zàèéìòùA-Z])", + "replacement": "", + "context": "all", + "category": "structural", + "minIntensity": "full" + }, + { + "name": "it_redundant_phrasing", + "pattern": "\\bnel caso in cui\\b", + "replacement": "se", + "context": "all", + "category": "structural", + "minIntensity": "lite" + }, + { + "name": "it_time_redundancy", + "pattern": "\\b(?:nel momento in cui|nell'istante in cui|nel periodo in cui)\\b", + "replacement": "quando", + "context": "all", + "category": "structural", + "minIntensity": "lite" + }, + { + "name": "it_place_redundancy", + "pattern": "\\b(?:all'interno di|nell'ambito di|nel contesto di)\\b", + "replacement": "in", + "context": "all", + "category": "structural", + "minIntensity": "lite" + }, + { + "name": "it_recommendation", + "pattern": "\\b(?:ti (?:consiglierei|consiglio|suggerirei|suggerisco) di|sarebbe (?:meglio|opportuno|consigliabile)|converrebbe)\\b\\s*", + "replacement": "usa ", + "context": "assistant", + "category": "structural", + "minIntensity": "full" + }, + { + "name": "it_possibility", + "pattern": "\\b(?:è possibile che|potrebbe essere che|può darsi che)\\b\\s*", + "replacement": "forse ", + "context": "all", + "category": "structural", + "minIntensity": "full" + }, + { + "name": "it_necessity", + "pattern": "\\b(?:è necessario che|occorre che|bisogna che|è indispensabile che)\\b\\s*", + "replacement": "serve che ", + "context": "all", + "category": "structural", + "minIntensity": "lite" + }, + { + "name": "it_conclusion", + "pattern": "\\b(?:in conclusione|per concludere|riassumendo|in sintesi|tirando le somme)\\b[,:]?\\s*", + "replacement": "", + "context": "assistant", + "category": "structural", + "minIntensity": "full" + }, + { + "name": "it_double_negation", + "pattern": "\\bnon è (?:possibile|fattibile) (?:non |)\\b", + "replacement": "non si può ", + "context": "all", + "category": "structural", + "minIntensity": "full" + } + ] +} diff --git a/open-sse/services/compression/rules/it/ultra.json b/open-sse/services/compression/rules/it/ultra.json new file mode 100644 index 0000000000..6d8c486677 --- /dev/null +++ b/open-sse/services/compression/rules/it/ultra.json @@ -0,0 +1,106 @@ +{ + "language": "it", + "category": "ultra", + "rules": [ + { + "name": "it_articles", + "pattern": "\\b(?:[Ii]l|[Ll]o|[Ll]a|[Ii]|[Gg]li|[Ll]e|[Uu]n|[Uu]no|[Uu]na)\\s+(?=[a-zàèéìòù])", + "flags": "g", + "replacement": "", + "context": "all", + "category": "terse", + "minIntensity": "full" + }, + { + "name": "it_leader_phrases", + "pattern": "^(?:posso|possiamo|vado a|andiamo a|proviamo a|fammi|lasciami|si può)\\s+(?=[a-zàèéìòù])", + "replacement": "", + "context": "all", + "category": "terse", + "minIntensity": "full" + }, + { + "name": "it_ultra_database", + "pattern": "\\bbase(?:e|) dati\\b|\\bbase di dati\\b", + "replacement": "DB", + "context": "all", + "category": "terse", + "minIntensity": "full" + }, + { + "name": "it_ultra_config", + "pattern": "\\bconfigurazion(?:e|i)\\b", + "replacement": "config", + "context": "all", + "category": "terse", + "minIntensity": "full" + }, + { + "name": "it_ultra_function", + "pattern": "\\bfunzion(?:e|i)\\b", + "replacement": "fn", + "context": "all", + "category": "terse", + "minIntensity": "ultra" + }, + { + "name": "it_ultra_variable", + "pattern": "\\bvariabil(?:e|i)\\b", + "replacement": "var", + "context": "all", + "category": "terse", + "minIntensity": "ultra" + }, + { + "name": "it_ultra_application", + "pattern": "\\bapplicazion(?:e|i)\\b", + "replacement": "app", + "context": "all", + "category": "terse", + "minIntensity": "full" + }, + { + "name": "it_ultra_implementation", + "pattern": "\\bimplementazion(?:e|i)\\b", + "replacement": "impl", + "context": "all", + "category": "terse", + "minIntensity": "ultra" + }, + { + "name": "it_ultra_directory", + "pattern": "\\b(?:cartell(?:a|e)|director(?:y|ies))\\b", + "replacement": "dir", + "context": "all", + "category": "terse", + "minIntensity": "full" + }, + { + "name": "it_ultra_error", + "pattern": "\\bmessaggio di errore\\b", + "replacement": "errore", + "context": "all", + "category": "terse", + "minIntensity": "full" + }, + { + "name": "it_copula_drop", + "pattern": "\\b(?:che )?(?:è|sono) (?:un|una|il|la|lo|gli|le)\\s+(?=[a-zàèéìòù])", + "replacement": "", + "context": "all", + "category": "terse", + "minIntensity": "ultra" + }, + { + "name": "it_ultra_environment", + "pattern": "\\bambiente di (?:sviluppo|produzione)\\b", + "replacementMap": { + "ambiente di sviluppo": "dev", + "ambiente di produzione": "prod" + }, + "context": "all", + "category": "terse", + "minIntensity": "ultra" + } + ] +} diff --git a/open-sse/services/contextManager.ts b/open-sse/services/contextManager.ts index c6d51211f7..cb34af4018 100644 --- a/open-sse/services/contextManager.ts +++ b/open-sse/services/contextManager.ts @@ -254,7 +254,7 @@ function extractImageTokens(node: unknown, seen: Set): { node: unknown; * budget instead of measuring its base64 payload as raw text, then the * remainder of the structure is measured normally via the char/4 heuristic. */ -export function estimateTokens(text: string | object | null | undefined): number { +export function estimateTokens(text: unknown): number { if (!text) return 0; if (typeof text === "string") { return Math.ceil(text.length / CHARS_PER_TOKEN); diff --git a/open-sse/services/fusion.ts b/open-sse/services/fusion.ts index dd92c3bdbc..767da61531 100644 --- a/open-sse/services/fusion.ts +++ b/open-sse/services/fusion.ts @@ -20,7 +20,7 @@ */ import { errorResponse, sanitizeErrorMessage } from "../utils/error.ts"; import { extractTextContent } from "../translator/helpers/geminiHelper.ts"; -import type { ComboLogger, HandleSingleModel } from "./combo/types.ts"; +import type { ComboLogger, HandleSingleModel, ResolvedComboTarget } from "./combo/types.ts"; // Fusion tuning. Overridable per-combo via combo.config.fusionTuning. export const FUSION_DEFAULTS = { @@ -108,10 +108,7 @@ export function appendUserTurn(body: Body, text: string): Body { } else if (Array.isArray(body.input)) { next.input = [...(body.input as unknown[]), { role: "user", content: text }]; } else if (Array.isArray(body.contents)) { - next.contents = [ - ...(body.contents as unknown[]), - { role: "user", parts: [{ text }] }, - ]; + next.contents = [...(body.contents as unknown[]), { role: "user", parts: [{ text }] }]; } else { next.messages = [{ role: "user", content: text }]; } @@ -159,10 +156,7 @@ export function isToolBearingRequest(body: Body): boolean { type Sentinel = { __timeout?: true; __error?: unknown }; // Resolve a Response (or sentinel) within ms; the loser keeps running but is ignored. -function withTimeout( - promise: Promise, - ms: number -): Promise { +function withTimeout(promise: Promise, ms: number): Promise { return new Promise((resolve) => { const t = setTimeout(() => resolve({ __timeout: true }), ms); Promise.resolve(promise) @@ -224,16 +218,33 @@ export function collectPanel( }); } +export type FusionModel = ResolvedComboTarget | string; + export type HandleFusionChatOptions = { body: Body; - models: string[]; + models: FusionModel[]; handleSingleModel: HandleSingleModel; log: ComboLogger; comboName?: string; judgeModel?: string | null; + judgeTarget?: ResolvedComboTarget | null; tuning?: FusionTuning | null; }; +function getFusionModelString(model: FusionModel): string { + return typeof model === "string" ? model : model.modelStr; +} + +function dispatchFusionModel( + handleSingleModel: HandleSingleModel, + body: Body, + model: FusionModel +): Promise { + return typeof model === "string" + ? handleSingleModel(body, model) + : handleSingleModel(body, model.modelStr, model); +} + /** * Handle a fusion combo: fan the prompt out to every panel model in parallel, * then a judge model synthesizes one final answer from all panel responses. @@ -260,6 +271,7 @@ export async function handleFusionChat({ log, comboName, judgeModel, + judgeTarget, tuning, }: HandleFusionChatOptions): Promise { const panel = Array.isArray(models) ? models.filter(Boolean) : []; @@ -269,7 +281,7 @@ export async function handleFusionChat({ // A single-model fusion has nothing to fuse — just answer directly. if (panel.length === 1) { - return handleSingleModel(body, panel[0]); + return dispatchFusionModel(handleSingleModel, body, panel[0]); } // Reject an oversized panel BEFORE fan-out (issue #1905): fanning out N @@ -296,10 +308,10 @@ export async function handleFusionChat({ // gracefully via the answers.length===1 branch below (issue #6454). const minPanel = Math.min(Math.max(1, cfg.minPanel), panel.length); const hasExplicitJudge = Boolean(judgeModel && judgeModel.trim()); - const judge = hasExplicitJudge ? (judgeModel as string).trim() : panel[0]; + const judge = hasExplicitJudge ? (judgeModel as string).trim() : getFusionModelString(panel[0]); log.info( "FUSION", - `Combo "${comboName ?? ""}" | panel=${panel.length} [${panel.join(", ")}] | judge=${judge} | quorum=${minPanel}` + `Combo "${comboName ?? ""}" | panel=${panel.length} [${panel.map(getFusionModelString).join(", ")}] | judge=${judge} | quorum=${minPanel}` ); // Tool-bearing requests get no value from panel synthesis — panel members @@ -322,8 +334,8 @@ export async function handleFusionChat({ void _tc; const panelBody: Body = { ...rest, stream: false }; const t0 = Date.now(); - const calls = panel.map((m) => - withTimeout(handleSingleModel(panelBody, m), cfg.panelHardTimeoutMs) + const calls = panel.map((target) => + withTimeout(dispatchFusionModel(handleSingleModel, panelBody, target), cfg.panelHardTimeoutMs) ); const settled = await collectPanel(calls, { ...cfg, minPanel }); log.info("FUSION", `fan-out collected in ${Date.now() - t0}ms`); @@ -333,7 +345,7 @@ export async function handleFusionChat({ const failures: Array<{ model: string; reason: string }> = []; for (let i = 0; i < settled.length; i++) { const res = settled[i]; - const model = panel[i]; + const model = getFusionModelString(panel[i]); if (!res) { log.warn("FUSION", `Panel ${model} dropped (straggler/timeout)`); failures.push({ model, reason: "straggler_dropped" }); @@ -399,10 +411,7 @@ export async function handleFusionChat({ // synthesizing from a single source through itself would be redundant — // answer directly with the lone survivor (issue #6454). if (!hasExplicitJudge) { - log.info( - "FUSION", - `Only ${answers[0].model} succeeded — answering directly (no fusion)` - ); + log.info("FUSION", `Only ${answers[0].model} succeeded — answering directly (no fusion)`); return handleSingleModel(body, answers[0].model); } // An explicit judgeModel IS configured: honor it even with a single @@ -421,8 +430,8 @@ export async function handleFusionChat({ // SURVIVOR: prefer panel[0] when it survived, otherwise the first survivor. const effectiveJudge = hasExplicitJudge ? judge - : answers.some((a) => a.model === panel[0]) - ? panel[0] + : answers.some((a) => a.model === getFusionModelString(panel[0])) + ? getFusionModelString(panel[0]) : answers[0].model; if (answers.length === 1) { @@ -435,5 +444,7 @@ export async function handleFusionChat({ // 4. Judge analyzes + writes one final answer (streams to client if requested). const judgeBody = appendUserTurn(body, buildJudgePrompt(answers)); log.info("FUSION", `Judging ${answers.length} answers with ${effectiveJudge}`); - return handleSingleModel(judgeBody, effectiveJudge); + return judgeTarget + ? handleSingleModel(judgeBody, judgeTarget.modelStr, judgeTarget) + : handleSingleModel(judgeBody, effectiveJudge); } diff --git a/open-sse/services/kiroModels.ts b/open-sse/services/kiroModels.ts index dade388504..5a64410fc4 100644 --- a/open-sse/services/kiroModels.ts +++ b/open-sse/services/kiroModels.ts @@ -56,6 +56,12 @@ function toNonEmptyString(value: unknown): string | null { return trimmed.length > 0 ? trimmed : null; } +export type KiroPromptCaching = { + supportsPromptCaching: boolean; + minimumTokensPerCacheCheckpoint: number | null; + maximumCacheCheckpointsPerRequest: number | null; +}; + export type KiroModel = { id: string; name: string; @@ -68,8 +74,28 @@ export type KiroModel = { rateMultiplier?: number; upstreamModelId?: string; description?: string; + promptCaching?: KiroPromptCaching; }; +function toNonNegativeInteger(value: unknown): number | null { + return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null; +} + +function parsePromptCaching(value: unknown): KiroPromptCaching | undefined { + const promptCaching = asRecord(value); + if (typeof promptCaching.supportsPromptCaching !== "boolean") return undefined; + + return { + supportsPromptCaching: promptCaching.supportsPromptCaching, + minimumTokensPerCacheCheckpoint: toNonNegativeInteger( + promptCaching.minimumTokensPerCacheCheckpoint + ), + maximumCacheCheckpointsPerRequest: toNonNegativeInteger( + promptCaching.maximumCacheCheckpointsPerRequest + ), + }; +} + export type KiroModelsResult = { models: KiroModel[]; /** "api" = live discovery; "fallback" = static catalog (offline/unauthed/error). */ @@ -98,7 +124,8 @@ export function parseKiroModels(data: unknown): KiroModel[] { if (!id || seen.has(id)) continue; seen.add(id); const name = toNonEmptyString(item.modelName) || toNonEmptyString(item.name) || id; - models.push({ id, name, owned_by: "kiro" }); + const promptCaching = parsePromptCaching(item.promptCaching); + models.push({ id, name, owned_by: "kiro", ...(promptCaching && { promptCaching }) }); } return models; @@ -162,6 +189,7 @@ function expandKiroModels(data: unknown): KiroModel[] { const tokenLimits = asRecord(item.tokenLimits); const contextLength = Number(tokenLimits.maxInputTokens) || 200000; const rateMultiplier = Number(item.rateMultiplier); + const promptCaching = parsePromptCaching(item.promptCaching); for (const variant of buildVariants(upstreamId, display)) { if (seen.has(variant.id)) continue; @@ -172,6 +200,7 @@ function expandKiroModels(data: unknown): KiroModel[] { rateMultiplier: Number.isFinite(rateMultiplier) ? rateMultiplier : 1.0, upstreamModelId: upstreamId, description: toNonEmptyString(item.description) || "", + ...(promptCaching && { promptCaching }), }); } } diff --git a/open-sse/services/model.ts b/open-sse/services/model.ts index 3249c72b41..9bfc53a451 100644 --- a/open-sse/services/model.ts +++ b/open-sse/services/model.ts @@ -16,6 +16,16 @@ type ResolvedModelTarget = { model: string | null; }; +// Client context-window tags are routing hints, not part of provider model IDs. +const CONTEXT_WINDOW_SUFFIX_RE = /\[(\d+)([kKmM])?\]\s*$/; + +export function stripContextWindowSuffix( + modelStr: string | null | undefined +): string | null | undefined { + if (typeof modelStr !== "string" || !modelStr) return modelStr; + return modelStr.replace(CONTEXT_WINDOW_SUFFIX_RE, "").trimEnd(); +} + // Derive alias→provider mapping from the single source of truth (PROVIDER_ID_TO_ALIAS) // This prevents the two maps from drifting out of sync const ALIAS_TO_PROVIDER_ID: Record = {}; @@ -428,12 +438,12 @@ export function parseModel(modelStr: string | null | undefined): ParsedModel { }; } - // Extract [1m] suffix before parsing provider/model + // Extract the legacy [1m] marker while stripping all client context tags. let extendedContext = false; - let cleanStr = modelStr; - if (cleanStr.endsWith("[1m]")) { + const cleanStripped = stripContextWindowSuffix(modelStr) as string; + let cleanStr = cleanStripped; + if (/\[1m\]\s*$/i.test(modelStr)) { extendedContext = true; - cleanStr = cleanStr.slice(0, -4); } cleanStr = cleanStr.trim(); @@ -665,7 +675,9 @@ async function resolveModelByProviderInference(modelId: string, extendedContext: // Canonicalize candidates (deduplicate alias providers pointing to the same provider ID) const canonicalCandidates = Array.from( - new Set(candidatesToUse.map((p) => resolveProviderAlias(p)).filter((p): p is string => p !== null)) + new Set( + candidatesToUse.map((p) => resolveProviderAlias(p)).filter((p): p is string => p !== null) + ) ); // Filter candidates by active connections configured in the database diff --git a/open-sse/services/payloadRules.ts b/open-sse/services/payloadRules.ts index 12bb32151d..ad9a6415ad 100644 --- a/open-sse/services/payloadRules.ts +++ b/open-sse/services/payloadRules.ts @@ -85,7 +85,7 @@ function clonePayloadRulesConfig(config: PayloadRulesConfig): PayloadRulesConfig function normalizeModelSpecs(value: unknown): PayloadRuleModelSpec[] { return toArray(value) - .map((item) => { + .map((item): PayloadRuleModelSpec | null => { const name = typeof item?.name === "string" ? item.name.trim() : ""; const protocol = typeof item?.protocol === "string" ? item.protocol.trim() : ""; if (!name) return null; diff --git a/open-sse/services/pipeline.ts b/open-sse/services/pipeline.ts index 03dec5dc94..a759ddfeec 100644 --- a/open-sse/services/pipeline.ts +++ b/open-sse/services/pipeline.ts @@ -40,14 +40,30 @@ * a bad-request or auth error wastes quota and will never succeed. */ import { errorResponse } from "../utils/error.ts"; -import type { ComboLogger, HandleSingleModel } from "./combo/types.ts"; +import type { ComboLogger, HandleSingleModel, ResolvedComboTarget } from "./combo/types.ts"; // extractPanelText is a generic assistant-text extractor (OpenAI chat / Claude / // Gemini / Responses) — reused here to read each step's output, not fusion-specific. import { extractPanelText } from "./fusion.ts"; type Body = Record; -export type PipelineStep = { model: string; prompt?: string | null }; +export type PipelineStep = + | { + target: ResolvedComboTarget; + prompt?: string | null; + } + | { + model: string; + prompt?: string | null; + }; + +function getStepModel(step: PipelineStep): string { + return "target" in step ? step.target.modelStr : step.model; +} + +function getStepTarget(step: PipelineStep): ResolvedComboTarget | undefined { + return "target" in step ? step.target : undefined; +} /** * Prepend a system instruction to the client's original conversation (format-aware), @@ -146,23 +162,32 @@ export async function handlePipelineChat({ maxRetries = 0, retryDelayMs = 1000, }: HandlePipelineChatOptions): Promise { - const chain = (Array.isArray(steps) ? steps : []).filter((s) => s && s.model); + const chain = (Array.isArray(steps) ? steps : []).filter((step): step is PipelineStep => + Boolean(step && getStepModel(step)) + ); if (chain.length === 0) { return errorResponse(400, "Pipeline combo has no models"); } log.info( "PIPELINE", - `Combo "${comboName ?? ""}" | steps=${chain.length} [${chain.map((s) => s.model).join(" -> ")}]` + `Combo "${comboName ?? ""}" | steps=${chain.length} [${chain.map(getStepModel).join(" -> ")}]` ); // Single-step pipeline: nothing to chain — run it directly (streams to client). if (chain.length === 1) { - return handleSingleModel(prependSystemInstruction(body, chain[0].prompt), chain[0].model); + const step = chain[0]; + return handleSingleModel( + prependSystemInstruction(body, step.prompt), + getStepModel(step), + getStepTarget(step) + ); } let prevOutput = ""; for (let i = 0; i < chain.length; i++) { const step = chain[i]; + const stepModel = getStepModel(step); + const stepTarget = getStepTarget(step); const isFinal = i === chain.length - 1; const isFirst = i === 0; @@ -174,46 +199,55 @@ export async function handlePipelineChat({ if (!isFinal) stepBody = stripStreaming(stepBody); const t0 = Date.now(); - let res = await handleSingleModel(stepBody, step.model); + let res = await handleSingleModel(stepBody, stepModel, stepTarget); if (isFinal) { - log.info("PIPELINE", `Final step ${step.model} responded (${Date.now() - t0}ms)`); + log.info("PIPELINE", `Final step ${stepModel} responded (${Date.now() - t0}ms)`); return res; } // Transient retry: if the intermediate step failed with a retryable status // (429/502/503/504), retry the same step up to maxRetries times before // giving up. Non-transient errors (400/401/403/404) fail immediately. - for (let attempt = 0; attempt < maxRetries && !res.ok && TRANSIENT_STATUS.has(res.status); attempt++) { + for ( + let attempt = 0; + attempt < maxRetries && !res.ok && TRANSIENT_STATUS.has(res.status); + attempt++ + ) { log.warn( "PIPELINE", - `Step ${i + 1} (${step.model}) transient ${res.status}, retrying ${attempt + 1}/${maxRetries} in ${retryDelayMs}ms` + `Step ${i + 1} (${stepModel}) transient ${res.status}, retrying ${attempt + 1}/${maxRetries} in ${retryDelayMs}ms` ); await sleep(retryDelayMs); - res = await handleSingleModel(stepBody, step.model); + res = await handleSingleModel(stepBody, stepModel, stepTarget); } // An intermediate step must succeed with usable text — otherwise fail the whole // pipeline (never silently swallow; the client gets a clear, sanitized error). if (!res.ok) { - log.warn("PIPELINE", `Step ${i + 1} (${step.model}) failed`, { status: res.status }); + log.warn("PIPELINE", `Step ${i + 1} (${stepModel}) failed`, { + status: res.status, + }); const status = res.status >= 400 && res.status <= 599 ? res.status : 502; - return errorResponse(status, `Pipeline step ${i + 1} (${step.model}) failed`); + return errorResponse(status, `Pipeline step ${i + 1} (${stepModel}) failed`); } try { const json = await res.clone().json(); prevOutput = extractPanelText(json); } catch { - log.warn("PIPELINE", `Step ${i + 1} (${step.model}) returned an unparseable body`); - return errorResponse(502, `Pipeline step ${i + 1} (${step.model}) returned an unparseable body`); + log.warn("PIPELINE", `Step ${i + 1} (${stepModel}) returned an unparseable body`); + return errorResponse( + 502, + `Pipeline step ${i + 1} (${stepModel}) returned an unparseable body` + ); } if (!prevOutput.trim()) { - log.warn("PIPELINE", `Step ${i + 1} (${step.model}) returned empty output`); - return errorResponse(502, `Pipeline step ${i + 1} (${step.model}) returned empty output`); + log.warn("PIPELINE", `Step ${i + 1} (${stepModel}) returned empty output`); + return errorResponse(502, `Pipeline step ${i + 1} (${stepModel}) returned empty output`); } log.info( "PIPELINE", - `Step ${i + 1} ${step.model} ok (${prevOutput.length} chars, ${Date.now() - t0}ms)` + `Step ${i + 1} ${stepModel} ok (${prevOutput.length} chars, ${Date.now() - t0}ms)` ); } diff --git a/open-sse/services/rateLimitManager.ts b/open-sse/services/rateLimitManager.ts index c39b39c18e..87f48a46fa 100644 --- a/open-sse/services/rateLimitManager.ts +++ b/open-sse/services/rateLimitManager.ts @@ -164,13 +164,58 @@ function buildLimiterDefaults() { }; } -function updateAllLimiterSettings() { - const defaults = buildLimiterDefaults(); - for (const limiter of limiters.values()) { - limiter.updateSettings(defaults); +/** + * Apply new settings to a Bottleneck limiter and re-arm its reservoir-refresh + * heartbeat. + * + * Bottleneck 2.19.5 (frozen upstream dependency, no release since 2019) has a + * bug in `LocalDatastore#_startHeartbeat()` + * (node_modules/bottleneck/lib/LocalDatastore.js:29,56): the guard + * `if (this.heartbeat == null && ...)` only (re)creates the periodic + * reservoir-refresh interval the FIRST time it runs. Every later call — + * including the one `updateSettings()` itself triggers internally — falls + * into the `else` branch and does `clearInterval(this.heartbeat)` WITHOUT + * resetting `this.heartbeat` back to `null`. Because the stale reference is + * left in place, every future `_startHeartbeat()` call keeps taking the same + * dead `else` branch: the periodic reservoir refresh is gone forever after + * the FIRST manual `updateSettings()` call on a limiter — every limiter here + * starts with a live heartbeat (buildLimiterDefaults() always sets + * reservoirRefreshInterval/reservoirRefreshAmount), so that "first call" is + * whichever of the 5 updateSettings() call sites in this file runs first. + * + * Work around it here instead of patching node_modules: null out the stale + * reference ourselves and re-invoke `_startHeartbeat()` so it takes the + * "start a fresh interval" branch again. Every `limiter.updateSettings(...)` + * call in this file MUST go through this helper, never Bottleneck's method + * directly. + */ +async function applyLimiterSettings( + limiter: Bottleneck, + updates: Bottleneck.ConstructorOptions +): Promise { + await limiter.updateSettings(updates); + const store = ( + limiter as unknown as { + _store?: { + heartbeat?: ReturnType | null; + _startHeartbeat?: () => void; + }; + } + )._store; + if (store && typeof store._startHeartbeat === "function") { + if (store.heartbeat != null) clearInterval(store.heartbeat); + store.heartbeat = null; + store._startHeartbeat(); } } +async function updateAllLimiterSettings() { + const defaults = buildLimiterDefaults(); + await Promise.all( + Array.from(limiters.values(), (limiter) => applyLimiterSettings(limiter, defaults)) + ); +} + function reconcileEnabledConnections( connectionsRaw: unknown[], requestQueueSettings: RequestQueueSettings @@ -381,7 +426,7 @@ export async function initializeRateLimits() { connections as unknown[], currentRequestQueueSettings ); - updateAllLimiterSettings(); + await updateAllLimiterSettings(); // Load per-connection rate limit overrides connectionRateLimitOverrides.clear(); @@ -414,7 +459,7 @@ export async function applyRequestQueueSettings(nextSettings: RequestQueueSettin const { getCachedProviderConnections } = await import("@/lib/localDb"); const connections = await getCachedProviderConnections(); reconcileEnabledConnections(connections as unknown[], currentRequestQueueSettings); - updateAllLimiterSettings(); + await updateAllLimiterSettings(); } /** @@ -779,9 +824,7 @@ export function updateFromHeaders(provider, connectionId, headers, status, model logRateLimit( `⚠️ [RATE-LIMIT] ${provider}:${connectionId.slice(0, 8)} — near capacity, slowing down` ); - limiter.updateSettings({ - minTime: 200, // Add 200ms between requests - }); + trackAsyncOperation(applyLimiterSettings(limiter, { minTime: 200 })); return; } @@ -812,7 +855,7 @@ export function updateFromHeaders(provider, connectionId, headers, status, model } } - limiter.updateSettings(updates); + trackAsyncOperation(applyLimiterSettings(limiter, updates)); // Persist learned limits (debounced) recordLearnedLimit( @@ -1014,7 +1057,7 @@ async function loadPersistedLimits() { const limiter = limiters.get(key); if (limiter && limit > 0) { const inferredMinTime = minTime || Math.max(0, Math.floor(60000 / limit) - 10); - limiter.updateSettings({ minTime: inferredMinTime }); + await applyLimiterSettings(limiter, { minTime: inferredMinTime }); count++; } } @@ -1050,10 +1093,12 @@ export function updateFromResponseBody(provider, connectionId, responseBody, sta `🚫 [RATE-LIMIT] ${provider}:${connectionId.slice(0, 8)} — body-parsed retry: ${Math.ceil(retryAfterMs / 1000)}s (${reason})` ); - limiter.updateSettings({ - reservoir: 0, - reservoirRefreshAmount: 60, - reservoirRefreshInterval: retryAfterMs, - }); + trackAsyncOperation( + applyLimiterSettings(limiter, { + reservoir: 0, + reservoirRefreshAmount: 60, + reservoirRefreshInterval: retryAfterMs, + }) + ); } } diff --git a/open-sse/services/reasoningTokenBuffer.ts b/open-sse/services/reasoningTokenBuffer.ts index 8cce846d14..4c5ce88059 100644 --- a/open-sse/services/reasoningTokenBuffer.ts +++ b/open-sse/services/reasoningTokenBuffer.ts @@ -45,6 +45,12 @@ export function resolveReasoningBufferedMaxTokens( // request. Respect it verbatim instead of inflating (e.g. 1 -> 1001). if (current < REASONING_BUFFER_MIN_TRIGGER) return current; - const buffered = Math.max(current + 1000, Math.ceil(current * 1.5)); - return buffered > maxOutputTokens ? current : buffered; + // Issue #9507: never enlarge a client's explicit max_tokens. The #3587 + // headroom heuristic (Math.ceil(current * 1.5)) silently rewrote reasoning + // budgets upward (64000 -> 96000 on claude-opus-5), violating the #1761 + // contract that upward adjustment must be opt-in. The over-cap clamp above + // (line 42) already narrows, and the model's own output cap is the only + // legitimate ceiling; any headroom beyond the client-declared value is a + // silent cost increase the client did not authorize. + return current; } diff --git a/open-sse/services/specificityTypes.ts b/open-sse/services/specificityTypes.ts index 84c3da59b0..c85c1dbe21 100644 --- a/open-sse/services/specificityTypes.ts +++ b/open-sse/services/specificityTypes.ts @@ -30,6 +30,7 @@ export interface RuleInput { messages: Array<{ role?: string; content?: string | unknown }>; systemPrompt?: string; tools?: Array<{ + type?: string; function?: { name: string; description?: string; parameters?: unknown }; }>; model?: string; diff --git a/open-sse/transformer/responsesTransformer.ts b/open-sse/transformer/responsesTransformer.ts index bdaff6e8e3..89e7760583 100644 --- a/open-sse/transformer/responsesTransformer.ts +++ b/open-sse/transformer/responsesTransformer.ts @@ -87,7 +87,7 @@ export function createResponsesLogger(model, logsDir = null) { export function createResponsesApiTransformStream( logger = null, keepaliveIntervalMs = 3000, - options = {} + options: { customToolNames?: Iterable } = {} ) { const customToolNames = new Set(options.customToolNames || []); const state = { diff --git a/open-sse/translator/helpers/claudeHelper.ts b/open-sse/translator/helpers/claudeHelper.ts index e34704651c..b490fe4bd5 100644 --- a/open-sse/translator/helpers/claudeHelper.ts +++ b/open-sse/translator/helpers/claudeHelper.ts @@ -153,8 +153,18 @@ export function splitMisplacedToolResults(messages: ClaudeMessage[]): ClaudeMess // Fix tool_use/tool_result ordering for Claude API // 1. Assistant message with tool_use: remove text AFTER tool_use (Claude doesn't allow) // 2. Merge consecutive same-role messages +// 3. Reconcile tool_result blocks against the immediately previous tool_use message export function fixToolUseOrdering(messages: ClaudeMessage[]): ClaudeMessage[] { - if (messages.length <= 1) return messages; + if (messages.length === 0) return messages; + if ( + messages.length === 1 && + !( + Array.isArray(messages[0]?.content) && + messages[0].content.some((block) => block.type === "tool_result") + ) + ) { + return messages; + } // Pass 1: Fix assistant messages with tool_use - remove text after tool_use for (const msg of messages) { @@ -218,6 +228,53 @@ export function fixToolUseOrdering(messages: ClaudeMessage[]): ClaudeMessage[] { } } + // Claude accepts tool_result only for a tool_use in the immediately previous + // assistant message. Compacted cross-model history can retain an output after + // dropping its call; keep that output as user text instead of sending an + // invalid structured reference or discarding useful context. + for (let i = 0; i < merged.length; i++) { + const msg = merged[i]; + if (msg.role !== "user" || !Array.isArray(msg.content)) continue; + + const previous = merged[i - 1]; + const validIds = new Set( + previous?.role === "assistant" && Array.isArray(previous.content) + ? previous.content.flatMap((block) => + block.type === "tool_use" && typeof block.id === "string" && block.id ? [block.id] : [] + ) + : [] + ); + const pairedById = new Map(); + const otherContent: ClaudeContentBlock[] = []; + + for (const block of msg.content) { + if (block.type !== "tool_result") { + otherContent.push(block); + continue; + } + + const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : ""; + if (validIds.has(toolUseId) && !pairedById.has(toolUseId)) { + pairedById.set(toolUseId, block); + continue; + } + + const serialized = + typeof block.content === "string" + ? block.content + : (JSON.stringify(block.content ?? "") ?? ""); + otherContent.push({ + type: "text", + text: `[Unpaired tool result ${toolUseId || "unknown"}]\n${serialized}`, + }); + } + + const pairedResults = [...validIds].map( + (id) => pairedById.get(id) ?? { type: "tool_result", tool_use_id: id, content: "" } + ); + msg.content = [...pairedResults, ...otherContent]; + } + return merged; } diff --git a/open-sse/translator/helpers/responsesApiHelper.ts b/open-sse/translator/helpers/responsesApiHelper.ts index 179ae39344..1f856b11f1 100644 --- a/open-sse/translator/helpers/responsesApiHelper.ts +++ b/open-sse/translator/helpers/responsesApiHelper.ts @@ -3,7 +3,15 @@ * Delegates to the canonical translator to avoid logic duplication. */ import { openaiResponsesToOpenAIRequest } from "../request/openai-responses.ts"; +import { toRecord } from "../request/openai-responses/helpers.ts"; export function convertResponsesApiFormat(body, credentials = null, provider = null) { - return openaiResponsesToOpenAIRequest(provider, body, null, credentials); + const bodyModel = toRecord(body).model; + const requestedModel = + typeof bodyModel === "string" && bodyModel.trim().length > 0 + ? bodyModel.includes("/") || typeof provider !== "string" || provider.length === 0 + ? bodyModel + : `${provider}/${bodyModel}` + : provider; + return openaiResponsesToOpenAIRequest(requestedModel, body, null, credentials); } diff --git a/open-sse/translator/helpers/toolCallHelper.ts b/open-sse/translator/helpers/toolCallHelper.ts index caf69dd184..f0869951c7 100644 --- a/open-sse/translator/helpers/toolCallHelper.ts +++ b/open-sse/translator/helpers/toolCallHelper.ts @@ -1,7 +1,130 @@ +import { createHash } from "node:crypto"; + // Tool call helper functions for translator const ALPHANUM9 = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"; +type JsonRecord = Record; +type ToolNameAliases = Map; + +interface ToolFunction extends JsonRecord { + name?: unknown; + arguments?: unknown; +} + +interface ToolCallRecord extends JsonRecord { + id?: unknown; + type?: unknown; + function?: ToolFunction; +} + +interface ToolContentBlock extends JsonRecord { + type?: unknown; + id?: unknown; + tool_use_id?: unknown; +} + +interface ToolMessage extends JsonRecord { + role?: unknown; + tool_calls?: ToolCallRecord[]; + tool_call_id?: unknown; + content?: unknown; +} + +interface ToolCallBody extends JsonRecord { + messages?: ToolMessage[]; +} + +function toRecord(value: unknown): JsonRecord | null { + return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonRecord) : null; +} + +function aliasOpenAIToolName(name: unknown, maxLength: number, aliases: ToolNameAliases): unknown { + if (typeof name !== "string" || name.length === 0) return name; + + const safe = name.replace(/[^A-Za-z0-9_-]/g, "_"); + if (safe === name && safe.length <= maxLength) return safe; + + const hash = createHash("sha256").update(name).digest("hex").slice(0, 12); + const prefixLength = Math.max(0, maxLength - hash.length - 1); + const shortened = + prefixLength > 0 ? `${safe.slice(0, prefixLength)}_${hash}` : hash.slice(0, maxLength); + aliases.set(shortened, name); + return shortened; +} + +/** + * Mutates an OpenAI-compatible request so every function name satisfies a + * provider's maximum length and `[A-Za-z0-9_-]` character constraints. + * Returns alias → original entries for response restoration. + */ +export function normalizeOpenAIToolNames(body: unknown, maxLength: number): ToolNameAliases { + const aliases: ToolNameAliases = new Map(); + const root = toRecord(body); + if (!root || !Number.isInteger(maxLength) || maxLength < 1) return aliases; + + const alias = (name: unknown): unknown => aliasOpenAIToolName(name, maxLength, aliases); + + if (Array.isArray(root.tools)) { + for (const tool of root.tools) { + const fn = toRecord(toRecord(tool)?.function); + if (fn && typeof fn.name === "string") fn.name = alias(fn.name); + } + } + + const toolChoiceFunction = toRecord(toRecord(root.tool_choice)?.function); + if (toolChoiceFunction && typeof toolChoiceFunction.name === "string") { + toolChoiceFunction.name = alias(toolChoiceFunction.name); + } + + if (Array.isArray(root.messages)) { + for (const message of root.messages) { + const msg = toRecord(message); + if (!msg) continue; + if (Array.isArray(msg.tool_calls)) { + for (const toolCall of msg.tool_calls) { + const fn = toRecord(toRecord(toolCall)?.function); + if (fn && typeof fn.name === "string") fn.name = alias(fn.name); + } + } + if (msg.role === "tool" && typeof msg.name === "string") { + msg.name = alias(msg.name); + } + } + } + + return aliases; +} + +/** Restore normalized function names in OpenAI Chat Completions responses. */ +export function restoreOpenAIToolNames(body: unknown, aliases: unknown): boolean { + if (!(aliases instanceof Map) || aliases.size === 0) return false; + const root = toRecord(body); + if (!root || !Array.isArray(root.choices)) return false; + + let changed = false; + const restoreCalls = (calls: unknown): void => { + if (!Array.isArray(calls)) return; + for (const toolCall of calls) { + const fn = toRecord(toRecord(toolCall)?.function); + if (!fn || typeof fn.name !== "string") continue; + const original = aliases.get(fn.name); + if (typeof original !== "string" || original === fn.name) continue; + fn.name = original; + changed = true; + } + }; + + for (const choice of root.choices) { + const record = toRecord(choice); + if (!record) continue; + restoreCalls(toRecord(record.delta)?.tool_calls); + restoreCalls(toRecord(record.message)?.tool_calls); + } + + return changed; +} + // Fallback streaming tool_call id when a provider response omits one (index optional). // `call_` when no index is given; `call__` when an index is supplied. export function fallbackToolCallId(index?: number): string { @@ -23,7 +146,10 @@ function generateToolCallId9(): string { } /** @param options.use9CharId - When true, normalize ids to 9-char [a-zA-Z0-9] (e.g. Mistral); when false, only fix type/arguments, leave ids as-is */ -export function ensureToolCallIds(body, options?: { use9CharId?: boolean }) { +export function ensureToolCallIds( + body: T, + options?: { use9CharId?: boolean } +): T { if (!body.messages || !Array.isArray(body.messages)) return body; const use9CharId = options?.use9CharId === true; @@ -59,8 +185,11 @@ export function ensureToolCallIds(body, options?: { use9CharId?: boolean }) { } } - // Tool responses (role "tool") follow in same order as tool_calls; set tool_call_id by index. - // Stop when we hit another assistant so we only link tool messages that immediately follow this one. + // Tool responses (role "tool") follow in the same order as tool_calls. Rewrite + // every id only when the provider requires generated 9-char ids; otherwise keep + // explicit client ids and fill only missing ones. Overwriting a compacted orphan's + // explicit id by position can make it impersonate a different parallel call. + // Stop at the next assistant so we only link responses belonging to this turn. if (newIdsInOrder.length > 0) { let idx = 0; for (let j = i + 1; j < body.messages.length; j++) { @@ -68,7 +197,13 @@ export function ensureToolCallIds(body, options?: { use9CharId?: boolean }) { if (later.role === "assistant") break; if (later.role !== "tool") continue; if (idx < newIdsInOrder.length) { - later.tool_call_id = newIdsInOrder[idx]; + if ( + use9CharId || + later.tool_call_id == null || + String(later.tool_call_id).trim() === "" + ) { + later.tool_call_id = newIdsInOrder[idx]; + } idx++; } } @@ -79,23 +214,23 @@ export function ensureToolCallIds(body, options?: { use9CharId?: boolean }) { } // Get tool_call ids from assistant message (OpenAI format: tool_calls, Claude format: tool_use in content) -export function getToolCallIds(msg) { +export function getToolCallIds(msg: ToolMessage): string[] { if (msg.role !== "assistant") return []; - const ids = []; + const ids: string[] = []; // OpenAI format: tool_calls array if (msg.tool_calls && Array.isArray(msg.tool_calls)) { for (const tc of msg.tool_calls) { - if (tc.id) ids.push(tc.id); + if (tc.id) ids.push(String(tc.id)); } } // Claude format: tool_use blocks in content if (Array.isArray(msg.content)) { - for (const block of msg.content) { + for (const block of msg.content as ToolContentBlock[]) { if (block.type === "tool_use" && block.id) { - ids.push(block.id); + ids.push(String(block.id)); } } } @@ -104,18 +239,25 @@ export function getToolCallIds(msg) { } // Check if user message has tool_result for given ids (OpenAI format: role=tool, Claude format: tool_result in content) -export function hasToolResults(msg, toolCallIds) { +export function hasToolResults( + msg: ToolMessage | null | undefined, + toolCallIds: string[] +): boolean { if (!msg || !toolCallIds.length) return false; // OpenAI format: role = "tool" with tool_call_id if (msg.role === "tool" && msg.tool_call_id) { - return toolCallIds.includes(msg.tool_call_id); + return toolCallIds.includes(String(msg.tool_call_id)); } // Claude format: tool_result blocks in user message content if (msg.role === "user" && Array.isArray(msg.content)) { - for (const block of msg.content) { - if (block.type === "tool_result" && toolCallIds.includes(block.tool_use_id)) { + for (const block of msg.content as ToolContentBlock[]) { + if ( + block.type === "tool_result" && + block.tool_use_id && + toolCallIds.includes(String(block.tool_use_id)) + ) { return true; } } @@ -127,10 +269,10 @@ export function hasToolResults(msg, toolCallIds) { // Fix missing tool responses - insert empty tool_result if assistant has tool_use but next message has no tool_result. // Inserts in the same shape as the opening assistant message: OpenAI tool_calls → role:"tool"; // Claude tool_use blocks → role:"user" with tool_result content blocks. -export function fixMissingToolResponses(body) { +export function fixMissingToolResponses(body: T): T { if (!body.messages || !Array.isArray(body.messages)) return body; - const newMessages = []; + const newMessages: ToolMessage[] = []; for (let i = 0; i < body.messages.length; i++) { const msg = body.messages[i]; @@ -179,7 +321,7 @@ export function fixMissingToolResponses(body) { // role:"tool" messages and Claude-format tool_result content blocks. Drops a // user message entirely if stripping empties its content array. Returns the // same body reference when nothing needs to change (no-op fast path). -export function stripOrphanedToolResults(body) { +export function stripOrphanedToolResults(body: T): T { if (!body.messages || !Array.isArray(body.messages)) return body; const knownCallIds = new Set(); @@ -190,11 +332,11 @@ export function stripOrphanedToolResults(body) { } let changed = false; - const filteredMessages = []; + const filteredMessages: ToolMessage[] = []; for (const msg of body.messages) { if (msg.role === "tool" && msg.tool_call_id) { - if (knownCallIds.has(msg.tool_call_id)) { + if (knownCallIds.has(String(msg.tool_call_id))) { filteredMessages.push(msg); } else { changed = true; @@ -203,7 +345,7 @@ export function stripOrphanedToolResults(body) { } if (Array.isArray(msg.content)) { - const cleanedContent = msg.content.filter((block) => { + const cleanedContent = (msg.content as ToolContentBlock[]).filter((block) => { if (block?.type !== "tool_result") return true; return typeof block.tool_use_id === "string" && knownCallIds.has(block.tool_use_id); }); diff --git a/open-sse/translator/index.ts b/open-sse/translator/index.ts index 3b76f07c8c..27b1c37ef6 100644 --- a/open-sse/translator/index.ts +++ b/open-sse/translator/index.ts @@ -225,8 +225,12 @@ export function translateRequest( // Fix missing tool responses (insert empty tool_result if needed) fixMissingToolResponses(result); - // Strip orphaned tool results (tool_result/role:tool with no matching tool_call) - stripOrphanedToolResults(result); + // Claude reconciliation preserves orphaned tool output as labelled user text. + // Keep the raw result carriers until the target translator can perform that + // lossless conversion; other target formats retain the strict orphan filter. + if (targetFormat !== FORMATS.CLAUDE) { + stripOrphanedToolResults(result); + } // Normalize roles: developer→system unless preserved, system→user for incompatible models. // This handles (1) sourceFormat openai with messages containing developer → non-openai target @@ -259,11 +263,16 @@ export function translateRequest( if (directTranslator && sourceFormat !== FORMATS.OPENAI && targetFormat !== FORMATS.OPENAI) { // Thread the routed provider id so target translators can apply provider-specific // quirks (e.g. Vertex rejects function_call.id — #3440). + // Also thread signatureNamespace so Claude→Gemini can re-attach cached + // thoughtSignature on tool-use history (#8979 / #2504 parity with the hub path). + const hasNs = options?.signatureNamespace != null; + const hasProvider = provider != null; const directCredentials = - provider != null + hasNs || hasProvider ? { ...(credentials && typeof credentials === "object" ? credentials : {}), - _provider: provider, + ...(hasProvider ? { _provider: provider } : {}), + ...(hasNs ? { _signatureNamespace: options.signatureNamespace } : {}), } : credentials; result = directTranslator(model, result, stream, directCredentials); diff --git a/open-sse/translator/request/claude-to-gemini.ts b/open-sse/translator/request/claude-to-gemini.ts index 21d8192271..89807dfeca 100644 --- a/open-sse/translator/request/claude-to-gemini.ts +++ b/open-sse/translator/request/claude-to-gemini.ts @@ -5,10 +5,14 @@ import { tryParseJSON, cleanJSONSchemaForAntigravity, } from "../helpers/geminiHelper.ts"; -import { DEFAULT_THINKING_GEMINI_SIGNATURE } from "../../config/defaultThinkingSignature.ts"; import { buildGeminiTools, sanitizeGeminiToolName } from "../helpers/geminiToolsSanitizer.ts"; import { capMaxOutputTokens, capThinkingBudget } from "../../../src/lib/modelCapabilities.ts"; import { getModelSpec } from "../../../src/shared/constants/modelSpecs.ts"; +import { + buildGeminiThoughtSignatureKey, + resolveGeminiThoughtSignature, +} from "../../services/geminiThoughtSignatureStore.ts"; +import { buildHistoricalToolResultContext } from "./openai-to-gemini/helpers.ts"; /** * Direct Claude → Gemini request translator. @@ -26,6 +30,16 @@ export function claudeToGeminiRequest(model, body, stream, credentials = null) { // is scoped to the routed vertex provider only (threaded via credentials._provider). const provider = credentials && typeof credentials === "object" ? credentials._provider : null; const stripFunctionCallId = provider === "vertex" || provider === "vertex-partner"; + // Thread the signature namespace so a thinking model's thoughtSignature (cached on the + // Gemini→Claude response turn under `:`) is found and + // re-attached on the follow-up Claude→Gemini request. Without this, Claude Desktop + // combo turns hit HTTP 400 "missing thought_signature" (#8979 / #2504 parity). + const signatureNamespace = + credentials && + typeof credentials === "object" && + typeof credentials._signatureNamespace === "string" + ? credentials._signatureNamespace + : null; const result: { model: string; contents: Array>; @@ -81,14 +95,30 @@ export function claudeToGeminiRequest(model, body, stream, credentials = null) { } } - // ── Build tool_use name lookup (for tool_result matching) ────── - const toolUseNames = {}; + // ── Build tool_use name lookup + resolve thought signatures ──── + // Standard Gemini rejects signature-less native functionCall parts with + // HTTP 400 (#8979). Match the OPENAI→GEMINI "context" policy (#3688): only + // emit native functionCall/functionResponse when a real signature is + // available; otherwise represent history as context text. + const toolUseNames: Record = {}; + const resolvedSignatures = new Map(); if (body.messages && Array.isArray(body.messages)) { for (const msg of body.messages) { if (msg.role === "assistant" && Array.isArray(msg.content)) { for (const block of msg.content) { if (block.type === "tool_use" && block.id && block.name) { toolUseNames[block.id] = sanitizeToolName(block.name); + const clientSignature = + (typeof block.thoughtSignature === "string" && block.thoughtSignature) || + (typeof block.thought_signature === "string" && block.thought_signature) || + null; + const resolved = resolveGeminiThoughtSignature( + buildGeminiThoughtSignatureKey(signatureNamespace, block.id), + clientSignature + ); + if (typeof resolved === "string" && resolved.length > 0) { + resolvedSignatures.set(block.id, resolved); + } } } } @@ -99,6 +129,7 @@ export function claudeToGeminiRequest(model, body, stream, credentials = null) { if (body.messages && Array.isArray(body.messages)) { for (const msg of body.messages) { const parts = []; + let shouldUseEmbeddedSignature = true; if (Array.isArray(msg.content)) { for (const block of msg.content) { @@ -114,8 +145,25 @@ export function claudeToGeminiRequest(model, body, stream, credentials = null) { } break; - case "tool_use": + case "tool_use": { + const signatureForToolCall = resolvedSignatures.get(block.id); + // Signature-less historical tool_use → omit native functionCall + // (context mode). Matching tool_result becomes context text below. + if (!signatureForToolCall) { + break; + } + + const embeddedThoughtSignature = shouldUseEmbeddedSignature + ? signatureForToolCall + : undefined; + if (embeddedThoughtSignature) { + shouldUseEmbeddedSignature = false; + } + parts.push({ + ...(embeddedThoughtSignature + ? { thoughtSignature: embeddedThoughtSignature } + : {}), functionCall: { ...(stripFunctionCallId ? {} : { id: block.id }), name: sanitizeToolName(block.name), @@ -123,6 +171,7 @@ export function claudeToGeminiRequest(model, body, stream, credentials = null) { }, }); break; + } case "tool_result": { let content = block.content; @@ -137,10 +186,24 @@ export function claudeToGeminiRequest(model, body, stream, credentials = null) { } else if (typeof parsedContent !== "object") { parsedContent = { result: parsedContent }; } + + const toolUseId = block.tool_use_id; + const name = toolUseNames[toolUseId] || "unknown"; + + // Signature-less history: represent as context text so Gemini 3+ + // does not reject a native functionResponse without a matching + // signed functionCall (#8979 / #3688). + if (!resolvedSignatures.has(toolUseId)) { + parts.push({ + text: buildHistoricalToolResultContext(name, content), + }); + break; + } + parts.push({ functionResponse: { - ...(stripFunctionCallId ? {} : { id: block.tool_use_id }), - name: toolUseNames[block.tool_use_id] || "unknown", + ...(stripFunctionCallId ? {} : { id: toolUseId }), + name, response: { result: parsedContent }, }, }); @@ -167,14 +230,6 @@ export function claudeToGeminiRequest(model, body, stream, credentials = null) { if (parts.length > 0) { // Map Claude roles to Gemini roles const geminiRole = msg.role === "assistant" ? "model" : "user"; - - // Gemini 3+ expects the signature on all functionCall parts in a tool-call - // batch. If there is no real signature, we don't inject a fake one because - // Gemini API strictly validates it and returns 400. - if (geminiRole === "model") { - // No operation needed since we no longer inject fake signatures. - } - result.contents.push({ role: geminiRole, parts }); } } diff --git a/open-sse/translator/request/openai-responses.ts b/open-sse/translator/request/openai-responses.ts index 58863b47bc..4942c0f6bd 100644 --- a/open-sse/translator/request/openai-responses.ts +++ b/open-sse/translator/request/openai-responses.ts @@ -20,6 +20,7 @@ import { RESPONSES_STORE_MARKER, COPILOT_REASONING_SUMMARY_MARKER, WEB_SEARCH_TOOL_TYPES, + X_SEARCH_TOOL_TYPES, TOOL_SEARCH_TOOL_TYPES, IMAGE_GENERATION_TOOL_TYPES, toRecord, @@ -105,7 +106,7 @@ export function openaiResponsesToOpenAIRequest( // namespace tools (MCP tool groups used by Codex/OpenAI Responses API), and web_search server tools // (Anthropic versioned: web_search_20250305, web_search_20250101, etc. — or plain web_search). // tool_search is a Responses API built-in sent by newer Codex clients; silently skip it here - // (it will be filtered out during tools conversion below). + // (it will be filtered out during tools conversion below). x_search (#8964) same pattern. if ( toolType && toolType !== "function" && @@ -114,6 +115,7 @@ export function openaiResponsesToOpenAIRequest( toolType !== "namespace" && toolType !== "local_shell" && !WEB_SEARCH_TOOL_TYPES.test(toolType) && + !X_SEARCH_TOOL_TYPES.test(toolType) && !TOOL_SEARCH_TOOL_TYPES.test(toolType) && !IMAGE_GENERATION_TOOL_TYPES.test(toolType) && !tool.function @@ -575,6 +577,9 @@ export function openaiResponsesToOpenAIRequest( if (WEB_SEARCH_TOOL_TYPES.test(toolType)) { return toolValue; } + if (X_SEARCH_TOOL_TYPES.test(toolType)) { + return []; + } // local_shell is a Responses API built-in (Codex CLI injects it for shell // execution). Non-OpenAI upstreams (Kiro/Claude) have no local_shell type, // so map it to a regular "shell" function tool. The response translator @@ -763,7 +768,7 @@ export function openaiResponsesToOpenAIRequest( const reasoningRec = toRecord(root.reasoning); const effort = toString(reasoningRec.effort); if (effort && result.reasoning_effort === undefined) { - result.reasoning_effort = normalizeResponsesReasoningEffort(effort); + result.reasoning_effort = normalizeResponsesReasoningEffort(effort, model); } if ( credentialRecord._copilotClient === true && diff --git a/open-sse/translator/request/openai-responses/helpers.ts b/open-sse/translator/request/openai-responses/helpers.ts index 60d5177871..7c5b4afa63 100644 --- a/open-sse/translator/request/openai-responses/helpers.ts +++ b/open-sse/translator/request/openai-responses/helpers.ts @@ -7,6 +7,7 @@ export const COPILOT_REASONING_SUMMARY_MARKER = "_omnirouteCopilotReasoningSumma // Forward-compatible regex: matches web_search, web_search_20250305, and future versioned names. export const WEB_SEARCH_TOOL_TYPES = /^web_search/; +export const X_SEARCH_TOOL_TYPES = /^x_search/; // tool_search is a Responses API built-in sent by newer Codex clients; it has no Chat Completions // equivalent and must be silently dropped (not rejected with 400). export const TOOL_SEARCH_TOOL_TYPES = /^tool_search/; @@ -88,13 +89,18 @@ export function getVisibleResponsesReasoningSummaryText(item: unknown): string { const CODEX_GPT_5_6_MODEL_PATTERN = /^gpt-5\.6-(?:sol|terra|luna)(?:-(?:none|low|medium|high|xhigh|max|ultra))?$/; +const KIRO_GPT_5_6_MODEL_PATTERN = + /^(?:kiro|kr)\/gpt-5\.6-(?:sol|terra|luna)(?:-(?:none|low|medium|high|xhigh|max))?$/; function supportsNativeMaxReasoningEffort(model: unknown): boolean { const normalizedModel = toString(model) .trim() .toLowerCase() .replace(/^(?:codex|cx)\//, ""); - return CODEX_GPT_5_6_MODEL_PATTERN.test(normalizedModel); + return ( + CODEX_GPT_5_6_MODEL_PATTERN.test(normalizedModel) || + KIRO_GPT_5_6_MODEL_PATTERN.test(toString(model).trim().toLowerCase()) + ); } export function normalizeResponsesReasoningEffort(value: unknown, model?: unknown): string { diff --git a/open-sse/translator/request/openai-to-claude/toolResultAdjacency.ts b/open-sse/translator/request/openai-to-claude/toolResultAdjacency.ts index 9b40385df3..d2b2757432 100644 --- a/open-sse/translator/request/openai-to-claude/toolResultAdjacency.ts +++ b/open-sse/translator/request/openai-to-claude/toolResultAdjacency.ts @@ -7,19 +7,14 @@ type ClaudeMessage = { // Anthropic requires each user tool_result turn to immediately follow the // assistant turn containing the matching tool_use. OpenAI-compatible clients can // send intervening user text before a later role:"tool" message, so repair the -// ordering here and drop true orphan results. +// ordering here while preserving unmatched output for the Claude-format pass. export function enforceToolResultAdjacency(messages: ClaudeMessage[]): ClaudeMessage[] { const assistantByToolUseId = indexAssistantToolUses(messages); const resultsByAssistant = new Map(); const strippedMessages: ClaudeMessage[] = []; for (const msg of messages) { - stripAndCollectToolResults( - msg, - assistantByToolUseId, - resultsByAssistant, - strippedMessages - ); + stripAndCollectToolResults(msg, assistantByToolUseId, resultsByAssistant, strippedMessages); } return insertAdjacentToolResults(strippedMessages, resultsByAssistant); @@ -53,8 +48,19 @@ function stripAndCollectToolResults( for (const block of msg.content) { if (block.type !== "tool_result") { remainingBlocks.push(block); - } else { - collectMatchedToolResult(block, assistantByToolUseId, resultsByAssistant); + continue; + } + + if (!collectMatchedToolResult(block, assistantByToolUseId, resultsByAssistant)) { + const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : ""; + const serialized = + typeof block.content === "string" + ? block.content + : (JSON.stringify(block.content ?? "") ?? ""); + remainingBlocks.push({ + type: "text", + text: `[Unpaired tool result ${toolUseId || "unknown"}]\n${serialized}`, + }); } } @@ -67,16 +73,17 @@ function collectMatchedToolResult( block: ClaudeContentBlock, assistantByToolUseId: Map, resultsByAssistant: Map -): void { +): boolean { const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : ""; const assistant = toolUseId ? assistantByToolUseId.get(toolUseId) : undefined; - if (!assistant) return; + if (!assistant) return false; const grouped = resultsByAssistant.get(assistant) ?? []; - if (grouped.some((toolResult) => toolResult.tool_use_id === toolUseId)) return; + if (grouped.some((toolResult) => toolResult.tool_use_id === toolUseId)) return false; grouped.push(block); resultsByAssistant.set(assistant, grouped); + return true; } function insertAdjacentToolResults( diff --git a/open-sse/translator/request/openai-to-kiro.ts b/open-sse/translator/request/openai-to-kiro.ts index f6de86b49f..17a5f6d1d6 100644 --- a/open-sse/translator/request/openai-to-kiro.ts +++ b/open-sse/translator/request/openai-to-kiro.ts @@ -14,6 +14,7 @@ import { import { resolveKiroModelAlias, supportsKiroAdaptiveThinking, + supportsKiroNativeReasoning, } from "./openai-to-kiro/adaptiveThinking.ts"; /** @@ -46,6 +47,69 @@ function wrapSystemReminder(text: string): string { return `\n${text}\n`; } +/** Kiro rejects a `toolSpecification.description` longer than ~10000 chars. */ +const KIRO_TOOL_DESC_MAX = 10000; + +/** OpenAI- and Anthropic-shaped tool declarations, as clients actually send them. */ +type KiroToolInput = { + name?: string; + description?: string; + parameters?: unknown; + input_schema?: unknown; + function?: { name?: string; description?: string; parameters?: unknown }; +}; + +/** + * Build Kiro `toolSpecification` entries, relocating any oversized description + * out of the schema and returning it separately. + * + * Kiro answers a raw upstream 400 for a description over + * {@link KIRO_TOOL_DESC_MAX}, so the schema keeps a pointer and the full text is + * handed back to be prepended to the current turn's content — the same + * relocation kiro-gateway performs in + * `converters_core.py::process_tools_with_long_descriptions`. + * + * The docs are *returned* rather than stashed on the message object, because the + * tool-bearing user turn is moved into `history` on every multi-turn request + * (see the currentMessage promotion below). Carrying them on the message lost + * them there — the model then saw only the pointer and no documentation — and + * also leaked an unknown `_toolDocs` field into the upstream payload, which Kiro + * rejects. + */ +function buildKiroToolSpecs(tools: KiroToolInput[]): { + specs: Array>; + docs: string; +} { + const docs: string[] = []; + const specs = tools.map((t) => { + const name = t.function?.name || t.name; + let description = t.function?.description || t.description || ""; + + if (!description.trim()) { + description = `Tool: ${name}`; + } + + if (description.length > KIRO_TOOL_DESC_MAX) { + docs.push(`## Tool: ${name}\n\n${description}`); + description = `[Full documentation in system prompt under '## Tool: ${name}']`; + } + + return { + toolSpecification: { + name, + description, + inputSchema: { + json: normalizeKiroToolSchema( + t.function?.parameters || t.parameters || t.input_schema || {} + ), + }, + }, + }; + }); + + return { specs, docs: docs.join("\n\n---\n\n") }; +} + /** * Convert OpenAI messages to Kiro format * Rules: system/tool/user -> user role, merge consecutive same roles @@ -60,6 +124,7 @@ function convertMessages(messages, tools, model) { let pendingImages: Array<{ format: string; source: { bytes: string } }> = []; let currentRole = null; let toolsAttached = false; + let toolDocs = ""; // Only Claude models support images in Kiro. Kiro also routes non-Claude // models (deepseek, minimax, glm, qwen3-coder-next) that do not accept image @@ -89,7 +154,6 @@ function convertMessages(messages, tools, model) { tools?: Array>; }; }; - _toolDocs?: string; } = { userInputMessage: { content: content, @@ -118,39 +182,9 @@ function convertMessages(messages, tools, model) { if (!userMsg.userInputMessage.userInputMessageContext) { userMsg.userInputMessage.userInputMessageContext = {}; } - // Kiro API rejects requests with tool descriptions > ~10000 chars. - // Move long descriptions to system prompt (same approach as kiro-gateway). - const TOOL_DESC_MAX = 10000; - const toolDocs: string[] = []; - userMsg.userInputMessage.userInputMessageContext.tools = tools.map((t) => { - const name = t.function?.name || t.name; - let description = t.function?.description || t.description || ""; - - if (!description.trim()) { - description = `Tool: ${name}`; - } - - if (description.length > TOOL_DESC_MAX) { - toolDocs.push(`## Tool: ${name}\n\n${description}`); - description = `[Full documentation in system prompt under '## Tool: ${name}']`; - } - - return { - toolSpecification: { - name, - description, - inputSchema: { - json: normalizeKiroToolSchema( - t.function?.parameters || t.parameters || t.input_schema || {} - ), - }, - }, - }; - }); - // Attach tool docs to message so buildKiroPayload can prepend to content - if (toolDocs.length > 0) { - userMsg._toolDocs = toolDocs.join("\n\n---\n\n"); - } + const built = buildKiroToolSpecs(tools); + userMsg.userInputMessage.userInputMessageContext.tools = built.specs; + if (built.docs) toolDocs = built.docs; toolsAttached = true; } @@ -370,21 +404,9 @@ function convertMessages(messages, tools, model) { if (!currentMessage.userInputMessage.userInputMessageContext) { currentMessage.userInputMessage.userInputMessageContext = {}; } - currentMessage.userInputMessage.userInputMessageContext.tools = tools.map((t) => { - const name = t.function?.name || t.name; - const description = t.function?.description || t.description || `Tool: ${name}`; - return { - toolSpecification: { - name, - description, - inputSchema: { - json: normalizeKiroToolSchema( - t.function?.parameters || t.parameters || t.input_schema || {} - ), - }, - }, - }; - }); + const built = buildKiroToolSpecs(tools); + currentMessage.userInputMessage.userInputMessageContext.tools = built.specs; + if (built.docs) toolDocs = built.docs; toolsAttached = true; } @@ -577,7 +599,7 @@ function convertMessages(messages, tools, model) { alternatingHistory.push(item); } - return { history: alternatingHistory, currentMessage, toolsAttached }; + return { history: alternatingHistory, currentMessage, toolsAttached, toolDocs }; } /** Kiro's accepted reasoning-effort levels (`output_config.effort`). */ @@ -723,7 +745,7 @@ export function buildKiroPayload(model, body, stream, credentials) { } } - const { history, currentMessage, toolsAttached } = convertMessages( + const { history, currentMessage, toolsAttached, toolDocs } = convertMessages( messages, tools, normalizedModel @@ -735,8 +757,10 @@ export function buildKiroPayload(model, body, stream, credentials) { const timestamp = new Date().toISOString(); finalContent = `[Context: Current time is ${timestamp}]\n\n${finalContent}`; - // Prepend tool documentation for tools with long descriptions (moved from toolSpecification) - const toolDocs = (currentMessage as { _toolDocs?: string } | null)?._toolDocs; + // Prepend documentation for tools whose description was relocated out of + // `toolSpecification` (see buildKiroToolSpecs). Driven by convertMessages' + // return value, not the message object, so the docs survive the tool-bearing + // turn being moved into `history` on a multi-turn request. if (toolDocs) { finalContent = `# Tool Documentation\n\n${toolDocs}\n\n---\n\n${finalContent}`; } @@ -763,6 +787,7 @@ export function buildKiroPayload(model, body, stream, credentials) { topP?: number; }; additionalModelRequestFields?: { + reasoning?: { effort: string }; thinking?: { type: string; display?: string }; output_config?: { effort: string }; max_tokens?: number; @@ -847,29 +872,43 @@ export function buildKiroPayload(model, body, stream, credentials) { // thinking:{type:"adaptive"} + a clamped max_tokens), forwarded to AWS by // the Kiro executor's transformRequest allowlist — the graded effort lever, // gated on Kiro's adaptive-thinking allowlist (#6576), not supportsReasoning(). + // GPT-5.6 models use the native `reasoning:{effort}` field instead. They must + // not receive the Claude `output_config`/`thinking` envelope: Kiro rejects it + // as an unknown field for the GPT-5.6 family. const requestedEffort = resolveKiroEffort(body) || (modelRequestsThinking ? "high" : ""); - const kiroEffort = supportsKiroAdaptiveThinking(normalizedModel) ? requestedEffort : ""; + const usesNativeReasoning = supportsKiroNativeReasoning(normalizedModel); + const usesAdaptiveThinking = supportsKiroAdaptiveThinking(normalizedModel); + const kiroEffort = usesNativeReasoning || usesAdaptiveThinking ? requestedEffort : ""; if (kiroEffort) { - // `` / `` are Kiro/CodeWhisperer prompt - // conventions (NOT Anthropic API params); the length is a soft hint (the hard - // enable signal is ``), clamped to the model's thinking cap. - const thinkingLength = capThinkingBudget(normalizedModel, thinkingLengthForEffort(kiroEffort)); - const directive = - `enabled` + - `${thinkingLength}`; - payload.conversationState.currentMessage.userInputMessage.content = `${directive}\n\n${payload.conversationState.currentMessage.userInputMessage.content}`; - const fields: { - output_config: { effort: string }; - thinking: { type: string; display: string }; + reasoning?: { effort: string }; + output_config?: { effort: string }; + thinking?: { type: string; display: string }; max_tokens?: number; - } = { - output_config: { effort: kiroEffort }, - thinking: { type: "adaptive", display: "summarized" }, - }; + } = usesNativeReasoning + ? { reasoning: { effort: kiroEffort } } + : { + output_config: { effort: kiroEffort }, + thinking: { type: "adaptive", display: "summarized" }, + }; + + if (usesAdaptiveThinking) { + // `` / `` are Kiro/CodeWhisperer prompt + // conventions (NOT Anthropic API params); the length is a soft hint (the hard + // enable signal is ``), clamped to the model's thinking cap. + const thinkingLength = capThinkingBudget( + normalizedModel, + thinkingLengthForEffort(kiroEffort) + ); + const directive = + `enabled` + + `${thinkingLength}`; + payload.conversationState.currentMessage.userInputMessage.content = `${directive}\n\n${payload.conversationState.currentMessage.userInputMessage.content}`; + } + // Forward max_tokens only when the client set one, clamped to the model's // output window (floor 1024) — matches pi-kiro and avoids an over-budget reject. - if (maxTokens > 0) { + if (usesAdaptiveThinking && maxTokens > 0) { const capped = capMaxOutputTokens(normalizedModel, maxTokens) ?? maxTokens; fields.max_tokens = Math.max(Math.floor(capped), 1024); } diff --git a/open-sse/translator/request/openai-to-kiro/adaptiveThinking.ts b/open-sse/translator/request/openai-to-kiro/adaptiveThinking.ts index 338768f8d6..72ccc81951 100644 --- a/open-sse/translator/request/openai-to-kiro/adaptiveThinking.ts +++ b/open-sse/translator/request/openai-to-kiro/adaptiveThinking.ts @@ -7,17 +7,21 @@ * rejects the field for `claude-sonnet-4.5` and `claude-haiku-4.5` with a raw * upstream 400 (`additionalModelRequestFields is not supported for this * model`, issue #6576) even though both ARE thinking-capable on Anthropic's - * direct API. Only `claude-sonnet-5` is confirmed to accept the adaptive - * envelope on Kiro today — keep this allowlist in sync with - * `open-sse/config/providers/registry/kiro/index.ts` if Kiro's catalog or - * upstream behavior changes. + * direct API. `claude-sonnet-5` is confirmed to accept the adaptive envelope + * on Kiro today. GPT-5.6 models use Kiro's separate `reasoning.effort` shape, + * not this Claude adaptive envelope. */ const KIRO_ADAPTIVE_THINKING_MODELS = new Set(["claude-sonnet-5"]); +const KIRO_NATIVE_REASONING_MODELS = new Set(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]); export function supportsKiroAdaptiveThinking(normalizedModel: string): boolean { return KIRO_ADAPTIVE_THINKING_MODELS.has(normalizedModel); } +export function supportsKiroNativeReasoning(normalizedModel: string): boolean { + return KIRO_NATIVE_REASONING_MODELS.has(normalizedModel); +} + const KIRO_UNSUPPORTED_AGENTIC_MESSAGE = "Kiro agentic aliases are not supported. The '-agentic' suffix did not change the " + "upstream request; select a real Kiro model instead."; diff --git a/open-sse/translator/response/claude-to-openai.ts b/open-sse/translator/response/claude-to-openai.ts index 725799d026..026a3e1f3e 100644 --- a/open-sse/translator/response/claude-to-openai.ts +++ b/open-sse/translator/response/claude-to-openai.ts @@ -5,10 +5,14 @@ type OpenAIUsage = { prompt_tokens: number; completion_tokens: number; total_tokens: number; + reasoning_tokens?: number; prompt_tokens_details?: { cached_tokens?: number; cache_creation_tokens?: number; }; + completion_tokens_details?: { + reasoning_tokens?: number; + }; }; // Create OpenAI chunk helper @@ -153,6 +157,10 @@ export function claudeToOpenAIResponse(chunk, state) { typeof chunk.usage.input_tokens === "number" ? chunk.usage.input_tokens : 0; const outputTokens = typeof chunk.usage.output_tokens === "number" ? chunk.usage.output_tokens : 0; + const thinkingTokens = + typeof chunk.usage.output_tokens_details?.thinking_tokens === "number" + ? chunk.usage.output_tokens_details.thinking_tokens + : undefined; const cacheReadTokens = typeof chunk.usage.cache_read_input_tokens === "number" ? chunk.usage.cache_read_input_tokens @@ -181,6 +189,14 @@ export function claudeToOpenAIResponse(chunk, state) { output_tokens: outputTokens, }; + // Anthropic includes thinking in output_tokens. Surface the separately + // reported portion without adding it to completion_tokens a second time. + if (thinkingTokens !== undefined) { + state.usage.reasoning_tokens = thinkingTokens; + state.usage.completion_tokens_details = { reasoning_tokens: thinkingTokens }; + state.usage.output_tokens_details = { thinking_tokens: thinkingTokens }; + } + // Store cache tokens if present (needed for prompt_tokens_details in final chunk) const effectiveCacheReadTokens = cacheReadTokens || previousCacheReadTokens; const effectiveCacheCreationTokens = cacheCreationTokens || previousCacheCreationTokens; @@ -252,6 +268,14 @@ export function claudeToOpenAIResponse(chunk, state) { total_tokens: totalTokens, }; + const reasoningTokens = state.usage.reasoning_tokens; + if (typeof reasoningTokens === "number") { + finalChunk.usage.reasoning_tokens = reasoningTokens; + finalChunk.usage.completion_tokens_details = { + reasoning_tokens: reasoningTokens, + }; + } + // Add prompt_tokens_details if cached tokens exist if (cachedTokens > 0 || cacheCreationTokens > 0) { finalChunk.usage.prompt_tokens_details = {}; @@ -281,6 +305,14 @@ export function claudeToOpenAIResponse(chunk, state) { prompt_tokens: state.usage.input_tokens || 0, completion_tokens: state.usage.output_tokens || 0, total_tokens: (state.usage.input_tokens || 0) + (state.usage.output_tokens || 0), + ...(typeof state.usage.reasoning_tokens === "number" + ? { + reasoning_tokens: state.usage.reasoning_tokens, + completion_tokens_details: { + reasoning_tokens: state.usage.reasoning_tokens, + }, + } + : {}), }, } : {}; diff --git a/open-sse/translator/response/gemini-to-claude.ts b/open-sse/translator/response/gemini-to-claude.ts index 2307edd61e..61d4f4283a 100644 --- a/open-sse/translator/response/gemini-to-claude.ts +++ b/open-sse/translator/response/gemini-to-claude.ts @@ -2,6 +2,10 @@ import { register } from "../registry.ts"; import { FORMATS } from "../formats.ts"; import { isAbortFinishReason } from "../../utils/finishReason.ts"; import { REVERSE_MAP } from "../../services/claudeCodeToolRemapper.ts"; +import { + buildGeminiThoughtSignatureKey, + storeGeminiThoughtSignature, +} from "../../services/geminiThoughtSignatureStore.ts"; function normalizeToolName(name: string): string { return REVERSE_MAP[name] ?? name; @@ -56,6 +60,12 @@ export function geminiToClaudeResponse(chunk, state) { const hasThoughtSig = part.thoughtSignature || part.thought_signature; const isThought = part.thought === true; + // Capture thoughtSignature so the next functionCall (or same-part call) + // can persist it for Claude→Gemini follow-up turns (#8979 / #2504 parity). + if (typeof hasThoughtSig === "string" && hasThoughtSig.length > 0) { + state.pendingThoughtSignature = hasThoughtSig; + } + // Thinking content → thinking block (always open+close per chunk) if (isThought && part.text) { // Close any open text block first @@ -78,6 +88,17 @@ export function geminiToClaudeResponse(chunk, state) { continue; } + // Standalone thoughtSignature part (no text / no functionCall): keep + // pending and wait for the following functionCall — do not emit to Claude. + if ( + typeof hasThoughtSig === "string" && + hasThoughtSig.length > 0 && + (part.text === undefined || part.text === "") && + !part.functionCall + ) { + continue; + } + // Function call → tool_use block if (part.functionCall) { // Close any open text block first @@ -91,6 +112,22 @@ export function geminiToClaudeResponse(chunk, state) { const idx = state.contentBlockIndex++; const toolId = fc.id || `toolu_${Date.now()}_${idx}`; + const signatureForToolCall = + (typeof hasThoughtSig === "string" && hasThoughtSig.length > 0 + ? hasThoughtSig + : null) || + (typeof state.pendingThoughtSignature === "string" && + state.pendingThoughtSignature.length > 0 + ? state.pendingThoughtSignature + : null); + if (signatureForToolCall) { + storeGeminiThoughtSignature( + buildGeminiThoughtSignatureKey(state.signatureNamespace, toolId), + signatureForToolCall + ); + state.pendingThoughtSignature = null; + } + results.push({ type: "content_block_start", index: idx, diff --git a/open-sse/translator/response/openai-responses.ts b/open-sse/translator/response/openai-responses.ts index b3c6e92464..1a32b0710b 100644 --- a/open-sse/translator/response/openai-responses.ts +++ b/open-sse/translator/response/openai-responses.ts @@ -779,6 +779,37 @@ function markResponsesReasoningDeltaEmitted(state, itemId) { state.reasoningItemsWithDelta.add(id); } +// #9500 — streaming separator helper. When summary_index increments mid-stream +// for a given item_id, a new reasoning segment begins; prefix "\n\n" so segments +// don't arrive back-to-back. Only prefixes when a delta was already emitted for +// the item AND the index advanced — never on the first segment. Lives here (not +// in pureHelpers.ts) because it reads and mutates stream state, which the pure +// leaf must not hold. +function buildResponsesReasoningSummaryDelta(state, data, reasoningDelta) { + const itemId = data.item_id != null ? String(data.item_id) : ""; + const summaryIndex = typeof data.summary_index === "number" ? data.summary_index : null; + if (!(state.reasoningSummaryIndex instanceof Map)) { + state.reasoningSummaryIndex = new Map(); + } + const lastIndex = itemId ? state.reasoningSummaryIndex.get(itemId) : undefined; + const alreadyEmittedForItem = itemId + ? state.reasoningItemsWithDelta instanceof Set && state.reasoningItemsWithDelta.has(itemId) + : Boolean(state.reasoningDeltaEmitted); + let deltaText = reasoningDelta; + if ( + summaryIndex !== null && + lastIndex !== undefined && + summaryIndex > lastIndex && + alreadyEmittedForItem + ) { + deltaText = `\n\n${reasoningDelta}`; + } + if (itemId && (lastIndex === undefined || summaryIndex > lastIndex)) { + state.reasoningSummaryIndex.set(itemId, summaryIndex); + } + return deltaText; +} + // #5786 — build a Chat-format reasoning delta chunk in the shape the client renders in // its thinking panel (`reasoning_content`, or `reasoning_text` for Copilot-compatible // clients). Mirrors the `response.reasoning_summary_text.delta` branch. @@ -1175,17 +1206,16 @@ function openaiResponsesToOpenAIResponseStream(chunk, state) { }; } - // Handle true reasoning summary ("Thought for 15s"). - // Emit as `delta.reasoning_content` — matches the shape used by the - // `reasoning_content_text.delta` branch above and is what Chat clients - // (OpenCode, Claude Code, Cursor, etc.) actually render in their thinking - // panel. A nested `delta.reasoning.summary` object is swallowed by most - // stream mergers and never reaches the user. + // Handle true reasoning summary ("Thought for 15s"). Emit as `delta.reasoning_content` + // — matches the `reasoning_content_text.delta` branch above and is what Chat clients + // (OpenCode, Claude Code, Cursor, etc.) render in their thinking panel. A nested + // `delta.reasoning.summary` object is swallowed by most stream mergers. if (eventType === "response.reasoning_summary_text.delta") { const reasoningDelta = data.delta || ""; if (!reasoningDelta) return null; markResponsesReasoningDeltaEmitted(state, data.item_id); - return buildResponsesReasoningDeltaChunk(state, reasoningDelta); + const deltaText = buildResponsesReasoningSummaryDelta(state, data, reasoningDelta); + return buildResponsesReasoningDeltaChunk(state, deltaText); } // #5786 — reasoning summary exposed ONLY as a terminal snapshot on diff --git a/open-sse/translator/response/openai-responses/pureHelpers.ts b/open-sse/translator/response/openai-responses/pureHelpers.ts index e2cc70fce4..e35ad24854 100644 --- a/open-sse/translator/response/openai-responses/pureHelpers.ts +++ b/open-sse/translator/response/openai-responses/pureHelpers.ts @@ -166,11 +166,15 @@ export function normalizeUpstreamFailure(data, fallbackType = "server_error") { export function extractResponsesReasoningSummaryText(item) { if (!item || !Array.isArray(item.summary)) return ""; + // #9500 — reasoning summary parts are discrete segments; join with "\n\n" + // (matches extractThinkingFromContent convention). Filter empties so an + // empty summary_text element does not produce a dangling separator. return item.summary .map((part) => part && typeof part === "object" && typeof part.text === "string" ? part.text : "" ) - .join(""); + .filter((text) => text.length > 0) + .join("\n\n"); } // #7095/#7176 — when Codex exposes a reasoning item only as encrypted private diff --git a/open-sse/translator/response/openai-to-claude.ts b/open-sse/translator/response/openai-to-claude.ts index 15b481da74..6a5d1687ad 100644 --- a/open-sse/translator/response/openai-to-claude.ts +++ b/open-sse/translator/response/openai-to-claude.ts @@ -284,6 +284,7 @@ export function openaiToClaudeResponse(chunk, state) { // Strip the Claude OAuth prefix from an incoming tool name (if any). const incomingName = (() => { let n = tc.function?.name || ""; + n = state.toolNameMap?.get(n) || n; if (n.startsWith(CLAUDE_OAUTH_TOOL_PREFIX)) n = n.slice(CLAUDE_OAUTH_TOOL_PREFIX.length); return n; })(); diff --git a/open-sse/utils/aiSdkCompat.ts b/open-sse/utils/aiSdkCompat.ts index fb26394a4b..2973ac06a0 100644 --- a/open-sse/utils/aiSdkCompat.ts +++ b/open-sse/utils/aiSdkCompat.ts @@ -130,6 +130,16 @@ export function resolveStreamFlag( return false; } + // OpenAI Chat Completions: omitted `stream` defaults to false per the OpenAI + // contract. A client that says nothing is asking for a JSON object, not an + // SSE event stream. Honor a pure text/event-stream Accept as an explicit SSE + // opt-in; otherwise default to non-stream. The application/json check above + // already handles the Vercel/OpenAI SDK mixed-signature case. + if (sourceFormat === "openai") { + if (acceptsEventStream) return true; + return false; + } + // No explicit stream param — preserve OmniRoute's streaming default unless // the client explicitly asks for JSON and does not also accept SSE. return !clientWantsJsonResponse(acceptHeader); diff --git a/open-sse/utils/earlyStreamKeepalive.ts b/open-sse/utils/earlyStreamKeepalive.ts index 2a7fe25dff..b8c3c631f8 100644 --- a/open-sse/utils/earlyStreamKeepalive.ts +++ b/open-sse/utils/earlyStreamKeepalive.ts @@ -1,13 +1,18 @@ /** - * Early SSE keepalive wrapper for streaming route handlers. + * @file earlyStreamKeepalive.ts + * @description Early SSE keepalive wrapper so short idle-read clients stay connected + * while the handler waits on upstream first-byte (reasoning models, combo failover). + * + * @changes + * - [2026-07-28] [Cursor Grok 4.5] - Scrub omniroute from client-facing keepalive id/model/comment frames + * - [2026-07-28] [Cursor Grok 4.5] - Neutralize Responses startup thinking text (no OmniRoute brand leak) * * Strict HTTP clients (notably Codex CLI's `reqwest`, which has a ~5s idle-read * timeout) drop the connection if no bytes arrive shortly after the request. - * OmniRoute, however, holds the streaming response until `ensureStreamReadiness` - * observes the upstream's first useful byte — which can exceed 5s for reasoning - * models that "think" before emitting any token (#2544). `curl` has no such - * idle timeout, so it was never affected, which is why the bug looked - * client-specific. + * The proxy holds the streaming response until `ensureStreamReadiness` observes + * the upstream's first useful byte — which can exceed 5s for reasoning models + * that "think" before emitting any token (#2544). `curl` has no such idle + * timeout, so it was never affected, which is why the bug looked client-specific. * * This wrapper keeps the connection warm without disturbing the handler's * internal logic (combo failover, stream readiness, account cooldown all still @@ -27,12 +32,13 @@ */ const ENCODER = new TextEncoder(); -const KEEPALIVE_FRAME = ENCODER.encode(": omniroute-keepalive\n\n"); +const KEEPALIVE_FRAME = ENCODER.encode(": keepalive\n\n"); // OpenAI-compatible keepalive: a syntactically valid empty streaming chunk. // Some OpenAI-compatible clients parse every non-empty SSE line as JSON and // reject legal SSE comments before their first provider chunk arrives. +// id/model stay brand-neutral — these frames go to the client, not upstream. export const OPENAI_KEEPALIVE_FRAME = ENCODER.encode( - 'data: {"id":"omniroute-keepalive","object":"chat.completion.chunk","created":0,"model":"omniroute","choices":[{"index":0,"delta":{},"finish_reason":null}]}\n\n' + 'data: {"id":"chatcmpl-keepalive","object":"chat.completion.chunk","created":0,"model":"keepalive","choices":[{"index":0,"delta":{},"finish_reason":null}]}\n\n' ); // The first slow-path frame must be a valid OpenAI chunk without creating // visible reasoning that clients persist into the conversation. @@ -51,8 +57,9 @@ export const ANTHROPIC_PING_FRAME = ENCODER.encode('event: ping\ndata: {"type":" // real upstream response — once it arrives — starts its own independent // response.created lifecycle from scratch; this placeholder item never // carries a response_id and isn't meant to be continued. -const RESPONSES_STARTUP_ITEM_ID = "rs_omniroute_keepalive"; -const STARTUP_THINKING_TEXT = "OmniRoute: got request, sending to provider"; +const RESPONSES_STARTUP_ITEM_ID = "rs_keepalive"; +// Brand-neutral placeholder — clients persist this as visible reasoning. +const STARTUP_THINKING_TEXT = "✨"; export const RESPONSES_STARTUP_THINKING_FRAME = ENCODER.encode( [ { @@ -144,7 +151,7 @@ export type EarlyStreamKeepaliveOptions = { signal?: AbortSignal | null; /** * Frame emitted on each keepalive tick. Defaults to an SSE comment - * (`: omniroute-keepalive`). Anthropic-format routes (/v1/messages) must pass + * (`: keepalive`). Anthropic-format routes (/v1/messages) must pass * `ANTHROPIC_PING_FRAME` instead, because Anthropic clients ignore SSE comments * for their stream watchdog and only a real `event: ping` keeps them from aborting. */ diff --git a/open-sse/utils/openAIStreamChunk.ts b/open-sse/utils/openAIStreamChunk.ts new file mode 100644 index 0000000000..d249d78ff8 --- /dev/null +++ b/open-sse/utils/openAIStreamChunk.ts @@ -0,0 +1,33 @@ +import { restoreOpenAIToolNames } from "../translator/helpers/toolCallHelper.ts"; + +type JsonRecord = Record; + +export function normalizeFinalOpenAIStreamChunk( + parsed: JsonRecord, + toolNameMap: unknown +): { changed: boolean; hasFinishReason: boolean } { + let changed = false; + if (parsed.id != null && typeof parsed.id !== "string") { + parsed.id = String(parsed.id); + changed = true; + } + + if (Array.isArray(parsed.choices)) { + for (const choice of parsed.choices as JsonRecord[]) { + const delta = (choice as JsonRecord | null | undefined)?.delta as JsonRecord | undefined; + if (!Array.isArray(delta?.tool_calls)) continue; + for (const toolCall of delta.tool_calls as JsonRecord[]) { + if (toolCall?.id != null && typeof toolCall.id !== "string") { + toolCall.id = String(toolCall.id); + changed = true; + } + } + } + } + + changed = restoreOpenAIToolNames(parsed, toolNameMap) || changed; + const firstChoice = Array.isArray(parsed.choices) + ? (parsed.choices[0] as JsonRecord | undefined) + : undefined; + return { changed, hasFinishReason: Boolean(firstChoice?.finish_reason) }; +} diff --git a/open-sse/utils/passthroughTailProcessor.ts b/open-sse/utils/passthroughTailProcessor.ts index 732e09cb4f..23d04e8a27 100644 --- a/open-sse/utils/passthroughTailProcessor.ts +++ b/open-sse/utils/passthroughTailProcessor.ts @@ -45,6 +45,7 @@ export type PassthroughTailProcessorContext = { setPassthroughResponsesCurrentFunctionCallKey: (value: string | null) => void; hasPassthroughToolCalls: () => boolean; toResponsesCompletedWithToolCalls: (parsed: JsonRecord) => JsonRecord; + restoreOpenAIToolNames: (parsed: JsonRecord) => boolean; }; function asRecord(value: unknown): JsonRecord { @@ -290,7 +291,9 @@ export function processBufferedPassthroughLine( if (isResponses) { output = handleResponsesTailPayload(parsed, output, context); } else if (!isClaude) { + const restoredToolName = context.restoreOpenAIToolNames(parsed); handleOpenAiTailPayload(parsed, context); + if (restoredToolName) output = `data: ${JSON.stringify(parsed)}\n\n`; } context.pushClientPayload(parsed); diff --git a/open-sse/utils/proxyDispatcher.ts b/open-sse/utils/proxyDispatcher.ts index ebf6b53f1b..25d065a2c9 100644 --- a/open-sse/utils/proxyDispatcher.ts +++ b/open-sse/utils/proxyDispatcher.ts @@ -11,6 +11,7 @@ import { getDispatcherCache, getRetryCachedDispatcher, setDefaultCachedDispatcher, + setDispatcherCacheEntry, setRetryCachedDispatcher, } from "./proxyDispatcherCache.ts"; @@ -96,20 +97,27 @@ export function getProxyDispatcherConnectionLimit( function getProxyDispatcherOptions(env: Record = process.env) { const options = getDispatcherOptions(); - // Disable keep-alive and pipelining for proxy connections. - // Cheap proxy servers aggressively drop idle sockets without sending TCP RST, - // causing "socket hang up" or "Client network socket disconnected" errors - // on subsequent requests that try to reuse the pooled connection. + // #9100: restore keep-alive on the proxy path. The previous hard-coded + // keepAliveTimeout: 1 (1ms) destroyed the pooled socket right after every + // response, forcing a fresh TCP+TLS+CONNECT handshake per request. Proxies + // that throttle connection churn then serialized concurrent requests behind + // ~30s stalls (5 concurrent → 1 fast + 4× ~29.5s). The socket now stays + // alive for at least 30s (the default fetchKeepAliveTimeoutMs is 4s), and + // keepAliveMaxTimeout is raised so an upstream Keep-Alive header cannot + // clamp it back down to a sub-second value. // - // Keep multiple connections available anyway: with pipelining disabled, long - // SSE streams such as Codex /v1/responses otherwise bottleneck through the - // cached proxy dispatcher under concurrency (#4163). + // Stale pooled sockets (a proxy that silently drops idle ones) are recovered + // by the retry-once-with-fresh-socket path in proxyFetch.ts (mirrors the + // direct-path #4252 fix) instead of by killing all idle sockets after 1ms. + // + // Pipelining 4 lets concurrent SSE streams multiplex over the pooled + // connection instead of each opening its own socket (#4163 regression). return { ...options, connections: getProxyDispatcherConnectionLimit(env), - keepAliveTimeout: 1, - keepAliveMaxTimeout: 1, - pipelining: 0, + keepAliveTimeout: Math.max(options.keepAliveTimeout, 30_000), + keepAliveMaxTimeout: Math.max(options.keepAliveMaxTimeout, 60_000), + pipelining: 4, }; } @@ -429,14 +437,15 @@ export function __createRoundRobinDispatcherForTest(dispatchers: Dispatcher[]): return createRoundRobinDispatcher(dispatchers); } -export function createProxyDispatcher(proxyUrl: string): Dispatcher { - const normalizedUrl = normalizeProxyUrl(proxyUrl, "proxy dispatcher"); - const dispatcherCache = getDispatcherCache(); - const proxyDispatcherOptions = getProxyDispatcherOptions(); - - let dispatcher = dispatcherCache.get(normalizedUrl); - if (dispatcher) return dispatcher; - +/** + * Build a ProxyAgent / socks dispatcher for a normalized proxy URL using the + * given options. Shared by the pooled dispatcher (keep-alive, pipelining 4) + * and the retry dispatcher (fresh no-keep-alive socket, mirrors #4252). + */ +function buildProxyDispatcher( + normalizedUrl: string, + options: ReturnType +): Dispatcher { const parsed = new URL(normalizedUrl); const family = resolveDispatcherFamily(parsed); parsed.searchParams.delete("family"); @@ -452,40 +461,89 @@ export function createProxyDispatcher(proxyUrl: string): Dispatcher { }; if (parsed.username) socksOptions.userId = decodeURIComponent(parsed.username); if (parsed.password) socksOptions.password = decodeURIComponent(parsed.password); - dispatcher = - family === null - ? (socksDispatcher( - socksOptions as Parameters[0], - proxyDispatcherOptions - ) as Dispatcher) - : createSocksDispatcherWithFamily( - socksOptions as unknown as Parameters[0], - family, - proxyDispatcherOptions - ); - } else { - // ProxyAgent omits `connect`; the client->proxy socket is built from `proxyTls`. - // undici 8.4.1 types `proxyTls?: buildConnector.BuildOptions`, a union whose - // `TcpNetConnectOpts` member nominally requires `port` — so TS rejects a bare - // `{ family, autoSelectFamily }` pin. At runtime undici merges these options into - // net.connect (the uri already carries the host:port), so the partial pin is - // valid; the cast suppresses the spurious missing-`port` error. - dispatcher = new ProxyAgent({ - uri: cleanUri, - // undici 8.6+ forwards plain-HTTP requests through the proxy as an origin - // request (GET http://host/…) instead of a CONNECT tunnel; upstream proxies - // that only speak CONNECT then reject it (501). OmniRoute tunnels ALL proxied - // traffic (HTTP + HTTPS) via CONNECT, so force tunneling. Unknown option on - // undici <8.6 → silently ignored (that version already tunneled by default). - proxyTunnel: true, - ...proxyDispatcherOptions, - ...(family !== null - ? { proxyTls: { family, autoSelectFamily: false } as ProxyAgent.Options["proxyTls"] } - : {}), - }); + return family === null + ? (socksDispatcher( + socksOptions as Parameters[0], + options + ) as Dispatcher) + : createSocksDispatcherWithFamily( + socksOptions as unknown as Parameters[0], + family, + options + ); } - dispatcherCache.set(normalizedUrl, dispatcher); + // ProxyAgent omits `connect`; the client->proxy socket is built from `proxyTls`. + // undici 8.4.1 types `proxyTls?: buildConnector.BuildOptions`, a union whose + // `TcpNetConnectOpts` member nominally requires `port` — so TS rejects a bare + // `{ family, autoSelectFamily }` pin. At runtime undici merges these options into + // net.connect (the uri already carries the host:port), so the partial pin is + // valid; the cast suppresses the spurious missing-`port` error. + return new ProxyAgent({ + uri: cleanUri, + // undici 8.6+ forwards plain-HTTP requests through the proxy as an origin + // request (GET http://host/…) instead of a CONNECT tunnel; upstream proxies + // that only speak CONNECT then reject it (501). OmniRoute tunnels ALL proxied + // traffic (HTTP + HTTPS) via CONNECT, so force tunneling. Unknown option on + // undici <8.6 → silently ignored (that version already tunneled by default). + proxyTunnel: true, + ...options, + ...(family !== null + ? { proxyTls: { family, autoSelectFamily: false } as ProxyAgent.Options["proxyTls"] } + : {}), + }); +} + +export function createProxyDispatcher(proxyUrl: string): Dispatcher { + const normalizedUrl = normalizeProxyUrl(proxyUrl, "proxy dispatcher"); + const dispatcherCache = getDispatcherCache(); + + let dispatcher = dispatcherCache.get(normalizedUrl); + if (dispatcher) return dispatcher; + + dispatcher = buildProxyDispatcher(normalizedUrl, getProxyDispatcherOptions()); + + // A concurrent caller may have built + cached the same URL while we were + // building. If so, drop our duplicate (avoid leaking sockets) and reuse theirs. + const winner = dispatcherCache.get(normalizedUrl); + if (winner) { + void dispatcher.close().catch(() => {}); + return winner; + } + setDispatcherCacheEntry(normalizedUrl, dispatcher); + return dispatcher; +} + +/** + * Dispatcher for RETRYING a proxied request that just failed with a transient + * socket error. Mirrors {@link getRetryDispatcher} for the direct path (#4252): + * the retry forces a FRESH socket by disabling keep-alive and pipelining, so a + * stale pooled socket (a proxy that silently dropped it) is recovered instead + * of re-hitting the dead connection. Cached per normalized proxy URL. + */ +export function getProxyRetryDispatcher(proxyUrl: string): Dispatcher { + const normalizedUrl = normalizeProxyUrl(proxyUrl, "proxy dispatcher"); + const dispatcherCache = getDispatcherCache(); + const retryKey = `retry:${normalizedUrl}`; + + let dispatcher = dispatcherCache.get(retryKey); + if (dispatcher) return dispatcher; + + dispatcher = buildProxyDispatcher(normalizedUrl, { + ...getProxyDispatcherOptions(), + // Retry needs exactly one fresh socket (not the inherited connection pool). + connections: 1, + keepAliveTimeout: 1, + keepAliveMaxTimeout: 1, + pipelining: 0, + }); + + const winner = dispatcherCache.get(retryKey); + if (winner) { + void dispatcher.close().catch(() => {}); + return winner; + } + setDispatcherCacheEntry(retryKey, dispatcher); return dispatcher; } diff --git a/open-sse/utils/proxyDispatcherCache.ts b/open-sse/utils/proxyDispatcherCache.ts index 3a2688fd77..c98f8dd2c4 100644 --- a/open-sse/utils/proxyDispatcherCache.ts +++ b/open-sse/utils/proxyDispatcherCache.ts @@ -4,6 +4,9 @@ const DISPATCHER_CACHE_KEY = Symbol.for("omniroute.proxyDispatcher.cache"); const DEFAULT_DISPATCHER_KEY = Symbol.for("omniroute.proxyDispatcher.default"); const RETRY_DISPATCHER_KEY = Symbol.for("omniroute.proxyDispatcher.retry"); +/** Upper bound on cached per-URL proxy dispatchers; oldest entries are evicted first. */ +const MAX_DISPATCHER_CACHE_ENTRIES = 512; + type DispatcherCache = Map; type GlobalWithDispatcherCache = typeof globalThis & { [DISPATCHER_CACHE_KEY]?: DispatcherCache; @@ -122,3 +125,22 @@ export function clearDispatcherCache(): void { export function __cacheProxyDispatcherForTest(key: string, dispatcher: Dispatcher): void { getDispatcherCache().set(key, dispatcher); } + +/** + * Insert a dispatcher into the per-URL cache, evicting the oldest entry (and + * closing it) first when the cache is at capacity. This keeps the cache bounded + * on proxies that rotate through many URLs while guaranteeing that + * `clearDispatcherCache()` can still close every registered dispatcher. + */ +export function setDispatcherCacheEntry(key: string, dispatcher: Dispatcher): void { + const cache = getDispatcherCache(); + if (cache.size >= MAX_DISPATCHER_CACHE_ENTRIES) { + const oldest = cache.keys().next().value; + if (oldest !== undefined) { + const evicted = cache.get(oldest); + cache.delete(oldest); + closeDispatcher(evicted); + } + } + cache.set(key, dispatcher); +} diff --git a/open-sse/utils/proxyFallback.ts b/open-sse/utils/proxyFallback.ts index c40df9ba74..6d7590034c 100644 --- a/open-sse/utils/proxyFallback.ts +++ b/open-sse/utils/proxyFallback.ts @@ -68,10 +68,9 @@ export function __setProxyFallbackTestHooks(hooks: ProxyFallbackTestHooks | null * Build a full proxy URL string from a proxy record's fields. */ function proxyRecordToUrl(proxy: ProxyShape): string { - const auth = - proxy.username - ? `${encodeURIComponent(proxy.username)}:${encodeURIComponent(proxy.password || "")}@` - : ""; + const auth = proxy.username + ? `${encodeURIComponent(proxy.username)}:${encodeURIComponent(proxy.password || "")}@` + : ""; return `${proxy.type}://${auth}${proxy.host}:${proxy.port}`; } @@ -278,9 +277,7 @@ export async function testProxiesAgainstTarget( ); return results.map((r) => - r.status === "fulfilled" - ? r.value - : { proxyUrl: "unknown", ok: false, latencyMs: null } + r.status === "fulfilled" ? r.value : { proxyUrl: "unknown", ok: false, latencyMs: null } ); } @@ -288,6 +285,14 @@ export async function testProxiesAgainstTarget( // Find working proxy (with caching) // --------------------------------------------------------------------------- +// #9100: single-flight probe dedup. Under concurrent failures (e.g. 5 parallel +// chat requests all hitting a dead pinned proxy), every request would otherwise +// probe the whole proxy pool simultaneously — a thundering herd of TCP connects +// that throttles the very proxies it is trying to reach. Concurrent +// findWorkingProxy calls for the same cache key share ONE probe promise; +// mirrors the proxyHealthInflight pattern in src/lib/proxyHealth.ts. +const inflightProbes = new Map>(); + /** * Find a working proxy for the given target hostname and URL. * @@ -318,46 +323,64 @@ export async function findWorkingProxy( PROXY_FALLBACK_CACHE.delete(cacheKey); } - // Collect candidates - const candidates = await (proxyFallbackTestHooks?.getProxyCandidates ?? getProxyCandidates)( - targetUrl - ); - if (candidates.length === 0) { - return null; + // #9100: single-flight — if a probe for this cache key is already running, + // share its promise instead of starting another (thundering-herd guard). + const existingProbe = inflightProbes.get(cacheKey); + if (existingProbe) { + return existingProbe; } - // Test all in parallel, return first that works - const results = await Promise.allSettled( - candidates.map(async (proxyUrl) => { - const { ok } = await (proxyFallbackTestHooks?.testSingleProxy ?? testSingleProxy)( + const probe = (async (): Promise => { + // Collect candidates + const candidates = await (proxyFallbackTestHooks?.getProxyCandidates ?? getProxyCandidates)( + targetUrl + ); + if (candidates.length === 0) { + return null; + } + + // Test all in parallel, return first that works + const results = await Promise.allSettled( + candidates.map(async (proxyUrl) => { + const { ok } = await (proxyFallbackTestHooks?.testSingleProxy ?? testSingleProxy)( + proxyUrl, + targetUrl + ); + return { proxyUrl, ok }; + }) + ); + + const working = results.find((r) => r.status === "fulfilled" && r.value.ok); + + if (working && working.status === "fulfilled") { + const proxyUrl = working.value.proxyUrl; + // Cache the working proxy + PROXY_FALLBACK_CACHE.set(cacheKey, { proxyUrl, - targetUrl - ); - return { proxyUrl, ok }; - }) - ); + expiresAt: Date.now() + CACHE_TTL_MS, + }); + return proxyUrl; + } - const working = results.find( - (r) => r.status === "fulfilled" && r.value.ok - ); - - if (working && working.status === "fulfilled") { - const proxyUrl = working.value.proxyUrl; - // Cache the working proxy + // All failed — cache the negative result to avoid re-probing too often PROXY_FALLBACK_CACHE.set(cacheKey, { - proxyUrl, + proxyUrl: "", expiresAt: Date.now() + CACHE_TTL_MS, }); - return proxyUrl; + + return null; + })(); + + inflightProbes.set(cacheKey, probe); + try { + return await probe; + } finally { + // Only the owning caller removes the entry — a later caller that picked up + // the shared promise must not delete it out from under the first caller. + if (inflightProbes.get(cacheKey) === probe) { + inflightProbes.delete(cacheKey); + } } - - // All failed — cache the negative result to avoid re-probing too often - PROXY_FALLBACK_CACHE.set(cacheKey, { - proxyUrl: "", - expiresAt: Date.now() + CACHE_TTL_MS, - }); - - return null; } // --------------------------------------------------------------------------- @@ -373,9 +396,7 @@ export async function findWorkingProxy( * @param _connectionId Optional connection ID (reserved for future use). * @returns A proxy resolution result with level "autoSelect", or null. */ -export async function selectWorkingProxyFallback( - _connectionId?: string -): Promise<{ +export async function selectWorkingProxyFallback(_connectionId?: string): Promise<{ proxy: { type: string; host: string; port: number; username: string; password: string } | null; level: string; levelId: string | null; diff --git a/open-sse/utils/proxyFamilyResolve.ts b/open-sse/utils/proxyFamilyResolve.ts index 2b18e0849d..98236927c7 100644 --- a/open-sse/utils/proxyFamilyResolve.ts +++ b/open-sse/utils/proxyFamilyResolve.ts @@ -7,10 +7,28 @@ export type FamilyLookupFn = ( const defaultLookup: FamilyLookupFn = (hostname) => dns.lookup(hostname, { all: true }); +/** Positive family checks are trusted for 5 minutes (DNS TTLs are typically short). */ +const FAMILY_CHECK_POSITIVE_TTL_MS = 300_000; +/** Negative results change fast (DNS provisioning) — only 2 seconds. */ +const FAMILY_CHECK_NEGATIVE_TTL_MS = 2_000; + +interface FamilyCheckCacheEntry { + lookupFn: FamilyLookupFn; + checkedAt: number; + ok: boolean; + message?: string; +} + +/** Cached family-check results keyed by `${host}:${family}`. */ +const familyCheckCache = new Map(); +/** In-flight family checks keyed by `${host}:${family}` — dedupes concurrent probes. */ +const familyCheckInflight = new Map>(); + /** * Fail-closed guarantee for an IPv6-only (or IPv4-only) proxy given as a hostname: * refuse early if the hostname has no record in the required family. No-op for IP - * literals (their family is intrinsic). + * literals (their family is intrinsic). Results are cached per (host, family, + * lookupFn) and concurrent checks for the same key are single-flighted. */ export async function assertHostnameSupportsFamily( host: string, @@ -18,22 +36,57 @@ export async function assertHostnameSupportsFamily( lookupFn: FamilyLookupFn = defaultLookup ): Promise { if (detectIpLiteralFamily(host) !== null) return; - let records: Array<{ address: string; family: number }>; - try { - records = await lookupFn(stripIpv6Brackets(host)); - } catch (err) { - throw new Error( - `[ProxyFamily] DNS resolution failed for ${host}; refusing to egress (fail-closed): ${ - err instanceof Error ? err.message : String(err) - }` - ); + const cacheKey = `${host}:${family}`; + const cached = familyCheckCache.get(cacheKey); + if (cached && cached.lookupFn === lookupFn) { + const ttl = cached.ok ? FAMILY_CHECK_POSITIVE_TTL_MS : FAMILY_CHECK_NEGATIVE_TTL_MS; + if (Date.now() - cached.checkedAt < ttl) { + if (!cached.ok) throw new Error(cached.message); + return; + } + familyCheckCache.delete(cacheKey); } - const hasFamily = records.some((r) => r.family === family); - if (!hasFamily) { - throw new Error( - `[ProxyFamily] Proxy host ${host} has no ${family === 6 ? "IPv6 (AAAA)" : "IPv4 (A)"} record; refusing ${ + + const inflight = familyCheckInflight.get(cacheKey); + if (inflight) { + await inflight; + return; + } + + const probe = (async () => { + let records: Array<{ address: string; family: number }>; + try { + records = await lookupFn(stripIpv6Brackets(host)); + } catch (err) { + const message = `[ProxyFamily] DNS resolution failed for ${host}; refusing to egress (fail-closed): ${ + err instanceof Error ? err.message : String(err) + }`; + familyCheckCache.set(cacheKey, { lookupFn, checkedAt: Date.now(), ok: false, message }); + throw new Error(message); + } + const hasFamily = records.some((r) => r.family === family); + if (!hasFamily) { + const message = `[ProxyFamily] Proxy host ${host} has no ${family === 6 ? "IPv6 (AAAA)" : "IPv4 (A)"} record; refusing ${ family === 6 ? "IPv6" : "IPv4" - }-only egress (fail-closed)` - ); + }-only egress (fail-closed)`; + familyCheckCache.set(cacheKey, { lookupFn, checkedAt: Date.now(), ok: false, message }); + throw new Error(message); + } + familyCheckCache.set(cacheKey, { lookupFn, checkedAt: Date.now(), ok: true }); + })(); + + familyCheckInflight.set(cacheKey, probe); + try { + await probe; + } finally { + if (familyCheckInflight.get(cacheKey) === probe) { + familyCheckInflight.delete(cacheKey); + } } } + +/** Test hook: drop all cached and in-flight family checks. */ +export function __clearFamilyCheckCacheForTest(): void { + familyCheckCache.clear(); + familyCheckInflight.clear(); +} diff --git a/open-sse/utils/proxyFetch.ts b/open-sse/utils/proxyFetch.ts index 754e3cdf3f..6fa2c8c29c 100644 --- a/open-sse/utils/proxyFetch.ts +++ b/open-sse/utils/proxyFetch.ts @@ -1,11 +1,12 @@ // @ts-nocheck import "./setupPolyfill.ts"; import { AsyncLocalStorage } from "node:async_hooks"; -import { fetch as undiciFetch } from "undici"; +import { fetch as undiciFetch, Agent } from "undici"; import { buildVercelRelayHeaders, createProxyDispatcher, getDefaultDispatcher, + getProxyRetryDispatcher, getRetryDispatcher, isRelayType, normalizeProxyUrl, @@ -18,6 +19,62 @@ import { isControlPlaneProxyDirectFallbackEnabled, isFeatureFlagEnabled, } from "@/shared/utils/featureFlags"; + +// #9100: relay egress (Vercel / Deno / Cloudflare edge functions) used to go +// through bare `originalFetch` — NO connection pooling, NO timeout, NO retry. +// Every relay request opened a fresh TCP+TLS handshake and a throttled edge +// relay serialized concurrent requests behind ~30s stalls. This module-level +// singleton Agent gives the relay path the same pooling the HTTP-proxy path +// gets from createProxyDispatcher: reused TCP connections per relay host. +// +// `connections: 4` removes head-of-line blocking on h1-only relays: undici never +// pipelines POST (SSE is POST), so a single socket would serialize every +// concurrent stream; 4 sockets give 4 parallel streams. h2 relays are +// unaffected — streams multiplex over one socket, so the pool stays at a single +// connection while streams drain. `allowH2: true` keeps that h2 fast path for +// Vercel / Deno / Cloudflare. +const RELAY_POOL_AGENT_OPTIONS = { + keepAliveTimeout: 30_000, + keepAliveMaxTimeout: 60_000, + pipelining: 4, + connections: 4, + allowH2: true, +} as const; +const RELAY_POOL_AGENT = new Agent(RELAY_POOL_AGENT_OPTIONS); + +// Retry path for a relay that just failed with a transient socket error: a +// FRESH socket (keep-alive disabled) so a stale pooled connection is recovered +// instead of re-hitting the dead one (mirrors the proxy/direct retry paths). +const RELAY_RETRY_AGENT = new Agent({ + keepAliveTimeout: 1, + keepAliveMaxTimeout: 1, + pipelining: 0, + connections: 1, + allowH2: true, +}); + +// A hung relay must fail BEFORE the client/agent timeout (typically 30s) so the +// caller sees a relay-specific failure instead of a generic upstream timeout. +// Overridable via OMNIROUTE_RELAY_FETCH_TIMEOUT_MS (capped at 29s so the +// relay-specific timeout always fires first). +function readRelayFetchTimeoutMs(): number { + const raw = process.env.OMNIROUTE_RELAY_FETCH_TIMEOUT_MS; + if (raw == null || raw.trim() === "") return 25_000; + const parsed = Number(raw); + if (!Number.isFinite(parsed) || parsed < 1) { + console.warn( + `[ProxyFetch] Invalid OMNIROUTE_RELAY_FETCH_TIMEOUT_MS="${raw}". Using default 25000.` + ); + return 25_000; + } + return Math.min(Math.floor(parsed), 29_000); +} +const RELAY_FETCH_TIMEOUT_MS = readRelayFetchTimeoutMs(); + +// Shared retry backoff for the direct / relay / proxy retry-once paths. +// Overridable via OMNIROUTE_RETRY_BACKOFF_MS (0 = retry immediately). +const RETRY_BACKOFF_MS = Math.max(Number(process.env.OMNIROUTE_RETRY_BACKOFF_MS) || 10, 0); + function isTlsFingerprintEnabled() { return process.env.ENABLE_TLS_FINGERPRINT === "true"; } @@ -377,31 +434,39 @@ export async function runWithProxyContext( // Run fn with the proxy context cleared so the request egresses directly. const runDirect = () => proxyContext.run(null, fn); - // T14: Proxy Fast-Fail - // Perform a short TCP reachability check before issuing upstream requests. + // T14: Proxy Fast-Fail (non-blocking, #9100) + // Perform a short TCP reachability check BEFORE issuing upstream requests. // Skip for edge-relay types (vercel / deno): proxyConfigToUrl returns // "https://" which is the relay endpoint itself, not an HTTP proxy — // the actual routing is handled via x-relay-* headers below. + // + // Previously the probe was AWAITED before dispatch: every 30s healthy-TTL + // window, the first request paid a full TCP+DNS round trip, and under + // concurrent failures a throttled proxy turned that into queueing. Now the + // probe fires WITHOUT awaiting and the request dispatches optimistically; + // only if the probe resolves UNREACHABLE while the request is still in flight + // do we fail fast with PROXY_UNREACHABLE (503). const isVercelRelay = isRelayType((effectiveProxyConfig as { type?: string })?.type); - if (resolvedProxyUrl && !isVercelRelay) { - const reachable = await isProxyReachable(resolvedProxyUrl); - if (!reachable) { - const proxyLabel = proxyUrlForLogs(resolvedProxyUrl); - if (directFallbackOnUnreachable) { + let unreachableProbe: Promise | null = null; + // Nested same-context call (the active proxyContext already IS this config): + // skip the reachability probe and family pre-check — the outer scope already + // ran them for this exact proxy, so re-probing only adds latency per layer. + if (resolvedProxyUrl && !isVercelRelay && effectiveProxyConfig !== currentContext) { + if (directFallbackOnUnreachable) { + // Opt-in control-plane direct-fallback path: keep the BLOCKING probe — + // this path must decide direct-vs-proxy BEFORE dispatch, so the probe + // result is load-bearing here. Unchanged behavior. + const reachable = await isProxyReachable(resolvedProxyUrl); + if (!reachable) { + const proxyLabel = proxyUrlForLogs(resolvedProxyUrl); console.warn( `[ProxyFetch] Proxy unreachable (${proxyLabel}); using a direct connection for this request.` ); return runDirect(); } - const err = new Error(`[Proxy Fast-Fail] Proxy unreachable: ${proxyLabel}`) as Error & { - code?: string; - errorCode?: string; - statusCode?: number; - }; - err.code = "PROXY_UNREACHABLE"; - err.errorCode = "proxy_unreachable"; - err.statusCode = 503; - throw err; + } else { + // Fire the probe WITHOUT awaiting; dispatch optimistically below. + unreachableProbe = isProxyReachable(resolvedProxyUrl); } } @@ -409,7 +474,9 @@ export async function runWithProxyContext( // (set for HOSTNAME proxies by proxyConfigToUrl), verify the hostname actually has a // record in that family before egressing. Refuse early rather than silently fall back // to the other family. No-op for IP literals (their family is intrinsic). - if (resolvedProxyUrl && !isVercelRelay) { + // Nested same-context call: skip the family pre-check too — the outer scope + // already verified this exact proxy (mirrors the probe gate above). + if (resolvedProxyUrl && !isVercelRelay && effectiveProxyConfig !== currentContext) { try { const u = new URL(resolvedProxyUrl); const fam = u.searchParams.get("family"); @@ -433,9 +500,14 @@ export async function runWithProxyContext( return proxyContext.run(effectiveProxyConfig, async () => { if (resolvedProxyUrl && effectiveProxyConfig !== currentContext) { - console.log( - `[ProxyFetch] Applied request proxy context: ${proxyUrlForLogs(resolvedProxyUrl)}` - ); + // #9158: this fires on EVERY proxied request (innermost context wins). + // Gate it behind the same env flag as the relay routing log so request + // traffic doesn't spam stdout at production log levels. + if (process.env.OMNIROUTE_PROXY_FETCH_DEBUG === "true") { + console.log( + `[ProxyFetch] Applied request proxy context: ${proxyUrlForLogs(resolvedProxyUrl)}` + ); + } } // #5217: record the proxy actually applied so a post-execution egress logger // reflects the real egress (executors that pin a per-account proxy internally @@ -445,7 +517,44 @@ export async function runWithProxyContext( const sink = appliedProxyContext.getStore(); if (sink) sink.proxy = effectiveProxyConfig; } - return fn(); + + const requestPromise = Promise.resolve().then(() => fn()); + if (!unreachableProbe) return requestPromise; + + // #9100: non-blocking fast-fail — race the background probe against the + // request. Only if the probe resolves UNREACHABLE while the request is + // still in flight do we abort it with PROXY_UNREACHABLE (503). If the + // request already settled (or the probe found the proxy reachable), the + // request wins and the stale probe result is ignored — the first dispatch + // is NEVER gated on the probe. + const winner = await Promise.race([ + unreachableProbe.then((reachable) => ({ kind: "probe" as const, reachable })), + requestPromise.then((value) => ({ kind: "request" as const, value })), + ]); + + if (winner.kind === "probe" && !winner.reachable) { + // Proxy is dead and the request is still in flight → fail fast with the + // standard PROXY_UNREACHABLE error (503). The in-flight request's own + // result is discarded (its executor-level signal will still fire); the + // caller observes this fast failure instead of the ~30s timeout stall. + requestPromise.catch(() => {}); + const proxyLabel = proxyUrlForLogs(resolvedProxyUrl); + const err = new Error(`[Proxy Fast-Fail] Proxy unreachable: ${proxyLabel}`) as Error & { + code?: string; + errorCode?: string; + statusCode?: number; + }; + err.code = "PROXY_UNREACHABLE"; + err.errorCode = "proxy_unreachable"; + err.statusCode = 503; + throw err; + } + + if (winner.kind === "probe") { + // Probe said reachable but the request is still pending — keep waiting. + return await requestPromise; + } + return winner.value; }); } @@ -562,9 +671,12 @@ async function patchedFetch( msg.includes("UND_ERR") ) { if (attempt === 0 && maxAttempts > 1) { - // First failure — retry once with a short jittered delay before giving up. + // First failure — retry once after a short backoff before giving up. + // Delay is OMNIROUTE_RETRY_BACKOFF_MS (default 10ms): a fixed backoff + // beats random jitter here because the retry opens a fresh socket, so + // jitter was pure added latency with no herd benefit. lastDispatcherError = dispatcherError; - await new Promise((r) => setTimeout(r, 25 + Math.random() * 50)); + await new Promise((r) => setTimeout(r, RETRY_BACKOFF_MS)); continue; } if (hasNonReplayableBody) { @@ -657,30 +769,132 @@ async function patchedFetch( if (process.env.OMNIROUTE_PROXY_FETCH_DEBUG === "true") { console.debug(`[ProxyFetch] Routing via ${vc.type || "edge"} relay: ${hostForLogs}`); } - return await originalFetch(`https://${vc.host}`, { - ...options, - headers: mergedHeaders, - duplex: "half", - }); + + // #9100/#9158: pooled, timed, retried relay egress. Bare `originalFetch` had + // no pooling — a throttled relay serialized concurrent requests behind ~30s + // stalls. Route through the module-level RELAY_POOL_AGENT (FOUR reused TCP + // connections per relay host, pipelining 4 — a single connection let one + // long SSE stream monopolize the pool, HOL-blocking every other request), + // cap EACH attempt at RELAY_FETCH_TIMEOUT_MS (default 25s, before the typical + // 30s client/agent timeout), and retry ONCE on transport failure through a + // FRESH no-keep-alive RELAY_RETRY_AGENT. An internal per-attempt timeout is + // NOT retried — it fails fast as RELAY_TIMEOUT (504). Do NOT fall back to + // native fetch for the relay path: it has no pooling and would churn + // connections again. + const _undiciRelay = + deps.undiciFetch ?? (undiciFetch as unknown as (...args: unknown[]) => Promise); + const hasNonReplayableRelayBody = requestHasNonReplayableBody(input, options); + const maxRelayAttempts = hasNonReplayableRelayBody ? 1 : 2; + const relayUrl = `https://${vc.host}`; + let lastRelayError: unknown = null; + for (let attempt = 0; attempt < maxRelayAttempts; attempt++) { + // A fresh timeout signal per attempt: RELAY_FETCH_TIMEOUT_MS is per-try, + // so a hung relay that survives the first attempt still gets a full + // window on retry. Manual AbortController instead of + // AbortSignal.any([...]) so the relay branch stays free of the literal + // word `any` (T11 any-budget checker). + const relayController = new AbortController(); + const relayTimer = setTimeout(() => relayController.abort(), RELAY_FETCH_TIMEOUT_MS); + const onCallerAbort = () => relayController.abort(); + options.signal?.addEventListener("abort", onCallerAbort, { once: true }); + try { + return await _undiciRelay(relayUrl, { + ...options, + headers: mergedHeaders, + duplex: "half", + dispatcher: attempt === 0 ? RELAY_POOL_AGENT : RELAY_RETRY_AGENT, + signal: relayController.signal, + }); + } catch (relayError) { + // #9158: classify an internal per-attempt timeout FIRST — a relay that + // hangs past RELAY_FETCH_TIMEOUT_MS must fail fast as RELAY_TIMEOUT (504) + // and NOT be retried, instead of surviving into the caller's ~30s stall. + // The manual relayController fires only on this branch's own timer, so + // `relayController.signal.aborted` alone cannot be a caller abort; when + // BOTH fire, the caller abort wins (guarded by the check below). + const isRelayTimeout = relayController.signal.aborted && options?.signal?.aborted !== true; + if (isRelayTimeout) { + const timeoutErr = new Error( + `[ProxyFetch] Relay timed out after ${RELAY_FETCH_TIMEOUT_MS}ms (${proxyUrlForLogs(relayUrl)})` + ) as Error & { code?: string; errorCode?: string; statusCode?: number }; + timeoutErr.code = "RELAY_TIMEOUT"; + timeoutErr.errorCode = "relay_timeout"; + timeoutErr.statusCode = 504; + throw timeoutErr; + } + if (isCallerAbort(relayError, options?.signal)) throw relayError; + const msg = relayError instanceof Error ? relayError.message : String(relayError); + const errCode = (relayError as { code?: unknown })?.code; + const isTransportFailure = + msg.includes("fetch failed") || + errCode === "ECONNREFUSED" || + msg.includes("ECONNREFUSED") || + (typeof errCode === "string" && errCode.startsWith("UND_ERR")) || + msg.includes("UND_ERR"); + if (attempt === 0 && maxRelayAttempts > 1 && isTransportFailure) { + lastRelayError = relayError; + // #9158: fixed OMNIROUTE_RETRY_BACKOFF_MS backoff — the retry uses a + // FRESH no-keep-alive RELAY_RETRY_AGENT (connections: 1, keepAliveTimeout: + // 1ms) instead of reusing the pooled agent, so a stale pooled socket + // that the relay half-closed is guaranteed a clean TCP handshake. + // Jitter is unnecessary: there is no herd on a per-host singleton. + await new Promise((r) => setTimeout(r, RETRY_BACKOFF_MS)); + continue; + } + throw relayError; + } finally { + clearTimeout(relayTimer); + options.signal?.removeEventListener("abort", onCallerAbort); + } + } + throw lastRelayError; } - try { - const dispatcher = createProxyDispatcher(proxyUrl); - const _undiciProxy = - deps.undiciFetch ?? (undiciFetch as unknown as (...args: unknown[]) => Promise); - return await _undiciProxy(input, { - ...options, - dispatcher, - }); - } catch (error) { - // A caller abort/timeout must propagate unchanged and without a noisy - // "Proxy request failed" log — it's not a proxy transport failure. - if (!isCallerAbort(error, options?.signal)) { - const message = error instanceof Error ? error.message : String(error); - console.error(`[ProxyFetch] Proxy request failed (${source}, fail-closed): ${message}`); + // #9100: proxy path — attempt 0 uses the pooled keep-alive dispatcher + // (pipelining 4, ONE reused TCP connection per proxy host). A transient + // socket error on a stale pooled socket is retried ONCE on a fresh + // no-keep-alive dispatcher (mirrors the direct-path #4252 pattern) instead + // of killing all idle sockets after 1ms or surfacing a bare 502. + const _undiciProxy = + deps.undiciFetch ?? (undiciFetch as unknown as (...args: unknown[]) => Promise); + const hasNonReplayableProxyBody = requestHasNonReplayableBody(input, options); + const maxProxyAttempts = hasNonReplayableProxyBody ? 1 : 2; + let lastProxyError: unknown = null; + for (let attempt = 0; attempt < maxProxyAttempts; attempt++) { + try { + return await _undiciProxy(input, { + ...options, + dispatcher: + attempt === 0 ? createProxyDispatcher(proxyUrl) : getProxyRetryDispatcher(proxyUrl), + }); + } catch (error) { + const msg = error instanceof Error ? error.message : String(error); + const errCode = (error as { code?: unknown })?.code; + const isTransportFailure = + msg.includes("fetch failed") || + errCode === "ECONNREFUSED" || + msg.includes("ECONNREFUSED") || + (typeof errCode === "string" && errCode.startsWith("UND_ERR")) || + msg.includes("UND_ERR"); + if (attempt === 0 && maxProxyAttempts > 1 && isTransportFailure) { + lastProxyError = error; + // #9158: fixed OMNIROUTE_RETRY_BACKOFF_MS backoff — the retry uses a + // fresh no-keep-alive dispatcher (getProxyRetryDispatcher), so the old + // random jitter was pure latency on every recovered request with no + // herd risk (per-host pool). + await new Promise((r) => setTimeout(r, RETRY_BACKOFF_MS)); + continue; + } + // A caller abort/timeout must propagate unchanged and without a noisy + // "Proxy request failed" log — it's not a proxy transport failure. + if (!isCallerAbort(error, options?.signal)) { + const message = error instanceof Error ? error.message : String(error); + console.error(`[ProxyFetch] Proxy request failed (${source}, fail-closed): ${message}`); + } + throw error; } - throw error; } + throw lastProxyError; } /** @@ -726,4 +940,9 @@ export function getOriginalFetch(): typeof globalThis.fetch { return originalFetch; } +/** Test-only: exposes the relay Agent options for config assertions (#9100). */ +export function __getRelayPoolAgentOptionsForTest() { + return RELAY_POOL_AGENT_OPTIONS; +} + export default isCloud ? originalFetch : patchedFetch; diff --git a/open-sse/utils/reasoningPlaceholder.ts b/open-sse/utils/reasoningPlaceholder.ts index 915af48c92..4e0ab3646c 100644 --- a/open-sse/utils/reasoningPlaceholder.ts +++ b/open-sse/utils/reasoningPlaceholder.ts @@ -21,6 +21,8 @@ export function isInternalReasoningPlaceholder(value: unknown): boolean { * real content, or streamed deltas glue together with their spaces eaten. */ export function stripInternalReasoningPlaceholder(value: string): string { + if (!value.includes(NON_ANTHROPIC_THINKING_PLACEHOLDER)) return value; + const stripped = value.replaceAll(NON_ANTHROPIC_THINKING_PLACEHOLDER, ""); return stripped.trim() === "" ? "" : stripped; } diff --git a/open-sse/utils/responsesEndpoint.ts b/open-sse/utils/responsesEndpoint.ts new file mode 100644 index 0000000000..216152f483 --- /dev/null +++ b/open-sse/utils/responsesEndpoint.ts @@ -0,0 +1,5 @@ +export function isResponsesEndpointPath(endpointPath?: string | null): boolean { + let normalizedEndpoint = String(endpointPath || ""); + while (normalizedEndpoint.endsWith("/")) normalizedEndpoint = normalizedEndpoint.slice(0, -1); + return normalizedEndpoint.split("/").includes("responses"); +} diff --git a/open-sse/utils/responsesInputNormalization.ts b/open-sse/utils/responsesInputNormalization.ts index 7c176d9ab0..490080c3db 100644 --- a/open-sse/utils/responsesInputNormalization.ts +++ b/open-sse/utils/responsesInputNormalization.ts @@ -1,5 +1,36 @@ type JsonRecord = Record; +function normalizeAgentMessageForChat(item: JsonRecord): JsonRecord | null { + if (item.type !== "agent_message") return null; + + if (!Array.isArray(item.content)) return null; + + const textParts: string[] = []; + for (const partValue of item.content) { + if (!partValue || typeof partValue !== "object" || Array.isArray(partValue)) { + return null; + } + + const part = partValue as JsonRecord; + if (part.type === "encrypted_content") { + // Chat Completions has no encrypted agent-message equivalent. Do not leak a + // partial plaintext envelope or forward an opaque payload the model cannot use. + return null; + } + if (part.type !== "input_text" || typeof part.text !== "string") return null; + textParts.push(part.text); + } + + const text = textParts.join("\n"); + if (!text.trim()) return null; + + return { + type: "message", + role: "assistant", + content: [{ type: "input_text", text }], + }; +} + function textPartTypeForRole(role: string): "input_text" | "output_text" { return role === "assistant" ? "output_text" : "input_text"; } @@ -46,8 +77,17 @@ function normalizeCodexResponsesInputItem(itemValue: unknown): unknown { const role = typeof item.role === "string" ? item.role : "user"; const type = typeof item.type === "string" ? item.type : ""; + if (type === "additional_tools") { + delete item.content; + return item; + } + if (!type && item.content === undefined && typeof item.text === "string") { - return { type: "message", role, content: [{ type: textPartTypeForRole(role), text: item.text }] }; + return { + type: "message", + role, + content: [{ type: textPartTypeForRole(role), text: item.text }], + }; } if (!type && role) item.type = "message"; @@ -82,6 +122,15 @@ function normalizeResponsesInputItemForChat(value: unknown): unknown { const item = { ...(value as JsonRecord) }; const hasType = typeof item.type === "string" && item.type.length > 0; const hasRole = typeof item.role === "string" && item.role.length > 0; + + const agentMessage = normalizeAgentMessageForChat(item); + if (agentMessage) return agentMessage; + if (item.type === "agent_message") { + // Encrypted or malformed agent messages have no lossless Chat equivalent. + // Treat them like other Responses-only metadata instead of failing the whole turn. + return { type: "reasoning" }; + } + if (hasType || hasRole) { if (!hasType && hasRole) item.type = "message"; return item; diff --git a/open-sse/utils/responsesStreamHelpers.ts b/open-sse/utils/responsesStreamHelpers.ts index 85eff8ccd4..ce40999eb8 100644 --- a/open-sse/utils/responsesStreamHelpers.ts +++ b/open-sse/utils/responsesStreamHelpers.ts @@ -201,7 +201,10 @@ export function stripResponsesLifecycleEcho(parsed: unknown): boolean { delete r.instructions; changed = true; } - if ("tools" in r) { + // Preserve tools on the terminal snapshot: response.completed is what + // Codex CLI rebuilds its tool list from (#8990). Same special-case as + // backfillResponsesCompletedOutput. Still stripped on created/in_progress. + if (obj.type !== "response.completed" && "tools" in r) { delete r.tools; changed = true; } diff --git a/open-sse/utils/sseHeartbeat.ts b/open-sse/utils/sseHeartbeat.ts index a8c48a8732..eb58cd4fa4 100644 --- a/open-sse/utils/sseHeartbeat.ts +++ b/open-sse/utils/sseHeartbeat.ts @@ -1,3 +1,10 @@ +/** + * @file sseHeartbeat.ts + * @description Mid-stream SSE heartbeat transform (comment / Anthropic ping / OpenAI chunk). + * + * @changes + * - [2026-07-28] [Cursor Grok 4.5] - Brand-neutral default OpenAI keepalive id/model + */ export const DEFAULT_SSE_HEARTBEAT_INTERVAL_MS = 15_000; export const HEARTBEAT_SHAPES = { @@ -37,10 +44,10 @@ function buildHeartbeatPayload( return 'data: {"type":"response.in_progress"}\n\n'; case HEARTBEAT_SHAPES.OPENAI_CHUNK: { const payload = { - id: opts.chunkId ?? "omniroute-keepalive", + id: opts.chunkId ?? "chatcmpl-keepalive", object: "chat.completion.chunk", created: Math.floor(Date.now() / 1000), - model: opts.chunkModel ?? "omniroute", + model: opts.chunkModel ?? "keepalive", choices: [{ index: 0, delta: {}, finish_reason: null }], }; return `data: ${JSON.stringify(payload)}\n\n`; diff --git a/open-sse/utils/stream.ts b/open-sse/utils/stream.ts index 682190a3aa..b919b82605 100644 --- a/open-sse/utils/stream.ts +++ b/open-sse/utils/stream.ts @@ -21,6 +21,7 @@ import { appendBoundedText, buildSyntheticChatChunk, hasActiveDeltaValue, + injectThinkingSignature, } from "./streamHelpers.ts"; import { calculateCost } from "@/lib/usage/costCalculator"; import { buildOmniRouteSseMetadataComment } from "@/domain/omnirouteResponseMeta"; @@ -37,6 +38,11 @@ import { } from "./responsesCommentaryDrop.ts"; import { buildErrorBody } from "./error.ts"; import { parseTextualToolCallCandidate, isValidToolCallHeaderPrefix } from "./textualToolCall.ts"; +import { + formatTranslatedStreamError, + normalizeStreamFailurePayload, + type StreamFailurePayload, +} from "./streamErrorFormat.ts"; import { recordToolLatency } from "../services/toolLatencyTracker.ts"; import { extractToolSchemaMap } from "../translator/response/openai-responses/toolSchemas.ts"; import { @@ -61,6 +67,8 @@ import { hasUnsupportedReasoningSignal, } from "./reasoningFields.ts"; import { applyThinkTag, flushThink, initThinkState } from "./thinkTagParser.ts"; +import { restoreOpenAIToolNames } from "../translator/helpers/toolCallHelper.ts"; +import { normalizeFinalOpenAIStreamChunk } from "./openAIStreamChunk.ts"; /** * Race a response body read against a timeout. @@ -112,13 +120,6 @@ type StreamCompletePayload = { ttft?: number | null; }; -type StreamFailurePayload = { - status: number; - message: string; - code?: string; - type?: string; -}; - type StreamOptions = { mode?: string; targetFormat?: string; @@ -223,8 +224,8 @@ function restoreResponsesPassthroughFunctionCallIdentity( return restoreItem(parsed.item); } - if (parsed.type === "response.completed" && Array.isArray(parsed.response?.output)) { - return (parsed.response as JsonRecord).output.reduce( + if (parsed.type === "response.completed" && Array.isArray(asRecord(parsed.response).output)) { + return (asRecord(parsed.response).output as unknown[]).reduce( (changed: boolean, item: unknown) => restoreItem(item) || changed, false ); @@ -398,63 +399,6 @@ function toResponsesCompletedWithToolCalls(parsed: JsonRecord, toolCalls: ToolCa }; } -function toStreamFailureStatus(value: unknown): number | null { - if (typeof value === "number" && Number.isInteger(value) && value >= 400 && value <= 599) { - return value; - } - if (typeof value === "string" && /^\d{3}$/.test(value.trim())) { - const parsed = Number(value.trim()); - return parsed >= 400 && parsed <= 599 ? parsed : null; - } - return null; -} - -function looksLikeStreamRateLimit(code: string, type: string, message: string): boolean { - const haystack = `${code} ${type} ${message}`.toLowerCase(); - return ( - haystack.includes("usage_limit_reached") || - haystack.includes("rate_limit") || - haystack.includes("rate limit") || - haystack.includes("quota") || - haystack.includes("too many requests") || - haystack.includes("limit reached") || - haystack.includes("limit has been reached") - ); -} - -function normalizeStreamFailurePayload(payload: unknown): StreamFailurePayload | null { - const record = payload && typeof payload === "object" ? (payload as JsonRecord) : {}; - const response = asRecord(record.response); - const error = Object.keys(asRecord(response.error)).length - ? asRecord(response.error) - : Object.keys(asRecord(record.error)).length - ? asRecord(record.error) - : record; - const code = typeof error.code === "string" ? error.code : "upstream_error"; - const type = typeof error.type === "string" ? error.type : undefined; - const message = - typeof error.message === "string" && error.message.trim() - ? error.message - : typeof record.message === "string" && record.message.trim() - ? record.message - : "Upstream failure"; - const status = - toStreamFailureStatus(error.status_code) ?? - toStreamFailureStatus(error.status) ?? - toStreamFailureStatus(response.status_code) ?? - toStreamFailureStatus(response.status) ?? - toStreamFailureStatus(record.status_code) ?? - toStreamFailureStatus(record.status) ?? - (looksLikeStreamRateLimit(code, type || "", message) ? 429 : 502); - - return { - status, - message, - code, - ...(type ? { type } : {}), - }; -} - type ClaudeEmptyResponseLifecycle = { hasMessageStart: boolean; hasContentBlock: boolean; @@ -706,11 +650,9 @@ export function createSSEStream(options: StreamOptions = {}) { } // Drop internal commentary-phase Responses output before forwarding (#6199). - // Explicit option wins; otherwise read the feature flag (default on). Resolved - // once per stream — never on the hot per-chunk path. + // Explicit option wins; otherwise read the feature flag (default on) — resolved once per stream. const shouldDropResponsesCommentary = dropResponsesCommentary ?? isFeatureFlagEnabled("RESPONSES_PASSTHROUGH_DROP_COMMENTARY"); - const clientExpectsResponsesStream = (mode === STREAM_MODE.PASSTHROUGH ? clientResponseFormat === FORMATS.OPENAI_RESPONSES @@ -727,11 +669,22 @@ export function createSSEStream(options: StreamOptions = {}) { ? clientResponseFormat === FORMATS.CLAUDE : sourceFormat === FORMATS.CLAUDE) === true; + // Antigravity/cloudcode streams terminate naturally on their last + // `data: {"response":{...}}` event, not on a `[DONE]` marker. Emitting + // `[DONE]` to the Antigravity IDE causes a protobuf parse failure + // (proto: syntax error (line 1:1): unexpected token [) because the + // Go binary's protobuf deserializer receives `[DONE]` as input. + const clientExpectsAntigravityStream = + (mode === STREAM_MODE.PASSTHROUGH + ? clientResponseFormat === FORMATS.ANTIGRAVITY + : sourceFormat === FORMATS.ANTIGRAVITY) === true; + // Single source of truth for the [DONE] decision, used at both emission // sites below. Only OpenAI Chat Completions clients expect [DONE]; - // Responses API and Anthropic SSE terminate on their own protocol events - // (response.completed / message_stop respectively). - const shouldEmitDoneTerminator = !clientExpectsResponsesStream && !clientExpectsClaudeStream; + // Responses API, Anthropic SSE, and Antigravity/cloudcode terminate on + // their own protocol events (response.completed / message_stop / last + // response candidate respectively). + const shouldEmitDoneTerminator = !clientExpectsResponsesStream && !clientExpectsClaudeStream && !clientExpectsAntigravityStream; let buffer = ""; let usage: UsageTokenRecord | null = null; @@ -816,6 +769,7 @@ export function createSSEStream(options: StreamOptions = {}) { // Guard against duplicate [DONE] events — ensures exactly one per stream let doneSent = false; + let upstreamErrorForwarded = false; const providerPayloadCollector = createStructuredSSECollector({ stage: "provider_response", // #9315: compute the summary live from every pushed chunk (not just the @@ -1597,6 +1551,7 @@ export function createSSEStream(options: StreamOptions = {}) { } } else if (isClaudeSSE) { // Claude SSE: extract usage, track content, forward as-is + const thinkingSignatureInjected = injectThinkingSignature(parsed, provider); const extracted = extractUsage(parsed); if (extracted) { // Non-destructive merge: never overwrite a positive value with 0 @@ -1638,7 +1593,7 @@ export function createSSEStream(options: StreamOptions = {}) { parsed.delta.thinking ); } - if (restoredToolName) { + if (restoredToolName || thinkingSignatureInjected) { output = `data: ${JSON.stringify(parsed)}\n\n`; injectedUsage = true; } @@ -1726,6 +1681,7 @@ export function createSSEStream(options: StreamOptions = {}) { continue; } + const restoredOpenAIToolName = restoreOpenAIToolNames(parsed, toolNameMap); const idFixed = hadNonStringTopLevelId ? false : fixInvalidId(parsed); if (!hasValuableContent(parsed, FORMATS.OPENAI)) { @@ -1914,7 +1870,8 @@ export function createSSEStream(options: StreamOptions = {}) { needsReserialization || toolCallIdCoerced || hadNonStringToolCallId || - hadNonStringTopLevelId + hadNonStringTopLevelId || + restoredOpenAIToolName ) { output = `data: ${JSON.stringify(parsed)}\n\n`; injectedUsage = true; @@ -1980,6 +1937,17 @@ export function createSSEStream(options: StreamOptions = {}) { const parsed = parseSSELine(trimmed); if (!parsed) continue; + if (upstreamErrorForwarded) continue; + + if (parsed.error) { + const output = formatTranslatedStreamError(parsed, sourceFormat); + reqLogger?.appendConvertedChunk?.(output); + controller.enqueue(encoder.encode(output)); + upstreamErrorForwarded = true; + doneSent = true; + continue; + } + // #5786 — drop replayed Responses-API events (identical/lower sequence_number // re-sent on an upstream reconnect) so their deltas are not glued twice into // the translated client stream. @@ -2171,6 +2139,10 @@ export function createSSEStream(options: StreamOptions = {}) { if (streamTimedOut) { return; } + if (upstreamErrorForwarded) { + clearPendingRequestFromStream(); + return; + } try { const remaining = decoder.decode(); if (remaining) buffer += remaining; @@ -2244,6 +2216,8 @@ export function createSSEStream(options: StreamOptions = {}) { toResponsesCompletedWithToolCalls(parsed, [ ...passthroughToolCalls.values(), ]) as JsonRecord, + restoreOpenAIToolNames: (parsed: JsonRecord) => + restoreOpenAIToolNames(parsed, toolNameMap), }; for (const line of normalizedTailLines) { @@ -2291,36 +2265,12 @@ export function createSSEStream(options: StreamOptions = {}) { output = `data: ${JSON.stringify(flushedParsed)}\n\n`; } } else if (!isClaude) { - let flushChanged = false; - const flushedHadNonStringTopLevelId = - flushedParsed?.id != null && typeof flushedParsed.id !== "string"; - if (flushedHadNonStringTopLevelId) { - flushedParsed.id = String(flushedParsed.id); - flushChanged = true; - } - if (Array.isArray(flushedParsed.choices)) { - for (const choice of flushedParsed.choices as JsonRecord[]) { - const tcs = (choice as JsonRecord | undefined)?.delta as - JsonRecord | undefined; - if (Array.isArray(tcs?.tool_calls)) { - for (const tc of tcs.tool_calls as JsonRecord[]) { - if (tc?.id != null && typeof tc.id !== "string") { - tc.id = String(tc.id); - flushChanged = true; - } - } - } - } - } + const { changed: flushChanged, hasFinishReason } = + normalizeFinalOpenAIStreamChunk(flushedParsed, toolNameMap); // #7800: track finish_reason in the flush path too, so a // final chunk without trailing newline still suppresses the // synthetic finish_reason synthesis. - if ( - Array.isArray(flushedParsed.choices) && - (flushedParsed.choices[0] as JsonRecord | undefined)?.finish_reason - ) { - passthroughSawFinishReason = true; - } + if (hasFinishReason) passthroughSawFinishReason = true; if (flushChanged) { output = `data: ${JSON.stringify(flushedParsed)}\n\n`; } @@ -2489,6 +2439,8 @@ export function createSSEStream(options: StreamOptions = {}) { console.warn( `[STREAM] Empty assistant response after tool_calls completion (${provider || "provider"}:${model || "unknown"}) — sessionId=${sessionId}` ); + } else if (passthroughHasToolCalls && !content.trim() && reasoning.trim()) { + message.content = ""; } const responseBody = { diff --git a/open-sse/utils/streamErrorFormat.ts b/open-sse/utils/streamErrorFormat.ts new file mode 100644 index 0000000000..56b747f4e4 --- /dev/null +++ b/open-sse/utils/streamErrorFormat.ts @@ -0,0 +1,115 @@ +import { FORMATS } from "../translator/formats.ts"; +import { buildErrorBody } from "./error.ts"; + +/** + * Upstream stream-failure normalization + client-format error framing. + * + * Extracted from stream.ts (file-size gate, #9314) — pure functions operating only + * on plain payload objects, no dependency on the SSE stream/controller state. + */ + +type JsonRecord = Record; + +export type StreamFailurePayload = { + status: number; + message: string; + code?: string; + type?: string; +}; + +function asRecord(value: unknown): JsonRecord { + return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonRecord) : {}; +} + +function toStreamFailureStatus(value: unknown): number | null { + if (typeof value === "number" && Number.isInteger(value) && value >= 400 && value <= 599) { + return value; + } + if (typeof value === "string" && /^\d{3}$/.test(value.trim())) { + const parsed = Number(value.trim()); + return parsed >= 400 && parsed <= 599 ? parsed : null; + } + return null; +} + +function looksLikeStreamRateLimit(code: string, type: string, message: string): boolean { + const haystack = `${code} ${type} ${message}`.toLowerCase(); + return ( + haystack.includes("usage_limit_reached") || + haystack.includes("rate_limit") || + haystack.includes("rate limit") || + haystack.includes("quota") || + haystack.includes("too many requests") || + haystack.includes("limit reached") || + haystack.includes("limit has been reached") + ); +} + +export function normalizeStreamFailurePayload(payload: unknown): StreamFailurePayload | null { + const record = payload && typeof payload === "object" ? (payload as JsonRecord) : {}; + const response = asRecord(record.response); + const error = Object.keys(asRecord(response.error)).length + ? asRecord(response.error) + : Object.keys(asRecord(record.error)).length + ? asRecord(record.error) + : record; + const code = typeof error.code === "string" ? error.code : "upstream_error"; + const type = typeof error.type === "string" ? error.type : undefined; + const message = + typeof error.message === "string" && error.message.trim() + ? error.message + : typeof record.message === "string" && record.message.trim() + ? record.message + : "Upstream failure"; + const status = + toStreamFailureStatus(error.status_code) ?? + toStreamFailureStatus(error.status) ?? + toStreamFailureStatus(response.status_code) ?? + toStreamFailureStatus(response.status) ?? + toStreamFailureStatus(record.status_code) ?? + toStreamFailureStatus(record.status) ?? + (looksLikeStreamRateLimit(code, type || "", message) ? 429 : 502); + + return { + status, + message, + code, + ...(type ? { type } : {}), + }; +} + +export function formatTranslatedStreamError(payload: unknown, sourceFormat?: string): string { + const failure = normalizeStreamFailurePayload(payload) ?? { + status: 502, + message: "Upstream stream error", + code: "stream_error", + type: "server_error", + }; + const errorBody = buildErrorBody(failure.status, failure.message, undefined, { + type: failure.type ?? "server_error", + code: failure.code ?? "stream_error", + }); + + if (sourceFormat === FORMATS.OPENAI_RESPONSES) { + const failed = { + type: "response.failed", + response: { + id: `resp_error_${Date.now()}`, + object: "response", + created_at: Math.floor(Date.now() / 1000), + status: "failed", + background: false, + error: errorBody.error, + output: [], + }, + sequence_number: 0, + }; + return `event: response.failed\ndata: ${JSON.stringify(failed)}\n\n`; + } + + if (sourceFormat === FORMATS.CLAUDE) { + return `event: error\ndata: ${JSON.stringify({ type: "error", error: errorBody.error })}\n\n`; + } + + return `data: ${JSON.stringify(errorBody)}\n\ndata: [DONE]\n\n`; +} diff --git a/open-sse/utils/streamHelpers.ts b/open-sse/utils/streamHelpers.ts index 5e5000094e..d9fb78415b 100644 --- a/open-sse/utils/streamHelpers.ts +++ b/open-sse/utils/streamHelpers.ts @@ -13,6 +13,7 @@ import { FORMATS } from "../translator/formats.ts"; import { hasAnyReasoningSignal } from "./reasoningFields.ts"; +import { getRegistryEntry } from "../config/providerRegistry.ts"; type SSEPayloadOptions = { eventType?: string; @@ -523,3 +524,24 @@ export function hasActiveDeltaValue(value: unknown): boolean { } return value !== null && value !== undefined; } + +// Claude SSE content_block_start normalization for providers (e.g. MiniMax) whose thinking +// blocks omit `signature` on the opening event. Strict Anthropic Messages clients deserialize +// this field before a later signature_delta arrives — inject only the empty envelope +// placeholder, never synthesize/replace a provider-supplied signature. +export function injectThinkingSignature( + parsed: { type?: string; content_block?: { type?: string; signature?: string } }, + provider: string | null +): boolean { + if ( + provider !== null && + getRegistryEntry(provider)?.ensureThinkingSignature === true && + parsed.type === "content_block_start" && + parsed.content_block?.type === "thinking" && + parsed.content_block.signature === undefined + ) { + parsed.content_block.signature = ""; + return true; + } + return false; +} diff --git a/open-sse/utils/usageTracking.ts b/open-sse/utils/usageTracking.ts index 90f457b77e..93d41c83cc 100644 --- a/open-sse/utils/usageTracking.ts +++ b/open-sse/utils/usageTracking.ts @@ -217,6 +217,7 @@ export function filterUsageForFormat(usage, targetFormat) { [FORMATS.CLAUDE]: [ "input_tokens", "output_tokens", + "output_tokens_details", "cache_read_input_tokens", "cache_creation_input_tokens", "estimated", @@ -232,9 +233,13 @@ export function filterUsageForFormat(usage, targetFormat) { [FORMATS.OPENAI_RESPONSES]: [ "input_tokens", "output_tokens", + "total_tokens", "input_tokens_details", "output_tokens_details", "estimated", + "cost_in_usd_ticks", + "server_side_tool_usage_details", + "server_side_tool_usage", ], // OpenAI format (default for OPENAI, CODEX, KIRO, etc.) default: [ @@ -371,6 +376,7 @@ export function extractUsage(chunk) { output_tokens: chunk.usage.output_tokens || 0, cache_read_input_tokens: chunk.usage.cache_read_input_tokens, cache_creation_input_tokens: chunk.usage.cache_creation_input_tokens, + reasoning_tokens: chunk.usage.output_tokens_details?.thinking_tokens, }); } @@ -425,12 +431,15 @@ export function extractUsage(chunk) { // chunks do not silently drop token usage. const usageMeta = chunk.usageMetadata || chunk.response?.usageMetadata; if (usageMeta && typeof usageMeta === "object") { + // Gemini reports thoughts outside candidates. Fold them into completion so + // every provider keeps reasoning as a subset of completion tokens. + const thoughts = usageMeta.thoughtsTokenCount || 0; return normalizeUsage({ prompt_tokens: usageMeta.promptTokenCount || 0, - completion_tokens: usageMeta.candidatesTokenCount || 0, + completion_tokens: (usageMeta.candidatesTokenCount || 0) + thoughts, total_tokens: usageMeta.totalTokenCount, cached_tokens: usageMeta.cachedContentTokenCount, - reasoning_tokens: usageMeta.thoughtsTokenCount, + reasoning_tokens: thoughts, }); } diff --git a/package-lock.json b/package-lock.json index 4e42863a02..7c321b3421 100644 --- a/package-lock.json +++ b/package-lock.json @@ -27,6 +27,7 @@ "@xyflow/react": "^12.11.1", "axios": "^1.16.1", "bcryptjs": "^3.0.3", + "better-sqlite3": "^13.0.2", "bottleneck": "^2.19.5", "clsx": "^2.1.1", "commander": "^15.0.0", @@ -151,7 +152,7 @@ "@atjsh/llmlingua-2": "2.0.3", "@huggingface/transformers": "3.5.2", "@tensorflow/tfjs": "4.22.0", - "better-sqlite3": "^13.0.1", + "better-sqlite3": "^13.0.2", "js-tiktoken": "^1.0.20", "keytar": "^7.9.0", "tls-client-node": "^0.2.0", @@ -3692,9 +3693,6 @@ "cpu": [ "arm" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3711,9 +3709,6 @@ "cpu": [ "arm64" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3730,9 +3725,6 @@ "cpu": [ "ppc64" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3749,9 +3741,6 @@ "cpu": [ "riscv64" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3768,9 +3757,6 @@ "cpu": [ "s390x" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3787,9 +3773,6 @@ "cpu": [ "x64" ], - "libc": [ - "glibc" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3806,9 +3789,6 @@ "cpu": [ "arm64" ], - "libc": [ - "musl" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3825,9 +3805,6 @@ "cpu": [ "x64" ], - "libc": [ - "musl" - ], "license": "LGPL-3.0-or-later", "optional": true, "os": [ @@ -3844,9 +3821,6 @@ "cpu": [ "arm" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3869,9 +3843,6 @@ "cpu": [ "arm64" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3894,9 +3865,6 @@ "cpu": [ "ppc64" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3919,9 +3887,6 @@ "cpu": [ "riscv64" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3944,9 +3909,6 @@ "cpu": [ "s390x" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3969,9 +3931,6 @@ "cpu": [ "x64" ], - "libc": [ - "glibc" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -3994,9 +3953,6 @@ "cpu": [ "arm64" ], - "libc": [ - "musl" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -4019,9 +3975,6 @@ "cpu": [ "x64" ], - "libc": [ - "musl" - ], "license": "Apache-2.0", "optional": true, "os": [ @@ -5393,9 +5346,6 @@ "cpu": [ "arm64" ], - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -5412,9 +5362,6 @@ "cpu": [ "arm64" ], - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -5431,9 +5378,6 @@ "cpu": [ "x64" ], - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -5450,9 +5394,6 @@ "cpu": [ "x64" ], - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -10670,9 +10611,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -10690,9 +10628,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -10710,9 +10645,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -10730,9 +10662,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -12779,9 +12708,6 @@ "arm" ], "dev": true, - "libc": [ - "glibc" - ], "optional": true, "os": [ "linux" @@ -12795,9 +12721,6 @@ "arm" ], "dev": true, - "libc": [ - "musl" - ], "optional": true, "os": [ "linux" @@ -12811,9 +12734,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "optional": true, "os": [ "linux" @@ -12827,9 +12747,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "optional": true, "os": [ "linux" @@ -12843,9 +12760,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "optional": true, "os": [ "linux" @@ -12859,9 +12773,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "optional": true, "os": [ "linux" @@ -13759,10 +13670,9 @@ } }, "node_modules/better-sqlite3": { - "version": "13.0.1", - "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-13.0.1.tgz", - "integrity": "sha512-LYpmOXdkpQYf4wmlxkdzW01XGlOXNIbjLg45yNkh0FQ4814VbK9PdOFmhZpYbej+EZtR/i3FDdhEG98HqZdgnA==", - "hasInstallScript": true, + "version": "13.0.2", + "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-13.0.2.tgz", + "integrity": "sha512-jW6oufeDhXZaiX9Lw5A+oerVClx4iFrI6uDj1zu7SqUAjak9vbJvA0NEcKLNxHiQHb6kYCoFzzXYV0YOauhV3g==", "license": "MIT", "optional": true, "dependencies": { diff --git a/package.json b/package.json index 380889a66d..e7ce576237 100644 --- a/package.json +++ b/package.json @@ -23,6 +23,7 @@ ".env.example", "scripts/build/postinstall.mjs", "scripts/build/fixTlsClientNodeBinary.mjs", + "scripts/build/fixPlaywrightAndroid.mjs", "bin/cli/runtime/", "scripts/postinstall.mjs", "scripts/build/postinstallSupport.mjs", @@ -189,6 +190,7 @@ "check:bundle-size": "node scripts/check/check-bundle-size.mjs", "check:circular-deps": "node scripts/check/check-circular-deps.mjs", "check:mutation-ratchet": "node scripts/check/check-mutation-ratchet.mjs", + "check:rtl-ratchet": "node scripts/check/check-rtl-ratchet.mjs", "check:licenses": "node scripts/check/check-licenses.mjs", "check:pr-evidence": "node scripts/check/check-pr-evidence.mjs", "check:vuln-ratchet": "node scripts/check/check-vuln-ratchet.mjs", @@ -322,7 +324,7 @@ "@atjsh/llmlingua-2": "2.0.3", "@huggingface/transformers": "3.5.2", "@tensorflow/tfjs": "4.22.0", - "better-sqlite3": "^13.0.1", + "better-sqlite3": "^13.0.2", "js-tiktoken": "^1.0.20", "keytar": "^7.9.0", "tls-client-node": "^0.2.0", @@ -399,6 +401,15 @@ "sharp" ] }, + "allowScripts": { + "better-sqlite3": true, + "esbuild": true, + "@swc/core": true, + "@parcel/watcher": true, + "keytar": true, + "protobufjs": true, + "unrs-resolver": true + }, "overrides": { "dompurify": "^3.4.12", "fast-xml-parser": "^5.10.1", diff --git a/public/providers/unorouter.svg b/public/providers/unorouter.svg new file mode 100644 index 0000000000..a9f5f22200 --- /dev/null +++ b/public/providers/unorouter.svg @@ -0,0 +1 @@ +UnoRouterU diff --git a/public/providers/zoocode.png b/public/providers/zoocode.png new file mode 100644 index 0000000000..57c9ae8515 Binary files /dev/null and b/public/providers/zoocode.png differ diff --git a/scripts/build/assembleStandalone.mjs b/scripts/build/assembleStandalone.mjs index 27faa6c5cf..3b9842e45a 100644 --- a/scripts/build/assembleStandalone.mjs +++ b/scripts/build/assembleStandalone.mjs @@ -48,6 +48,10 @@ import fs from "node:fs/promises"; import fsSync from "node:fs"; import path from "node:path"; +import { + colocateLlmlinguaOptionals, + SEED_PACKAGES, +} from "./colocateOptionals.mjs"; /** * Check whether a path exists (async). @@ -116,6 +120,25 @@ const EXTRA_MODULE_ENTRIES = [ { label: "split2", src: ["node_modules", "split2"], dest: ["node_modules", "split2"] }, { label: "migrations", src: ["src", "lib", "db", "migrations"], dest: ["migrations"] }, { label: "MITM server", src: ["src", "mitm", "server.cjs"], dest: ["src", "mitm", "server.cjs"] }, + { + // #9451: server.cjs requires 6 shims from ./_internal/ (bypass, ingest, + // forwardTarget, aliasConfig, standaloneRouting, rootCaShim) which the MITM + // child process loads via require(). Next.js's standalone tracer never sees + // them (server.cjs is a separate node process, not imported by the main + // server), so the _internal/ directory must be copied explicitly or the MITM + // child crashes with MODULE_NOT_FOUND at boot. + label: "MITM _internal shims (#9451)", + src: ["src", "mitm", "_internal"], + dest: ["src", "mitm", "_internal"], + }, + { + // #9451: rootCaShim.cjs does `await import("selfsigned")` for dynamic SSL + // certificate generation. The MITM child is not traced by Next.js, so the + // package is absent from the Docker standalone bundle without this entry. + label: "selfsigned (MITM rootCaShim dynamic import — #9451)", + src: ["node_modules", "selfsigned"], + dest: ["node_modules", "selfsigned"], + }, { label: "run-standalone script", src: ["scripts", "dev", "run-standalone.mjs"], @@ -717,6 +740,19 @@ export function assembleStandalone({ // 6. Optionally copy native assets + extra modules (synchronous) if (copyNatives) { copyNativeAssetsAndExtraModules(projectRoot, resolvedOutDir); + + // #9166: dynamically imported LLMLingua packages are not reliably traced + // into the standalone bundle. Copy their complete dependency closure from + // the installed root tree without overwriting packages already traced by + // Next.js. Include transformers here so its ONNX runtime closure is also + // guaranteed in Docker/standalone builds. + colocateLlmlinguaOptionals({ + rootDir: projectRoot, + targetNodeModulesDir: path.join(resolvedOutDir, "node_modules"), + seeds: [...SEED_PACKAGES, "@huggingface/transformers"], + log: (message) => + console.log(`[assembleStandalone] ${message.trim()}`), + }); } // 7. Optionally dereference Turbopack hashed-module symlinks so the bundle is diff --git a/scripts/build/colocateOptionals.mjs b/scripts/build/colocateOptionals.mjs index 5317d2fe8a..91548954b0 100644 --- a/scripts/build/colocateOptionals.mjs +++ b/scripts/build/colocateOptionals.mjs @@ -97,47 +97,81 @@ export function computeDependencyClosure(nodeModulesDir, seeds = SEED_PACKAGES) } /** - * Co-locate the SLM optional closure from `/node_modules` into - * `/dist/node_modules`. No-op when the standalone `dist` bundle or the optional seeds are - * absent, and idempotent once co-located. Never throws. + * Co-locate the SLM optional dependency closure from `/node_modules` + * into a standalone bundle's `node_modules`. * - * @param {{ rootDir: string, log?: (message: string) => void }} opts + * The default destination remains `/dist/node_modules` for the npm + * postinstall path. Standalone builders, including Docker, may provide + * `targetNodeModulesDir`. + * + * Packages already present in the destination are never overwritten. This + * preserves the standalone bundle's pinned dependency instances while filling + * dynamically imported packages that Next.js did not trace. + * + * @param {{ + * rootDir: string, + * targetNodeModulesDir?: string, + * seeds?: string[], + * log?: (message: string) => void + * }} opts * @returns {{ skipped: true, reason: string } * | { skipped: false, copied: number, closure: number }} */ -export function colocateLlmlinguaOptionals({ rootDir, log = () => {} }) { +export function colocateLlmlinguaOptionals({ + rootDir, + targetNodeModulesDir, + seeds = SEED_PACKAGES, + log = () => {}, +}) { const rootNm = join(rootDir, "node_modules"); - const distNm = join(rootDir, "dist", "node_modules"); + const targetNm = targetNodeModulesDir ?? join(rootDir, "dist", "node_modules"); - if (!existsSync(distNm)) { - return { skipped: true, reason: "no standalone dist/node_modules" }; + if (!existsSync(targetNm)) { + return { + skipped: true, + reason: targetNodeModulesDir + ? "no target node_modules" + : "no standalone dist/node_modules", + }; } - // Gate: only run when the optional stack was actually installed (`npm install --include=optional`). - if (!SEED_PACKAGES.every((seed) => existsSync(join(rootNm, seed)))) { + + // Only run when every requested closure root was installed. + if (!seeds.every((seed) => existsSync(join(rootNm, seed)))) { return { skipped: true, reason: "SLM optionals not installed at root" }; } - // Idempotent: the entry package is already co-located → nothing to do. - if (existsSync(join(distNm, "@atjsh", "llmlingua-2"))) { + + const closure = computeDependencyClosure(rootNm, seeds); + + // Check the complete closure rather than only the entry package. A partially + // populated bundle must still receive any missing transitive dependencies. + if ( + closure.length > 0 && + closure.every((name) => existsSync(join(targetNm, name))) + ) { return { skipped: true, reason: "already co-located" }; } - const closure = computeDependencyClosure(rootNm); let copied = 0; for (const name of closure) { - const dest = join(distNm, name); - if (existsSync(dest)) continue; // no-clobber: keep dist's pinned copy (transformers 3.5.2, …) + const dest = join(targetNm, name); + if (existsSync(dest)) continue; + try { mkdirSync(dirname(dest), { recursive: true }); cpSync(join(rootNm, name), dest, { recursive: true }); copied++; } catch (err) { - log(` ⚠️ LLMLingua optional co-location failed for ${name}: ${err.message}`); + log( + ` ⚠️ LLMLingua optional co-location failed for ${name}: ${err.message}` + ); } } if (copied > 0) { - log(` ✅ Co-located ${copied} LLMLingua SLM optional package(s) into dist/node_modules.\n`); + log( + ` ✅ Co-located ${copied} LLMLingua SLM optional package(s) into standalone node_modules.\n` + ); } return { skipped: false, copied, closure: closure.length }; diff --git a/scripts/build/fixPlaywrightAndroid.mjs b/scripts/build/fixPlaywrightAndroid.mjs new file mode 100644 index 0000000000..bfacfad723 --- /dev/null +++ b/scripts/build/fixPlaywrightAndroid.mjs @@ -0,0 +1,90 @@ +#!/usr/bin/env node + +/** + * playwright-core Android/Termux platform patch (#7265). + * + * playwright-core's bundled coreBundle.js has three IIFEs that compute the + * browser-cache directory by checking `process.platform` for "linux", "darwin", + * or "win32". On Android (Termux), Node.js may report process.platform as + * "android", causing each IIFE to throw "Unsupported platform: android" at + * module load time — crashing the entire server before any browser is launched. + * + * This script patches the three platform checks to also accept "android", + * treating it identically to "linux" (same XDG_CACHE_HOME convention). + * + * The patch is applied to both root node_modules (for dev/build) and + * dist/node_modules (for the standalone bundle). It is idempotent — running + * multiple times is safe. + * + * Fixes: https://github.com/diegosouzapw/OmniRoute/issues/7265 + */ + +import { existsSync, readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; + +const PATCHED_MARKER = "/* omniroute-android-patch */"; + +/** + * Patch coreBundle.js to accept Android as a valid platform. + * Returns true if the file was modified, false if already patched or not found. + */ +function patchCoreBundle(filePath) { + if (!existsSync(filePath)) return false; + + let content = readFileSync(filePath, "utf8"); + + // Already patched — skip + if (content.includes(PATCHED_MARKER)) return false; + + // The three platform-check patterns in coreBundle.js: + // 1. defaultCacheDirectory IIFE (line ~28594) + // 2. defaultCacheDirectory2 IIFE (line ~51278) + // 3. daemon session dir computation (line ~68847) + // + // Original pattern: if (process.platform === "linux") + // Patched pattern: if (process.platform === "linux" || process.platform === "android") + // + // We use a regex that matches the exact pattern and only replaces the first + // occurrence in each of the three IIFEs. The marker comment is appended once + // to signal idempotency. + + const original = /if \(process\.platform === "linux"\)/g; + const patched = `if (process.platform === "linux" || process.platform === "android") ${PATCHED_MARKER}`; + + const count = (content.match(original) || []).length; + if (count === 0) { + // Either already patched or different version — check for our marker + return false; + } + + content = content.replace(original, patched); + writeFileSync(filePath, content, "utf8"); + return true; +} + +export function fixPlaywrightAndroid({ rootDir, log = (m) => console.log(m) } = {}) { + const targets = [ + join(rootDir, "node_modules", "playwright-core", "lib", "coreBundle.js"), + join(rootDir, "dist", "node_modules", "playwright-core", "lib", "coreBundle.js"), + ]; + + let patched = 0; + for (const target of targets) { + if (patchCoreBundle(target)) { + patched++; + log(` ✅ Patched playwright-core for Android: ${target}`); + } + } + + if (patched > 0) { + log(` ✅ playwright-core Android patch applied (${patched} file(s))\n`); + } + + return patched; +} + +// When run directly (not imported), execute the patch +if (process.argv[1] && process.argv[1].endsWith("fixPlaywrightAndroid.mjs")) { + const rootDir = process.argv[2] || process.cwd(); + fixPlaywrightAndroid({ rootDir }); +} diff --git a/scripts/build/postinstall.mjs b/scripts/build/postinstall.mjs index 9972e4771e..a2fa8acca4 100644 --- a/scripts/build/postinstall.mjs +++ b/scripts/build/postinstall.mjs @@ -24,7 +24,7 @@ * Fixes: https://github.com/diegosouzapw/OmniRoute/issues/7802 */ -import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync } from "node:fs"; +import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; @@ -32,11 +32,61 @@ import { PUBLISHED_BUILD_ARCH, PUBLISHED_BUILD_PLATFORM } from "./native-binary- import { hasStandaloneAppBundle, isTermux } from "./postinstallSupport.mjs"; import { colocateLlmlinguaOptionals } from "./colocateOptionals.mjs"; import { fixTlsClientNodeBinary } from "./fixTlsClientNodeBinary.mjs"; +import { fixPlaywrightAndroid } from "./fixPlaywrightAndroid.mjs"; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); const ROOT = join(__dirname, "..", ".."); +/** + * Patch node-gyp's common.gypi to include the android_ndk_path variable. + * + * On Termux/Android, node-gyp's bundled common.gypi (in ~/.cache/node-gyp//) + * does not define the `android_ndk_path` variable that the build system expects. + * Setting GYP_DEFINES="android_ndk_path=''" is not enough because common.gypi + * is parsed separately and the variable must be declared in the 'variables' section. + * + * This function finds and patches the common.gypi for the current Node.js version, + * adding `'android_ndk_path%': ''` to the variables block. The patch is idempotent. + */ +function patchNodeGypCommonGypi() { + try { + const nodeVersion = process.version; // e.g. "v26.4.0" + const gypDir = join( + process.env.HOME || process.env.USERPROFILE || "/root", + ".cache", + "node-gyp", + nodeVersion.replace(/^v/, "") + ); + const commonGypi = join(gypDir, "include", "node", "common.gypi"); + + if (!existsSync(commonGypi)) { + console.warn(` ⚠️ common.gypi not found at ${commonGypi}, skipping patch`); + return; + } + + let content = readFileSync(commonGypi, "utf8"); + + // Check if already patched + if (content.includes("android_ndk_path")) { + return; + } + + // Find the variables section and add android_ndk_path + // The pattern is: 'variables': { 'node_use_openssl%': ... } + // We insert our variable right after the opening of the variables block + const variablesMatch = content.match(/('variables'\s*:\s*\{)/); + if (variablesMatch) { + const insertPos = content.indexOf(variablesMatch[0]) + variablesMatch[0].length; + content = content.slice(0, insertPos) + "\n 'android_ndk_path%': ''," + content.slice(insertPos); + writeFileSync(commonGypi, content, "utf8"); + console.log(` ✅ Patched common.gypi for Android at ${commonGypi}`); + } + } catch (err) { + console.warn(` ⚠️ Could not patch common.gypi: ${err.message}`); + } +} + const appBinary = join( ROOT, "dist", @@ -148,6 +198,9 @@ async function fixBetterSqliteBinary() { const env = { ...process.env }; if (isAndroid) { env.GYP_DEFINES = "android_ndk_path=''"; + // Patch node-gyp's common.gypi to include android_ndk_path variable + // so the gyp build system doesn't fail with "Unknown variable" + patchNodeGypCommonGypi(); } execSync(rebuildCmd, { @@ -345,9 +398,41 @@ async function ensureLlmlinguaOptionals() { } } +/** + * Preflight check for development installs (when standalone dist/ bundle is not present). + * Warns or errors if critical native dependencies like better-sqlite3 were skipped by npm >= 11 + * allowScripts restrictions. + */ +async function verifyDevNativeModules() { + if (hasStandaloneAppBundle(ROOT)) { + return; + } + + const criticalModules = [ + { name: "better-sqlite3", fatal: true }, + { name: "esbuild", fatal: true }, + ]; + + for (const { name, fatal } of criticalModules) { + if (!existsSync(join(ROOT, "node_modules", name))) { + const level = fatal ? "🔴 CRITICAL" : "⚠️ WARNING"; + console.error(`\n ${level}: '${name}' is missing from node_modules/`); + console.error(` This usually happens with npm ≥ 11, which blocks install`); + console.error(` scripts for optional dependencies by default.`); + console.error(`\n Fix options:`); + console.error(` 1. npm approve-scripts ${name} && npm install`); + console.error(` 2. npm pack ${name} && tar -xzf ${name}-*.tgz -C node_modules`); + console.error(` && mv node_modules/package node_modules/${name}`); + console.error(` 3. Downgrade to npm 10: npm install -g npm@10\n`); + } + } +} + +await verifyDevNativeModules(); await fixBetterSqliteBinary(); await fixWreqJsBinary(); await fixTlsClientNodeBinary({ rootDir: ROOT }); +await fixPlaywrightAndroid({ rootDir: ROOT }); await ensureSwcHelpers(); await ensureLlmlinguaOptionals(); await syncProjectEnv(); diff --git a/scripts/build/prepublish.ts b/scripts/build/prepublish.ts index bd8612adfa..c899544d83 100644 --- a/scripts/build/prepublish.ts +++ b/scripts/build/prepublish.ts @@ -39,6 +39,65 @@ const __dirname = dirname(__filename); const ROOT = join(__dirname, "..", ".."); const NPX_BIN = process.platform === "win32" ? "npx.cmd" : "npx"; +// On Windows the npm/npx entry points are `.cmd` shims, and Node >= 20 refuses to +// spawn a `.cmd` without a shell (EINVAL, from the CVE-2024-27980 hardening). On +// Node 24 that makes every `execFileSync(NPX_BIN, ...)` in this script fail, which +// silently skipped the MITM utilities, the MCP server bundle, the LLMLingua worker +// and the OpenCode plugin while the build still reported success. +// +// `shell: true` would fix the spawn but disables argument escaping (DEP0190), so it +// is only the last resort. Preferred order: run the tool's own JS entry point with +// this Node binary — no shim, no shell, nothing to escape. +function resolveLocalBinEntry(packageName: string, binName: string): string | null { + try { + const packageJsonPath = join(ROOT, "node_modules", packageName, "package.json"); + if (!existsSync(packageJsonPath)) return null; + const meta = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { + bin?: string | Record; + }; + const relative = typeof meta.bin === "string" ? meta.bin : meta.bin?.[binName]; + if (!relative) return null; + const absolute = join(ROOT, "node_modules", packageName, relative); + return existsSync(absolute) ? absolute : null; + } catch { + return null; + } +} + +function resolveBundledNpmEntry(name: "npm-cli.js" | "npx-cli.js"): string | null { + const candidate = join(dirname(process.execPath), "node_modules", "npm", "bin", name); + return existsSync(candidate) ? candidate : null; +} + +/** + * Runs a build tool without ever touching a `.cmd` shim. `packageName` is where the + * tool lives in the local dependency tree; when it is not installed there the call + * falls back to the Node-resolved `npx` entry point, and only then to the shim. + */ +function runBuildTool( + packageName: string, + binName: string, + args: readonly string[], + options: Parameters[2] +): void { + const localEntry = resolveLocalBinEntry(packageName, binName); + if (localEntry) { + execFileSync(process.execPath, [localEntry, ...args], options); + return; + } + const npxEntry = resolveBundledNpmEntry("npx-cli.js"); + if (npxEntry) { + execFileSync(process.execPath, [npxEntry, binName, ...args], options); + return; + } + // Last resort. The arguments here are static build literals, never user input, + // so the missing escaping under `shell` is not an injection surface. + execFileSync(NPX_BIN, [binName, ...args], { + ...options, + shell: process.platform === "win32", + }); +} + const DIST_DIR = join(ROOT, "dist"); const METHOD_GUARD_REQUIRE = 'require("./http-method-guard.cjs").installHttpMethodGuard();\n'; @@ -205,7 +264,7 @@ if (existsSync(mitmSrc)) { writeFileSync(tmpTsconfigPath, JSON.stringify(mitmTsconfig, null, 2)); try { - execFileSync(NPX_BIN, ["tsc", "-p", "tsconfig.mitm.tmp.json"], { + runBuildTool("typescript", "tsc", ["-p", "tsconfig.mitm.tmp.json"], { cwd: ROOT, stdio: "inherit", }); @@ -235,10 +294,10 @@ if (existsSync(mcpSrcFile)) { console.log(" 🔨 Bundling MCP Server (TypeScript → JavaScript)..."); mkdirSync(mcpDestDir, { recursive: true }); try { - execFileSync( - NPX_BIN, + runBuildTool( + "esbuild", + "esbuild", [ - "esbuild", "open-sse/mcp-server/server.ts", "--bundle", "--platform=node", @@ -281,10 +340,10 @@ if (existsSync(llmWorkerSrc)) { console.log(" 🔨 Bundling LLMLingua ONNX worker (TypeScript → JavaScript)..."); mkdirSync(llmWorkerDestDir, { recursive: true }); try { - execFileSync( - NPX_BIN, + runBuildTool( + "esbuild", + "esbuild", [ - "esbuild", "open-sse/services/compression/engines/llmlingua/onnxWorker.ts", "--bundle", "--platform=node", @@ -309,10 +368,10 @@ const cliDestFile = join(ROOT, "bin", "omniroute.mjs"); if (existsSync(cliSrcFile)) { console.log(" 🔨 Bundling CLI Entrypoint (TypeScript → JavaScript)..."); try { - execFileSync( - NPX_BIN, + runBuildTool( + "esbuild", + "esbuild", [ - "esbuild", "bin/omniroute.ts", "--bundle", "--platform=node", @@ -349,13 +408,18 @@ if (existsSync(opencodePluginSrc) && existsSync(join(opencodePluginSrc, "package // needs the plugin's own devDependencies (typescript, @opencode-ai/plugin // types). Without this install a fresh CI publish fails at this step. if (!existsSync(join(opencodePluginSrc, "node_modules"))) { - const NPM_BIN = process.platform === "win32" ? "npm.cmd" : "npm"; - execFileSync(NPM_BIN, ["install", "--no-audit", "--no-fund"], { + const npmEntry = resolveBundledNpmEntry("npm-cli.js"); + if (!npmEntry) { + throw new Error( + "npm-cli.js not found next to the running Node binary; cannot install the plugin dependencies without falling back to a .cmd shim." + ); + } + execFileSync(process.execPath, [npmEntry, "install", "--no-audit", "--no-fund"], { cwd: opencodePluginSrc, stdio: "inherit", }); } - execFileSync(NPX_BIN, ["tsup"], { + runBuildTool("tsup", "tsup", [], { cwd: opencodePluginSrc, stdio: "inherit", env: { ...process.env, NODE_ENV: "production" }, diff --git a/scripts/build/runtime-env.mjs b/scripts/build/runtime-env.mjs index ea91bf9190..d8dbe45765 100644 --- a/scripts/build/runtime-env.mjs +++ b/scripts/build/runtime-env.mjs @@ -86,6 +86,20 @@ export function buildNodeHeapArgs(env = process.env, memoryLimit) { return envHasExplicitHeapFlag(env) ? [] : [`${MAX_OLD_SPACE_FLAG}=${memoryLimit}`]; } +/** + * Build the complete argument list for spawning the Node.js server runtime. + * Prefer IPv4 DNS results before starting the application so undici does not + * stall on hosts whose IPv6 route silently drops outbound connections. + * + * @param {NodeJS.ProcessEnv | Record} [env] + * @param {number} memoryLimit — calibrated V8 heap ceiling (MB) + * @param {string} serverPath — standalone server entrypoint + * @returns {string[]} + */ +export function buildNodeRuntimeArgs(env = process.env, memoryLimit, serverPath) { + return ["--dns-result-order=ipv4first", ...buildNodeHeapArgs(env, memoryLimit), serverPath]; +} + /** * @param {NodeJS.ProcessEnv | Record} [fromEnv] * Defaults to process.env. Pass bootstrap `merged` so project `.env` PORT applies before spawn. @@ -107,6 +121,7 @@ export function withRuntimePortEnv(env, runtimePorts) { PORT: String(dashboardPort), DASHBOARD_PORT: String(dashboardPort), API_PORT: String(apiPort), + HOSTNAME: env.OMNIROUTE_HOSTNAME || "0.0.0.0", }; } diff --git a/scripts/check/check-docs-counts-sync.mjs b/scripts/check/check-docs-counts-sync.mjs index c529ea47c5..c0e4cf83f6 100644 --- a/scripts/check/check-docs-counts-sync.mjs +++ b/scripts/check/check-docs-counts-sync.mjs @@ -259,7 +259,7 @@ export function buildChecks() { actual: readProviderTotal(), docKey: "providers", strict: true, - files: ["README.md", "CLAUDE.md"], + files: ["README.md", "AGENTS.md"], }, { label: "i18n locales count", @@ -317,9 +317,9 @@ export function buildChecks() { skipBefore: /(tools?|definitions?)\s*\(\s*$/i, skipAfter: /^\s*\(\d+ CLI/, }, - ["README.md", "CLAUDE.md", "docs/frameworks/MCP-SERVER.md"] + ["README.md", "AGENTS.md", "docs/frameworks/MCP-SERVER.md"] ), - claim(f.mcpScopes, "MCP scopes", { pattern: /(\d+) scopes/gi }, ["README.md", "CLAUDE.md"]), + claim(f.mcpScopes, "MCP scopes", { pattern: /(\d+) scopes/gi }, ["README.md", "AGENTS.md"]), claim(f.cliTotal, "CLI tools", { pattern: /(\d+) tools(?=\s*\(\d+ CLI)/gi }, ["README.md"]), ]; })(), diff --git a/scripts/check/check-rtl-ratchet.mjs b/scripts/check/check-rtl-ratchet.mjs new file mode 100644 index 0000000000..0a3f21ab54 --- /dev/null +++ b/scripts/check/check-rtl-ratchet.mjs @@ -0,0 +1,133 @@ +#!/usr/bin/env node +// scripts/check/check-rtl-ratchet.mjs +// RTL layout ratchet. Counts physical directional Tailwind classes in TSX. +// +// tests/unit/ui/rtl-logical-classes.test.tsx pins four high-impact components +// and says so: "#3541 (partial, core layout)". This measures the rest, so the +// remaining backlog cannot grow while it is worked through. +// +// Physical classes (ml/mr/pl/pr/left/right/text-left/border-l/rounded-l ...) do +// not mirror under dir=rtl. Tailwind v4 logical utilities (ms/me/ps/pe/start/ +// end/text-start/border-s/rounded-s) do. +// +// Output: rtlPhysicalClasses=N +// +// Advisory by default (exit 0). With --ratchet, reads +// metrics.rtlPhysicalClasses.value from config/quality/quality-baseline.json and +// exits 1 only when the measured count is HIGHER (direction: down). +// +// node scripts/check/check-rtl-ratchet.mjs +// node scripts/check/check-rtl-ratchet.mjs --list # show the worst files +// node scripts/check/check-rtl-ratchet.mjs --ratchet # blocking + +import fs from "node:fs"; +import path from "node:path"; +import { pathToFileURL } from "node:url"; + +const ROOT = process.cwd(); +const QUIET = process.argv.includes("--quiet"); +const LIST = process.argv.includes("--list"); +const RATCHET = process.argv.includes("--ratchet"); +const BASELINE_PATH = path.join(ROOT, "config/quality/quality-baseline.json"); +const SCAN_DIRS = ["src", "electron"]; +const SKIP = new Set(["node_modules", ".next", "dist", "build", "out", "coverage", ".git"]); + +// Physical utilities that govern placement and do not mirror under dir=rtl. +const PHYSICAL = + /(? 0) { + perFile.push({ file: path.relative(ROOT, file), count: n }); + total += n; + } + } + } + perFile.sort((a, b) => b.count - a.count); + return { total, perFile }; +} + +function main() { + const { total, perFile } = measure(); + console.log(`rtlPhysicalClasses=${total}`); + + if (LIST) { + for (const { file, count } of perFile.slice(0, 25)) { + console.log(` ${String(count).padStart(4)} ${file}`); + } + console.log(` ${perFile.length} file(s) affected`); + } + + if (!RATCHET) return 0; + + let baseline; + try { + const json = JSON.parse(fs.readFileSync(BASELINE_PATH, "utf-8")); + baseline = json?.metrics?.rtlPhysicalClasses?.value; + } catch (err) { + // A measurement failure must not block, only a measured regression. + if (!QUIET) console.log(`rtlPhysicalClasses=SKIP reason=baseline-unreadable (${err.message})`); + return 0; + } + if (typeof baseline !== "number") { + if (!QUIET) console.log("rtlPhysicalClasses=SKIP reason=baseline-absent"); + return 0; + } + if (total > baseline) { + console.error( + `RTL ratchet: ${total} physical directional classes, baseline ${baseline}. ` + + `Use logical utilities (ms/me/ps/pe/start/end/text-start) so the layout ` + + `mirrors under dir=rtl, or re-baseline with justification.`, + ); + return 1; + } + if (!QUIET) console.log(`rtlPhysicalClasses OK (${total} <= ${baseline})`); + return 0; +} + +// Only run when invoked directly, so countViolations can be unit tested. +if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) { + process.exit(main()); +} diff --git a/scripts/check/check-test-masking.mjs b/scripts/check/check-test-masking.mjs index 0f94b55d6a..9bb8832586 100644 --- a/scripts/check/check-test-masking.mjs +++ b/scripts/check/check-test-masking.mjs @@ -251,7 +251,7 @@ export function findReimplementedConditions(prodSources, testSource, testImports * (filtro D do git diff --diff-filter=MDR). * * `deletionAllowlist` (`_deletedWithReplacement` no test-masking-allowlist.json) - * isenta uma deleção de duas formas, cada uma com sua própria verificação: + * isenta uma deleção de três formas, cada uma com sua própria verificação: * 1. `replacement` (path string) — o substituto declarado existe no HEAD e é * ele próprio um arquivo de teste — o caso "reescrito em outro path sem * rename detectável" (conteúdo novo demais para o -M do git). @@ -259,12 +259,19 @@ export function findReimplementedConditions(prodSources, testSource, testImports * os arquivos de produção listados precisam estar ausentes no HEAD (sem * substituto porque não há mais código a testar). Usar apenas quando a * remoção do código-fonte está confirmada na mesma commit/PR. + * 3. `strayFromCommit` (hash) + `reason` (não-vazio) — o arquivo entrou no + * repositório POR ACIDENTE no commit declarado (ex.: um commit de docs + * que varreu artefatos de worktree de outra sessão, caso f4e93f339d) e a + * deleção devolve o arquivo ao seu fluxo dono (um PR/issue aberto). O + * gate verifica via git que o commit declarado é exatamente o que ADICIONOU + * o arquivo; o `reason` deve nomear o PR/issue dono para a revisão humana. * Qualquer entrada cuja condição declarada não se verifique continua flagada. */ export function evaluateDeletedFiles( deletedPaths, deletionAllowlist = {}, - fileExists = fs.existsSync + fileExists = fs.existsSync, + addedByCommit = lookupAddedByCommit ) { const flags = []; for (const f of deletedPaths) { @@ -285,6 +292,21 @@ export function evaluateDeletedFiles( ); continue; } + if (entry && typeof entry.strayFromCommit === "string" && entry.strayFromCommit.trim()) { + if (typeof entry.reason !== "string" || !entry.reason.trim()) { + flags.push( + `${f}: deleção allowlistada como stray mas sem \`reason\` — nomeie o PR/issue dono do arquivo` + ); + continue; + } + const actual = addedByCommit(f); + const declared = entry.strayFromCommit.trim(); + if (actual && (actual === declared || actual.startsWith(declared))) continue; + flags.push( + `${f}: deleção allowlistada como stray de ${declared} mas o commit que adicionou o arquivo é ${actual ?? "desconhecido"}` + ); + continue; + } flags.push( `${f}: arquivo de teste deletado — revisão humana obrigatória (mascaramento alto-sinal)` ); @@ -292,6 +314,26 @@ export function evaluateDeletedFiles( return flags; } +/** + * (subcheck 1, forma 3) Hash COMPLETO do commit que adicionou `path` (o add + * mais recente — cobre o caso deletado-e-readicionado). `null` quando o git + * não conhece o path. + */ +function lookupAddedByCommit(path) { + try { + const out = execFileSync("git", ["log", "--diff-filter=A", "--format=%H", "--", path], { + encoding: "utf8", + }); + const hashes = out + .split("\n") + .map((s) => s.trim()) + .filter(Boolean); + return hashes.length ? hashes[0] : null; + } catch { + return null; + } +} + /** * Parse `git diff --name-status -M --diff-filter=DR` output, separating TRUE * test-file deletions ("D\tpath") from RENAMES ("R\told\tnew"). diff --git a/scripts/ci/resolve-docker-publish-version.sh b/scripts/ci/resolve-docker-publish-version.sh new file mode 100644 index 0000000000..a9844e76a7 --- /dev/null +++ b/scripts/ci/resolve-docker-publish-version.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +# Resolve the Docker tag/channel for a docker-publish workflow event. +# +# Usage: +# resolve-docker-publish-version.sh EVENT_NAME REF_TYPE REF_NAME [INPUT_VERSION] [DEFAULT_BRANCH] +# +# Outputs exactly one safe tag string: +# - workflow_dispatch: requested version without a leading v +# - push tag: tag without a leading v +# - push main: main +# - push to the current default release/v* branch: next +# - release: release tag without a leading v +set -euo pipefail + +EVENT_NAME="${1:?event name required}" +REF_TYPE="${2:-}" +REF_NAME="${3:-}" +INPUT_VERSION="${4:-}" +DEFAULT_BRANCH="${5:-}" + +case "$EVENT_NAME" in + workflow_dispatch) + VERSION="${INPUT_VERSION#v}" + ;; + push) + if [ "$REF_TYPE" = "tag" ]; then + VERSION="${REF_NAME#v}" + else + case "$REF_NAME" in + main) + VERSION="main" + ;; + release/v*) + if [ -z "$DEFAULT_BRANCH" ] || [ "$REF_NAME" != "$DEFAULT_BRANCH" ]; then + echo "Refusing to publish next from non-default release branch: $REF_NAME" >&2 + exit 1 + fi + VERSION="next" + ;; + *) + echo "Unsupported Docker publish branch: $REF_NAME" >&2 + exit 1 + ;; + esac + fi + ;; + release) + VERSION="${REF_NAME#v}" + ;; + *) + VERSION="${REF_NAME#v}" + ;; +esac + +if ! printf '%s' "$VERSION" | grep -qE '^[A-Za-z0-9._-]+$'; then + echo "Refusing to use unsafe VERSION value: $VERSION" >&2 + exit 1 +fi + +printf '%s\n' "$VERSION" diff --git a/scripts/ci/should-promote-latest.sh b/scripts/ci/should-promote-latest.sh index 12704b7962..e118086c88 100755 --- a/scripts/ci/should-promote-latest.sh +++ b/scripts/ci/should-promote-latest.sh @@ -22,11 +22,13 @@ set -euo pipefail VERSION="${1:?version required}" -# A pre-release VERSION must never grab :latest (callers already short-circuit -# this, but stay safe as a standalone unit). -case "$VERSION" in - *-*) echo "false"; exit 0 ;; -esac +# Only a stable x.y.z release may ever grab :latest. Floating channels such as +# `main` and `next`, plus every pre-release identifier, fail closed here even if +# a caller forgets to short-circuit them first. +if ! printf '%s' "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then + echo "false" + exit 0 +fi # Build the stable candidate set: incoming tags (v-stripped, pre-releases # dropped) plus VERSION itself, then pick the numerically highest. diff --git a/scripts/quality/validate-release-green.mjs b/scripts/quality/validate-release-green.mjs index e1adca9927..f9693aa92e 100644 --- a/scripts/quality/validate-release-green.mjs +++ b/scripts/quality/validate-release-green.mjs @@ -96,9 +96,7 @@ export function firstFailureLine(out) { .split("\n") .map((l) => l.trim()) .filter(Boolean); - const hit = lines.find((l) => - /✖|✗|not ok|AssertionError|error TS|FAIL|Error:|REGRESS/i.test(l) - ); + const hit = lines.find((l) => /✖|✗|not ok|AssertionError|error TS|FAIL|Error:|REGRESS/i.test(l)); return (hit || lines[lines.length - 1] || "failed").slice(0, 200); } @@ -570,10 +568,20 @@ async function main() { // release — that is why it is a HARD pre-flight gate. const slow = [ { + // Raised 45→100min 2026-08-05: a hermetic-env run on the loaded devbox + // (load 7-26) was still inside invocation 1 of 3 at 76min when killed; + // contention factor 2-3× was measured against idle windows, and no idle + // measurement exists yet. The pre-flight's REAL condition is exactly + // this contended one (unit runs in Promise.all with integration+vitest + // plus whatever else the devbox carries), and there 45min provably + // killed a healthy suite and fabricated a false base-red. The ceiling's + // purpose — turning a genuine hang (stuck SQLite handle = zero progress + // forever) into a visible failure — survives at 100min. + // TODO: measure on the idle .113 box and re-tighten to ~1.8× measured. id: "unit", - label: "Unit tests (full suite, CI concurrency — runs ~20-35min silently)", + label: "Unit tests (full suite, CI concurrency — ~30-50min idle, up to ~100min under load)", args: ["run", "test:unit:ci"], - timeout: 45 * 60 * 1000, + timeout: 100 * 60 * 1000, }, { id: "vitest", @@ -582,10 +590,16 @@ async function main() { timeout: 15 * 60 * 1000, }, { + // Measured 2026-08-05 on an idle 16-core box: 22m08s hermetic (935 tests, + // 112 files at --test-concurrency=1, i.e. strictly serial because ~16 of + // them bind a port or share a DB). The old "~3-10min" estimate was stale by + // ~3x and the 20min ceiling killed a healthy run. 40min keeps the ceiling's + // real purpose — turning a genuine hang (unreleased DB handle) into a + // visible failure — without punishing a long-but-healthy suite. id: "integration", - label: "Integration tests (~3-10min)", + label: "Integration tests (~20-25min)", args: ["run", "test:integration"], - timeout: 20 * 60 * 1000, + timeout: 40 * 60 * 1000, }, ]; if (WITH_BUILD) { diff --git a/scripts/query_all_provider_connections.cjs b/scripts/query_all_provider_connections.cjs new file mode 100644 index 0000000000..4479efec06 --- /dev/null +++ b/scripts/query_all_provider_connections.cjs @@ -0,0 +1,12 @@ +const Database = require('better-sqlite3'); +const path = require('path'); +const dbPath = path.resolve(process.env.USERPROFILE, '.omniroute', 'storage.sqlite'); +try { + const db = new Database(dbPath, { readonly: true }); + const rows = db.prepare(`SELECT id, provider, name, auth_type, is_active, last_error, test_status, updated_at FROM provider_connections ORDER BY updated_at DESC LIMIT 200`).all(); + console.log(JSON.stringify(rows, null, 2)); + db.close(); +} catch (err) { + console.error('ERROR', err && err.message); + process.exit(2); +} diff --git a/scripts/query_providers.cjs b/scripts/query_providers.cjs new file mode 100644 index 0000000000..cfad330655 --- /dev/null +++ b/scripts/query_providers.cjs @@ -0,0 +1,12 @@ +const Database = require('better-sqlite3'); +const path = require('path'); +const dbPath = path.resolve(process.env.USERPROFILE, '.omniroute', 'storage.sqlite'); +try { + const db = new Database(dbPath, { readonly: true }); + const rows = db.prepare(`SELECT id, provider, name, auth_type, is_active, api_key IS NOT NULL as has_api_key, access_token IS NOT NULL as has_access_token, refresh_token IS NOT NULL as has_refresh, last_error, test_status, provider_specific_data, updated_at FROM provider_connections WHERE provider LIKE '%anthropic%' OR provider='anthropic' OR provider LIKE '%claude%' OR provider='claude'`).all(); + console.log(JSON.stringify(rows, null, 2)); + db.close(); +} catch (err) { + console.error('ERROR', err && err.message); + process.exit(2); +} diff --git a/scripts/query_providers.js b/scripts/query_providers.js new file mode 100644 index 0000000000..cfad330655 --- /dev/null +++ b/scripts/query_providers.js @@ -0,0 +1,12 @@ +const Database = require('better-sqlite3'); +const path = require('path'); +const dbPath = path.resolve(process.env.USERPROFILE, '.omniroute', 'storage.sqlite'); +try { + const db = new Database(dbPath, { readonly: true }); + const rows = db.prepare(`SELECT id, provider, name, auth_type, is_active, api_key IS NOT NULL as has_api_key, access_token IS NOT NULL as has_access_token, refresh_token IS NOT NULL as has_refresh, last_error, test_status, provider_specific_data, updated_at FROM provider_connections WHERE provider LIKE '%anthropic%' OR provider='anthropic' OR provider LIKE '%claude%' OR provider='claude'`).all(); + console.log(JSON.stringify(rows, null, 2)); + db.close(); +} catch (err) { + console.error('ERROR', err && err.message); + process.exit(2); +} diff --git a/src/app/(dashboard)/dashboard/HomePageClient.tsx b/src/app/(dashboard)/dashboard/HomePageClient.tsx index 3b1e2a91da..b5b5883dfd 100644 --- a/src/app/(dashboard)/dashboard/HomePageClient.tsx +++ b/src/app/(dashboard)/dashboard/HomePageClient.tsx @@ -498,6 +498,12 @@ export default function HomePageClient({ machineId }: HomePageClientProps) { const canonicalProviderId = normalizeProviderId(rawProviderId); if (!canonicalProviderId || byProvider.has(canonicalProviderId)) return; + // Exclude providers with no active connections (or where all connections are deactivated) + const hasActiveConn = providerConnections.some( + (c) => normalizeProviderId(c.provider) === canonicalProviderId && c.isActive !== false + ); + if (!hasActiveConn) return; + const resolvedName = getProviderDisplayLabel(rawProviderId, providerNodes) || name || @@ -515,10 +521,11 @@ export default function HomePageClient({ machineId }: HomePageClientProps) { providerStats .filter((provider) => provider.total > 0) .forEach((provider) => addProvider(provider.id, provider.provider.name)); + providerConnections.forEach((conn) => addProvider(conn.provider)); Object.keys(providerMetrics).forEach((provider) => addProvider(provider)); return Array.from(byProvider.values()); - }, [providerStats, providerMetrics, providerNodes]); + }, [providerStats, providerMetrics, providerNodes, providerConnections]); const { lastProvider, errorProvider } = providerTopology; diff --git a/src/app/(dashboard)/dashboard/providers/[id]/__tests__/passthroughModelRowDisplayName.test.tsx b/src/app/(dashboard)/dashboard/providers/[id]/__tests__/passthroughModelRowDisplayName.test.tsx new file mode 100644 index 0000000000..ab826a7239 --- /dev/null +++ b/src/app/(dashboard)/dashboard/providers/[id]/__tests__/passthroughModelRowDisplayName.test.tsx @@ -0,0 +1,75 @@ +// @vitest-environment jsdom +// +// Regression test: opaque model ids must still render a readable label. +// +// Gateways that expose preset-style model ids (32-char hex GUIDs) still return a +// friendly `name` in their /models payload, and CompatibleModelsSection already +// computes it as `displayName` (`model.name || model.id`). But the render used to +// destructure only { modelId, alias, isHidden, source, isFree } — dropping +// displayName — and PassthroughModelRow had no name fallback, so every such model +// showed the bare GUID plus "Click to set alias". +// +// This asserts the friendly name is rendered when there is no alias, that an alias +// still wins over it, and that a displayName equal to the id is NOT echoed (which +// would print the GUID twice). + +import React, { act } from "react"; +import { createRoot } from "react-dom/client"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; + +import PassthroughModelRow from "../components/PassthroughModelRow"; + +const GUID = "0123456789abcdef0123456789abcdef"; + +let container: HTMLDivElement; + +beforeEach(() => { + container = document.createElement("div"); + document.body.appendChild(container); +}); + +afterEach(() => { + container.remove(); +}); + +function renderRow(extra: Record) { + const root = createRoot(container); + act(() => { + root.render( + {}} + // The alias slot only renders when the row is alias-editable. + onSetAlias={() => {}} + t={(_key: string, _values?: Record) => ""} + effectiveModelNormalize={() => false} + effectiveModelPreserveDeveloper={() => false} + saveModelCompatFlags={() => {}} + getUpstreamHeadersRecord={() => ({})} + {...extra} + /> + ); + }); + return container.textContent || ""; +} + +describe("PassthroughModelRow — friendly name fallback", () => { + it("renders the upstream name when the model has no alias", () => { + const text = renderRow({ displayName: "Speech To Text (Fast)", alias: null }); + expect(text).toContain("Speech To Text (Fast)"); + }); + + it("prefers an explicit alias over the upstream name", () => { + const text = renderRow({ displayName: "Speech To Text (Fast)", alias: "whisper" }); + expect(text).toContain("whisper"); + expect(text).not.toContain("Speech To Text (Fast)"); + }); + + it("does not echo the id when displayName equals the model id", () => { + const text = renderRow({ displayName: GUID, alias: null }); + // The id is shown once as the model label; the alias slot must not repeat it. + expect(text.split(GUID).length - 1).toBe(1); + }); +}); diff --git a/src/app/(dashboard)/dashboard/providers/[id]/components/CompatibleModelsSection.tsx b/src/app/(dashboard)/dashboard/providers/[id]/components/CompatibleModelsSection.tsx index 7a8542265b..f82e7f9f70 100644 --- a/src/app/(dashboard)/dashboard/providers/[id]/components/CompatibleModelsSection.tsx +++ b/src/app/(dashboard)/dashboard/providers/[id]/components/CompatibleModelsSection.tsx @@ -429,7 +429,7 @@ export default function CompatibleModelsSection({ onAutoHideFailedChange={onAutoHideFailedChange} />
- {displayModels.map(({ modelId, alias, isHidden, source, isFree }) => { + {displayModels.map(({ modelId, alias, displayName, isHidden, source, isFree }) => { const fullModel = `${providerDisplayAlias}/${modelId}`; return ( { + setSavingEnabled(true); + try { + const response = await fetch("/api/providers", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + provider: "dahl", + apiKey: apiKey.trim(), + name: "Dahl Manual", + priority: 1, + isActive: true, + testStatus: "unknown", + }), + }); + const data = await response.json().catch(() => ({})); + if (!response.ok) { + throw new Error(data?.error?.message || data?.error || noAuthT("updateProviderFailed")); + } + notify.success(noAuthT("providerAdded", { provider: providerName })); + } catch (error) { + notify.error(error instanceof Error ? error.message : noAuthT("updateProviderFailed")); + } finally { + setSavingEnabled(false); + } + }, + [noAuthT, notify, providerName] + ); + const accountProviderName = ACCOUNT_PROVIDER_NAMES[providerId]; const host = providerProxy?.host; const providerProxyControl = supportsNoAuthProviderProxy(providerId) ? ( @@ -129,6 +159,8 @@ export default function NoAuthProviderControls({ } : undefined } + showManualKeyInput={providerId === "dahl"} + onManualApiKeyAdd={providerId === "dahl" ? handleManualApiKeyAdd : undefined} enabled={enabled} savingEnabled={savingEnabled} onEnabledChange={handleEnabledChange} diff --git a/src/app/(dashboard)/dashboard/providers/[id]/components/PassthroughModelRow.tsx b/src/app/(dashboard)/dashboard/providers/[id]/components/PassthroughModelRow.tsx index edbc55f93d..131aa926dd 100644 --- a/src/app/(dashboard)/dashboard/providers/[id]/components/PassthroughModelRow.tsx +++ b/src/app/(dashboard)/dashboard/providers/[id]/components/PassthroughModelRow.tsx @@ -23,6 +23,10 @@ export interface PassthroughModelRowProps { fullModel: string; provider: string; alias?: string | null; + // Upstream-provided friendly name (`name` in the /models payload). Gateways that + // expose opaque model ids (GUID-style presets) still send a readable name — show it + // instead of "Click to set alias" so the list is not a wall of hex. + displayName?: string | null; source?: string; isFree?: boolean; isHidden?: boolean; @@ -52,6 +56,7 @@ export default function PassthroughModelRow({ modelId, fullModel, alias, + displayName, source, isFree, isHidden, @@ -77,6 +82,11 @@ export default function PassthroughModelRow({ const [aliasValue, setAliasValue] = useState(alias || ""); const inputRef = useRef(null); + // Only useful when it actually differs from the id — otherwise we would just print + // the opaque id twice. + const upstreamName = + displayName && displayName !== modelId && displayName !== fullModel ? displayName : null; + useEffect(() => { if (editing && inputRef.current) { inputRef.current.focus(); @@ -151,10 +161,12 @@ export default function PassthroughModelRow({ ? providerText(t, "clickToEditAlias", "Alias: {alias} (click to edit)", { alias, }) - : providerText(t, "clickToSetAlias", "Click to set alias") + : upstreamName + ? `${upstreamName} — ${providerText(t, "clickToSetAlias", "Click to set alias")}` + : providerText(t, "clickToSetAlias", "Click to set alias") } > - {alias || providerText(t, "clickToSetAlias", "Click to set alias")} + {alias || upstreamName || providerText(t, "clickToSetAlias", "Click to set alias")} )} diff --git a/src/app/(dashboard)/dashboard/providers/[id]/components/modals/EditCompatibleNodeModal.tsx b/src/app/(dashboard)/dashboard/providers/[id]/components/modals/EditCompatibleNodeModal.tsx index ec0f1fcdf7..2d01e82b71 100644 --- a/src/app/(dashboard)/dashboard/providers/[id]/components/modals/EditCompatibleNodeModal.tsx +++ b/src/app/(dashboard)/dashboard/providers/[id]/components/modals/EditCompatibleNodeModal.tsx @@ -45,9 +45,11 @@ export default function EditCompatibleNodeModal({ const [checkKey, setCheckKey] = useState(""); const [checkModelId, setCheckModelId] = useState(""); const [validating, setValidating] = useState(false); - const [validationResult, setValidationResult] = useState< - null | { valid: boolean; error?: string | null; method?: string | null } - >(null); + const [validationResult, setValidationResult] = useState(null); const [showAdvanced, setShowAdvanced] = useState(false); useEffect(() => { @@ -117,6 +119,7 @@ export default function EditCompatibleNodeModal({ baseUrl: formData.baseUrl, apiKey: checkKey, type: isAnthropic ? "anthropic-compatible" : "openai-compatible", + apiType: !isAnthropic ? formData.apiType : undefined, compatMode: isCcCompatible ? "cc" : undefined, chatPath: formData.chatPath || (isCcCompatible ? CC_COMPATIBLE_DEFAULT_CHAT_PATH : ""), modelsPath: isCcCompatible ? "" : formData.modelsPath, diff --git a/src/app/(dashboard)/dashboard/providers/[id]/hooks/useApiKeySave.ts b/src/app/(dashboard)/dashboard/providers/[id]/hooks/useApiKeySave.ts index 620a80a63e..97b9974532 100644 --- a/src/app/(dashboard)/dashboard/providers/[id]/hooks/useApiKeySave.ts +++ b/src/app/(dashboard)/dashboard/providers/[id]/hooks/useApiKeySave.ts @@ -137,11 +137,17 @@ export function useApiKeySave({ } return null; } + // Even if the server returned an error, the connection may have been + // persisted (e.g. post-commit housekeeping failed after the DB write). + // Refresh the list so the UI picks it up on next render. + void fetchConnections(); const data = await res.json().catch(() => ({})); const errorMsg = data.error?.message || data.error || t("failedSaveConnection"); return errorMsg; } catch (error) { console.log("Error saving connection:", error); + // The connection may still have been persisted despite the network error. + void fetchConnections(); return t("failedSaveConnectionRetry"); } }, diff --git a/src/app/(dashboard)/dashboard/providers/components/AddCompatibleProviderModal.tsx b/src/app/(dashboard)/dashboard/providers/components/AddCompatibleProviderModal.tsx index ee107c63b6..7306298902 100644 --- a/src/app/(dashboard)/dashboard/providers/components/AddCompatibleProviderModal.tsx +++ b/src/app/(dashboard)/dashboard/providers/components/AddCompatibleProviderModal.tsx @@ -100,9 +100,11 @@ export default function AddCompatibleProviderModal({ const [checkKey, setCheckKey] = useState(""); const [checkModelId, setCheckModelId] = useState(""); const [validating, setValidating] = useState(false); - const [validationResult, setValidationResult] = useState< - null | { valid: boolean; error?: string | null; method?: string | null } - >(null); + const [validationResult, setValidationResult] = useState(null); const [showAdvanced, setShowAdvanced] = useState(false); const apiTypeOptions = useMemo( @@ -222,6 +224,7 @@ export default function AddCompatibleProviderModal({ apiKey: checkKey, type: defaults.type, }; + if (defaults.hasApiType) body.apiType = formData.apiType; if (defaults.hasModelsPath) body.modelsPath = formData.modelsPath || ""; if (defaults.compatMode) { body.compatMode = defaults.compatMode; diff --git a/src/app/(dashboard)/dashboard/providers/components/ProviderCard.tsx b/src/app/(dashboard)/dashboard/providers/components/ProviderCard.tsx index a1efc70ec6..4faea53e21 100644 --- a/src/app/(dashboard)/dashboard/providers/components/ProviderCard.tsx +++ b/src/app/(dashboard)/dashboard/providers/components/ProviderCard.tsx @@ -17,6 +17,7 @@ import { import { CategoryDot } from "./CategoryDot"; import { isCheaperInferenceProviderId, isKimiPartnerProviderId } from "../featuredProviders"; +import { useOpenRouterProviderStat } from "../context/openRouterProviderStatsContext"; interface ProviderStats { total?: number; @@ -228,6 +229,7 @@ const ProviderCard = forwardRef(function const isKimiPartner = isKimiPartnerProviderId(provider.id || providerId); const isCheaperInferencePartner = isCheaperInferenceProviderId(provider.id || providerId); const isSponsorPartner = isKimiPartner || isCheaperInferencePartner; + const openRouterStat = useOpenRouterProviderStat(provider.id || providerId); const codexServiceTierLabel = stats.codexServiceTier === "flex" ? providerText(t, "codexTierFlexLabel", "Flex") @@ -287,6 +289,36 @@ const ProviderCard = forwardRef(function ) : null; + const openRouterTooltipBits: string[] = []; + if (openRouterStat?.headquarters) openRouterTooltipBits.push(`HQ: ${openRouterStat.headquarters}`); + if (openRouterStat?.dataPolicy?.training === false) { + openRouterTooltipBits.push(providerText(t, "openRouterNoTraining", "Does not train on prompts")); + } + if (openRouterStat?.dataPolicy?.retainsPrompts === false) { + openRouterTooltipBits.push(providerText(t, "openRouterNoRetention", "Does not retain prompts")); + } + const openRouterTooltip = openRouterStat + ? providerText(t, "openRouterPopularityTooltip", "OpenRouter usage rank #{rank}", { + rank: openRouterStat.popularityRank, + }) + (openRouterTooltipBits.length ? ` — ${openRouterTooltipBits.join(" · ")}` : "") + : ""; + + // OpenRouter popularity badge — data refreshed daily from OpenRouter's + // provider directory + usage rankings (see src/lib/catalog/openrouterProviderStats.ts). + // Absent entirely for providers OpenRouter doesn't track; never affects routing. + const openRouterPopularityChip = openRouterStat ? ( + + trending_up + {providerText(t, "openRouterPopularityBadge", "OR #{rank}", { + rank: openRouterStat.popularityRank, + })} + + ) : null; + const dotLabels: Record = { free: tc("free"), "no-auth": t("noAuthLabel"), @@ -417,10 +449,12 @@ const ProviderCard = forwardRef(function isCompatible || isCcCompatible || isAnthropicCompatible || - isSponsorPartner) && ( + isSponsorPartner || + Boolean(openRouterStat)) && (
{kimiOfficialSupporterChip} {cheaperInferenceSupporterChip} + {openRouterPopularityChip} {provider.serviceKinds?.map((k) => ( = new Map(); +const Context = + createContext>(EMPTY_STATS_MAP); + +export function OpenRouterProviderStatsProvider({ + entries, + children, +}: { + entries: OpenRouterProviderStatsEntry[]; + children: ReactNode; +}) { + const bySlug = useMemo(() => new Map(entries.map((entry) => [entry.slug, entry])), [entries]); + return {children}; +} + +export function useOpenRouterProviderStat( + providerId: string | undefined +): OpenRouterProviderStatsEntry | undefined { + const bySlug = useContext(Context); + return providerId ? bySlug.get(providerId) : undefined; +} diff --git a/src/app/(dashboard)/dashboard/providers/hooks/useProviderUrlFilters.ts b/src/app/(dashboard)/dashboard/providers/hooks/useProviderUrlFilters.ts new file mode 100644 index 0000000000..02bd84d49c --- /dev/null +++ b/src/app/(dashboard)/dashboard/providers/hooks/useProviderUrlFilters.ts @@ -0,0 +1,100 @@ +"use client"; + +import { useEffect, useState } from "react"; +import type { ReadonlyURLSearchParams } from "next/navigation"; +import { + readProviderFiltersFromUrl, + syncProviderFiltersToUrl, +} from "../providerPageUtils"; +import { + readProviderDisplayModePreference, + type ProviderDisplayMode, +} from "../providerPageStorage"; + +interface UseProviderUrlFiltersArgs { + searchParams: ReadonlyURLSearchParams; + providerDisplayMode: ProviderDisplayMode; + setProviderDisplayMode: (mode: ProviderDisplayMode) => void; + searchQuery: string; + setSearchQuery: (value: string) => void; + modelSearchQuery: string; + setModelSearchQuery: (value: string) => void; + activeCategory: string | null; + setActiveCategory: (value: string | null) => void; + showFreeOnly: boolean; + setShowFreeOnly: (value: boolean) => void; + activeServiceKind: string | null; + setActiveServiceKind: (value: string | null) => void; +} + +/** + * useProviderUrlFilters — two-way sync between the providers dashboard filter + * state and the URL query string, so a filtered/searched view is bookmarkable + * and shareable. + * + * Hydration guard: the filter→URL sync effect must not write the URL before + * the initial URL→state read has applied, or a bookmarked view would be + * transiently clobbered by the default state on the first paint. + * + * Returns `displayModePreferenceReady`, which the caller also gates other + * display-mode-dependent effects on. + */ +export function useProviderUrlFilters({ + searchParams, + providerDisplayMode, + setProviderDisplayMode, + searchQuery, + setSearchQuery, + modelSearchQuery, + setModelSearchQuery, + activeCategory, + setActiveCategory, + showFreeOnly, + setShowFreeOnly, + activeServiceKind, + setActiveServiceKind, +}: UseProviderUrlFiltersArgs): { displayModePreferenceReady: boolean } { + const [displayModePreferenceReady, setDisplayModePreferenceReady] = useState(false); + const [filtersHydrated, setFiltersHydrated] = useState(false); + + useEffect(() => { + const urlMode = readProviderFiltersFromUrl(searchParams).displayMode; + setProviderDisplayMode(urlMode ?? readProviderDisplayModePreference()); + setDisplayModePreferenceReady(true); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [searchParams]); + + useEffect(() => { + const urlFilters = readProviderFiltersFromUrl(searchParams); + setSearchQuery(urlFilters.searchQuery ?? ""); + setModelSearchQuery(urlFilters.modelSearchQuery ?? ""); + setActiveCategory(urlFilters.category ?? null); + setShowFreeOnly(urlFilters.showFreeOnly ?? false); + setActiveServiceKind(urlFilters.mediaKind ?? null); + setFiltersHydrated(true); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [searchParams]); + + useEffect(() => { + if (!filtersHydrated || !displayModePreferenceReady) return; + syncProviderFiltersToUrl({ + searchQuery, + modelSearchQuery, + displayMode: providerDisplayMode, + category: activeCategory, + showFreeOnly, + mediaKind: activeServiceKind, + }); + }, [ + filtersHydrated, + displayModePreferenceReady, + searchQuery, + modelSearchQuery, + providerDisplayMode, + activeCategory, + showFreeOnly, + activeServiceKind, + ]); + + return { displayModePreferenceReady }; +} diff --git a/src/app/(dashboard)/dashboard/providers/page.tsx b/src/app/(dashboard)/dashboard/providers/page.tsx index cac4648d3b..c5f537a61e 100644 --- a/src/app/(dashboard)/dashboard/providers/page.tsx +++ b/src/app/(dashboard)/dashboard/providers/page.tsx @@ -22,6 +22,7 @@ import useEmailPrivacyStore from "@/store/emailPrivacyStore"; import { useNotificationStore } from "@/store/notificationStore"; import { useTranslations } from "next-intl"; import { useSyncedModelsByProvider } from "./hooks/useSyncedModelsByProvider"; +import { useProviderUrlFilters } from "./hooks/useProviderUrlFilters"; import { buildStaticProviderEntries, buildCompatibleProviderGroups, @@ -30,13 +31,12 @@ import { shouldFilterProviderEntriesForDisplayMode, shouldShowFirstProviderHint, shouldShowProviderSection, - syncSearchToUrl, upsertProviderNodeById, loadProviderPageData, } from "./providerPageUtils"; -import type { ProviderEntry } from "./providerPageUtils"; +import type { ProviderEntry, OpenRouterProviderStatsEntry } from "./providerPageUtils"; +import { OpenRouterProviderStatsProvider } from "./context/openRouterProviderStatsContext"; import { - readProviderDisplayModePreference, shouldSyncProviderDisplayMode, writeProviderDisplayModePreference, type ProviderDisplayMode, @@ -192,7 +192,6 @@ export default function ProvidersPage() { const [testingMode, setTestingMode] = useState(null); const [testResults, setTestResults] = useState(null); const [providerDisplayMode, setProviderDisplayMode] = useState("all"); - const [displayModePreferenceReady, setDisplayModePreferenceReady] = useState(false); const [oauthEnvRepairStatus, setOauthEnvRepairStatus] = useState<{ available: boolean; missingCount: number; @@ -202,6 +201,9 @@ export default function ProvidersPage() { const [modelSearchQuery, setModelSearchQuery] = useState(""); const liveModelsByProviderId = useSyncedModelsByProvider(); const [showFreeOnly, setShowFreeOnly] = useState(false); + const [openRouterProviderStats, setOpenRouterProviderStats] = useState< + OpenRouterProviderStatsEntry[] + >([]); const [activeCategory, setActiveCategory] = useState(null); // #4240: media-category (serviceKind) filter — composes with activeCategory, // search and configured-only. null = no serviceKind filter. @@ -228,21 +230,21 @@ export default function ProvidersPage() { const addCcCompatibleLabel = t("addCcCompatible"); const searchParams = useSearchParams(); - useEffect(() => { - setProviderDisplayMode(readProviderDisplayModePreference()); - setDisplayModePreferenceReady(true); - }, []); - - useEffect(() => { - const searchFromUrl = searchParams.get("search"); - if (searchFromUrl) { - setSearchQuery(searchFromUrl); - } - }, [searchParams]); - - useEffect(() => { - syncSearchToUrl(searchQuery); - }, [searchQuery]); + const { displayModePreferenceReady } = useProviderUrlFilters({ + searchParams, + providerDisplayMode, + setProviderDisplayMode, + searchQuery, + setSearchQuery, + modelSearchQuery, + setModelSearchQuery, + activeCategory, + setActiveCategory, + showFreeOnly, + setShowFreeOnly, + activeServiceKind, + setActiveServiceKind, + }); useEffect(() => { const fetchData = async () => { @@ -257,6 +259,7 @@ export default function ProvidersPage() { if (data.expirations) setExpirations(data.expirations); if (data.blockedProviders) setBlockedProviders(data.blockedProviders); setCodexGlobalServiceMode(getCodexGlobalServiceMode(data.settings)); + setOpenRouterProviderStats(data.openRouterProviderStats); } catch (error) { console.log("Error fetching data:", error); } finally { @@ -814,6 +817,7 @@ export default function ProvidersPage() { shouldShowFirstProviderHint(connections.length, searchQuery) && !showAllProviders; return ( +
{showFirstProviderHint && ( @@ -1816,6 +1820,7 @@ export default function ProvidersPage() {
)}
+ ); } diff --git a/src/app/(dashboard)/dashboard/providers/providerPageUtils.ts b/src/app/(dashboard)/dashboard/providers/providerPageUtils.ts index 90c42a8482..b48c434e60 100644 --- a/src/app/(dashboard)/dashboard/providers/providerPageUtils.ts +++ b/src/app/(dashboard)/dashboard/providers/providerPageUtils.ts @@ -15,7 +15,10 @@ import { getModelsByProviderId } from "@/shared/constants/models"; import { providerHasServiceKind } from "@/lib/providers/serviceKindIndex"; import { compareTr, matchesAnyToken, matchesSearch } from "@/shared/utils/turkishText"; import { fetchWithTimeout } from "@/shared/utils/fetchTimeout"; -import type { ProviderDisplayMode } from "./providerPageStorage"; +import { + parseProviderDisplayModePreference, + type ProviderDisplayMode, +} from "./providerPageStorage"; import { getFeaturedProviderRank } from "./featuredProviders"; export interface ProviderStatsSnapshot { @@ -71,22 +74,117 @@ export function shouldShowFirstProviderHint( } export function syncSearchToUrl(searchQuery: string): void { + syncProviderFiltersToUrl({ searchQuery }); +} + +/** All dashboard summary-chip category keys that are valid in `?cat=`. */ +const PROVIDER_CATEGORY_URL_VALUES = new Set([ + "oauth", + "ide", + "free", + "no-auth", + "upstream-proxy", + "apikey", + "compatible", + "webcookie", + "search", + "webfetch", + "audio", + "local", + "cloudagent", +]); + +/** Media/service-kind chip keys that are valid in `?media=`. */ +const PROVIDER_SERVICE_KIND_URL_VALUES = new Set([ + "image", + "video", + "music", + "tts", + "stt", + "embedding", +]); + +export interface ProviderFilterUrlState { + searchQuery?: string; + modelSearchQuery?: string; + displayMode?: ProviderDisplayMode; + category?: string | null; + showFreeOnly?: boolean; + mediaKind?: string | null; +} + +/** + * Reflect the providers dashboard filters in the URL query string via + * history.replaceState so a filtered view can be bookmarked/shared: + * + * ?search= provider-name / id search (#8624) + * ?model= model-name search + * ?mode=all|configured|compact display mode (All / Configured / Compact) + * ?cat= active summary category (oauth, ide, free, no-auth, …) + * ?media= media/service-kind filter (image, video, music, …) + * + * "Free Tier" is encoded as `?cat=free` (showFreeOnly). Params carrying no + * filter are removed so the URL stays canonical and shareable. + */ +export function syncProviderFiltersToUrl(state: ProviderFilterUrlState): void { if (typeof window === "undefined") return; const url = new URL(window.location.href); - const currentSearch = url.searchParams.get("search") || ""; + const params = url.searchParams; + let changed = false; - if (searchQuery.trim()) { - if (currentSearch !== searchQuery) { - url.searchParams.set("search", searchQuery); - window.history.replaceState(window.history.state, "", url.toString()); - } - } else if (url.searchParams.has("search")) { - url.searchParams.delete("search"); + const setOrRemove = (key: string, value: string | null | undefined) => { + const next = value != null && value.length > 0 ? value : null; + const current = params.get(key); + if (next === current) return; + if (next === null) params.delete(key); + else params.set(key, next); + changed = true; + }; + + setOrRemove("search", state.searchQuery?.trim()); + setOrRemove("model", state.modelSearchQuery?.trim()); + setOrRemove("mode", state.displayMode && state.displayMode !== "all" ? state.displayMode : null); + setOrRemove("cat", state.showFreeOnly ? "free" : state.category || null); + setOrRemove("media", state.mediaKind || null); + + if (changed) { window.history.replaceState(window.history.state, "", url.toString()); } } +/** Parse the provider dashboard filters back out of URL query params. */ +export function readProviderFiltersFromUrl(params: URLSearchParams): ProviderFilterUrlState { + const state: ProviderFilterUrlState = {}; + + const search = params.get("search"); + if (search) state.searchQuery = search; + + const model = params.get("model"); + if (model) state.modelSearchQuery = model; + + const mode = parseProviderDisplayModePreference(params.get("mode")); + if (mode) state.displayMode = mode; + + const category = params.get("cat"); + if (category && PROVIDER_CATEGORY_URL_VALUES.has(category)) { + if (category === "free") { + state.showFreeOnly = true; + state.category = null; + } else { + state.showFreeOnly = false; + state.category = category; + } + } + + const media = params.get("media"); + if (media && PROVIDER_SERVICE_KIND_URL_VALUES.has(media)) { + state.mediaKind = media; + } + + return state; +} + export function shouldShowProviderSection( category: string, activeCategory: string | null, @@ -452,6 +550,28 @@ export interface ProviderPageData { expirations: any | null; blockedProviders: string[] | null; settings: any | null; + /** OpenRouter-sourced popularity/identity enrichment, keyed by provider slug. Empty if the sync hasn't run yet or the fetch failed. */ + openRouterProviderStats: OpenRouterProviderStatsEntry[]; +} + +/** Mirrors ProviderPopularityEntry from src/lib/catalog/openrouterProviderStats.ts (kept local to avoid a server-only import from a client component). */ +export interface OpenRouterProviderStatsEntry { + slug: string; + displayName: string; + headquarters?: string; + statusPageUrl?: string | null; + byokEnabled?: boolean; + dataPolicy?: { + training?: boolean; + retainsPrompts?: boolean; + termsOfServiceURL?: string; + privacyPolicyURL?: string; + }; + iconUrl?: string; + modelCount: number; + totalTokens: number; + totalRequests: number; + popularityRank: number; } // Bound each first-paint request so a single stalled connection cannot freeze @@ -489,12 +609,14 @@ export async function loadProviderPageData( } }; - const [connectionsData, nodesData, expirationsData, settingsData] = await Promise.all([ - safeJson("/api/providers"), - safeJson("/api/provider-nodes"), - safeJson("/api/providers/expiration"), - safeJson("/api/settings", { cache: "no-store" }), - ]); + const [connectionsData, nodesData, expirationsData, settingsData, openRouterStatsData] = + await Promise.all([ + safeJson("/api/providers"), + safeJson("/api/provider-nodes"), + safeJson("/api/providers/expiration"), + safeJson("/api/settings", { cache: "no-store" }), + safeJson("/api/providers/openrouter-stats"), + ]); return { connections: Array.isArray(connectionsData?.connections) ? connectionsData.connections : [], @@ -505,5 +627,6 @@ export async function loadProviderPageData( ? settingsData.blockedProviders : null, settings: settingsData ?? null, + openRouterProviderStats: Array.isArray(openRouterStatsData?.data) ? openRouterStatsData.data : [], }; } diff --git a/src/app/(dashboard)/dashboard/settings/components/ModelCapabilityOverridesTab.tsx b/src/app/(dashboard)/dashboard/settings/components/ModelCapabilityOverridesTab.tsx index 04d182b6b5..a4d3c2cb14 100644 --- a/src/app/(dashboard)/dashboard/settings/components/ModelCapabilityOverridesTab.tsx +++ b/src/app/(dashboard)/dashboard/settings/components/ModelCapabilityOverridesTab.tsx @@ -5,7 +5,7 @@ import { useTranslations } from "next-intl"; import { Card, Button } from "@/shared/components"; import { matchesSearch } from "@/shared/utils/turkishText"; -type ModelOverrideKey = "max_token"; +type ModelOverrideKey = "context_length" | "max_input_tokens" | "max_output_tokens"; type StatusTone = "success" | "error" | "info"; type ModelOverrideTarget = { @@ -337,7 +337,7 @@ function ModelOverrideForm({ onSave: (target: string, key: ModelOverrideKey, value: number) => void; }) { const t = useTranslations("settings"); - const [key, setKey] = useState("max_token"); + const [key, setKey] = useState("context_length"); const [value, setValue] = useState(""); const numericValue = Number(value); const saveDisabled = !activeTarget || !Number.isInteger(numericValue) || numericValue <= 0; @@ -349,7 +349,9 @@ function ModelOverrideForm({ onChange={(event) => setKey(event.target.value as ModelOverrideKey)} className="sm:w-40 px-2 py-2 text-xs bg-bg-base border border-border rounded-md focus:outline-none focus:border-primary" > - + + + Promise; onMappingsSave: (agentId: string, mappings: MappingRow[]) => Promise; @@ -38,6 +39,7 @@ export function AgentCard({ target, agentState, serverRunning, + serverState, mappings, onDnsToggle, onMappingsSave, @@ -50,7 +52,9 @@ export function AgentCard({ const dnsEnabled = agentState?.dns_enabled ?? false; const setupCompleted = agentState?.setup_completed ?? false; - const certTrusted = agentState?.cert_trusted ?? false; + // Fix #8656 Issue A: Use server-level cert trust as fallback + // (one server cert applies to all agents; agentState.cert_trusted is never written to DB) + const certTrusted = agentState?.cert_trusted ?? serverState.certTrusted ?? false; const isInvestigating = target.viability === "investigating"; const getStatusBadge = () => { @@ -250,8 +254,11 @@ export function AgentCard({ target={target} agentState={agentState} serverRunning={serverRunning} + serverState={serverState} + currentMappings={mappings} onClose={() => setWizardOpen(false)} onDnsToggle={onDnsToggle} + onMappingsSave={onMappingsSave} /> )} diff --git a/src/app/(dashboard)/dashboard/tools/agent-bridge/components/AgentList.tsx b/src/app/(dashboard)/dashboard/tools/agent-bridge/components/AgentList.tsx index d2fca8c359..fa4365b385 100644 --- a/src/app/(dashboard)/dashboard/tools/agent-bridge/components/AgentList.tsx +++ b/src/app/(dashboard)/dashboard/tools/agent-bridge/components/AgentList.tsx @@ -4,13 +4,14 @@ import { useState } from "react"; import { useTranslations } from "next-intl"; import { AgentCard } from "./AgentCard"; import type { MitmTargetView } from "@/mitm/types"; -import type { AgentStateEntry, AgentMappingsMap } from "../AgentBridgePageClient"; +import type { AgentStateEntry, AgentMappingsMap, AgentBridgeServerState } from "../AgentBridgePageClient"; import type { MappingRow } from "./ModelMappingTable"; interface AgentListProps { targets: MitmTargetView[]; agentStates: AgentStateEntry[]; serverRunning: boolean; + serverState: AgentBridgeServerState; mappingsMap: AgentMappingsMap; onDnsToggle: (agentId: string, enabled: boolean) => Promise; onMappingsSave: (agentId: string, mappings: MappingRow[]) => Promise; @@ -26,6 +27,7 @@ export function AgentList({ targets, agentStates, serverRunning, + serverState, mappingsMap, onDnsToggle, onMappingsSave, @@ -130,6 +132,7 @@ export function AgentList({ target={target} agentState={stateByAgent[target.id]} serverRunning={serverRunning} + serverState={serverState} mappings={mappingsMap[target.id] ?? []} onDnsToggle={onDnsToggle} onMappingsSave={onMappingsSave} diff --git a/src/app/(dashboard)/dashboard/tools/agent-bridge/components/ModelMappingTable.tsx b/src/app/(dashboard)/dashboard/tools/agent-bridge/components/ModelMappingTable.tsx index 7d2feaef94..ac67e9a7b2 100644 --- a/src/app/(dashboard)/dashboard/tools/agent-bridge/components/ModelMappingTable.tsx +++ b/src/app/(dashboard)/dashboard/tools/agent-bridge/components/ModelMappingTable.tsx @@ -29,6 +29,18 @@ export function ModelMappingTable({ agentId, mappings, onSave }: ModelMappingTab setSelectorOpen(null); }; + const addMapping = () => { + setRows((prev) => [...prev, { source: "", target: "" }]); + }; + + const removeMapping = (index: number) => { + setRows((prev) => prev.filter((_, i) => i !== index)); + }; + + const updateSource = (index: number, source: string) => { + setRows((prev) => prev.map((r, i) => (i === index ? { ...r, source } : r))); + }; + const handleSave = async () => { setSaving(true); try { @@ -38,66 +50,101 @@ export function ModelMappingTable({ agentId, mappings, onSave }: ModelMappingTab } }; - if (rows.length === 0) { - return ( -

- {t("noMappings") || "No model mappings configured. Run setup wizard to auto-detect models."} -

- ); - } - return (
-
-
⭐ Star the repoFree — genuinely helps visibilityStar OmniRoute
🐙 GitHub SponsorsOne-off or monthly · zero platform feegithub.com/sponsors/diegosouzapw
🏢 Open CollectiveCompanies — issues an invoice/receipt · transparent booksopencollective.com/omniroute
☕ Ko-fiQuick one-off tip, no signup for the donorko-fi.com/diegosouzapw
🧋 Buy Me a CoffeeSmall, informal gesturebuymeacoffee.com/diegosouzapw
🖐 LiberapayRecurring · non-profit · open sourceliberapay.com/diegosouzapw
Codex CLI
Codex CLI
                           		 Cline
Cline
                           		 Kilo Code
Kilo Code
                           		Roo CodeRoo Code
Roo Code
                           		Zoo Code
Zoo Code
                           		 Continue
Continue
                           
- - - - - - - - {rows.map((row, i) => ( - - - - - ))} - -
- {t("sourceModel") || "Source model (agent native)"} - - {t("targetModel") || "Target model (OmniRoute)"} -
- {row.source} - - -
- + {rows.length === 0 ? ( +
+

+ {t("noMappingsDesc") || "No model mappings configured yet. Add mappings to route agent requests through OmniRoute."} +

+ +
+ ) : ( + <> +
+ + + + + + + + + + {rows.map((row, i) => ( + + + + + + ))} + +
+ {t("sourceModel") || "Source model (agent native)"} + + {t("targetModel") || "Target model (OmniRoute)"} +
+ updateSource(i, e.target.value)} + placeholder="e.g., gpt-4" + className="w-full rounded border border-border/40 bg-card px-2 py-1 text-xs font-mono focus:outline-none focus:ring-2 focus:ring-primary/50" + /> + + + + +
+
-
- -
+
+ + +
+ + )} {selectorOpen !== null && ( void; onDnsToggle: (agentId: string, enabled: boolean) => Promise; + onMappingsSave: (agentId: string, mappings: { source: string; target: string }[]) => Promise; } type Step = "verify" | "dns" | "mappings"; +interface DetectedModelsResponse { + agentId: string; + detectedModels: string[]; + requestCount: number; +} + /** * 3-step setup wizard for a single agent. * Step 1: Verify server + cert @@ -25,13 +34,19 @@ export function SetupWizard({ target, agentState, serverRunning, + serverState, + currentMappings, onClose, onDnsToggle, + onMappingsSave, }: SetupWizardProps) { const t = useTranslations("agentBridge"); const tc = useTranslations("common"); const [step, setStep] = useState("verify"); const [enablingDns, setEnablingDns] = useState(false); + const [detectedModels, setDetectedModels] = useState([]); + const [loadingModels, setLoadingModels] = useState(false); + const [selectedModels, setSelectedModels] = useState>(new Set()); useEffect(() => { const handler = (e: KeyboardEvent) => { @@ -41,7 +56,26 @@ export function SetupWizard({ return () => document.removeEventListener("keydown", handler); }, [onClose]); - const certTrusted = agentState?.cert_trusted ?? false; + // Fetch detected models when we reach the mappings step + useEffect(() => { + if (step === "mappings") { + setLoadingModels(true); + fetch(`/api/tools/agent-bridge/agents/${target.id}/detected-models`) + .then((res) => res.json()) + .then((data: DetectedModelsResponse) => { + setDetectedModels(data.detectedModels || []); + }) + .catch(() => { + setDetectedModels([]); + }) + .finally(() => { + setLoadingModels(false); + }); + } + }, [step, target.id]); + + // Fix #8656 Issue A: Use server-level cert trust as fallback + const certTrusted = agentState?.cert_trusted ?? serverState.certTrusted ?? false; const dnsEnabled = agentState?.dns_enabled ?? false; const handleEnableDns = async () => { @@ -54,6 +88,44 @@ export function SetupWizard({ } }; + const toggleModelSelection = (model: string) => { + setSelectedModels((prev) => { + const next = new Set(prev); + if (next.has(model)) { + next.delete(model); + } else { + next.add(model); + } + return next; + }); + }; + + const handleAddSelectedModels = async () => { + if (selectedModels.size === 0) return; + + // Merge detected models with existing mappings instead of replacing + // Filter out models that already exist in current mappings + const existingSources = new Set(currentMappings.map((m) => m.source)); + const newMappings = Array.from(selectedModels) + .filter((source) => !existingSources.has(source)) // Only add new ones + .map((source) => ({ + source, + target: "", // Will be selected later in the main card + })); + + // Combine existing + new mappings + const allMappings = [...currentMappings, ...newMappings]; + + try { + await onMappingsSave(target.id, allMappings); + // Wait a bit for the parent to refresh state before closing + await new Promise((resolve) => setTimeout(resolve, 300)); + onClose(); + } catch { + // Error handling in parent component + } + }; + const steps: { id: Step; label: string }[] = [ { id: "verify", label: t("wizardStep1Label") }, { id: "dns", label: t("wizardStep2Label") }, @@ -192,7 +264,50 @@ export function SetupWizard({ check_circle

{t("wizardStep3Success")}

-

{t("wizardStep3Desc")}

+ + {loadingModels ? ( +
+ progress_activity + Detecting models from intercepted traffic... +
+ ) : detectedModels.length > 0 ? ( +
+

+ Found {detectedModels.length} model{detectedModels.length !== 1 ? "s" : ""} in intercepted traffic. Select the ones you want to add: +

+
+ {detectedModels.map((model) => ( + + ))} +
+ {selectedModels.size > 0 && ( +

+ {selectedModels.size} model{selectedModels.size !== 1 ? "s" : ""} selected. + You'll map them to OmniRoute models in the next screen. +

+ )} +
+ ) : ( +
+

+ No models detected yet. Use {target.name} to make a request, then run this wizard again to auto-detect models from traffic. +

+

+ Or close this wizard and add mappings manually in the agent card. +

+
+ )} )} @@ -247,13 +362,25 @@ export function SetupWizard({ )} {step === "mappings" && ( - + <> + {detectedModels.length > 0 && selectedModels.size > 0 ? ( + + ) : ( + + )} + )} diff --git a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaCardGrid.tsx b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaCardGrid.tsx index ed524043c8..438e9f99c4 100644 --- a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaCardGrid.tsx +++ b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/QuotaCardGrid.tsx @@ -2,6 +2,9 @@ import type { ReactNode } from "react"; import QuotaCard from "./QuotaCard"; +import { PROVIDER_ORDER } from "./constants"; +import { compareProviderGroups } from "./utils"; +import { compareTr } from "@/shared/utils/turkishText"; interface Props { connections: any[]; @@ -47,50 +50,63 @@ export default function QuotaCardGrid({ }: Props) { if (connections.length === 0) return null; - // Group connections by provider, preserving the order from sortedConnections. + // Group connections by provider (preserving in-group order), then order the + // groups deterministically: PROVIDER_ORDER rank → label (locale-aware) → + // key. Without this the group order followed first-appearance in the + // status/reset-sorted list, so groups shuffled whenever quota refreshed. const groups = new Map(); for (const conn of connections) { const list = groups.get(conn.provider) ?? []; list.push(conn); groups.set(conn.provider, list); } + const orderedProviders = [...groups.keys()].sort((a, b) => + compareProviderGroups(a, b, { + providerOrder: PROVIDER_ORDER, + providerLabels, + compare: compareTr, + }) + ); return (
- {[...groups.entries()].map(([provider, conns]) => ( -
-

- {providerLabels[provider] || provider} - - ({conns.length} account{conns.length !== 1 ? "s" : ""}) - -

-
- {conns.map((conn) => ( - onRefresh(conn.id, conn.provider)} - onOpenCutoff={() => onOpenCutoff(conn)} - onOpenResetCredits={() => onOpenResetCredits?.(conn.id, conn.provider)} - onToggleActive={(nextActive) => onToggleActive(conn.id, nextActive)} - togglingActive={togglingActiveId === conn.id} - redeemingResetCredit={redeemingResetCreditId === conn.id} - loadingResetCredits={loadingResetCreditsId === conn.id} - quotaVisibility={quotaVisibility} - onHideQuota={onHideQuota ? (q) => onHideQuota(conn.provider, q) : undefined} - onShowQuota={onShowQuota ? (q) => onShowQuota(conn.provider, q) : undefined} - /> - ))} + {orderedProviders.map((provider) => { + const conns = groups.get(provider)!; + return ( +
+

+ {providerLabels[provider] || provider} + + ({conns.length} account{conns.length !== 1 ? "s" : ""}) + +

+
+ {conns.map((conn) => ( + onRefresh(conn.id, conn.provider)} + onOpenCutoff={() => onOpenCutoff(conn)} + onOpenResetCredits={() => onOpenResetCredits?.(conn.id, conn.provider)} + onToggleActive={(nextActive) => onToggleActive(conn.id, nextActive)} + togglingActive={togglingActiveId === conn.id} + redeemingResetCredit={redeemingResetCreditId === conn.id} + loadingResetCredits={loadingResetCreditsId === conn.id} + quotaVisibility={quotaVisibility} + onHideQuota={onHideQuota ? (q) => onHideQuota(conn.provider, q) : undefined} + onShowQuota={onShowQuota ? (q) => onShowQuota(conn.provider, q) : undefined} + /> + ))} +
-
- ))} + ); + })}
); } diff --git a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.tsx b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.tsx index e7c9dfed76..b70a126309 100644 --- a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.tsx +++ b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.tsx @@ -12,6 +12,7 @@ import { calculatePercentage, matchesProviderFilter, buildProviderOptions, + compareQuotaConnections, } from "./utils"; import Card from "@/shared/components/Card"; import { CardSkeleton } from "@/shared/components/Loading"; @@ -529,8 +530,12 @@ export default function ProviderLimits({ ); const sortedConnections = useMemo(() => { - return [...filteredConnections].sort( - (a, b) => (PROVIDER_ORDER[a.provider] || 99) - (PROVIDER_ORDER[b.provider] || 99) + return [...filteredConnections].sort((a, b) => + compareQuotaConnections(a, b, { + providerOrder: PROVIDER_ORDER, + providerLabels: PROVIDER_LABEL, + compare: compareTr, + }) ); }, [filteredConnections]); const visibleQuotaData = useVisibleQuotaData(sortedConnections, quotaData); @@ -650,9 +655,10 @@ export default function ProviderLimits({ return true; }); - // Inside each group we still want "critical first, then alert, then ok, - // then empty; tiebreak by soonest reset". Provider order between groups - // is enforced separately via PROVIDER_ORDER. + // Provider rank stays the outer sort key so each group keeps its fixed + // slot (mirrors dashboard/providers determinism); "critical first, then + // alert, then ok, then empty; tiebreak by soonest reset" only orders + // accounts inside their own provider group. const statusRank: Record = { critical: 0, alert: 1, @@ -660,14 +666,21 @@ export default function ProviderLimits({ empty: 3, all: 4, }; - return [...filtered].sort((a, b) => { - const sa = statusRank[statusByConnection[a.id] || "empty"]; - const sb = statusRank[statusByConnection[b.id] || "empty"]; - if (sa !== sb) return sa - sb; - const ra = getSoonestResetMs(visibleQuotaData[a.id]?.quotas); - const rb = getSoonestResetMs(visibleQuotaData[b.id]?.quotas); - return ra - rb; - }); + return [...filtered].sort((a, b) => + compareQuotaConnections(a, b, { + providerOrder: PROVIDER_ORDER, + providerLabels: PROVIDER_LABEL, + compare: compareTr, + accountCompare: (x, y) => { + const sx = statusRank[statusByConnection[x.id] || "empty"]; + const sy = statusRank[statusByConnection[y.id] || "empty"]; + if (sx !== sy) return sx - sy; + const rx = getSoonestResetMs(visibleQuotaData[x.id]?.quotas); + const ry = getSoonestResetMs(visibleQuotaData[y.id]?.quotas); + return rx - ry; + }, + }) + ); }, [ sortedConnections, tierByConnection, diff --git a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.tsx b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.tsx index 01750d89b0..66ecdbfa20 100644 --- a/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.tsx +++ b/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/utils.tsx @@ -620,3 +620,110 @@ export function buildProviderOptions( } return Array.from(seen).sort(compare); } + +// --- Deterministic quota-card ordering ------------------------------------- +// Mirrors the dashboard/providers rule (`providerPageUtils.ts:: +// sortProviderEntriesByName`): every level of ordering must end in a stable, +// data-independent tiebreak so cards never re-flow between refreshes. +// +// Before this, `visibleConnections` globally sorted ALL connections by +// status then soonest reset, and QuotaCardGrid grouped by first-appearance — +// so each provider group's position was decided by whichever of its accounts +// happened to sort first (status/reset change every refresh → groups +// shuffled). Provider rank is now a sort key again, so a group's position is +// fixed by PROVIDER_ORDER and account status/reset only orders accounts +// inside their own group. + +export interface QuotaOrderConnection { + id?: unknown; + provider?: unknown; + name?: unknown; + email?: unknown; + displayName?: unknown; +} + +/** Label/name key: providers-page `getProviderSortLabel` — case-insensitive display name. */ +function quotaConnLabel(conn: QuotaOrderConnection): string { + const name = typeof conn.name === "string" ? conn.name : ""; + const provider = typeof conn.provider === "string" ? conn.provider : ""; + return (name || provider).toLowerCase(); +} + +/** Technical tiebreak key: providers-page `providerId.localeCompare(...)` — ASCII on purpose. */ +function quotaConnTiebreak(conn: QuotaOrderConnection): string { + const email = typeof conn.email === "string" ? conn.email : ""; + const id = typeof conn.id === "string" ? conn.id : String(conn.id ?? ""); + return email || id; +} + +function providerRank(provider: unknown, providerOrder: Record): number { + const key = typeof provider === "string" ? provider : ""; + return providerOrder[key] ?? 99; +} + +/** + * Order connections for the quota card grid. Levels (first non-zero wins): + * 1. `PROVIDER_ORDER` rank — keeps each provider group glued to its fixed slot. + * 2. Provider label (locale-aware, case-insensitive) — orders unranked providers. + * 3. Provider key ASCII — deterministic tiebreak between aliased/equal labels. + * 4. `accountCompare` (optional) — in-group intent (critical-first, soonest reset). + * 5. Account label, then email/id ASCII — so equal-status accounts never shuffle. + */ +export function compareQuotaConnections( + a: T, + b: T, + opts: { + providerOrder: Record; + providerLabels?: Record; + accountCompare?: (a: T, b: T) => number; + compare?: (a: string, b: string) => number; + } +): number { + const cmp = opts.compare ?? ((x: string, y: string) => x.localeCompare(y)); + const labels = opts.providerLabels ?? {}; + + const ra = providerRank(a.provider, opts.providerOrder); + const rb = providerRank(b.provider, opts.providerOrder); + if (ra !== rb) return ra - rb; + + const pa = typeof a.provider === "string" ? a.provider : ""; + const pb = typeof b.provider === "string" ? b.provider : ""; + const providerLabelCmp = cmp(labels[pa] ?? pa, labels[pb] ?? pb); + if (providerLabelCmp !== 0) return providerLabelCmp; + if (pa !== pb) return pa < pb ? -1 : 1; + + if (opts.accountCompare) { + const acc = opts.accountCompare(a, b); + if (acc !== 0) return acc; + } + + const accountLabelCmp = cmp(quotaConnLabel(a), quotaConnLabel(b)); + if (accountLabelCmp !== 0) return accountLabelCmp; + const ta = quotaConnTiebreak(a); + const tb = quotaConnTiebreak(b); + return ta < tb ? -1 : ta > tb ? 1 : 0; +} + +/** + * Order provider group keys for rendering. Same provider-level rule as + * `compareQuotaConnections` (rank → label → key), used by QuotaCardGrid to + * place group headers deterministically. + */ +export function compareProviderGroups( + a: string, + b: string, + opts: { + providerOrder: Record; + providerLabels?: Record; + compare?: (a: string, b: string) => number; + } +): number { + const cmp = opts.compare ?? ((x: string, y: string) => x.localeCompare(y)); + const labels = opts.providerLabels ?? {}; + const ra = providerRank(a, opts.providerOrder); + const rb = providerRank(b, opts.providerOrder); + if (ra !== rb) return ra - rb; + const labelCmp = cmp(labels[a] ?? a, labels[b] ?? b); + if (labelCmp !== 0) return labelCmp; + return a < b ? -1 : a > b ? 1 : 0; +} diff --git a/src/app/(dashboard)/dashboard/webhooks/WebhooksPageClient.tsx b/src/app/(dashboard)/dashboard/webhooks/WebhooksPageClient.tsx index 1753fe958a..125ea3b497 100644 --- a/src/app/(dashboard)/dashboard/webhooks/WebhooksPageClient.tsx +++ b/src/app/(dashboard)/dashboard/webhooks/WebhooksPageClient.tsx @@ -24,6 +24,7 @@ export function WebhooksPageClient() { const [testingId, setTestingId] = useState(null); const [feedback, setFeedback] = useState(null); const [wizardOpen, setWizardOpen] = useState(false); + const [editingWebhook, setEditingWebhook] = useState(null); const [deleteTarget, setDeleteTarget] = useState(null); const [deleting, setDeleting] = useState(false); @@ -101,6 +102,21 @@ export function WebhooksPageClient() { } }; + const handleAddWebhook = () => { + setEditingWebhook(null); + setWizardOpen(true); + }; + + const handleEditWebhook = (webhook: WebhookItem) => { + setEditingWebhook(webhook); + setWizardOpen(true); + }; + + const handleCloseWizard = () => { + setWizardOpen(false); + setEditingWebhook(null); + }; + const handleDelete = async () => { if (!deleteTarget) return; setDeleting(true); @@ -134,7 +150,7 @@ export function WebhooksPageClient() {
+ {showManualKeyInput && ( +
+ setManualApiKey(e.target.value)} + placeholder="Paste API key..." + className="rounded-md border border-black/10 bg-bg px-2 py-1 text-xs dark:border-white/10" + disabled={addingManualKey || !enabled} + /> + + +
+ )} + {!showManualKeyInput && onManualApiKeyAdd && ( + + )} @@ -541,12 +603,14 @@ export default function NoAuthAccountCard({ )}