llm-switcher 1.6.7 → 1.6.9

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog — LLM Switcher
 
+## 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
+
+- **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
 
 - **Jev Goal Check Interception Gate:** Intercept Claude Code stopping condition evaluators (`/goal`) and verify task completion independently using Jev System One typed decision judgments (`complete`, `evidence`, `unfinished`). Fails closed on missing or unverified work, preventing premature completion claims when models merely edit reports rather than implementing fixes.

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.
 

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.
 

package/formats.mjs

@@ -39,6 +39,8 @@ function canonFinish(raw) {
   if (['length', 'max_tokens', 'max_output_tokens'].includes(r)) return 'length';
   if (['tool_calls', 'tool_call', 'function_call', 'function_calls', 'tool_use'].includes(r)) return 'tool_calls';
   if (['content_filter', 'safety', 'recitation', 'language', 'blocklist', 'prohibited_content', 'spii'].includes(r)) return 'content_filter';
+  // Gemini gave up on a tool call: as 'stop' the client would see a silent, empty turn.
+  if (r === 'malformed_function_call') return 'error';
   return 'stop';
 }
 
@@ -394,6 +396,7 @@ function parseArgs(v) {
   if (v === undefined || v === null) return {};
   if (typeof v === 'object') return v;
   if (typeof v === 'string') {
+    if (!v.trim()) return {};
     try { return JSON.parse(v); } catch { return { raw: v }; }
   }
   return {};
@@ -788,7 +791,9 @@ function responsesToIR(payload, { allowOpaqueCompaction = false } = {}) {
     ir.thinking = thinkingFromReasoningParam(payload.reasoning);
   }
   ir.responseFormat = responseFormatIR(payload.text?.format);
-  if (ir.compaction) { ir.tools = []; ir.toolChoice = 'none'; ir.responseFormat = null; }
+  // Tools stay declared: Anthropic refuses tool_use history without them, and OpenAI refuses
+  // tool_choice without tools. 'none' alone keeps the summary turn free of calls.
+  if (ir.compaction) { ir.toolChoice = ir.tools.length ? 'none' : null; ir.responseFormat = null; }
   return ir;
 }
 
