llm-switcher 1.6.6 → 1.6.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog — LLM Switcher
 
+## 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.
+- **Dedicated Goal Check Dashboard (`#/goal-check`):** Manage Goal Check with provider source inheritance, custom URL and endpoint overrides, model combobox with auto-discovery, live connection test probe, fine-grained threshold controls, and real-time verification history.
+- **Notice Shim Preflight Model & Credential Check:** Automatically verify upstream endpoint reachability, API key validity, and configured model availability whenever a tool session is launched from the notice shim (`claude`, `codex`, `agy`). Instantly alerts the developer in the terminal if an active model was deprecated or dropped upstream, preventing cryptic downstream errors.
+- **Clear Gateway Error Messages:** Translate ambiguous upstream 404 (model not found) and 401 (invalid key) errors into actionable explanations directing users to reconfigure via `switch ui`.
+
 ## Release 1.6.6 — 2026-10-09
 
 - **Consistent MCP Tool Aliasing across ToolSearch and History:** Ensure tool names in instructions, structured `ToolSearch` references, query history, and upstream declarations use the identical collision-resolved alias mapping across Chat, Anthropic, and Vertex conversions. Original client tool names are restored before Claude Code executes tool calls or queries `ToolSearch`, preventing mid-response stream rejections (`upstream called undeclared tool`) when interacting with MCP tools exceeding 64 characters (such as Chrome DevTools MCP).

package/docs/goal-check.md

@@ -0,0 +1,75 @@
+# Goal Check: Kiểm Tra Hoàn Thành Goal Bằng Jev System One
+
+**Goal Check** là cơ chế cổng kiểm soát (gatekeeper/veto) độc lập tích hợp tại `llm-switcher`. Tính năng này bảo vệ các prompt-based stopping condition evaluator của Claude Code (đặc biệt là lệnh `/goal`), ngăn chặn các phán quyết hoàn thành sai (false completion) khi chưa có đủ bằng chứng thực thi bằng tool.
+
+---
+
+## 1. Vấn đề giải quyết
+
+Trong Claude Code (v2.1.295), khi người dùng đặt `/goal`, hệ thống sử dụng một evaluator model riêng đọc transcript và trả về `{ok, reason, impossible?}`:
+- **Lỗ hổng**: Evaluator chỉ đọc văn bản và dễ bị nhầm lẫn giữa việc *sửa báo cáo* (rút finding, ghi PASS audit) với việc *sửa code thật sự*.
+- **Hệ quả**: Ngay khi evaluator trả về `ok: true`, Claude Code lập tức gỡ hook và ghi nhận `goal_status.met: true`.
+- **Giải pháp**: `llm-switcher` chặn phản hồi của evaluator trước khi gửi về client, đồng thời gọi mô hình quyết định **Jev (System One typed decision API)** trên 3 trục độc lập:
+  1. `complete`: Toàn bộ công việc theo condition đã hoàn thành thực sự (ngưỡng mặc định: $\ge 0.90$).
+  2. `evidence`: Có tool-result trực tiếp chứng minh kết quả thực thi (ngưỡng mặc định: $\ge 0.85$).
+  3. `unfinished`: Còn công việc dang dở, lỗi chưa xử lý hoặc verification thiếu (ngưỡng mặc định: $\le 0.10$).
+
+---
+
+## 2. Nguyên tắc hoạt động & Quyết định hợp nhất
+
+Gateway chỉ trả về `ok: true` khi **cả hai bên đồng thuận**:
+- Evaluator gốc của Claude Code trả về `ok: true`.
+- Jev xác nhận cả 3 điểm số đều đạt ngưỡng cấu hình và evidence không vượt kích thước tối đa.
+
+| Native Evaluator | Jev / Evidence Checks | Trả về Claude Code | Ghi chú |
+| :--- | :--- | :--- | :--- |
+| `ok: false` | Bất kỳ | `ok: false` | Giữ nguyên lý do gốc của native |
+| `ok: true` | Đạt cả 3 ngưỡng | `ok: true` | Cho phép hoàn thành lượt |
+| `ok: true` | Một trong 3 trục không đạt | `ok: false` | Veto: Nêu rõ trục vi phạm (ví dụ `complete=0.14 < 0.90`) và yêu cầu cung cấp tool evidence |
+| `ok: true` | Lỗi mạng / HTTP 5xx / timeout / thiếu key | `ok: false` | Fail-closed: Báo `Goal Check verification unavailable` |
+| `ok: true` | State vượt quá `maxStateChars` | `ok: false` | Báo `Insufficient evidence` (state quá lớn) |
+| `impossible: true` | Bất kỳ | `ok: false, impossible: true` | Giữ nguyên ngữ nghĩa thất bại của native |
+
+> **Fail-closed**: Lỗi mạng, thiếu dữ liệu hoặc lỗi cấu hình Jev **không bao giờ** biến thành phán quyết hoàn thành.
+
+---
+
+## 3. Cấu hình qua Dashboard
+
+Truy cập `# /goal-check` từ menu bên trái:
+
+1. **Enable Goal Check**: Toggle bật/tắt (Mặc định: **OFF**).
+2. **Model Provider Source**: Chọn profile có sẵn (như `intact-claude`) để kế thừa Base URL và API key, hoặc chọn *Custom Endpoint*.
+3. **Base URL**: URL nhà cung cấp Jev (ví dụ: `https://intact.louispham.qzz.io/v1`).
+4. **API Key**: Khóa truy cập (được che dạng masked khi hiển thị).
+5. **Goal Check Model**: Model ID quyết định (mặc định: `typesafe/jev-latest`).
+6. **Test Connection**: Probe thử nghiệm gửi payload quyết định mẫu nhỏ để xác minh kết nối và schema trả về.
+7. **Save Configuration**: Lưu cấu hình an toàn vào `config.json`.
+
+### Tùy chọn nâng cao (Advanced)
+- **Decision Endpoint Override**: Cho phép ghi đè đường dẫn đầy đủ tới API quyết định (mặc định: `<Base URL>/systemone`).
+- **Complete Score Threshold (`completeMin`)**: Ngưỡng hoàn thành tối thiểu (mặc định: 0.90).
+- **Evidence Score Threshold (`evidenceMin`)**: Ngưỡng bằng chứng thực thi tối thiểu (mặc định: 0.85).
+- **Unfinished Score Max (`unfinishedMax`)**: Trần công việc dang dở tối đa (mặc định: 0.10).
+- **Timeout (`timeoutMs`)**: Thời gian chờ cuộc gọi Jev (mặc định: 8000 ms).
+- **Total Gate Deadline (`totalTimeoutMs`)**: Tổng hạn ngạch thời gian của cổng (mặc định: 25000 ms).
+- **Max State Evidence Budget (`maxStateChars`)**: Giới hạn ký tự transcript gửi Jev (mặc định: 60000 ký tự).
+
+---
+
+## 4. API Endpoints
+
+Tất cả endpoint yêu cầu header `x-llm-switcher-token` (hoặc admin cookie):
+- `GET /api/goal-check`: Lấy cấu hình (đã mask key) và trạng thái kết nối.
+- `POST /api/goal-check`: Cập nhật cấu hình, lưu vào `config.json`.
+- `POST /api/goal-check/test`: Thử nghiệm kết nối tới Jev endpoint.
+- `GET /api/goal-check/logs`: Lấy danh sách ring buffer các lượt kiểm tra gần nhất.
+
+---
+
+## 5. Phạm vi & Giới hạn
+
+- **Phạm vi bảo vệ**: Áp dụng cho các prompt stop-condition hook của Claude Code (bao gồm `/goal`).
+- **Không áp dụng**: Request chat thông thường, Idle Compaction, Codex CLI, TaskUpdate/TaskCompleted.
+- **Giới hạn mô hình**: Jev là mô hình quyết định dựa trên văn bản; không tự chạy lệnh, đọc file hay xem ảnh chụp màn hình trực tiếp. Nếu task đòi hỏi bằng chứng thị giác mà không có biểu diễn text tương đương, gate sẽ đánh giá là thiếu bằng chứng.

