evrex-mcp 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
-
-// src/index.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-
-// src/tools.ts
-import { execFileSync } from "node:child_process";
-import { realpathSync } from "node:fs";
-import { dirname, isAbsolute, relative, resolve as resolvePath } from "node:path";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // src/client.ts
-var DEFAULT_API_BASE_URL = "https://evrex-backend-production.up.railway.app";
-var API_BASE_URL = (process.env.EVREX_API_BASE_URL ?? process.env.EVREX_API_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
-var EVREX_TOKEN = process.env.EVREX_TOKEN ?? process.env.EVREX_API_TOKEN ?? null;
+var client_exports = {};
+__export(client_exports, {
+  evrexApi: () => evrexApi
+});
 function headers() {
   const base = { "Content-Type": "application/json" };
   if (EVREX_TOKEN) base.Authorization = `Bearer ${EVREX_TOKEN}`;
@@ -25,33 +25,328 @@ function describeFailure(method, path, status, statusText) {
   }
   return `${method} ${path} -> ${status} ${statusText}`;
 }
-async function get(path) {
-  const res = await fetch(`${API_BASE_URL}${path}`, { headers: headers() });
-  if (!res.ok) throw new Error(describeFailure("GET", path, res.status, res.statusText));
-  return await res.json();
-}
-async function post(path, body) {
+async function request(method, path, { body, absentIsAnswer } = {}) {
   const res = await fetch(`${API_BASE_URL}${path}`, {
-    method: "POST",
+    method,
     headers: headers(),
-    body: JSON.stringify(body)
+    ...body === void 0 ? {} : { body: JSON.stringify(body) }
   });
-  if (!res.ok) throw new Error(describeFailure("POST", path, res.status, res.statusText));
+  if (res.status === 404 && absentIsAnswer) return null;
+  if (!res.ok) throw new Error(describeFailure(method, path, res.status, res.statusText));
   return await res.json();
 }
-var evrexApi = {
-  baseUrl: API_BASE_URL,
-  repos: () => get("/repos"),
-  commits: (repoPath) => get(`/commits?repoPath=${encodeURIComponent(repoPath)}`),
-  commit: (sha) => get(`/commits/${sha}`).catch(() => null),
-  sessions: (repoPath) => get(`/sessions?repoPath=${encodeURIComponent(repoPath)}`),
-  session: (id) => get(`/sessions/${id}`).catch(() => null),
-  ask: (repoPath, text, filePaths) => post("/ask", { repoPath, text, filePaths }),
-  // Evidence-only retrieval (BM25 + embedding), no LLM synthesis call — see
-  // apps/backend/src/query/query.service.ts#search. Used by evrex_search,
-  // which wants ranked hits fast, not a synthesized paragraph.
-  search: (repoPath, text, filePaths) => post("/search", { repoPath, text, filePaths })
-};
+var DEFAULT_API_BASE_URL, API_BASE_URL, EVREX_TOKEN, get, getOrNull, post, evrexApi;
+var init_client = __esm({
+  "src/client.ts"() {
+    "use strict";
+    DEFAULT_API_BASE_URL = "https://api.evrex.ai";
+    API_BASE_URL = (process.env.EVREX_API_BASE_URL ?? process.env.EVREX_API_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+    EVREX_TOKEN = process.env.EVREX_TOKEN ?? process.env.EVREX_API_TOKEN ?? null;
+    get = (path) => request("GET", path);
+    getOrNull = (path) => request("GET", path, { absentIsAnswer: true });
+    post = (path, body) => request("POST", path, { body });
+    evrexApi = {
+      baseUrl: API_BASE_URL,
+      repos: () => get("/repos"),
+      commits: (repoPath) => get(`/commits?repoPath=${encodeURIComponent(repoPath)}`),
+      // Abbreviated shas resolve server-side, so a value pasted from `git log`
+      // works here (apps/backend/src/reads/reads.service.ts#resolveSha).
+      commit: (sha) => getOrNull(`/commits/${encodeURIComponent(sha)}`),
+      sessions: (repoPath) => get(`/sessions?repoPath=${encodeURIComponent(repoPath)}`),
+      session: (id) => getOrNull(`/sessions/${encodeURIComponent(id)}`),
+      ask: (repoPath, text, filePaths) => post("/ask", { repoPath, text, filePaths }),
+      // Evidence-only retrieval (BM25 + embedding), no LLM synthesis call — see
+      // apps/backend/src/query/query.service.ts#search. Used by evrex_search,
+      // which wants ranked hits fast, not a synthesized paragraph.
+      search: (repoPath, text, filePaths) => post("/search", { repoPath, text, filePaths })
+    };
+  }
+});
+
+// src/credential-store.ts
+var credential_store_exports = {};
+__export(credential_store_exports, {
+  CredentialStore: () => CredentialStore,
+  NoKeychainError: () => NoKeychainError,
+  systemRunner: () => systemRunner
+});
+import { spawn } from "node:child_process";
+var SERVICE, ACCOUNT, systemRunner, NoKeychainError, CredentialStore, WINDOWS_PATH, WINDOWS_STORE, WINDOWS_RETRIEVE, WINDOWS_REMOVE;
+var init_credential_store = __esm({
+  "src/credential-store.ts"() {
+    "use strict";
+    SERVICE = "evrex-capture";
+    ACCOUNT = "evrex";
+    systemRunner = {
+      platform: process.platform,
+      run(command, args, stdin) {
+        return new Promise((resolve) => {
+          const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+          let stdout = "";
+          let stderr = "";
+          child.stdout.on("data", (d) => stdout += d.toString());
+          child.stderr.on("data", (d) => stderr += d.toString());
+          child.on("error", () => resolve({ code: 127, stdout: "", stderr: "" }));
+          child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+          if (stdin !== void 0) child.stdin.write(stdin);
+          child.stdin.end();
+        });
+      }
+    };
+    NoKeychainError = class extends Error {
+      constructor(platform) {
+        super(
+          `evrex could not find a credential store on this machine (${platform}).
+  macOS   needs \`security\`, which ships with the system.
+  Linux   needs \`secret-tool\` \u2014 install libsecret-tools (Debian/Ubuntu)
+          or libsecret (Fedora/Arch), and make sure a keyring daemon is running.
+  Windows needs PowerShell.
+evrex will not fall back to writing the credential in a plain file.`
+        );
+        this.name = "NoKeychainError";
+      }
+    };
+    CredentialStore = class {
+      constructor(runner = systemRunner) {
+        this.runner = runner;
+      }
+      async available() {
+        switch (this.runner.platform) {
+          case "darwin":
+            return (await this.runner.run("security", ["help"])).code !== 127;
+          case "win32":
+            return (await this.runner.run("powershell", ["-Command", "$PSVersionTable.PSVersion.Major"])).code !== 127;
+          default:
+            return (await this.runner.run("secret-tool", ["--version"])).code !== 127;
+        }
+      }
+      /**
+       * Replaces any existing credential rather than adding a second one. A
+       * machine that re-enrols after expiry must end up with exactly one entry, or
+       * the next read is a coin flip between the live credential and a dead one.
+       */
+      async store(secret) {
+        if (!await this.available()) throw new NoKeychainError(this.runner.platform);
+        switch (this.runner.platform) {
+          case "darwin": {
+            const result = await this.runner.run(
+              "security",
+              ["add-generic-password", "-a", ACCOUNT, "-s", SERVICE, "-U", "-w"],
+              `${secret}
+${secret}
+`
+            );
+            if (result.code !== 0) throw new Error(`Keychain write failed: ${result.stderr.trim()}`);
+            return;
+          }
+          case "win32": {
+            const result = await this.runner.run(
+              "powershell",
+              ["-NoProfile", "-Command", WINDOWS_STORE],
+              secret
+            );
+            if (result.code !== 0) throw new Error(`DPAPI write failed: ${result.stderr.trim()}`);
+            return;
+          }
+          default: {
+            const result = await this.runner.run(
+              "secret-tool",
+              ["store", "--label=evrex capture credential", "service", SERVICE, "account", ACCOUNT],
+              secret
+            );
+            if (result.code !== 0) throw new Error(`secret-tool write failed: ${result.stderr.trim()}`);
+            return;
+          }
+        }
+      }
+      /** Null when there is nothing stored, which is the normal pre-enrolment state. */
+      async retrieve() {
+        if (!await this.available()) throw new NoKeychainError(this.runner.platform);
+        switch (this.runner.platform) {
+          case "darwin": {
+            const r = await this.runner.run("security", [
+              "find-generic-password",
+              "-a",
+              ACCOUNT,
+              "-s",
+              SERVICE,
+              "-w"
+            ]);
+            return r.code === 0 ? r.stdout.trim() || null : null;
+          }
+          case "win32": {
+            const r = await this.runner.run("powershell", ["-NoProfile", "-Command", WINDOWS_RETRIEVE]);
+            return r.code === 0 ? r.stdout.trim() || null : null;
+          }
+          default: {
+            const r = await this.runner.run("secret-tool", [
+              "lookup",
+              "service",
+              SERVICE,
+              "account",
+              ACCOUNT
+            ]);
+            return r.code === 0 ? r.stdout.trim() || null : null;
+          }
+        }
+      }
+      /** Idempotent: removing a credential that is not there is not an error. */
+      async remove() {
+        if (!await this.available()) return;
+        switch (this.runner.platform) {
+          case "darwin":
+            await this.runner.run("security", [
+              "delete-generic-password",
+              "-a",
+              ACCOUNT,
+              "-s",
+              SERVICE
+            ]);
+            return;
+          case "win32":
+            await this.runner.run("powershell", ["-NoProfile", "-Command", WINDOWS_REMOVE]);
+            return;
+          default:
+            await this.runner.run("secret-tool", [
+              "clear",
+              "service",
+              SERVICE,
+              "account",
+              ACCOUNT
+            ]);
+            return;
+        }
+      }
+    };
+    WINDOWS_PATH = "$env:APPDATA\\evrex\\capture.cred";
+    WINDOWS_STORE = `
+$ErrorActionPreference = 'Stop'
+$p = "${WINDOWS_PATH}"
+New-Item -ItemType Directory -Force -Path (Split-Path $p) | Out-Null
+$secret = [Console]::In.ReadToEnd().Trim()
+ConvertTo-SecureString $secret -AsPlainText -Force | ConvertFrom-SecureString | Set-Content -Path $p
+`.trim();
+    WINDOWS_RETRIEVE = `
+$ErrorActionPreference = 'Stop'
+$p = "${WINDOWS_PATH}"
+if (-not (Test-Path $p)) { exit 1 }
+$sec = Get-Content $p | ConvertTo-SecureString
+[Runtime.InteropServices.Marshal]::PtrToStringAuto(
+  [Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec))
+`.trim();
+    WINDOWS_REMOVE = `
+$p = "${WINDOWS_PATH}"
+if (Test-Path $p) { Remove-Item $p -Force }
+`.trim();
+  }
+});
+
+// src/enrol.ts
+var enrol_exports = {};
+__export(enrol_exports, {
+  RENEW_WITHIN_MS: () => RENEW_WITHIN_MS,
+  enrol: () => enrol,
+  needsRenewal: () => needsRenewal
+});
+async function keychainReady(deps) {
+  try {
+    return await deps.store.available();
+  } catch {
+    return false;
+  }
+}
+async function enrol(deps) {
+  if (!await keychainReady(deps)) {
+    deps.log(new NoKeychainError(process.platform).message);
+    return { ok: false, reason: "no_keychain" };
+  }
+  let started;
+  try {
+    const res = await deps.fetch(`${deps.baseUrl}/auth/device/start`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        deviceName: deps.hostname(),
+        agentKind: "claude-code",
+        clientVersion: deps.clientVersion
+      })
+    });
+    if (!res.ok) throw new Error(String(res.status));
+    started = await res.json();
+  } catch {
+    deps.log(`Could not reach evrex at ${deps.baseUrl}.`);
+    return { ok: false, reason: "unreachable" };
+  }
+  deps.log("");
+  deps.log(`  Enrolling ${deps.hostname()}.`);
+  deps.log("");
+  deps.log(`  1. Open  ${deps.dashboardUrl}/devices`);
+  deps.log(`  2. Enter this code:  ${started.userCode}`);
+  deps.log("");
+  deps.log("  Waiting for approval. Ctrl-C to stop.");
+  let interval = started.intervalMs;
+  for (; ; ) {
+    await deps.sleep(interval);
+    let outcome;
+    try {
+      const res = await deps.fetch(`${deps.baseUrl}/auth/device/poll`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ deviceCode: started.deviceCode })
+      });
+      outcome = await res.json();
+    } catch {
+      continue;
+    }
+    switch (outcome.status) {
+      case "pending":
+        continue;
+      case "slow_down":
+        interval = Math.max(interval, outcome.retryAfterMs);
+        continue;
+      case "denied":
+        deps.log("  Enrolment was declined.");
+        return { ok: false, reason: "denied" };
+      case "expired":
+        deps.log("  That code expired. Run enrolment again for a new one.");
+        return { ok: false, reason: "expired" };
+      case "granted": {
+        await deps.store.store(outcome.token);
+        deps.log("");
+        deps.log(`  ${deps.hostname()} is enrolled.`);
+        if (outcome.expiresAt) {
+          deps.log(`  The credential renews automatically before ${outcome.expiresAt.slice(0, 10)}.`);
+        }
+        return { ok: true, expiresAt: outcome.expiresAt };
+      }
+    }
+  }
+}
+function needsRenewal(expiresAt, now) {
+  if (!expiresAt) return false;
+  const expiry = new Date(expiresAt).getTime();
+  if (Number.isNaN(expiry)) return false;
+  return expiry - now <= RENEW_WITHIN_MS;
+}
+var RENEW_WITHIN_MS;
+var init_enrol = __esm({
+  "src/enrol.ts"() {
+    "use strict";
+    init_credential_store();
+    RENEW_WITHIN_MS = 7 * 24 * 60 * 60 * 1e3;
+  }
+});
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/tools.ts
+init_client();
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve as resolvePath } from "node:path";
 
 // ../../packages/llm-core/src/client.ts
 import Anthropic from "@anthropic-ai/sdk";
