llm-switcher 1.6.8 → 1.6.10

package/CHANGELOG.md

@@ -1,9 +1,30 @@
 # Changelog — LLM Switcher
 
+## Release 1.6.10 — 2026-10-11
+
+- **`reasoning_content` replay.** On assistant tool-call turns, `auto` mode sends the earlier thinking as `reasoning_content`. `native` mode sends it only when the profile sets `replayReasoning: true`, because a strict OpenAI-compatible server can refuse the field. `off` mode never sends it.
+- **Codex to Anthropic with thinking.** If an open tool loop has no signed thinking, the request drops `thinking`. Anthropic refused this request with HTTP 400.
+- **Gemini schema and turn shape.** A nested object with no properties gets an optional `_placeholder` property. An untyped `const` becomes a string. Tool output with keys that start with `$` is wrapped as `{result: ...}`. A request never ends on a model turn: the proxy adds a user turn `Continue.`.
+- **Schema sanitizer.** Keywords with a `null` value and `pattern` values with lookaround are removed.
+- **Long tool names from Codex.** Names longer than 64 characters use the hashed shortener, so two long names do not collide.
+- **Repeated tool ids.** On the direct Anthropic route, a repeated `tool_use` id gets a suffix (`_2`, `_3`), and the matching `tool_result` changes with it.
+- **Context overflow errors.** Anthropic clients receive `invalid_request_error` with a message that starts with `prompt is too long`. Responses clients receive the code `context_length_exceeded`.
+
+## Release 1.6.9 — 2026-10-11
+
+- **Compaction keeps the tools.** A Codex compaction turn with tool history now keeps the `tools` list and sets `tool_choice` to `none`. Before, Anthropic and OpenAI chat upstreams refused this turn with HTTP 400.
+- **Foreign tool ids.** Tool ids that do not match `^[a-zA-Z0-9_-]+$` (for example `functions.Read:0`) are rewritten before they go to Anthropic. The rewrite is deterministic, so a replayed history gives the same id.
+- **Empty text blocks.** The direct Anthropic route removes empty `system` blocks and empty text blocks. Anthropic refused them with HTTP 400.
+- **Cut streams.** If an upstream stream closes without a finish reason and without `[DONE]`, the client receives an error. Before, the client received a completed turn with a partial tool call.
+- **Gemini `MALFORMED_FUNCTION_CALL`.** This finish reason is now an error, not an empty turn.
+- **Empty tool arguments.** An empty arguments string becomes `{}`, not `{"raw":""}`.
+
 ## Release 1.6.8 — 2026-10-09
 
-- **Dedicated Documentation & User Guide Hub (`#/docs`):** Integrated a full-featured, zero-dependency documentation viewer into the Web UI. Features a sticky scroll-spy table of contents, 1-click code copy with clipboard toast feedback, and 10 comprehensive guides covering edge gateway architecture, cross-platform installation, complete CLI cheatsheet, Blindfold TLS interception & CA safety guarantees, Antigravity CLI (`agy`) relay security, token optimizer interop with the Healer engine, Agent Skill (`SKILL.md`) & MCP server setup, Idle Compaction, Jev Goal Check gate, annotated `config.json` schema, and troubleshooting.
-- **Audit & Documentation Alignment:** Reconciled documentation across README, localized guides, agent skills, and Model Context Protocol definitions to strictly reflect v1.6.8 multi-active routing, zero-mutation invariants, and Bifrost passthrough dynamics.
+- **Reorganized Sidebar Navigation by Frequency of Use:** Reordered sidebar navigation to align strictly with developer operational workflows: 1. `Routes & Profiles` (daily configuration & profile switching), 2. `Request Inspector` (live request monitoring & debugging), 3. `Model Catalog` (model discovery & testing), 4. `System Doctor` (health checks, port conflicts & shims), 5. `Goal Check` (agent task completion verification & veto), 6. `Idle Compaction` (idle prefix compaction & cache metrics), and 7. `Docs & Guide` (reference manual & technical guides at the bottom of navigation).
+- **Dedicated intact Gateway Upstream Pooler Guide (`#doc-intact`):** Added a comprehensive, in-depth installation and operational manual for intact inside the Web UI Documentation hub (`#/docs`). Covers Zero-CGO Go build & npm global install, CLI flags, environment variables, systemd service unit setup, Cloudflare Tunnel ingress, TOTP zero-password authentication, account rotation (Round Robin 1 vs N reqs for prompt caching, Fallback, Standby), conversation stickiness, 429 Retry Shorter, Blacklist auto-healing, Bifrost passthrough, and Contract Lab synchronization.
+- **Dedicated Documentation & User Guide Hub (`#/docs`):** Integrated a full-featured, zero-dependency documentation viewer into the Web UI. Features a sticky scroll-spy table of contents, 1-click code copy with clipboard toast feedback, and 11 comprehensive guides covering edge gateway architecture, cross-platform installation, intact upstream pooler, complete CLI cheatsheet, Blindfold TLS interception & CA safety guarantees, Antigravity CLI (`agy`) relay security, token optimizer interop with the Healer engine, Agent Skill (`SKILL.md`) & MCP server setup, Idle Compaction, Jev Goal Check gate, annotated `config.json` schema, and troubleshooting.
+- **Audit & Documentation Alignment:** Reconciled documentation across README.md, README.vi.md, agent skills, and Model Context Protocol definitions to strictly reflect v1.6.8 multi-active routing, zero-mutation invariants, and Bifrost passthrough dynamics.
 
 ## Release 1.6.7 — 2026-10-09
 

