diff --git a/.env.example b/.env.example index 4cb877425c..d96a2c72d6 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. @@ -1338,6 +1364,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) @@ -1893,6 +1923,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. @@ -2225,6 +2264,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/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/Dockerfile b/Dockerfile index 1924fcef5a..47780263c6 100644 --- a/Dockerfile +++ b/Dockerfile @@ -179,8 +179,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..e0fba74af8 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**.
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/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/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/config/quality/file-size-baseline.json b/config/quality/file-size-baseline.json index eda3bfc98f..9b8280ec8a 100644 --- a/config/quality/file-size-baseline.json +++ b/config/quality/file-size-baseline.json @@ -172,7 +172,7 @@ "_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, @@ -190,7 +190,7 @@ "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, @@ -343,16 +343,16 @@ "_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": 1578, + "open-sse/executors/base.ts": 1623, "open-sse/executors/chatgpt-web.ts": 3241, "open-sse/executors/codex.ts": 1534, "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": 5020, + "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, @@ -363,8 +363,8 @@ "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": 1174, + "open-sse/services/rateLimitManager.ts": 1105, + "open-sse/translator/response/openai-responses.ts": 1204, "open-sse/utils/cursorAgentProtobuf.ts": 1505, "open-sse/utils/stream.ts": 2889, "src/app/(dashboard)/dashboard/HomePageClient.tsx": 1381, @@ -405,7 +405,7 @@ "src/sse/handlers/chat.ts": 1845, "src/sse/services/auth.ts": 2508, "tests/unit/account-fallback-service.test.ts": 1572, - "tests/unit/provider-validation-specialty.test.ts": 2980, + "tests/unit/provider-validation-specialty.test.ts": 2985, "open-sse/executors/hyperagent.ts": 1026 }, "_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).", @@ -416,5 +416,9 @@ "_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_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/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.yml b/docker-compose.yml index b20b067788..427b468ccd 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -58,7 +58,13 @@ services: 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/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/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/reference/ENVIRONMENT.md b/docs/reference/ENVIRONMENT.md index 1bf2f0f064..244d7024eb 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. | @@ -714,6 +718,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/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/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/providers/index.ts b/open-sse/config/providers/index.ts index bb693f912b..84594c924a 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"; @@ -446,4 +447,5 @@ export const REGISTRY: Record = { hcnsec: hcnsecProvider, promptql: promptqlProvider, hyperagent: hyperagentProvider, + unorouter: unorouterProvider, }; 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/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..4b44537ce4 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, @@ -40,6 +43,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 +66,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 +324,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": @@ -604,6 +673,10 @@ export class DefaultExecutor extends BaseExecutor { 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 +862,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/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 028590a09e..b74ec33890 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"; @@ -626,6 +633,7 @@ export async function handleChatCore({ sourceFormat, isResponsesEndpoint, nativeCodexPassthrough, + nativeXaiResponsesPassthrough, isDroidCLI, isOpencodeClient, copilotCompatibleReasoning, @@ -746,7 +754,9 @@ export async function handleChatCore({ sourceFormat, customModelTargetFormat, providerSpecificData: credentials?.providerSpecificData, + nativeXaiResponsesPassthrough, }); + const nativeResponsesPassthrough = nativeCodexPassthrough || nativeXaiResponsesPassthrough; const initialProviderRequest = body && typeof body === "object" && !Array.isArray(body) @@ -786,7 +796,7 @@ export async function handleChatCore({ provider, sourceFormat, targetFormat, - nativeCodexPassthrough, + nativeCodexPassthrough: nativeResponsesPassthrough, interceptSearchOverride, }); if (webSearchFallbackPlan.enabled) { @@ -804,7 +814,7 @@ export async function handleChatCore({ provider, sourceFormat, targetFormat, - nativeCodexPassthrough, + nativeCodexPassthrough: nativeResponsesPassthrough, interceptFetchOverride, }); if (webFetchFallbackPlan.enabled) { @@ -1084,6 +1094,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 @@ -1100,6 +1114,7 @@ export async function handleChatCore({ compressionSettings?.exclusions ); let promptCompressionEnabled = compressionSettingsResult.enabled && !compressionExcluded; + reactiveContextCompactionEnabled = compressionSettingsResult.enabled && !compressionExcluded; contextEditingEnabled = compressionSettingsResult.contextEditingEnabled; if (compressionExcluded) { void writeCompressionSkip( @@ -1749,7 +1764,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)` @@ -1809,27 +1824,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 @@ -1840,7 +1834,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, { @@ -1864,11 +1858,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 }) ); @@ -1877,13 +1866,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( @@ -1974,9 +1965,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 }; @@ -2065,20 +2064,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 }); } @@ -2611,7 +2613,7 @@ export async function handleChatCore({ const getExecutionCredentials = () => resolveExecutionCredentialsFor({ credentials, - nativeCodexPassthrough, + nativeCodexPassthrough: nativeResponsesPassthrough, endpointPath, targetFormat, provider, @@ -4191,14 +4193,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, @@ -4294,17 +4296,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/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/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..c4a0d5cc63 100644 --- a/open-sse/services/combo.ts +++ b/open-sse/services/combo.ts @@ -2188,7 +2188,10 @@ async function handleRoundRobinCombo({ 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. diff --git a/open-sse/services/combo/comboStructure.ts b/open-sse/services/combo/comboStructure.ts index 4bb3aabc33..554e162985 100644 --- a/open-sse/services/combo/comboStructure.ts +++ b/open-sse/services/combo/comboStructure.ts @@ -13,13 +13,10 @@ import { getModelContextLimit } from "../../../src/lib/modelCapabilities"; 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 { getTargetProvider, MAX_COMBO_DEPTH } from "./comboPredicates.ts"; import { evaluateContextLimit } from "./contextOverrideGate.ts"; @@ -323,7 +320,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); } 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/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/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/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/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 70b62a04e3..dca61a31fa 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 d7f107fbb7..e083787014 100644 --- a/open-sse/translator/index.ts +++ b/open-sse/translator/index.ts @@ -224,8 +224,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 @@ -258,11 +262,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 ab4182b746..67c4a9eb11 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, @@ -103,7 +104,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" && @@ -112,6 +113,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 @@ -531,6 +533,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 @@ -719,7 +724,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 a65a7fe86b..7f31eb99ea 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/; @@ -51,13 +52,18 @@ export function imageUrlToText(value: 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 112355381f..346c23ffa9 100644 --- a/open-sse/translator/response/openai-responses.ts +++ b/open-sse/translator/response/openai-responses.ts @@ -726,6 +726,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. @@ -1122,17 +1153,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/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/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/stream.ts b/open-sse/utils/stream.ts index 3958745e02..45b0d92c0c 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"; @@ -40,6 +41,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 { @@ -64,6 +70,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. @@ -115,13 +123,6 @@ type StreamCompletePayload = { ttft?: number | null; }; -type StreamFailurePayload = { - status: number; - message: string; - code?: string; - type?: string; -}; - type StreamOptions = { mode?: string; targetFormat?: string; @@ -226,8 +227,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 ); @@ -401,63 +402,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; @@ -709,11 +653,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 @@ -730,11 +672,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; @@ -819,6 +772,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", }); @@ -1595,6 +1549,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 @@ -1636,7 +1591,7 @@ export function createSSEStream(options: StreamOptions = {}) { parsed.delta.thinking ); } - if (restoredToolName) { + if (restoredToolName || thinkingSignatureInjected) { output = `data: ${JSON.stringify(parsed)}\n\n`; injectedUsage = true; } @@ -1724,6 +1679,7 @@ export function createSSEStream(options: StreamOptions = {}) { continue; } + const restoredOpenAIToolName = restoreOpenAIToolNames(parsed, toolNameMap); const idFixed = hadNonStringTopLevelId ? false : fixInvalidId(parsed); if (!hasValuableContent(parsed, FORMATS.OPENAI)) { @@ -1912,7 +1868,8 @@ export function createSSEStream(options: StreamOptions = {}) { needsReserialization || toolCallIdCoerced || hadNonStringToolCallId || - hadNonStringTopLevelId + hadNonStringTopLevelId || + restoredOpenAIToolName ) { output = `data: ${JSON.stringify(parsed)}\n\n`; injectedUsage = true; @@ -1978,6 +1935,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. @@ -2169,6 +2137,10 @@ export function createSSEStream(options: StreamOptions = {}) { if (streamTimedOut) { return; } + if (upstreamErrorForwarded) { + clearPendingRequestFromStream(); + return; + } try { const remaining = decoder.decode(); if (remaining) buffer += remaining; @@ -2242,6 +2214,8 @@ export function createSSEStream(options: StreamOptions = {}) { toResponsesCompletedWithToolCalls(parsed, [ ...passthroughToolCalls.values(), ]) as JsonRecord, + restoreOpenAIToolNames: (parsed: JsonRecord) => + restoreOpenAIToolNames(parsed, toolNameMap), }; for (const line of normalizedTailLines) { @@ -2289,36 +2263,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`; } @@ -2487,6 +2437,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..33328fa4fc 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", @@ -322,7 +323,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", 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..7bda5fa527 100644 --- a/scripts/build/assembleStandalone.mjs +++ b/scripts/build/assembleStandalone.mjs @@ -116,6 +116,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"], 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..c0450705cf 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, { @@ -348,6 +401,7 @@ async function ensureLlmlinguaOptionals() { 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-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/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 ( (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,49 @@ 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 +361,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() {