@@ -60,6 +355,75 @@ var DEFAULT_MAX_TOKENS = 16e3;
 // ../../packages/llm-core/src/complete.ts
 import Anthropic2 from "@anthropic-ai/sdk";
 
+// ../../packages/llm-core/src/providers.ts
+var OPENAI_COMPATIBLE_BASE_URLS = {
+  openai: "https://api.openai.com/v1",
+  groq: "https://api.groq.com/openai/v1",
+  cerebras: "https://api.cerebras.ai/v1",
+  openrouter: "https://openrouter.ai/api/v1"
+};
+var DEFAULT_MODELS = {
+  anthropic: "claude-haiku-4-5",
+  openai: "gpt-4o",
+  // gemini-2.0-flash is retired: Google answers a request for it with
+  // "no longer available to new users. Please update your code to use
+  // models/gemini-3.6-flash". Second time a stale default has done this —
+  // Groq's llama-3.3-70b-versatile went the same way — and the failure looks
+  // identical to having no key at all, so it is worth checking against the
+  // provider's own model list when insights stop appearing.
+  google: "gemini-3.6-flash",
+  // Free tiers, chosen for extraction: a capable model behind a rate limit
+  // beats a weak one behind none, because indexing is a background batch and
+  // can wait out a limit but cannot recover a missed rejected approach.
+  // The smaller of the two open models, and the better one here: measured on
+  // ten real sessions it beat gpt-oss-120b on every category and ran faster.
+  // Groq's catalogue also turns over — llama-3.3-70b-versatile was the obvious
+  // default and 404s now — and a wrong name is a 404 that degrades to no
+  // insights, so `GET /models` is the check when this breaks.
+  groq: "openai/gpt-oss-20b",
+  cerebras: "llama-3.3-70b",
+  openrouter: "meta-llama/llama-3.3-70b-instruct:free",
+  // Cheapest credible host of this model measured at the time of writing
+  // ($0.03/$0.14 per million against Cloudflare's $0.20/$0.30), and the model
+  // that scored best on decisions and constraints in
+  // apps/backend/scripts/eval-extraction.mjs.
+  "openai-compatible": "openai/gpt-oss-20b",
+  // Small on purpose. Every invocation re-sends the CLI's own system prompt
+  // and is billed to the operator, so the default is the cheapest model that
+  // can read a transcript rather than the CLI's own default.
+  "claude-cli": "haiku",
+  "codex-cli": "",
+  // Measured the best of the models that fit on a laptop — see
+  // apps/backend/scripts/eval-extraction.mjs. Overridden with
+  // EVREX_LOCAL_MODEL for whatever is already pulled.
+  local: "qwen3:8b"
+};
+var DEFAULT_LOCAL_BASE_URL = "http://localhost:11434/v1";
+function providerForBaseUrl(baseUrl) {
+  const url = (baseUrl ?? "").trim();
+  if (!url) return null;
+  return /^https?:\/\//i.test(url) ? "openai-compatible" : null;
+}
+function detectProvider(key) {
+  const k = (key ?? "").trim();
+  if (!k) return null;
+  if (k.startsWith("sk-ant-")) return "anthropic";
+  if (k.startsWith("AIza") || k.startsWith("AQ.")) return "google";
+  if (k.startsWith("gsk_")) return "groq";
+  if (k.startsWith("csk-")) return "cerebras";
+  if (k.startsWith("sk-or-")) return "openrouter";
+  if (k.startsWith("sk-")) return "openai";
+  if (/^https?:\/\//i.test(k)) return "local";
+  if (/^(ollama|local)$/i.test(k)) return "local";
+  if (/^claude-?cli$/i.test(k)) return "claude-cli";
+  if (/^codex-?cli$/i.test(k)) return "codex-cli";
+  return null;
+}
+function localBaseUrl(key) {
+  const k = key.trim();
+  return /^https?:\/\//i.test(k) ? k.replace(/\/+$/, "") : DEFAULT_LOCAL_BASE_URL;
+}
+
 // ../../packages/llm-core/src/extraction.ts
 var MAX_ITEMS_PER_CATEGORY = 6;
 var EXTRACTION_SYSTEM_PROMPT = [
@@ -129,8 +493,14 @@ async function synthesizeAnswer(question, evidence, client2, options = {}) {
     );
     return null;
   }
-  if (typeof body !== "object" || body === null || !isValidSynthesis(body, evidence.length)) {
-    options.logger?.warn("synthesis response cited evidence it was not given");
+  if (body === null) {
+    options.logger?.warn("synthesis skipped: no answer from the model");
+    return null;
+  }
+  if (typeof body !== "object" || !isValidSynthesis(body, evidence.length)) {
+    options.logger?.warn(
+      "synthesis response was not usable: wrong shape, wrong sentence count, or a citation to evidence it was not given"
+    );
     return null;
   }
   const raw = body;
@@ -141,24 +511,149 @@ async function synthesizeAnswer(question, evidence, client2, options = {}) {
   };
 }
 
-// ../../packages/llm-core/src/providers.ts
-var DEFAULT_MODELS = {
-  anthropic: "claude-opus-5",
-  openai: "gpt-4o",
-  google: "gemini-2.0-flash"
+// ../../packages/llm-core/src/cli-client.ts
+import { execFile } from "node:child_process";
+var TIMEOUT_MS = 12e4;
+var CLAUDE = {
+  provider: "claude-cli",
+  command: "claude",
+  args: (model) => [
+    "-p",
+    // `--bare` never reads OAuth credentials or the system keychain, so this
+    // cannot run on a Claude.ai subscription — it requires ANTHROPIC_API_KEY.
+    //
+    // That is deliberate and it is the whole compliance question. Anthropic's
+    // consumer terms prohibit accessing the service "through automated or
+    // non-human means, whether through a bot, script, or otherwise" except
+    // via an API key, and evrex spawning the CLI is a script doing exactly
+    // that. Anthropic's own headless documentation points the same way:
+    // `--bare` is "the recommended mode for scripted and SDK calls" and "will
+    // become the default for `-p` in a future release".
+    //
+    // It costs this provider its reason to exist — with an API key in the
+    // environment there is little point going through the CLI at all — which
+    // is the honest answer to "can we spend a subscription instead of a
+    // budget": no, and evrex had already recorded that conclusion once.
+    "--bare",
+    "--output-format",
+    "json",
+    // Extraction is a reading task; the CLI's default is far larger than it
+    // needs and is billed to the operator.
+    ...model ? ["--model", model] : ["--model", "haiku"]
+  ],
+  parse: (stdout) => {
+    try {
+      const envelope = JSON.parse(stdout);
+      if (envelope.is_error) return null;
+      return typeof envelope.result === "string" ? envelope.result : null;
+    } catch {
+      return null;
+    }
+  }
 };
-function detectProvider(key) {
-  const k = (key ?? "").trim();
-  if (!k) return null;
-  if (k.startsWith("sk-ant-")) return "anthropic";
-  if (k.startsWith("AIza")) return "google";
-  if (k.startsWith("sk-")) return "openai";
-  return null;
+var CODEX = {
+  provider: "codex-cli",
+  command: "codex",
+  // `exec` is Codex's non-interactive mode. It prints the answer plainly, so
+  // there is no envelope to unwrap.
+  args: (model) => ["exec", ...model ? ["--model", model] : []],
+  parse: (stdout) => stdout.trim() || null,
+  requiresEnv: "OPENAI_API_KEY"
+};
+var CLI_SPECS = {
+  "claude-cli": CLAUDE,
+  "codex-cli": CODEX
+};
+function unfence(text) {
+  const fenced = /```(?:json)?\s*([\s\S]*?)\s*```/.exec(text);
+  return (fenced ? fenced[1] : text).trim();
 }
+var CliClient = class {
+  constructor(spec, model, logger, run = execFile) {
+    this.spec = spec;
+    this.model = model;
+    this.logger = logger;
+    this.run = run;
+    this.provider = spec.provider;
+  }
+  /**
+   * Never set. A CLI bills the operator's existing subscription rather than a
+   * metered key, so there is no quota to spend that handing over to evrex's
+   * own would relieve — and a CLI that refuses is a configuration problem the
+   * operator has to fix, not one another provider can absorb.
+   */
+  exhausted = false;
+  provider;
+  async completeJson(request2) {
+    const required = this.spec.requiresEnv;
+    if (required && !process.env[required]) {
+      this.logger.warn(
+        `${this.spec.command} needs ${required} set: evrex will not drive a CLI that is signed in with a consumer subscription, which the provider's terms do not allow.`
+      );
+      return null;
+    }
+    const shape = request2.schema ? `
+
+Respond with JSON matching exactly this schema, and nothing else:
+${JSON.stringify(request2.schema)}` : "\n\nRespond with JSON and nothing else.";
+    const prompt = `${request2.system}${shape}
+
+${request2.user}`;
+    const stdout = await new Promise((resolve) => {
+      const child = this.run(
+        this.spec.command,
+        [...this.spec.args(request2.model ?? this.model)],
+        { timeout: TIMEOUT_MS, maxBuffer: 1 << 26 },
+        (error, out) => {
+          if (error) {
+            this.logger.warn(
+              `${this.spec.command} call failed: ${error.message.slice(0, 200)}`
+            );
+            resolve(null);
+            return;
+          }
+          resolve(String(out));
+        }
+      );
+      child.stdin?.end(prompt);
+    });
+    if (stdout === null) return null;
+    const answer = this.spec.parse(stdout);
+    if (!answer) return null;
+    try {
+      return JSON.parse(unfence(answer));
+    } catch {
+      this.logger.warn(`${this.spec.command} did not return usable JSON`);
+      return null;
+    }
+  }
+};
 
 // ../../packages/llm-core/src/provider-clients.ts
 import Anthropic3 from "@anthropic-ai/sdk";
 var NOOP = { warn: () => void 0, error: () => void 0 };
+var realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var MAX_RETRIES = 4;
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+function isExhaustedStatus(status, retriesSpent) {
+  if (status === 401 || status === 403) return true;
+  return status === 429 && retriesSpent;
+}
+async function waitBeforeRetry(response, attempt, sleep) {
+  const header = response.headers.get("retry-after") ?? response.headers.get("x-ratelimit-reset-tokens");
+  const seconds = header ? parseDuration(header) : null;
+  const backoff = Math.min(8 * 2 ** attempt, 60);
+  const wait = Math.min(seconds ?? backoff, MAX_RETRY_WAIT_SECONDS);
+  await sleep(wait * 1e3);
+}
+var MAX_RETRY_WAIT_SECONDS = 90;
+function parseDuration(value) {
+  const plain = Number(value);
+  if (Number.isFinite(plain)) return plain;
+  const match = /^(?:(\d+(?:\.\d+)?)m)?(?:(\d+(?:\.\d+)?)s)?$/.exec(value.trim());
+  if (!match || !match[1] && !match[2]) return null;
+  return Number(match[1] ?? 0) * 60 + Number(match[2] ?? 0);
+}
 function parseJsonBody(text) {
   const trimmed = text.trim();
   const fenced = /^```(?:json)?\s*([\s\S]*?)\s*```$/.exec(trimmed);
@@ -176,114 +671,189 @@ var AnthropicClient = class {
     this.sdk = new Anthropic3({ apiKey: key });
   }
   provider = "anthropic";
+  exhausted = false;
   sdk;
-  async completeJson(request) {
+  async completeJson(request2) {
     try {
       const message = await this.sdk.messages.create({
-        model: request.model ?? this.model,
-        max_tokens: request.maxTokens ?? DEFAULT_MAX_TOKENS,
-        system: request.system,
-        messages: [{ role: "user", content: request.user }],
-        ...request.schema ? {
+        model: request2.model ?? this.model,
+        max_tokens: request2.maxTokens ?? DEFAULT_MAX_TOKENS,
+        // The breakpoint sits at the end of the system prompt, which is the
+        // only part of these requests that repeats. Rendering order is
+        // tools -> system -> messages, so a marker here caches everything
+        // ahead of the transcript.
+        //
+        // Deliberately NOT on the user block. That block is a different
+        // transcript chunk on every call, so a breakpoint there would write a
+        // fresh cache entry per request and read none of them back — paying
+        // the write premium for nothing, which is worse than not caching.
+        system: [
+          {
+            type: "text",
+            text: request2.system,
+            cache_control: { type: "ephemeral" }
+          }
+        ],
+        messages: [{ role: "user", content: request2.user }],
+        ...request2.schema ? {
           output_config: {
-            format: { type: "json_schema", schema: request.schema }
+            format: { type: "json_schema", schema: request2.schema }
           }
         } : {}
       });
+      this.reportCacheUsage(message.usage);
       const text = message.content.filter((b) => b.type === "text").map((b) => b.text).join("");
       return parseJsonBody(text);
     } catch (err) {
+      const status = err?.status;
+      if (typeof status === "number" && isExhaustedStatus(status, true)) {
+        this.exhausted = true;
+      }
       this.logger.warn(`anthropic call failed: ${describeError(err)}`);
       return null;
     }
   }
+  /**
+   * Says out loud whether the cache was actually used.
+   *
+   * A prompt shorter than the model's minimum cacheable prefix is not an
+   * error and produces no warning from the API — it simply never caches, and
+   * `cache_control` sits in the request looking as though it works. The
+   * minimum is per-model and not monotonic across generations (4,096 tokens
+   * on Haiku 4.5, 512 on Opus 5), so the same prompt can cache on one model
+   * and silently not on another.
+   *
+   * Reported once per process rather than per call: this is a fact about the
+   * prompt and the model, identical for every session in a run, and a line
+   * per extraction would be noise.
+   */
+  reportedCacheState = false;
+  reportCacheUsage(usage) {
+    if (this.reportedCacheState) return;
+    this.reportedCacheState = true;
+    const read = usage.cache_read_input_tokens ?? 0;
+    const written = usage.cache_creation_input_tokens ?? 0;
+    if (read > 0 || written > 0) return;
+    this.logger.warn(
+      `[evrex] prompt caching is enabled but this prompt is below ${this.model}'s minimum cacheable prefix, so nothing was cached (${usage.input_tokens} input tokens). It will start caching if the shared prefix grows past the model's floor.`
+    );
+  }
 };
-var OpenAiClient = class {
-  constructor(key, model, logger) {
+var GoogleClient = class {
+  constructor(key, model, logger, sleep = realSleep) {
     this.key = key;
     this.model = model;
     this.logger = logger;
+    this.sleep = sleep;
   }
-  provider = "openai";
-  async completeJson(request) {
+  provider = "google";
+  exhausted = false;
+  async completeJson(request2, attempt = 0) {
+    const model = request2.model ?? this.model;
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`;
+    const shape = request2.schema ? `
+
+Respond with JSON matching exactly this schema:
+${JSON.stringify(request2.schema)}` : "";
     try {
-      const res = await fetch("https://api.openai.com/v1/chat/completions", {
+      const res = await fetch(url, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${this.key}`
+          "x-goog-api-key": this.key
         },
         body: JSON.stringify({
-          model: request.model ?? this.model,
-          messages: [
-            { role: "system", content: request.system },
-            { role: "user", content: request.user }
-          ],
-          ...request.schema ? {
-            response_format: {
-              type: "json_schema",
-              json_schema: {
-                name: "evrex_result",
-                strict: true,
-                schema: request.schema
-              }
-            }
-          } : { response_format: { type: "json_object" } }
+          systemInstruction: { parts: [{ text: request2.system + shape }] },
+          contents: [{ role: "user", parts: [{ text: request2.user }] }],
+          generationConfig: { responseMimeType: "application/json" }
         })
       });
+      if (RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES) {
+        await waitBeforeRetry(res, attempt, this.sleep);
+        return this.completeJson(request2, attempt + 1);
+      }
       if (!res.ok) {
+        if (isExhaustedStatus(res.status, true)) this.exhausted = true;
         this.logger.warn(
-          `openai call failed: ${res.status} ${(await res.text()).slice(0, 200)}`
+          `google call failed: ${res.status} ${(await res.text()).slice(0, 200)}`
         );
         return null;
       }
       const body = await res.json();
-      const text = body.choices?.[0]?.message?.content;
-      return typeof text === "string" ? parseJsonBody(text) : null;
+      const text = body.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("");
+      return text ? parseJsonBody(text) : null;
     } catch (err) {
-      this.logger.warn(`openai call failed: ${describeError(err)}`);
+      this.logger.warn(`google call failed: ${describeError(err)}`);
       return null;
     }
   }
 };
-var GoogleClient = class {
-  constructor(key, model, logger) {
+var OpenAiCompatibleClient = class {
+  constructor(provider, baseUrl, key, model, logger, sleep = realSleep) {
+    this.provider = provider;
+    this.baseUrl = baseUrl;
     this.key = key;
     this.model = model;
     this.logger = logger;
+    this.sleep = sleep;
   }
-  provider = "google";
-  async completeJson(request) {
-    const model = request.model ?? this.model;
-    const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`;
-    const shape = request.schema ? `
+  exhausted = false;
+  async completeJson(request2, attempt = 0) {
+    const strict = this.provider === "openai";
+    const shape = request2.schema && !strict ? `
 
 Respond with JSON matching exactly this schema:
-${JSON.stringify(request.schema)}` : "";
+${JSON.stringify(request2.schema)}` : "";
     try {
-      const res = await fetch(url, {
+      const res = await fetch(`${this.baseUrl}/chat/completions`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          "x-goog-api-key": this.key
+          // A local server does not want one, and some reject an empty bearer
+          // token outright.
+          ...this.key ? { Authorization: `Bearer ${this.key}` } : {}
         },
         body: JSON.stringify({
-          systemInstruction: { parts: [{ text: request.system + shape }] },
-          contents: [{ role: "user", parts: [{ text: request.user }] }],
-          generationConfig: { responseMimeType: "application/json" }
+          model: request2.model ?? this.model,
+          messages: [
+            { role: "system", content: request2.system + shape },
+            { role: "user", content: request2.user }
+          ],
+          ...request2.schema && strict ? {
+            response_format: {
+              type: "json_schema",
+              json_schema: {
+                name: "evrex_result",
+                strict: true,
+                schema: request2.schema
+              }
+            }
+          } : { response_format: { type: "json_object" } },
+          // Extraction is a reading task with a right answer, not a writing
+          // task, and a default sampling temperature makes it a different
+          // answer each run: one model scored 53% and then 20% on the same ten
+          // sessions before this was pinned. Indexing twice must not produce
+          // two different histories.
+          temperature: 0,
+          stream: false
         })
       });
+      if (RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES) {
+        await waitBeforeRetry(res, attempt, this.sleep);
+        return this.completeJson(request2, attempt + 1);
+      }
       if (!res.ok) {
+        if (isExhaustedStatus(res.status, true)) this.exhausted = true;
         this.logger.warn(
-          `google call failed: ${res.status} ${(await res.text()).slice(0, 200)}`
+          `${this.provider} call failed: ${res.status} ${(await res.text()).slice(0, 200)}`
         );
         return null;
       }
       const body = await res.json();
-      const text = body.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("");
-      return text ? parseJsonBody(text) : null;
+      const text = body.choices?.[0]?.message?.content;
+      return typeof text === "string" ? parseJsonBody(text) : null;
     } catch (err) {
-      this.logger.warn(`google call failed: ${describeError(err)}`);
+      this.logger.warn(`${this.provider} call failed: ${describeError(err)}`);
       return null;
     }
   }
@@ -292,14 +862,37 @@ function describeError(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function createModelClient(key, options = {}) {
-  const provider = detectProvider(key);
+  const provider = providerForBaseUrl(options.baseUrl) ?? detectProvider(key);
   if (!provider || !key) return null;
   const logger = options.logger ?? NOOP;
   const model = options.model ?? DEFAULT_MODELS[provider];
   const trimmed = key.trim();
   if (provider === "anthropic") return new AnthropicClient(trimmed, model, logger);
-  if (provider === "openai") return new OpenAiClient(trimmed, model, logger);
-  return new GoogleClient(trimmed, model, logger);
+  const sleep = options.sleep ?? realSleep;
+  if (provider === "google")
+    return new GoogleClient(trimmed, model, logger, sleep);
+  const cli = CLI_SPECS[provider];
+  if (cli) return new CliClient(cli, model, logger);
+  if (provider === "local") {
+    return new OpenAiCompatibleClient(
+      provider,
+      options.baseUrl ?? localBaseUrl(trimmed),
+      null,
+      model,
+      logger,
+      sleep
+    );
+  }
+  const baseUrl = options.baseUrl ?? OPENAI_COMPATIBLE_BASE_URLS[provider];
+  if (!baseUrl) return null;
+  return new OpenAiCompatibleClient(
+    provider,
+    baseUrl,
+    trimmed,
+    model,
+    logger,
+    sleep
+  );
 }
 
 // src/synthesize.ts
@@ -357,6 +950,10 @@ async function synthesize(question, evidence) {
 
 // src/tools.ts
 var MAX_EXCERPT = 220;
+function confidenceLabel(p) {
+  if (p.status === "inferred") return `${Math.round((p.confidence ?? 0) * 100)}%`;
+  return p.status;
+}
 var MAX_ITEMS = 5;
 function truncate(text, max) {
   return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
@@ -490,6 +1087,7 @@ async function evrexWhy(filePath, question) {
       "NOTE: the blocks above were extracted by cue-phrase matching, not by a model reading the conversation \u2014 they may be incomplete or miss context."
     );
   }
+  const hasBlocks = rejected.length > 0 || constraints.length > 0 || decisions.length > 0;
   if (synthesisEnabled()) {
     const answer = await synthesize(text, evidence);
     parts.push(
@@ -497,12 +1095,11 @@ async function evrexWhy(filePath, question) {
     );
   } else {
     parts.push(
-      "HOW TO USE THIS: treat the constraints and rejected approaches above as binding \u2014 they are what this team already decided, not suggestions. Do not re-propose a rejected approach unless you have new information that specifically invalidates the stated reason, and say so if you do. Answer the user from the evidence below; if it does not actually cover their question, say that rather than inferring."
+      hasBlocks ? "HOW TO USE THIS: treat the constraints and rejected approaches above as binding \u2014 they are what this team already decided, not suggestions. Do not re-propose a rejected approach unless you have new information that specifically invalidates the stated reason, and say so if you do. Answer the user from the evidence below; if it does not actually cover their question, say that rather than inferring." : "HOW TO USE THIS: no decisions, constraints or rejected approaches were extracted for this file \u2014 only the raw evidence below. Treat it as history to read, not as settled policy, and say so if it does not cover the question."
     );
   }
   const evidenceLines = evidence.slice(0, MAX_ITEMS).map((e) => {
-    const conf = e.provenance.status === "verified" ? "verified" : `${Math.round((e.provenance.confidence ?? 0) * 100)}%`;
-    return `- [${e.kind} ${conf}] ${truncate(e.excerpt, MAX_EXCERPT)}`;
+    return `- [${e.kind} ${confidenceLabel(e.provenance)}] ${truncate(e.excerpt, MAX_EXCERPT)}`;
   });
   parts.push(`EVIDENCE:
 ${evidenceLines.join("\n")}`);
@@ -528,7 +1125,7 @@ async function evrexSearch(query) {
   const rank = (e) => e.provenance.status === "verified" ? 1 : e.provenance.confidence ?? 0;
   results.sort((a, b) => rank(b.e) - rank(a.e));
   const lines = results.slice(0, MAX_ITEMS * 2).map(({ repo, e }) => {
-    const conf = e.provenance.status === "verified" ? "verified" : `${Math.round((e.provenance.confidence ?? 0) * 100)}%`;
+    const conf = confidenceLabel(e.provenance);
     const repoTag = multiRepo ? ` \xB7 ${repo.name}` : "";
     return `- [${e.kind} ${e.refId.slice(0, 8)} ${conf}${repoTag}] ${truncate(e.excerpt.replace(/\s+/g, " ").trim(), MAX_EXCERPT)}`;
   });
@@ -543,9 +1140,15 @@ ${truncate(commit.body, MAX_EXCERPT)}` : ""}`
   ];
   if (commit.link) {
     const session = await evrexApi.session(commit.link.sessionId);
-    const status = commit.link.provenance.status === "verified" ? "verified" : "inferred";
-    const conf = commit.link.provenance.status === "verified" ? "" : ` (${Math.round((commit.link.provenance.confidence ?? 0) * 100)}%)`;
-    parts.push(`LINKED SESSION (${status}${conf}): ${session ? session.intent : commit.link.sessionId}`);
+    const status = commit.link.provenance.status;
+    const conf = status === "inferred" ? ` (${Math.round((commit.link.provenance.confidence ?? 0) * 100)}%)` : "";
+    if (session) {
+      parts.push(`LINKED SESSION (${status}${conf}): ${session.intent}`);
+    } else {
+      parts.push(
+        `LINKED SESSION (${status}${conf}): ${commit.link.sessionId} \u2014 NOT INDEXED. The commit was stamped as belonging to this session, but the transcript was never uploaded, so no reasoning is available for it. Do not treat this as recovered context.`
+      );
+    }
     if (session) {
       if (session.rejected.length > 0) {
         parts.push(
@@ -575,7 +1178,8 @@ ${lines.join("\n")}`);
 }
 
 // src/index.ts
-var server = new McpServer({ name: "evrex", version: "0.1.0" });
+var VERSION = "0.4.0";
+var server = new McpServer({ name: "evrex", version: VERSION });
 server.registerTool(
   "evrex_why",
   {
@@ -626,7 +1230,28 @@ function assertConfigured() {
   );
   process.exit(1);
 }
+async function runEnrolment() {
+  const { enrol: enrol2 } = await Promise.resolve().then(() => (init_enrol(), enrol_exports));
+  const { CredentialStore: CredentialStore3 } = await Promise.resolve().then(() => (init_credential_store(), credential_store_exports));
+  const { hostname } = await import("node:os");
+  const { evrexApi: evrexApi2 } = await Promise.resolve().then(() => (init_client(), client_exports));
+  const result = await enrol2({
+    fetch: globalThis.fetch,
+    store: new CredentialStore3(),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    log: (line) => console.error(line),
+    now: () => Date.now(),
+    hostname,
+    baseUrl: evrexApi2.baseUrl,
+    dashboardUrl: process.env.EVREX_DASHBOARD_URL ?? "https://app.evrex.ai",
+    clientVersion: VERSION
+  });
+  process.exit(result.ok ? 0 : 1);
+}
 async function main() {
+  if (process.argv[2] === "enrol" || process.argv[2] === "enroll") {
+    await runEnrolment();
+  }
   assertConfigured();
   const transport = new StdioServerTransport();
   await server.connect(transport);