package/README.md

@@ -597,6 +597,23 @@ reuse a stable prefix. Native Codex compaction remains Codex's own responsibilit
 When using intact, configure the profile with an authorized intact API key. Client User-Agent
 matching chooses the native protocol route; it does not replace upstream authentication.
 
+### Goal check (Jev System One evaluator veto)
+
+In Claude Code, when setting `/goal`, a specialized prompt-based evaluator reads the transcript and
+decides whether the condition was met. However, the evaluator only inspects text and can hallucinate
+completion — mistaking report editing or retracted audit findings for genuine code fixes (false completion).
+
+**Goal Check** intercepts the evaluator response before it reaches Claude Code, and queries the **Jev
+(System One)** decision model across 3 independent scoring axes:
+- `complete` (>= 0.90): The task condition is genuinely fulfilled.
+- `evidence` (>= 0.85): Concrete tool-execution results exist (test runs, builds, file edits).
+- `unfinished` (<= 0.10): No pending work, unaddressed errors, or missing verification.
+
+**Fail-Closed principle:** The gateway yields `ok: true` only when **both** the native evaluator and Jev
+agree. Any network error, timeout, missing evidence, or schema violation results in an automatic Veto
+(`ok: false`), instructing the agent to provide verifiable tool evidence. Configure via the **Goal Check**
+dashboard tab or `config.json` (`goalCheck`).
+
 ### Updates
 
 When npm has a newer release, the dashboard shows a notice. Click **Update now** in this notice. The gateway installs the release and starts the new code. Then the dashboard reloads. `switch update` does the same from a terminal.
@@ -749,7 +766,7 @@ of the routing.
       // A profile that serves Codex MUST have publicModels (see Codex-first setup).
       "publicModels": ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"], // official names for main, review, subagent
       "codexRoles": { "review": "gpt-5.6-sol" }, // optional: pair one role with another public name
-      "defaultModels": { "main": "gemini-3.8-flash", "review": "gemini-3.7-flash-medium", "subagent": "gemini-3.6-flash-low" }      "defaultModels": { "main": "gemini-3.8-flash", "review": "gemini-3.7-flash-medium", "subagent": "gemini-3.6-flash-low" },
+      "defaultModels": { "main": "gemini-3.8-flash", "review": "gemini-3.7-flash-medium", "subagent": "gemini-3.6-flash-low" }
     },
     "agy-default": {
       "name": "agy via intact",
@@ -763,6 +780,20 @@ of the routing.
     }
   },
   "debug": false,