@@ -1232,7 +1237,7 @@ function irToAnthropicBody(ir, model, opts = {}) {
     if (m.role === 'tool') {
       messages.push({
         role: 'user',
-        content: [{ type: 'tool_result', tool_use_id: m.toolCallId,
+        content: [{ type: 'tool_result', tool_use_id: safeToolId(m.toolCallId),
           content: m.images?.length ? [...contentToAnthropicBlocks(m.content), ...contentToAnthropicBlocks(m.images)] : m.content ?? '' }]
       });
       continue;
@@ -1240,7 +1245,7 @@ function irToAnthropicBody(ir, model, opts = {}) {
     if (m.role === 'assistant') {
       const blocks = contentToAnthropicBlocks(m.content).filter(b => b.type === 'text');
       for (const tc of (m.toolCalls || [])) {
-        blocks.push({ type: 'tool_use', id: tc.id, name: toolName(tc.name), input: parseArgs(tc.args) });
+        blocks.push({ type: 'tool_use', id: safeToolId(tc.id), name: toolName(tc.name), input: parseArgs(tc.args) });
       }
       if (blocks.length) messages.push({ role: 'assistant', content: blocks });
       continue;
@@ -1629,6 +1634,11 @@ function toAnthropicBlocks(content) {
   return Array.isArray(content) ? content.filter(Boolean) : [];
 }
 
+// Anthropic refuses a text block with no visible text ("text content blocks must be non-empty").
+function isBlankText(b) {
+  return b?.type === 'text' && !(typeof b.text === 'string' && b.text.trim());
+}
+
 function toolResultText(block) {
   const c = block.content;
   const text = typeof c === 'string' ? c
@@ -1643,9 +1653,20 @@ function healAnthropicPayload(payload) {
   const src = payload.messages.filter(m => m && (m.role === 'user' || m.role === 'assistant'));
   let changed = src.length !== payload.messages.length;
 
-  // Step 0: drop thinking blocks with fake signatures; merge adjacent user turns (so a tool_result split
-  // into a later turn can still be matched with its tool_use).
+  let system = payload.system;
+  if (Array.isArray(system) && system.some(isBlankText)) {
+    system = system.filter(b => !isBlankText(b));
+    changed = true;
+    notes.push('dropped empty text blocks');
+  }
+  const dropSystem = Array.isArray(system) ? !system.length : typeof system === 'string' && !system.trim();
+  if (dropSystem) changed = true;
+
+  // Step 0: drop thinking blocks with fake signatures and empty text blocks; rewrite foreign tool ids;
+  // merge adjacent user turns (so a tool_result split into a later turn can still be matched with its tool_use).
   const msgs = [];
+  const emptyTurn = () => ({ role: 'user', content: [{ type: 'text', text: '(empty)' }] });
+  let emptyUser = false;
   for (const m of src) {
     let content = m.content;
     if (m.role === 'assistant' && Array.isArray(content)) {
@@ -1655,11 +1676,31 @@ function healAnthropicPayload(payload) {
         notes.push('stripped placeholder-signed thinking blocks');
         content = kept;
       }
-      if (!content.length) {
+    }
+    if (Array.isArray(content)) {
+      const kept = [];
+      let renamed = false;
+      for (const b of content) {
+        if (isBlankText(b)) continue;
+        if (b?.type === 'tool_use' && b.id && safeToolId(b.id) !== b.id) { kept.push({ ...b, id: safeToolId(b.id) }); renamed = true; }
+        else if (b?.type === 'tool_result' && b.tool_use_id && safeToolId(b.tool_use_id) !== b.tool_use_id) { kept.push({ ...b, tool_use_id: safeToolId(b.tool_use_id) }); renamed = true; }
+        else kept.push(b);
+      }
+      if (kept.length !== content.length) notes.push('dropped empty text blocks');
+      if (renamed) notes.push('sanitized foreign tool ids');
+      if (renamed || kept.length !== content.length) {
         changed = true;
-        continue;
+        content = kept;
       }
     }
+    if (!toAnthropicBlocks(typeof content === 'string' ? content.trim() : content).length) {
+      // An emptied user turn still holds its place between two assistant turns, or at the end.
+      changed = true;
+      if (m.role === 'user') emptyUser = true;
+      continue;
+    }
+    if (emptyUser && m.role === 'assistant' && msgs[msgs.length - 1]?.role !== 'user') msgs.push(emptyTurn());
+    emptyUser = false;
     const last = msgs[msgs.length - 1];
     if (m.role === 'user' && last && last.role === 'user') {
       last.content = [...toAnthropicBlocks(last.content), ...toAnthropicBlocks(content)];
@@ -1668,6 +1709,7 @@ function healAnthropicPayload(payload) {
     }
     msgs.push({ ...m, content });
   }
+  if (emptyUser && msgs[msgs.length - 1]?.role !== 'user') msgs.push(emptyTurn());
 
   // Steps 1-3: pair up tool_use / tool_result.
   const out = [];
@@ -1723,6 +1765,8 @@ function healAnthropicPayload(payload) {
   }
 
   let body = { ...payload, messages: out };
+  if (dropSystem) delete body.system;
+  else if (system !== payload.system) body.system = system;
 
   // Step 5: thinking + an in-progress tool loop whose last assistant turn doesn't open with thinking.
   const thinkingOn = payload.thinking && payload.thinking.type && payload.thinking.type !== 'disabled';
@@ -1887,6 +1931,7 @@ function normalizeUpstream(parsed, outFormat) {
   for (const tc of smartToolCalls(node)) ev.tools.push(chunkToolFull(tc));
   const f = smartFinish(parsed, choice);
   if (f) ev.finish = canonFinish(f);
+  if (ev.finish === 'error') { ev.finish = null; ev.error = `Upstream finished with ${f}`; }
   return ev;
 }
 
@@ -2054,6 +2099,17 @@ function rand(n = 6) {
   return s.slice(0, n);
 }
 
+// Anthropic takes tool ids matching ^[a-zA-Z0-9_-]+$ only (Kimi sends "functions.Read:0"). The map must
+// stay pure: a replayed history has to give the same id, and the hash keeps "a.b" and "a:b" apart.
+function safeToolId(id) {
+  const s = String(id ?? '');
+  if (!s) return `toolu_${rand(24)}`;
+  if (/^[a-zA-Z0-9_-]+$/.test(s)) return s;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193);
+  return `${s.replace(/[^a-zA-Z0-9_-]/g, '_')}_${(h >>> 0).toString(36)}`;
+}
+
 function anthropicStopReason(canonical, hasTools) {
   if (canonical === 'length') return 'max_tokens';
   if (hasTools) return 'tool_use';
@@ -2147,7 +2203,7 @@ function createAnthropicStream(emit, model, opts = {}) {
         const fixed = vocab ? vocab.name(tc.name) : tc.name;
         const isShort = Boolean(vocab && typeof vocab.isShortened === 'function' && vocab.isShortened(tc.name));
         st = {
-          index: nextIndex++, id: tc.id || `toolu_${rand(24)}`, name: fixed || 'tool', closed: false,
+          index: nextIndex++, id: safeToolId(tc.id), name: fixed || 'tool', closed: false,
           // Shortened names keep caller's schema; ToolSearch query aliases still need restoring.
           buffered: '', held: Boolean(vocab && ((fixed && fixed !== tc.name && !isShort) || vocab.needsArgsRewrite?.(tc.name)))
         };
@@ -2212,7 +2268,7 @@ function buildAnthropicMessage({ model, think, text, tools, finish, prompt, comp
     // The name is written in the vocabulary the caller declared. A name it already uses is not
     // touched, so the whole layer costs nothing on a turn where the model agreed with the list.
     const fixed = repairToolCall(tc, vocab);
-    content.push({ type: 'tool_use', id: tc.id || `toolu_${rand(24)}`, name: fixed.name, input: parseArgs(fixed.args) });
+    content.push({ type: 'tool_use', id: safeToolId(tc.id), name: fixed.name, input: parseArgs(fixed.args) });
   }
   if (!content.length) content.push({ type: 'text', text: '' });
   const p = prompt || 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-switcher",
-  "version": "1.6.7",
+  "version": "1.6.9",
   "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code and Codex, with OpenAI-compatible, Anthropic and Vertex upstreams",
   "keywords": [
     "llm",

package/proxy.mjs

@@ -831,8 +831,9 @@ function buildUpstreamRequest(profile, outFormat, ir, mappedModel, req, slot = n
 async function pumpStream(upstreamRes, { normalize, col, renderer, splitter, signal, sink, tag }) {
   let streamError = null;
   let events = 0;
+  const framing = {};
   try {
-    for await (const parsed of readUpstreamPayloads(upstreamRes)) {
+    for await (const parsed of readUpstreamPayloads(upstreamRes, framing)) {
       events++;
       const ev = normalize(parsed);
       col.add(ev);
@@ -850,6 +851,8 @@ async function pumpStream(upstreamRes, { normalize, col, renderer, splitter, sig
       await drained(sink, signal);
     }
     if (!streamError && events === 0) streamError = 'Upstream returned an empty stream';
+    // A clean close with no finish reason is a cut: rendered as done, it hands the client half a tool call.
+    else if (!streamError && col.finish == null && !framing.done) streamError = 'Upstream stream ended before a finish reason';
   } catch (streamErr) {
     if (!signal.aborted) {
       console.error(`[${tag}] Stream error:`, streamErr.message);

package/tests/compaction.e2e.test.mjs

@@ -21,7 +21,7 @@ async function fixture(t) {
       if (body.stream) {
         res.setHeader('content-type', 'text/event-stream');
         res.write(`data: {"choices":\ndata: [{"index":0,"delta":{"content":"${summary}"}}]}\n\n`);
-        if (!truncate) res.write(`data: {"choices":[{"index":0,"delta":{},"finish_reason":"${finish}"}]}\n\ndata: [DONE]\n\n`);
+        if (!truncate) res.write(`data: {"choices":[{"index":0,"delta":{},"finish_reason":${JSON.stringify(finish)}}]}\n\ndata: [DONE]\n\n`);
         res.end();
       } else { res.setHeader('content-type', 'application/json'); res.end(JSON.stringify({ choices: [{ message: { content: summary }, finish_reason: finish }] })); }
     });
@@ -77,3 +77,19 @@ test('WS compaction replays the compacted state through previous_response_id', {
   assert.match(JSON.stringify(f.received.at(-1).messages), /KEEP_DECISION_7391.*NEXT_TURN/);
   assert.doesNotMatch(JSON.stringify(f.received.at(-1).messages), /ORIGINAL_HISTORY/);
 });
+test('stream cut without finish_reason renders error, not completed', { timeout: 20000 }, async t => {
+  const f = await fixture(t); f.failure('stop', true);
+  const codex = events(await (await f.send({ model: 'm', stream: true, input: [{ role: 'user', content: 'hi' }] })).text());
+  assert.ok(codex.some(e => e.type === 'response.failed'), JSON.stringify(codex));
+  assert.ok(!codex.some(e => e.type === 'response.completed'), JSON.stringify(codex));
+  const claude = await fetch(`http://127.0.0.1:${f.port}/v1/messages`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-profile': 'p1' },
+    body: JSON.stringify({ model: 'm', max_tokens: 64, stream: true, messages: [{ role: 'user', content: 'hi' }] }) });
+  const claudeEvents = events(await claude.text());
+  assert.ok(claudeEvents.some(e => e.type === 'error'), JSON.stringify(claudeEvents));
+  assert.ok(!claudeEvents.some(e => e.type === 'message_stop'), JSON.stringify(claudeEvents));
+});
+test('stream closed by [DONE] without finish_reason still completes', { timeout: 20000 }, async t => {
+  const f = await fixture(t); f.failure(null);
+  const codex = events(await (await f.send({ model: 'm', stream: true, input: [{ role: 'user', content: 'hi' }] })).text());
+  assert.ok(codex.some(e => e.type === 'response.completed'), JSON.stringify(codex));
+});

package/tests/formats.test.mjs

@@ -12,7 +12,7 @@ import {
   createChatStream, buildChatMessage, chatFinish, anthropicStopReason,
   smartText, smartReasoning, sanitizeJsonSchema, normalizeUpstream, buildVertexMessage,
   createCodeAssistStream,
-  budgetToEffort, effortToBudget, normalizeEffort, capEffort, mapEquivalentEffort, EFFORT_LEVELS
+  budgetToEffort, effortToBudget, normalizeEffort, capEffort, mapEquivalentEffort, EFFORT_LEVELS, parseArgs, buildAnthropicMessage
 } from '../formats.mjs';
 import { assertValidAnthropicEvents } from './helpers.mjs';
 
@@ -1053,3 +1053,117 @@ test('thinkingEffort profile option overrides client effort across all upstreams
   const autoChat = emitUpstreamBody('openai-chat', clientIR, 'gpt-5', { thinkingEffort: 'auto' });
   assert.equal(autoChat.reasoning_effort, 'low');
 });
+
+test('compaction_trigger with tool history keeps tools and forces tool_choice none', () => {
+  const ir = responsesToIR({
+    model: 'm', tools: [fn('Read')], text: { format: { type: 'json_object' } }, input: [
+      { role: 'user', content: 'read it' },
+      { type: 'function_call', call_id: 'c1', name: 'Read', arguments: '{"p":"a"}' },
+      { type: 'function_call_output', call_id: 'c1', output: 'data' },
+      { type: 'compaction_trigger' }
+    ]
+  });
+  assert.equal(ir.toolChoice, 'none');
+  assert.equal(ir.responseFormat, null);
+  const chat = irToChatBody(ir, 'gpt-x');
+  assert.equal(chat.tools?.length, 1);
+  assert.equal(chat.tool_choice, 'none');
+  assert.equal(chat.response_format, undefined);
+  const anthropic = irToAnthropicBody(ir, 'claude-x');
+  assert.equal(anthropic.tools?.length, 1);
+  assert.deepEqual(anthropic.tool_choice, { type: 'none' });
+  assert.ok(anthropic.messages.some(m => m.content.some(b => b.type === 'tool_use')));
+  const vertex = irToVertexBody(ir, 'gemini-x');
+  assert.equal(vertex.tools?.[0].functionDeclarations.length, 1);
+  assert.equal(vertex.toolConfig.functionCallingConfig.mode, 'NONE');
+  // With no tools at all there is nothing to switch off: tool_choice without tools is refused.
+  const bare = responsesToIR({ model: 'm', input: [{ role: 'user', content: 'hi' }, { type: 'compaction_trigger' }] });
+  assert.equal(irToChatBody(bare, 'gpt-x').tool_choice, undefined);
+  assert.equal(irToAnthropicBody(bare, 'claude-x').tool_choice, undefined);
+});
+
+test('anthropic emitters sanitize foreign tool ids consistently', () => {
+  const foreign = 'functions.Read:0';
+  const valid = /^[a-zA-Z0-9_-]+$/;
+  const history = [
+    { role: 'user', content: 'go' },
+    { role: 'assistant', content: [{ type: 'tool_use', id: foreign, name: 'Read', input: {} }] },
+    { role: 'user', content: [{ type: 'tool_result', tool_use_id: foreign, content: 'ok' }] }
+  ];
+  const ir = anthropicToIR({ model: 'x', tools: [{ name: 'Read', input_schema: { type: 'object', properties: {} } }], messages: history });
+  const body = irToAnthropicBody(ir, 'claude-x');
+  const use = body.messages[1].content.find(b => b.type === 'tool_use');
+  assert.match(use.id, valid);
+  assert.equal(body.messages[2].content[0].tool_use_id, use.id);
+  assert.equal(irToAnthropicBody(ir, 'claude-x').messages[1].content[0].id, use.id, 'a replayed history maps identically');
+
+  const message = buildAnthropicMessage({ model: 'x', tools: [{ id: foreign, name: 'Read', args: '{}' }], finish: 'tool_calls' });
+  assert.equal(message.content[0].id, use.id);
+  const events = [];
+  const stream = createAnthropicStream((e, d) => events.push(d), 'x');
+  stream.start();
+  stream.tool({ index: 0, id: foreign, name: 'Read', args: '{}' });
+  stream.finish('tool_calls');
+  assert.equal(events.find(e => e.type === 'content_block_start').content_block.id, use.id);
+
+  const healed = healAnthropicPayload({ model: 'claude', messages: history });
+  assert.equal(healed.changed, true);
+  assert.equal(healed.payload.messages[1].content[0].id, use.id);
+  assert.equal(healed.payload.messages[2].content[0].tool_use_id, use.id);
+
+  // Two ids that differ only in an invalid character must not collide, and a valid id is kept.
+  const ids = ['a.b', 'a:b', 'a_b'].map(id => buildAnthropicMessage({ model: 'x', tools: [{ id, name: 'f', args: '{}' }] }).content[0].id);
+  assert.equal(new Set(ids).size, 3);
+  assert.equal(ids[2], 'a_b');
+  assert.match(buildAnthropicMessage({ model: 'x', tools: [{ id: '', name: 'f', args: '{}' }] }).content[0].id, valid);
+});
+
+test('healAnthropicPayload drops empty system and empty text blocks', () => {
+  const nonEmpty = msgs => msgs.every(m => typeof m.content === 'string' ? m.content.trim()
+    : m.content.length && m.content.every(b => b.type !== 'text' || b.text.trim()));
+  const alternates = msgs => msgs[0].role === 'user' && msgs.every((m, i) => !i || m.role !== msgs[i - 1].role);
+  const r = healAnthropicPayload({
+    model: 'claude', system: [{ type: 'text', text: '' }], messages: [
+      { role: 'user', content: [{ type: 'text', text: '' }, { type: 'text', text: 'hi' }] },
+      { role: 'assistant', content: [{ type: 'text', text: ' ' }, { type: 'tool_use', id: 't1', name: 'f', input: {} }] },
+      { role: 'user', content: [{ type: 'tool_result', tool_use_id: 't1', content: 'ok' }] },
+      { role: 'assistant', content: [{ type: 'text', text: '' }] },
+      { role: 'user', content: [{ type: 'text', text: 'next' }] }
+    ]
+  });
+  assert.equal(r.changed, true);
+  assert.equal('system' in r.payload, false);
+  assert.ok(nonEmpty(r.payload.messages), JSON.stringify(r.payload.messages));
+  assert.ok(alternates(r.payload.messages), JSON.stringify(r.payload.messages));
+  assert.deepEqual(r.payload.messages.at(-1).content.map(b => b.type), ['tool_result', 'text']);
+
+  // A user turn that empties out between two assistant turns, or at the end, keeps its place.
+  const r2 = healAnthropicPayload({
+    model: 'claude', system: [{ type: 'text', text: 'sys' }, { type: 'text', text: '' }], messages: [
+      { role: 'user', content: 'go' },
+      { role: 'assistant', content: 'a' },
+      { role: 'user', content: [{ type: 'text', text: '' }] },
+      { role: 'assistant', content: 'b' },
+      { role: 'user', content: '' }
+    ]
+  });
+  assert.deepEqual(r2.payload.system, [{ type: 'text', text: 'sys' }]);
+  assert.ok(nonEmpty(r2.payload.messages), JSON.stringify(r2.payload.messages));
+  assert.ok(alternates(r2.payload.messages), JSON.stringify(r2.payload.messages));
+  assert.equal(r2.payload.messages.length, 5);
+  assert.equal(r2.payload.messages.at(-1).role, 'user');
+});
+
+test("parseArgs('') returns {}", () => {
+  assert.deepEqual(parseArgs(''), {});
+  assert.deepEqual(parseArgs('  \n'), {});
+  assert.deepEqual(parseArgs('{"a":1}'), { a: 1 });
+});
+
+test('Gemini MALFORMED_FUNCTION_CALL finish is an error, not stop', () => {
+  const ev = normalizeUpstream({ candidates: [{ content: { parts: [] }, finishReason: 'MALFORMED_FUNCTION_CALL' }] }, 'vertex');
+  assert.equal(ev.finish, null);
+  assert.match(String(ev.error), /MALFORMED_FUNCTION_CALL/);
+  const chat = normalizeUpstream({ choices: [{ delta: {}, finish_reason: 'malformed_function_call' }] }, 'openai-chat');
+  assert.match(String(chat.error), /malformed_function_call/i);
+});

package/tests/ui.test.mjs

@@ -115,3 +115,44 @@ test('the 1M switch is gone from the slots, the card and the payload', () => {
   assert.doesNotMatch(functionBody('collectCurrentSlotValues'), /model1M\s*[,}]/);
   assert.doesNotMatch(html, /profilePayload\.model1M/);
 });
+
+test('documentation tab is properly integrated with sidebar navigation, sections, and helpers', () => {
+  // Sidebar navigation link
+  assert.match(html, /<a class="nav-link" href="#\/docs" data-nav="docs"/);
+  // View panel exists
+  assert.match(html, /<div id="view-docs" class="view-panel"/);
+  // Table of Contents navigation exists
+  assert.match(html, /<nav class="docs-toc" id="docsToc"/);
+  
+  // All 11 core sections exist
+  const expectedSections = [
+    'doc-overview',
+    'doc-install',
+    'doc-intact',
+    'doc-cli',
+    'doc-blindfold',
+    'doc-agy',
+    'doc-optimizers',
+    'doc-agent-mcp',
+    'doc-advanced',
+    'doc-config',
+    'doc-faq'
+  ];
+  for (const s of expectedSections) {
+    assert.match(html, new RegExp(`id="${s}"`), `Missing section ${s} in ui.html`);
+    assert.match(html, new RegExp(`href="#${s}"`), `Missing TOC link for ${s} in ui.html`);
+  }
+
+  // Hash router handles 'docs'
+  assert.match(html, /validRoutes\s*=\s*\[[^\]]*'docs'[^\]]*\]/);
+  assert.match(html, /activeRoute === 'docs'/);
+
+  // Helper functions exist
+  assert.match(html, /function copyDocCode\(/);
+  assert.match(html, /function initDocsScrollSpy\(/);
+});
+
+test('sidebar menu is arranged logically by frequency of use', () => {
+  const navMatches = [...html.matchAll(/data-nav="([^"]+)"/g)].map(m => m[1]);
+  assert.deepEqual(navMatches, ['routes', 'logs', 'models', 'doctor', 'goal-check', 'compact', 'docs']);
+});