@modusensus/dsh-mneme 0.2.3 → 0.2.5

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-[![tests](https://img.shields.io/badge/tests-212%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-258%20passed-success)](https://github.com/modusensus/dsh-mneme)
 
 > 给 DeepSeek Harness 的跨会话记忆插件：让 Agent 记住你、记住项目、自动整理记忆。**Mneme**（Μνήμη）——希腊记忆女神 Mnemosyne 之名，掌管记忆与梦境，正如 autoDream 在后台巩固记忆。
 
@@ -19,16 +19,17 @@
 - **Markdown 镜像**：`preferences.md` / `projects.md` / `decisions.md` / `history.md` / `summary.md`，人类可读、可手工编辑（**人工修改优先**合并回库）
 - **4+1 种记忆类型**：`preference`（偏好）/ `project`（项目）/ `decision`（决策）/ `history`（历史）/ `summary`（总览）
 
-### 模型工具（6 个）
+### 模型工具（7 个）
 
 | 工具 | 功能 |
 |------|------|
 | `memory_save` | 记录一条记忆（自动按标题去重合并） |
 | `memory_search` | 全文搜索（中文子串友好，可启用向量语义搜索） |
-| `memory_list` | 按类型分页列出 |
+| `memory_list` | 按类型分页列出（`include_archived=true` 可查看已归档） |
 | `memory_update` | 修改已有记忆 |
 | `memory_delete` | 删除记忆 |
 | `memory_forget` | 抑制注入（降权不删除，可恢复） |
+| `memory_archive` | 归档/恢复记忆（v0.2.5；归档后隐藏于列表/搜索/注入/整理，`archived=false` 可恢复） |
 
 ### 自动注入 + 会话摘要
 
@@ -158,15 +159,33 @@ dsh web
 | `dreamThresholdChars` | `5000` | 触发整理的总字符阈值 |
 | `dreamDelayMs` | `2000` | 整理异步延迟（去抖） |
 | `dreamProvider` / `dreamModel` | 空 | dream 的 LLM 路由回退（默认用 agent 默认模型） |
+| `dreamMaxTokens` | `4096` | dream LLM 调用最大 token 数 |
+| `apiToken` | 空 | 可选 API 鉴权 token；设置后写操作与密钥接口要求 `Authorization: Bearer <apiToken>` |
 | `embedProvider` | `openai` | 语义后端：`openai`（默认，兼容 v0.1）/ `local`（ONNX 离线）/ `ollama` |
 | `localEmbedModel` | `Xenova/bge-small-zh-v1.5` | 本地 ONNX embedding 模型 |
 | `localEmbedDimension` | `512` | 本地 embedding 向量维度 |
+| `localEmbedDevice` | `cpu` | 本地推理设备：`cpu` / `gpu` |
 | `localEmbedBatchSize` | `8` | 本地 embedding 批大小（1-64） |
 | `ollamaBaseUrl` | `http://localhost:11434` | Ollama 服务地址 |
 | `ollamaModel` | `nomic-embed-text` | Ollama embedding 模型 |
-| `rerankEnabled` | `true` | 是否启用 Rerank 精排 |
+| `embedModelCacheDir` | 空 | 模型缓存目录（空 = transformers 默认缓存） |
+| `embedModelMirror` | `https://hf-mirror.com` | 模型下载镜像源 |
+| `vectorSearchTopK` | `20` | 向量搜索返回 Top-K |
+| `vectorSearchThreshold` | `0.65` | 向量搜索相似度阈值 |
+| `hybridSearchVectorWeight` | `0.6` | 混合搜索向量权重 |
+| `hybridSearchKeywordWeight` | `0.4` | 混合搜索关键词权重 |
+| `rerankEnabled` | `false` | 是否启用 Rerank 精排（显式开启才加载本地 onnxruntime 模型） |
+| `rerankProvider` | `none` | Rerank 后端：`local` / `none`（默认 `none`） |
 | `rerankModel` | `Xenova/bge-reranker-base` | Rerank 交叉编码模型 |
+| `rerankBatchSize` | `8` | Rerank 批大小 |
+| `rerankMaxCandidates` | `30` | Rerank 最大候选数 |
 | `rerankScoreThreshold` | `0.1` | Rerank 分数阈值（低于丢弃） |
+| `reflectionUpdateEnabled` | `true` | update 决策总开关 |
+| `reflectionFailureTracking` | `true` | 失败追踪总开关 |
+| `reflectionUpdateMaxPerRun` | `2` | 每次整理最多 update 数 |
+| `reflectionUpdateMinAgeHours` | `24` | 新建记忆保护期（小时） |
+
+> 🔐 **API 安全**：DSH 无内置鉴权且默认仅监听 `127.0.0.1`。插件 API 默认开放（便于 Web 面板即装即用）。如需防护（如局域网暴露），在配置中设置 `apiToken`：写操作（画像/规则/命令）与密钥端点（`vector-config`、`vector-reindex`）需携带 `Authorization: Bearer <token>`（前端设置面板可填入同一 token），只读的 `list` / `search` / `semantic` 保持开放。`/api/dsh-mneme/vector-config` 返回的 `apiKey` 已掩码（`sk-***…`），存储仍保留明文供调用；前端回传空或掩码值表示"不改 key"。
 
 ## 🏗️ 架构
 
@@ -178,7 +197,7 @@ dsh web
 │  服务层：saveWithDedupe / injectCandidates        │
 │         / mergeHumanEdits / onWrite 钩子          │
 ├─────────────────────────────────────────────────┤
-│  模型接口：6 个工具 + 自动注入 + 会话摘要          │
+│  模型接口：7 个工具 + 自动注入 + 会话摘要          │
 ├─────────────────────────────────────────────────┤
 │  autoDream：阈值调度 → LLM 决策清单               │
 │            → 校验（fail-safe）→ 应用 → 摘要       │
@@ -195,7 +214,7 @@ src/
 ├── mirror.js         # Markdown 镜像（渲染/解析，人工优先）
 ├── service.js        # 领域逻辑（去重合并、注入筛选、写入钩子）
 ├── config.js         # schemastery 配置 schema
-├── tools.js          # 6 个模型工具（defineTool）
+├── tools.js          # 7 个模型工具（defineTool）
 ├── inject.js         # systemPrompt.context 动态注入
 ├── summarize.js      # 会话结束 LLM 摘要
 ├── dream.js          # autoDream 调度 + runDream（LLM 决策 + 摘要）
@@ -206,7 +225,7 @@ src/
 lib/
 ├── client.js         # Web 面板（手写 ModuleLoader bundle）
 └── *.js              # src 的同步分发产物
-test/                 # 212 个 node:test 测试（含审计与三轴线压测不变量）
+test/                 # 258 个 node:test 测试（含审计与三轴线压测不变量）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步
 ```
 
@@ -215,14 +234,13 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 212 个测试
+npm test           # 运行 258 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```
 
 > 压测（`npm run stress`）三条轴线：**长会话检索**（Recall@k、陈旧残留率）、**冲突裁决**（可重放仲裁集：审计快照 hash + receipt + 幂等回放）、**多 Agent 并发**（丢更新、重复合并、事务/崩溃恢复）。每次 autoDream 运行都会写入审计表 `dream_runs`（输入快照 digest + 决策清单 + 逐 id 去向 + receipt），让高通过率下也能定位静默错误。
 
-> 注：`npm test` 使用 `--test-isolation=none` 适配受限沙箱；普通环境可直接 `node --test`。
 > `lib/` 是 `src/` 的同步分发产物（`npm run sync`），其中 `lib/client.js` 为手写 Web 面板源码，不受同步影响。
 
 ## 📄 设计文档

package/lib/api.js

@@ -1,10 +1,43 @@
 import { URL } from "node:url";
+import { timingSafeEqual } from "node:crypto";
 
 function sendJson(res, status, payload) {
   res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
   res.end(JSON.stringify(payload));
 }
 
+/**
+ * Mask an API key for client display: keep a recognizable prefix and suffix,
+ * hide the middle. Empty keys stay empty; short keys are fully hidden.
+ * The mask only exists in the API layer — storage keeps the real key.
+ */
+function maskApiKey(key) {
+  if (!key) return "";
+  if (key.length <= 8) return "***";
+  return `${key.slice(0, 3)}***${key.slice(-4)}`;
+}
+
+/** True when the request carries the configured apiToken (or no token is set). */
+function isAuthorized(req, apiToken) {
+  if (!apiToken) return true;
+  const raw = req.headers?.authorization ?? req.headers?.["x-dsh-mneme-token"] ?? "";
+  const token = raw.startsWith("Bearer ") ? raw.slice(7).trim() : raw.trim();
+  if (token === "" || token.length !== apiToken.length) return false;
+  // Constant-time comparison: avoid leaking the token via timing when the API
+  // is exposed beyond loopback.
+  return timingSafeEqual(Buffer.from(token), Buffer.from(apiToken));
+}
+
+/**
+ * Reject a request with 401 when auth is enabled and the token is missing or
+ * wrong. Returns true when the request may proceed.
+ */
+function requireAuth(req, res, apiToken) {
+  if (isAuthorized(req, apiToken)) return true;
+  sendJson(res, 401, { error: "unauthorized" });
+  return false;
+}
+
 /** Collect the request body as text (tolerant of empty/invalid bodies). */
 function readBody(req) {
   return new Promise((resolve) => {
@@ -23,7 +56,7 @@ function parseBody(text) {
   }
 }
 
-export function createApi(ctx, service, settings, commands, embedder, semantic = null) {
+export function createApi(ctx, service, settings, commands, embedder, semantic = null, apiToken = "") {
   const disposers = [];
 
   // Ensure the service has an embedder when the API layer was handed one
@@ -113,6 +146,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     handler(req, res) {
       try {
         if (req.method === "PUT" || req.method === "POST") {
+          if (!requireAuth(req, res, apiToken)) return;
           return readBody(req).then((text) => {
             const body = parseBody(text);
             settings.setProfile(typeof body.profile === "string" ? body.profile : "");
@@ -133,6 +167,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     handler(req, res) {
       try {
         if (req.method === "PUT" || req.method === "POST") {
+          if (!requireAuth(req, res, apiToken)) return;
           return readBody(req).then((text) => {
             const body = parseBody(text);
             settings.setRules(Array.isArray(body.rules) ? body.rules : []);
@@ -152,19 +187,31 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     path: "/api/dsh-mneme/vector-config",
     handler(req, res) {
       try {
+        // Secret-bearing endpoint: fully protected when apiToken is set.
+        if (!requireAuth(req, res, apiToken)) return;
         if (req.method === "PUT" || req.method === "POST") {
           return readBody(req).then((text) => {
             const body = parseBody(text);
+            // An empty apiKey, or one that already looks masked (round-trips
+            // through maskApiKey unchanged), means "keep the existing key".
+            // Only a fresh, unmasked key is treated as a real replacement.
+            const prev = settings.getVectorConfig();
+            const incoming = typeof body.apiKey === "string" ? body.apiKey.trim() : "";
+            const isMaskedOrEmpty = incoming === "" || maskApiKey(incoming) === incoming;
+            const key = isMaskedOrEmpty
+              ? (prev?.apiKey ?? "")
+              : incoming;
             const cfg = settings.setVectorConfig({
               enabled: body.enabled,
               baseUrl: body.baseUrl,
-              apiKey: body.apiKey,
+              apiKey: key,
               model: body.model
             });
-            sendJson(res, 200, { config: cfg });
+            sendJson(res, 200, { config: { ...cfg, apiKey: maskApiKey(cfg.apiKey) } });
           });
         }
-        sendJson(res, 200, { config: settings.getVectorConfig() ?? { enabled: false, baseUrl: "", apiKey: "", model: "" } });
+        const cfg = settings.getVectorConfig() ?? { enabled: false, baseUrl: "", apiKey: "", model: "" };
+        sendJson(res, 200, { config: { ...cfg, apiKey: maskApiKey(cfg.apiKey) } });
       } catch {
         sendJson(res, 500, { error: "internal" });
       }
@@ -177,6 +224,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     path: "/api/dsh-mneme/vector-reindex",
     handler(req, res) {
       try {
+        if (!requireAuth(req, res, apiToken)) return;
         if (!embedder) {
           sendJson(res, 200, { indexed: 0, skipped: 0, error: "vector-unavailable" });
           return;
@@ -227,6 +275,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     handler(req, res) {
       try {
         if (req.method === "POST") {
+          if (!requireAuth(req, res, apiToken)) return;
           return readBody(req).then((text) => {
             const body = parseBody(text);
             try {
@@ -242,6 +291,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           });
         }
         if (req.method === "DELETE") {
+          if (!requireAuth(req, res, apiToken)) return;
           const url = new URL(req.url, "http://localhost");
           const id = url.searchParams.get("id");
           const removed = id ? commands.remove(id) : false;

package/lib/client.js

@@ -9,6 +9,19 @@ window.__ModuleLoader__.load({
     let { useState, useEffect, useCallback, useRef } = react;
     let { createPortal } = reactDom;
 
+    // Unified API fetcher: attaches the optional apiToken (set in the settings
+    // panel, persisted in localStorage) as a Bearer header. When no token has
+    // been configured the header is omitted and the API stays open (default).
+    const API_TOKEN_KEY = "dsh-mneme-api-token";
+    function apiFetch(path, opts = {}) {
+      const token = (typeof window !== "undefined" && window.localStorage)
+        ? window.localStorage.getItem(API_TOKEN_KEY) || ""
+        : "";
+      const headers = { ...(opts.headers || {}) };
+      if (token) headers["Authorization"] = `Bearer ${token}`;
+      return fetch(path, { ...opts, headers });
+    }
+
     const inject = ["slots", "locale"];
 
     const NS = "memory";
@@ -53,7 +66,12 @@ window.__ModuleLoader__.load({
         "memory.settings.vectorSaved": "配置已保存",
         "memory.settings.vectorReindex": "重建索引",
         "memory.settings.vectorReindexing": "索引中…",
-        "memory.settings.vectorReindexDone": "已索引 {n} 条"
+        "memory.settings.vectorReindexDone": "已索引 {n} 条",
+        "memory.settings.apiTokenTitle": "API Token（可选）",
+        "memory.settings.apiTokenHint": "设置后，写操作与密钥接口（画像/规则/命令/向量配置）需携带 Authorization: Bearer <token>；面板只读操作不受影响。清空并保存可关闭鉴权。",
+        "memory.settings.apiTokenPlaceholder": "留空 = 不鉴权（默认）",
+        "memory.settings.apiTokenSave": "保存 Token",
+        "memory.settings.apiTokenSaved": "Token 已保存"
       },
       en: {
         "memory.panel.title": "Memory",
@@ -94,7 +112,12 @@ window.__ModuleLoader__.load({
         "memory.settings.vectorSaved": "Config saved",
         "memory.settings.vectorReindex": "Reindex",
         "memory.settings.vectorReindexing": "Indexing…",
-        "memory.settings.vectorReindexDone": "Indexed {n} items"
+        "memory.settings.vectorReindexDone": "Indexed {n} items",
+        "memory.settings.apiTokenTitle": "API Token (optional)",
+        "memory.settings.apiTokenHint": "When set, write operations and secret endpoints (profile/rules/commands/vector config) require Authorization: Bearer <token>. Read-only panel calls stay open. Save empty to disable.",
+        "memory.settings.apiTokenPlaceholder": "Empty = no auth (default)",
+        "memory.settings.apiTokenSave": "Save Token",
+        "memory.settings.apiTokenSaved": "Token saved"
       }
     };
 
@@ -120,7 +143,7 @@ window.__ModuleLoader__.load({
       const abortRef = useRef(null);
 
       useEffect(() => {
-        fetch("/api/dsh-mneme/vector-config")
+        apiFetch("/api/dsh-mneme/vector-config")
           .then((res) => res.json())
           .then((d) => setVecEnabled(!!d.config?.enabled))
           .catch(() => {});
@@ -137,7 +160,7 @@ window.__ModuleLoader__.load({
           const url = query.trim()
             ? `/api/dsh-mneme/search?q=${encodeURIComponent(query.trim())}&mode=${semantic ? "vector" : "auto"}`
             : `/api/dsh-mneme/list?${params.toString()}`;
-          const res = await fetch(url, { signal: controller.signal });
+          const res = await apiFetch(url, { signal: controller.signal });
           const data = await res.json();
           setItems(data.items || []);
         } catch (error) {
@@ -224,14 +247,18 @@ window.__ModuleLoader__.load({
       const [vectorSaved, setVectorSaved] = react.useState(false);
       const [reindexing, setReindexing] = react.useState(false);
       const [reindexMsg, setReindexMsg] = react.useState("");
+      const [apiToken, setApiToken] = react.useState(() =>
+        (typeof window !== "undefined" && window.localStorage) ? window.localStorage.getItem("dsh-mneme-api-token") || "" : ""
+      );
+      const [apiTokenSaved, setApiTokenSaved] = react.useState(false);
 
       const load = react.useCallback(async () => {
         try {
           const [p, r, c, v] = await Promise.all([
-            fetch("/api/dsh-mneme/profile").then((res) => res.json()),
-            fetch("/api/dsh-mneme/rules").then((res) => res.json()),
-            fetch("/api/dsh-mneme/commands").then((res) => res.json()),
-            fetch("/api/dsh-mneme/vector-config").then((res) => res.json())
+            apiFetch("/api/dsh-mneme/profile").then((res) => res.json()),
+            apiFetch("/api/dsh-mneme/rules").then((res) => res.json()),
+            apiFetch("/api/dsh-mneme/commands").then((res) => res.json()),
+            apiFetch("/api/dsh-mneme/vector-config").then((res) => res.json())
           ]);
           setProfile(p.profile || "");
           setRules(Array.isArray(r.rules) ? r.rules : []);
@@ -244,7 +271,7 @@ window.__ModuleLoader__.load({
 
       async function saveProfile() {
         try {
-          await fetch("/api/dsh-mneme/profile", {
+          await apiFetch("/api/dsh-mneme/profile", {
             method: "PUT",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ profile })
@@ -255,7 +282,7 @@ window.__ModuleLoader__.load({
       }
 
       async function putRules(next) {
-        await fetch("/api/dsh-mneme/rules", {
+        await apiFetch("/api/dsh-mneme/rules", {
           method: "PUT",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ rules: next })
@@ -282,7 +309,7 @@ window.__ModuleLoader__.load({
         const instruction = newCmd.instruction.trim();
         if (!name || !instruction) return;
         try {
-          const res = await fetch("/api/dsh-mneme/commands", {
+          const res = await apiFetch("/api/dsh-mneme/commands", {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ name, description: newCmd.description, instruction })
@@ -296,13 +323,13 @@ window.__ModuleLoader__.load({
       }
 
       async function removeCommand(id) {
-        await fetch(`/api/dsh-mneme/commands?id=${encodeURIComponent(id)}`, { method: "DELETE" });
+        await apiFetch(`/api/dsh-mneme/commands?id=${encodeURIComponent(id)}`, { method: "DELETE" });
         setCommands(commands.filter((c) => c.id !== id));
       }
 
       async function saveVector() {
         try {
-          await fetch("/api/dsh-mneme/vector-config", {
+          await apiFetch("/api/dsh-mneme/vector-config", {
             method: "PUT",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(vector)
@@ -316,7 +343,7 @@ window.__ModuleLoader__.load({
         setReindexing(true);
         setReindexMsg("");
         try {
-          const res = await fetch("/api/dsh-mneme/vector-reindex");
+          const res = await apiFetch("/api/dsh-mneme/vector-reindex");
           const data = await res.json();
           const n = data.indexed ?? 0;
           setReindexMsg(t("memory.settings.vectorReindexDone").replace("{n}", String(n)));
@@ -324,6 +351,15 @@ window.__ModuleLoader__.load({
         setReindexing(false);
       }
 
+      function saveToken() {
+        try {
+          if (apiToken.trim()) window.localStorage.setItem("dsh-mneme-api-token", apiToken.trim());
+          else window.localStorage.removeItem("dsh-mneme-api-token");
+          setApiTokenSaved(true);
+          setTimeout(() => setApiTokenSaved(false), 1500);
+        } catch { /* ignore */ }
+      }
+
       const inputStyle = { ...styles.search, marginBottom: 8 };
       const labelStyle = { fontSize: 12, fontWeight: 600, margin: "12px 0 4px" };
       const hintStyle = { fontSize: 11, color: "var(--dsw-alias-label-tertiary, #999)", marginBottom: 8 };
@@ -341,6 +377,14 @@ window.__ModuleLoader__.load({
         sectionTab === "memory"
           ? h(MemoryPanel, { t, embedded: true })
           : h("div", { style: { overflowY: "auto" } },
+              // api token (optional)
+              h("div", { style: { ...labelStyle, marginTop: 20 } }, t("memory.settings.apiTokenTitle")),
+              h("div", { style: hintStyle }, t("memory.settings.apiTokenHint")),
+              h("div", { style: { display: "flex", gap: 6 } },
+                h("input", { style: { ...inputStyle, flex: 1, marginBottom: 0 }, type: "password", value: apiToken, placeholder: t("memory.settings.apiTokenPlaceholder"), onChange: (e) => setApiToken(e.target.value) }),
+                h("button", { style: styles.footerButton, onClick: saveToken }, t("memory.settings.apiTokenSave"))
+              ),
+              apiTokenSaved && h("div", { style: { fontSize: 12, color: "var(--dsw-alias-state-success, #2a7)" } }, t("memory.settings.apiTokenSaved")),
               // profile
               h("div", { style: labelStyle }, t("memory.settings.profile")),
               h("div", { style: hintStyle }, t("memory.settings.profileHint")),

package/lib/config.js

@@ -14,6 +14,15 @@ export const Config = z.object({
   dreamModel: z.string(),
   dreamMaxTokens: z.natural().min(256).max(32768).default(4096),
 
+  // --- API protection ------------------------------------------------------
+  // Optional shared token for the plugin's HTTP API. Empty (default) keeps
+  // the API open (DSH binds to 127.0.0.1 and has no built-in auth); when set,
+  // sensitive endpoints (vector-config, vector-reindex, and all write ops on
+  // profile/rules/commands) require `Authorization: Bearer <apiToken>` (or
+  // `X-DSH-Mneme-Token`). Read-only list/search/semantic stay open so the
+  // Web panel keeps working without the token.
+  apiToken: z.string(),
+
   // --- semantic: local embedding provider (v0.2) --------------------------
   // "openai" keeps the legacy external-API path (settings vector config);
   // "local" runs an ONNX model in-process; "ollama" calls a local Ollama.
@@ -40,8 +49,11 @@ export const Config = z.object({
   hybridSearchKeywordWeight: z.number().min(0).max(1).default(0.4),
 
   // --- semantic: rerank layer (v0.2) --------------------------------------
-  rerankEnabled: z.boolean().default(true),
-  rerankProvider: z.union([z.const("local"), z.const("none")]).default("local"),
+  // Opt-in by default (item ⑥): the local cross-encoder pulls in onnxruntime
+  // (transformers.js) at init, so a bare install must not load it. Only an
+  // explicit rerankEnabled=true + rerankProvider="local" constructs LocalReranker.
+  rerankEnabled: z.boolean().default(false),
+  rerankProvider: z.union([z.const("local"), z.const("none")]).default("none"),
   rerankModel: z.string().default("Xenova/bge-reranker-base"),
   rerankBatchSize: z.natural().min(1).max(64).default(8),
   rerankMaxCandidates: z.natural().min(5).max(100).default(30),