+  "idleCompact": {
+    "enabled": false,
+    "codex": false,
+    "idleMinutes": 15,
+    "minBytes": 65536,
+    "model": ""
+  },
+  "goalCheck": {
+    "enabled": false,
+    "backend": "jev",
+    "baseURL": "https://intact.example.com/v1",
+    "apiKey": "sk-...",
+    "model": "typesafe/jev-latest"
+  },
   "contractLab": {
     "url": "https://intact.example.com",
     "apiKey": "sk-...",
@@ -791,10 +822,33 @@ Before it sends a sample, the gateway masks every string value with `x` of the s
 - `switch contract-probe [--model m]` sends six test requests per model and format through the gateway.
 - `switch contract-check` gets the open findings from intact and writes one test file for each lost field.
 
-### Self-improvement with intact
+### Self-improvement & Operation with intact (Recommended Upstream Pooler)
+
+[intact](https://github.com/louisphamdev/intact) is the credential proxy and multi-account pooler that this gateway recommends as its upstream. The two tools find and correct their own faults, in two closed loops.
+
+#### Quick Install for intact
+```bash
+# Global install via npm:
+npm install -g intact-gateway
+
+# Or compile from Go source (Zero-CGO, Pure-Go SQLite):
+git clone https://github.com/louisphamdev/intact.git && cd intact
+CGO_ENABLED=0 go build -o intact ./cmd/intact
+
+# Run intact with a specified SQLite database:
+intact -db /opt/intact/intact.db -addr 127.0.0.1:20142
+```
+
+#### Initial Setup for intact:
+1. **Enroll TOTP:** Run `intact -db /opt/intact/intact.db -show-totp` and add the setup key to Google Authenticator, 1Password, or Aegis.
+2. **Sign In to Dashboard:** Open `http://127.0.0.1:20142`, enter the 6-digit TOTP code (zero password storage).
+3. **Add Accounts:** Under **Providers → Add**, connect API keys (Groq, OpenRouter, Vertex, DeepSeek) or coding tool OAuth accounts (Claude Code, OpenAI Codex, Antigravity `agy`, GitHub Copilot).
+4. **Create API Key:** Under **Endpoint → API keys → Create**, create a key starting with `sk-intact-...`.
+5. **Connect from Switcher:** Open `switch ui` ➔ **Routes & Profiles** ➔ **+ Add Profile** ➔ Click **intact** or **agy on intact** template to auto-fill the optimized profile configuration.
 
-[intact](https://github.com/louisphamdev/intact) is the credential proxy that this gateway can use as its upstream. The two tools find and correct their own faults, in two loops.
+> 📖 **Comprehensive Manual:** For full CLI flags, environment variables, systemd service units, Cloudflare Tunnel ingress configuration, and deep troubleshooting, open the Web UI (`switch ui`) and navigate to the **Docs & Guide** tab (`#/docs`).
 
+#### Two Self-Improvement Loops:
 - **intact corrects what providers refuse.** It records every provider error and groups the errors that recur. For a fake 429, intact replays the failing request and removes the system prompt text in halves. It keeps the smallest text that the provider refuses as a filter in its database. Every machine gets the fix at once, and this gateway needs no update. Two examples: Antigravity answered a fake 429 to "You are Codex, an agent based on GPT-5" and to "You are a Claude agent, built on Anthropic's Claude Agent SDK".
 - **This gateway corrects what its converter loses.** With the contract lab on, the gateway sends masked samples to intact. intact compares each sample with the request that it received, and records each field that the conversion lost. `switch contract-check` writes one failing test for each finding, and the fix goes into the converter.
 
@@ -814,7 +868,8 @@ Because of this split, a provider fingerprint is never a rule in this gateway. I
 | `LLM_SWITCHER_CODE_ASSIST_TIMEOUT_MS` | Idle time of such a call, from 1000 to 2147483647 ms (default 300000). Before the answer starts, agy gets a 504. After it starts, the connection is cut. |
 | `LLM_SWITCHER_BIFROST_RETRY_MS` | Time before the gateway asks intact again after a failed Bifrost lookup (default 30000 ms). |
 | `x-llm-profile: <key>` header (alias `x-profile`) or `?profile=<key>` | Route a single request through a specific profile. An unknown key returns HTTP 400 instead of silently falling back. |
-| `profile.thinkingMode` | `auto` (default, for gateways like intact or 9Router): restore stripped thinking, inject a `<think>` guide for non-reasoning models, send `thinking` + `reasoning_effort`. `native` (strict OpenAI APIs): send only `reasoning_effort` when the client asks, never touch the prompt, use `max_completion_tokens`. `off`: never send reasoning parameters. |
+| `profile.thinkingMode` | `auto` (default, for gateways like intact or 9Router): restore stripped thinking, inject a `<think>` guide for non-reasoning models, send `thinking` + `reasoning_effort`, and send the earlier thinking as `reasoning_content` on assistant tool-call turns. `native` (strict OpenAI APIs): send only `reasoning_effort` when the client asks, never touch the prompt, use `max_completion_tokens`. Native mode never sends `reasoning_content` unless the profile sets `replayReasoning: true`. `off`: never send reasoning parameters. |
+| `profile.replayReasoning` | `true` sends the earlier thinking as `reasoning_content` on assistant tool-call turns in `native` mode. DeepSeek and Kimi thinking mode need it. The default is `false`. `auto` mode always sends the field, and `off` never sends it. The model name and the client request do not change this rule. |
 | `profile.thinkingEffort` | `auto` (default, caller/client controls effort), or an explicit override level: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`. Overrides client effort before routing upstream. Automatically maps to the nearest equivalent level accepted by the target upstream (e.g. OpenAI ceiling `high`, Anthropic `max`, Gemini budget bounds). In the Web UI, this selector dynamically hides with a guidance hint when Bifrost passthrough is active. |
 | `profile.endpoints.countTokens` | Override the Anthropic `count_tokens` URL. |
 | `profile.endpoints` | Override upstream URLs per format: `{ "openai-chat": "...", "anthropic": "...", "vertex": "https://.../models/{model}:{action}" }`. |

package/README.vi.md

@@ -592,6 +592,24 @@ thể nén prefix lớn hơn; các turn liên tiếp dùng lại prefix ổn đ
 Khi dùng intact, profile cần API key intact được cấp quyền. User-Agent chỉ chọn đường protocol
 gốc, không thay cho xác thực ở upstream.
 
+### Goal check (Cơ chế Veto Độc Lập Bằng Jev System One)
+
+Trong Claude Code, khi dùng lệnh `/goal`, hệ thống sử dụng một evaluator model chuyên biệt đọc
+transcript và đánh giá điều kiện đã hoàn thành hay chưa. Tuy nhiên, evaluator chỉ đọc văn bản và dễ
+bị ảo giác (hallucinate) — nhầm lẫn giữa việc *sửa báo cáo / rút finding* với việc *sửa code thật sự*
+(false completion).
+
+**Goal Check** chặn phản hồi của evaluator trước khi gửi về client, và gọi mô hình quyết định **Jev
+(System One)** chấm điểm độc lập trên 3 trục:
+- `complete` (>= 0.90): Toàn bộ công việc theo condition đã hoàn thành thực sự.
+- `evidence` (>= 0.85): Có kết quả thực thi tool trực tiếp chứng minh (chạy test, compile, sửa file).
+- `unfinished` (<= 0.10): Không còn công việc dang dở, lỗi chưa xử lý hoặc verification thiếu.
+
+**Nguyên tắc Fail-Closed:** Gateway chỉ trả về `ok: true` khi **cả hai bên** (evaluator gốc và Jev)
+đồng thuận. Mọi lỗi mạng, timeout, thiếu tool evidence hay schema không hợp lệ đều dẫn đến Veto
+(`ok: false`) tự động, yêu cầu agent tiếp tục thực hiện và cung cấp bằng chứng rõ ràng. Cấu hình tại
+tab **Goal Check** trên Web UI hoặc trường `goalCheck` trong `config.json`.
+
 ### Cập nhật
 
 Khi npm có bản mới, dashboard hiện một thông báo. Bấm **Update now** trong thông báo này. Gateway cài bản mới và chạy code mới. Sau đó dashboard tự tải lại. `switch update` làm việc tương tự từ terminal.
@@ -742,7 +760,7 @@ route.
       // Profile phục vụ Codex BẮT BUỘC có publicModels (xem Cấu hình ưu tiên Codex).
       "publicModels": ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"], // tên chính thức cho main, review, subagent
       "codexRoles": { "review": "gpt-5.6-sol" }, // không bắt buộc: ghép một vai trò với tên public khác
-      "defaultModels": { "main": "gemini-3.8-flash", "review": "gemini-3.7-flash-medium", "subagent": "gemini-3.6-flash-low" }      "defaultModels": { "main": "gemini-3.8-flash", "review": "gemini-3.7-flash-medium", "subagent": "gemini-3.6-flash-low" },
+      "defaultModels": { "main": "gemini-3.8-flash", "review": "gemini-3.7-flash-medium", "subagent": "gemini-3.6-flash-low" }
     },
     "agy-default": {
       "name": "agy qua intact",
@@ -756,6 +774,20 @@ route.
     }
   },
   "debug": false,
+  "idleCompact": {
+    "enabled": false,
+    "codex": false,
+    "idleMinutes": 15,
+    "minBytes": 65536,
+    "model": ""
+  },
+  "goalCheck": {
+    "enabled": false,
+    "backend": "jev",
+    "baseURL": "https://intact.example.com/v1",
+    "apiKey": "sk-...",
+    "model": "typesafe/jev-latest"
+  },
   "contractLab": {
     "url": "https://intact.example.com",
     "apiKey": "sk-...",
@@ -785,10 +817,33 @@ Trước khi gửi mẫu, gateway che mọi giá trị string bằng chuỗi `x`
 - `switch contract-probe [--model m]` gửi sáu request thử cho mỗi model và mỗi format qua gateway.
 - `switch contract-check` lấy các finding còn mở từ intact và ghi một file test cho mỗi field bị mất.
 
-### Tự cải thiện cùng intact
+### Tự cải thiện & Vận hành cùng intact (Upstream Pooler khuyên dùng)
+
+[intact](https://github.com/louisphamdev/intact) là proxy giữ credential và pool đa tài khoản mà gateway này khuyên dùng làm upstream. Hai công cụ tự tìm và tự sửa lỗi của nhau theo hai vòng khép kín.
+
+#### Cài đặt nhanh intact
+```bash
+# Cài đặt toàn cục qua npm:
+npm install -g intact-gateway
+
+# Hoặc biên dịch từ nguồn Go (Zero-CGO, Pure-Go SQLite):
+git clone https://github.com/louisphamdev/intact.git && cd intact
+CGO_ENABLED=0 go build -o intact ./cmd/intact
+
+# Khởi chạy intact với SQLite database chỉ định:
+intact -db /opt/intact/intact.db -addr 127.0.0.1:20142
+```
+
+#### Thiết lập ban đầu cho intact:
+1. **Lấy mã TOTP:** Chạy `intact -db /opt/intact/intact.db -show-totp` và quét/nhập setup key vào Google Authenticator, 1Password hoặc Aegis.
+2. **Đăng nhập Dashboard:** Mở trình duyệt tại `http://127.0.0.1:20142`, nhập mã 6 số TOTP (bảo mật tuyệt đối, không dùng mật khẩu văn bản).
+3. **Thêm tài khoản:** Vào mục **Providers → Add**, thêm các nhà cung cấp API key (Groq, OpenRouter, Vertex, DeepSeek) hoặc OAuth coding tools (Claude Code, OpenAI Codex, Antigravity `agy`, GitHub Copilot).
+4. **Tạo API key:** Vào **Endpoint → API keys → Create**, tạo key mới dạng `sk-intact-...`.
+5. **Định tuyến trên LLM Switcher:** Mở `switch ui` ➔ Tab **Routes & Profiles** ➔ Bấm **+ Add Profile** ➔ Chọn template **intact** hoặc **agy on intact** để tự động điền cấu hình tối ưu.
 
-[intact](https://github.com/louisphamdev/intact) là proxy giữ credential mà gateway này có thể dùng làm upstream. Hai công cụ tự tìm và tự sửa lỗi của nhau theo hai vòng.
+> 📖 **Cẩm nang toàn diện:** Để xem toàn bộ bảng tra cứu CLI flags, biến môi trường, file service systemd, cấu hình Cloudflare Tunnel và hướng dẫn vận hành chi tiết nhất, hãy mở Web UI (`switch ui`) và chuyển sang tab **Docs & Guide** (`#/docs`).
 
+#### 2 Vòng tự cải thiện giữa Switcher và intact:
 - **intact sửa những gì provider từ chối.** intact ghi lại mọi lỗi của provider và gom các lỗi lặp lại thành nhóm. Với 429 giả, intact gửi lại request lỗi và bỏ dần từng nửa system prompt. Đoạn nhỏ nhất mà provider từ chối được lưu thành filter trong database của intact. Mọi máy nhận bản sửa ngay, gateway này không cần cập nhật. Hai ví dụ: Antigravity trả 429 giả cho "You are Codex, an agent based on GPT-5" và cho "You are a Claude agent, built on Anthropic's Claude Agent SDK".
 - **Gateway này sửa những gì converter làm mất.** Khi bật contract lab, gateway gửi các mẫu đã che lên intact. intact so mỗi mẫu với request mà intact nhận được, rồi ghi lại mỗi field mà phép chuyển đổi làm mất. `switch contract-check` ghi một test đỏ cho mỗi finding, và bản sửa nằm trong converter.
 
@@ -808,7 +863,8 @@ Nhờ cách chia này, fingerprint của provider không bao giờ là rule tron
 | `LLM_SWITCHER_CODE_ASSIST_TIMEOUT_MS` | Thời gian chờ không có dữ liệu của lệnh gọi đó, từ 1000 tới 2147483647 ms (mặc định 300000). Trước khi câu trả lời bắt đầu, agy nhận 504. Sau khi đã bắt đầu, kết nối bị cắt. |
 | `LLM_SWITCHER_BIFROST_RETRY_MS` | Thời gian trước khi gateway hỏi lại intact sau một lần tra cứu Bifrost thất bại (mặc định 30000 ms). |
 | Header `x-llm-profile: <key>` (tên khác `x-profile`) hoặc `?profile=<key>` | Định tuyến riêng 1 request qua profile chỉ định. Key không tồn tại trả HTTP 400 thay vì âm thầm dùng profile khác. |
-| `profile.thinkingMode` | `auto` (mặc định, cho gateway như intact hoặc 9Router): phục hồi thinking bị xoá, inject hướng dẫn `<think>` cho model không có reasoning, gửi `thinking` + `reasoning_effort`. `native` (API OpenAI nghiêm ngặt): chỉ gửi `reasoning_effort` khi client yêu cầu, không sửa prompt, dùng `max_completion_tokens`. `off`: không bao giờ gửi tham số reasoning. |
+| `profile.thinkingMode` | `auto` (mặc định, cho gateway như intact hoặc 9Router): phục hồi thinking bị xoá, inject hướng dẫn `<think>` cho model không có reasoning, gửi `thinking` + `reasoning_effort`, và gửi lại thinking trước đó thành `reasoning_content` ở lượt assistant có tool call. `native` (API OpenAI nghiêm ngặt): chỉ gửi `reasoning_effort` khi client yêu cầu, không sửa prompt, dùng `max_completion_tokens`; không gửi `reasoning_content` trừ khi profile đặt `replayReasoning: true`. `off`: không bao giờ gửi tham số reasoning. |
+| `profile.replayReasoning` | `true`: ở chế độ `native`, gửi lại thinking trước đó thành `reasoning_content` ở lượt assistant có tool call. Thinking mode của DeepSeek và Kimi cần field này. Mặc định là `false`. `auto` luôn gửi, `off` không bao giờ gửi. Tên model và request của client không đổi quy tắc này. |
 | `profile.thinkingEffort` | `auto` (mặc định, client tự quyết định), hoặc đặt cố định mức override: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`. Ghi đè mức reasoning effort từ công cụ trước khi gửi lên upstream. Tự động ánh xạ về mức tương đương gần nhất mà upstream đích hỗ trợ (OpenAI trần `high`, Anthropic trần `max`, Gemini điều chỉnh `thinkingBudget`). Trên Web UI, tùy chọn này tự động ẩn cùng thông báo gợi ý khi profile bật chế độ Bifrost passthrough. |
 | `profile.endpoints.countTokens` | Ghi đè URL `count_tokens` của Anthropic. |
 | `profile.endpoints` | Ghi đè URL upstream theo từng format: `{ "openai-chat": "...", "anthropic": "...", "vertex": "https://.../models/{model}:{action}" }`. |