package/goalcheck-call.mjs

@@ -0,0 +1,208 @@
+// Network transport and schema validation for Jev System One decision API.
+import { buildJevQuestions } from './goalcheck.mjs';
+
+/**
+ * Resolve effective URL and API key for Jev decision call.
+ */
+export function resolveJevTarget(policy = {}, profiles = {}) {
+  let url = '';
+  let apiKey = policy.apiKey || '';
+  const model = policy.model || 'typesafe/jev-latest';
+
+  const sourceProf = policy.sourceProfile ? profiles[policy.sourceProfile] : null;
+
+  if (policy.decisionEndpoint && /^https?:\/\//i.test(policy.decisionEndpoint)) {
+    url = policy.decisionEndpoint;
+  } else if (policy.decisionEndpoint && policy.baseURL) {
+    const base = policy.baseURL.replace(/\/+$/, '');
+    const path = policy.decisionEndpoint.replace(/^\/+/, '');
+    url = `${base}/${path}`;
+  } else if (policy.baseURL) {
+    url = `${policy.baseURL.replace(/\/+$/, '')}/systemone`;
+  } else if (sourceProf && sourceProf.baseURL) {
+    url = `${sourceProf.baseURL.replace(/\/+$/, '')}/systemone`;
+  }
+
+  if (!apiKey && sourceProf && sourceProf.apiKey) {
+    // Only inherit key if not overridden to a different host
+    apiKey = sourceProf.apiKey;
+  }
+
+  return { url, apiKey, model };
+}
+
+/**
+ * Extract probability / score in [0, 1] from a Jev typed answer.
+ */
+export function extractScoreFromAnswer(answer) {
+  if (!answer || typeof answer !== 'object') return Number.NaN;
+  if (typeof answer.noul === 'number' && Number.isFinite(answer.noul)) {
+    return answer.noul;
+  }
+  if (typeof answer.score === 'number' && Number.isFinite(answer.score)) {
+    return answer.score;
+  }
+  if (answer.probabilities && typeof answer.probabilities.yes === 'number' && Number.isFinite(answer.probabilities.yes)) {
+    return answer.probabilities.yes;
+  }
+  if (answer.choice === 'yes' && typeof answer.confidence === 'number' && Number.isFinite(answer.confidence)) {
+    return answer.confidence;
+  }
+  if (answer.choice === 'no' && typeof answer.confidence === 'number' && Number.isFinite(answer.confidence)) {
+    return Math.round((1 - answer.confidence) * 1e6) / 1e6;
+  }
+  return Number.NaN;
+}
+
+/**
+ * Call Jev System One decision endpoint.
+ */
+export async function callJev({
+  url,
+  model,
+  apiKey,
+  state,
+  questions,
+  timeoutMs = 8000,
+  signal,
+  fetchImpl = globalThis.fetch
+}) {
+  if (!url) {
+    return { ok: false, reason: 'missing-url', message: 'No decision URL configured' };
+  }
+  if (!apiKey) {
+    return { ok: false, reason: 'no-key', message: 'No API key configured for decision endpoint' };
+  }
+
+  const ac = new AbortController();
+  const onAbort = () => ac.abort();
+  if (signal) {
+    if (signal.aborted) ac.abort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  }
+
+  const effectiveTimeout = Number.isFinite(timeoutMs) ? Math.max(500, Math.min(60000, timeoutMs)) : 8000;
+  const timer = setTimeout(() => ac.abort(), effectiveTimeout);
+  const startTime = Date.now();
+
+  try {
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({ model, state, questions }),
+      signal: ac.signal
+    });
+
+    const latencyMs = Date.now() - startTime;
+
+    if (!res.ok) {
+      const errBody = await res.text().catch(() => '');
+      return {
+        ok: false,
+        reason: `http-${res.status}`,
+        message: `HTTP ${res.status}: ${errBody.slice(0, 150)}`,
+        latencyMs
+      };
+    }
+
+    let data;
+    try {
+      data = JSON.parse(await res.text());
+    } catch {
+      return { ok: false, reason: 'bad-response', message: 'Response was not valid JSON', latencyMs };
+    }
+
+    if (!data || typeof data !== 'object' || !data.answers || typeof data.answers !== 'object') {
+      return { ok: false, reason: 'bad-response', message: 'Response missing answers map', latencyMs };
+    }
+
+    const completeScore = extractScoreFromAnswer(data.answers.complete);
+    const evidenceScore = extractScoreFromAnswer(data.answers.evidence);
+    const unfinishedScore = extractScoreFromAnswer(data.answers.unfinished);
+
+    if (Number.isNaN(completeScore) || Number.isNaN(evidenceScore) || Number.isNaN(unfinishedScore)) {
+      return {
+        ok: false,
+        reason: 'missing-answers',
+        message: 'One or more required answer scores (complete, evidence, unfinished) are missing or NaN',
+        latencyMs,
+        raw: data
+      };
+    }
+
+    return {
+      ok: true,
+      scores: {
+        complete: completeScore,
+        evidence: evidenceScore,
+        unfinished: unfinishedScore
+      },
+      model: data.model || model,
+      latencyMs,
+      raw: data
+    };
+  } catch (err) {
+    const latencyMs = Date.now() - startTime;
+    const isTimeout = ac.signal.aborted;
+    return {
+      ok: false,
+      reason: isTimeout ? 'timeout' : 'network',
+      message: isTimeout ? `Request timed out after ${effectiveTimeout}ms` : (err.message || 'Network error'),
+      latencyMs
+    };
+  } finally {
+    clearTimeout(timer);
+    if (signal) signal.removeEventListener('abort', onAbort);
+  }
+}
+
+/**
+ * Probe connection with a minimal synthetic decision query.
+ */
+export async function testJevConnection({
+  baseURL,
+  decisionEndpoint,
+  apiKey,
+  model,
+  sourceProfile,
+  profiles = {},
+  timeoutMs = 8000,
+  fetchImpl = globalThis.fetch
+}) {
+  const policy = { baseURL, decisionEndpoint, apiKey, model, sourceProfile };
+  const target = resolveJevTarget(policy, profiles);
+
+  if (!target.url) {
+    return { ok: false, error: 'Could not resolve decision URL. Specify Base URL or choose a profile.' };
+  }
+  if (!target.apiKey) {
+    return { ok: false, error: 'No API key provided or available from selected profile.' };
+  }
+
+  const testState = 'The user asked to add a unit test for password validation. The assistant created tests/auth.test.mjs and ran node --test tests/auth.test.mjs, which passed with 0 errors.';
+  const testQuestions = buildJevQuestions('Add a unit test for password validation');
+
+  const res = await callJev({
+    url: target.url,
+    model: target.model,
+    apiKey: target.apiKey,
+    state: testState,
+    questions: testQuestions,
+    timeoutMs,
+    fetchImpl
+  });
+
+  if (!res.ok) {
+    return { ok: false, error: res.message || res.reason || 'Probe failed', latencyMs: res.latencyMs };
+  }
+
+  return {
+    ok: true,
+    message: `Connected successfully to ${target.model} at ${target.url} (${res.latencyMs}ms)`,
+    latencyMs: res.latencyMs,
+    scores: res.scores
+  };
+}