@modusensus/dsh-mneme 0.7.31 → 0.7.32

package/src/tools.js

@@ -1,4 +1,9 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import { describeLocalRuntime, resolveRuntimeEntry } from "./runtime/loader.js";
+import { defaultRuntimeDir } from "./runtime/layout.js";
+import { hostModulesDir, loadRuntimeManifest, provisionRuntime } from "./runtime/provision.js";
+import { matchesPlatform } from "./runtime/closure.js";
+import { verifyPayload } from "./runtime/verify.js";
 
 const TEXT_OUTPUT = (text) => [{ type: "text", text }];
 // Per-registry tool-name registry: guards against duplicate registration on
@@ -331,6 +336,120 @@ export function createTools(ctx, service, config, embedder) {
         const memory = service.setArchived(args.id, args.archived ?? true);
         return { memory: { id: memory.id, archived: memory.archived } };
       }
+    }),
+
+    // 运行时口子（issue #131 / PR-C）。
+    //
+    // 为什么要有这个工具：mneme 的取向是「本体保持完善但轻量；重的功能存在、默认不开、不被依赖」。
+    // 本地向量化就是那个重功能 —— 它需要额外一份运行时（解包后数百 MB）。面板上有按钮，但用户
+    // 可能根本不看面板；这时 agent 需要一个入口，能先查状态、把代价告诉用户，再按需取回。
+    //
+    // 关于「要不要直接 provision」：它会联网、可能传几十到上百 MB、耗时数分钟。所以工具描述里
+    // 明确要求先告知用户；只有在用户已经表示要本地向量化时才直接动手。
+    defineTool({
+      name: "memory_runtime",
+      description:
+        "Inspect or provision the LOCAL inference runtime that dsh-mneme's local (offline) embedding and rerank need: " +
+        "the transformers + onnxruntime dependency closure, hundreds of MB unpacked. It is deliberately NOT a default " +
+        "dependency — mneme's core stays lightweight and local vectorization is opt-in — so this tool is the hook that " +
+        "makes the heavy capability available on demand. Use action=status first: it is read-only and reports whether " +
+        "the runtime is ready plus what provisioning would cost. action=provision tries, in order: (1) adopting an " +
+        "existing copy from this profile's node_modules (no network; hardlinked when on the same volume, so no extra " +
+        "disk), (2) a configured local .tgz directory, (3) downloading from the npm registry against a pinned manifest, " +
+        "verifying every tarball's sha512. Provisioning can transfer tens to hundreds of MB and take minutes: unless " +
+        "the user has already asked for local vectorization, tell them that cost before calling it. action=verify loads " +
+        "the runtime and runs one real inference (strictly offline, so the model must already be cached).",
+      parameters: {
+        action: { type: "string", enum: ["status", "provision", "verify"], required: true, description: "status = read-only; provision = fetch/adopt the runtime; verify = run one real inference" },
+        overwrite: { type: "boolean", description: "provision only: replace an existing payload (use when repairing a broken one)" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            summary: { type: "string", required: true },
+            status: { type: "string", required: true },
+            cost: { type: "string", required: true },
+            strategy: { type: "string" },
+            payloadId: { type: "string" },
+            packages: { type: "integer" },
+            files: { type: "integer" },
+            bytes: { type: "integer" },
+            dimension: { type: "integer" },
+            reason: { type: "string" }
+          }
+        },
+        render: (_args, value) => TEXT_OUTPUT(value.summary)
+      },
+      async execute(args) {
+        const runtimeDir = config?.runtimeDir ?? "";
+        const manifest = loadRuntimeManifest();
+        const forPlatform = Array.isArray(manifest?.packages) ? manifest.packages.filter((pkg) => matchesPlatform(pkg, process.platform, process.arch)) : null;
+        const cost =
+          `Local vectorization needs an extra local inference runtime (transformers + onnxruntime closure, ` +
+          `hundreds of MB unpacked${forPlatform ? `, ${forPlatform.length} packages for this platform` : ""}). ` +
+          `It is not a default dependency: provisioning adopts an existing copy when possible, otherwise downloads it.`;
+
+        if (args.action === "provision") {
+          const result = await provisionRuntime({
+            hostModulesDir: hostModulesDir(import.meta.url),
+            runtimeDir,
+            localTarballDir: config?.runtimeTarballDir ?? "",
+            mirror: config?.runtimeMirror ?? "",
+            overwrite: args.overwrite === true,
+            manifest
+          });
+          return {
+            summary: result.ok
+              ? `Runtime ${result.strategy === "download" ? "downloaded from npm" : "adopted from this machine"}: ` +
+                `${result.packages} packages / ${result.files} files. Local embedding can be used after a DSH reload.`
+              : `Could not provision the runtime: ${result.reason}`,
+            status: result.ok ? "available" : "failed",
+            cost,
+            strategy: result.strategy,
+            ...(result.payloadId ? { payloadId: result.payloadId } : {}),
+            ...(result.packages === undefined ? {} : { packages: result.packages }),
+            ...(result.files === undefined ? {} : { files: result.files }),
+            ...(result.bytes === undefined ? {} : { bytes: result.bytes }),
+            ...(result.reason ? { reason: result.reason } : {})
+          };
+        }
+
+        if (args.action === "verify") {
+          const candidate = resolveRuntimeEntry({ runtimeDir: runtimeDir || undefined });
+          if (candidate === null) {
+            return { summary: "No usable runtime payload to verify.", status: "missing", cost };
+          }
+          const report = await verifyPayload(candidate.dir, { cacheDir: config?.embedModelCacheDir || undefined });
+          return {
+            summary: report.ok
+              ? `Runtime verified: real inference succeeded (dim ${report.functional.dim}, ${report.functional.rows} rows, ` +
+                `${report.functional.elapsedMs}ms, offline). Integrity: ${report.integrity.status}.`
+              : `Runtime verification failed — structural: ${report.structural.ok}, functional: ${report.functional.ok} (${report.functional.reason}).`,
+            status: report.ok ? "verified" : "failed",
+            cost,
+            payloadId: candidate.payloadId,
+            ...(report.functional.dim ? { dimension: report.functional.dim } : {}),
+            ...(report.ok ? {} : { reason: report.functional.reason })
+          };
+        }
+
+        // status：只读，且刻意不加载模型（那要几百毫秒且碰缓存）。报告要给到 agent 足够的信息去
+        // 决定「要不要打扰用户」。
+        const report = describeLocalRuntime({ runtimeDir: runtimeDir || defaultRuntimeDir() });
+        return {
+          summary:
+            `Local inference runtime: ${report.status}` +
+            (report.payloadId ? ` (${report.payloadId}, ${report.procedure ?? "?"}, ${report.materialize ?? "?"})` : "") +
+            `. ${report.status === "available" ? "Local embedding/rerank can be used." : "Local embedding is unavailable — " + (report.hint ?? "")}`,
+          status: report.status,
+          cost,
+          ...(report.payloadId ? { payloadId: report.payloadId } : {}),
+          ...(forPlatform ? { packages: forPlatform.length } : {}),
+          ...(report.reason ? { reason: report.reason } : {})
+        };
+      }
     })
   ];
 

package/test/api.test.js

@@ -33,7 +33,7 @@ function req(path, method = "GET", body = null) {
   return r;
 }
 
-function setup(embedder, apiToken = "", config = null) {
+function setup(embedder, apiToken = "", config = null, semantic = undefined) {
   const store = createStore(":memory:");
   const service = createService({ store, mirror: null, config: {} });
   const settings = createSettings(store.db);
@@ -51,7 +51,7 @@ function setup(embedder, apiToken = "", config = null) {
       }
     }
   };
-  const api = createApi(ctx, service, settings, commands, embedder, undefined, apiToken, config);
+  const api = createApi(ctx, service, settings, commands, embedder, semantic, apiToken, config);
   return { store, service, routes, api, settings, apiToken };
 }
 
@@ -470,6 +470,73 @@ test("GET /api/dsh-mneme/semantic reports ready state per embedder", async () =>
   assert.equal(named.ready, true);
 });
 
+// --- #135: /semantic must tell "not configured" apart from "degraded" ---------
+
+test("GET /api/dsh-mneme/semantic reports configured/coverage/degraded", async () => {
+  const fetchSem = async (embedder, semantic) => {
+    const { routes } = setup(embedder, "", null, semantic);
+    const sem = routes.find((r) => r.path === "/api/dsh-mneme/semantic");
+    const res = new FakeRes();
+    await sem.handler(req("/api/dsh-mneme/semantic"), res);
+    assert.equal(res.statusCode, 200);
+    return JSON.parse(res.body);
+  };
+  // Stats double: `total` is the memory count, `embedded` the indexed count.
+  const index = (embeddedCount, totalCount) => ({
+    vectorIndex: { getStats: () => ({ embeddedCount, totalCount }) }
+  });
+  const openai = (ready, configured) => ({
+    name: "OpenAI",
+    get ready() { return ready; },
+    get configured() { return configured; },
+    embed() {}
+  });
+
+  // No embedder at all → everything reports absence, not a false green.
+  const none = await fetchSem(undefined, index(0, 0));
+  assert.equal(none.configured, null);
+  assert.equal(none.reason, "no-embedder");
+  assert.equal(none.degraded, false);
+  assert.deepEqual(none.coverage, { embedded: 0, total: 0, ratio: null },
+    "empty store → ratio null (0 would read as 'nothing embedded')");
+
+  // Configured embedder still initializing: unreachable ≠ unconfigured.
+  assert.equal((await fetchSem(openai(false, true), index(0, 346))).reason, "initializing");
+
+  // Never configured: reported as such even though the index has memories.
+  const unconfigured = await fetchSem(openai(false, false), index(0, 346));
+  assert.equal(unconfigured.ready, false);
+  assert.equal(unconfigured.configured, false);
+  assert.equal(unconfigured.reason, "not-configured");
+  assert.equal(unconfigured.degraded, false, "unconfigured was never meant to index");
+  assert.equal(unconfigured.coverage.ratio, 0);
+
+  // Configured, memories present, zero vectors — the state this machine sat in
+  // for weeks while the card showed a healthy provider.
+  const degraded = await fetchSem(openai(true, true), index(0, 346));
+  assert.equal(degraded.reason, null, "a complete config has no abnormal reason");
+  assert.equal(degraded.degraded, true);
+  assert.equal(degraded.coverage.ratio, 0);
+
+  // Healthy index.
+  const ok = await fetchSem(openai(true, true), index(173, 346));
+  assert.equal(ok.degraded, false);
+  assert.equal(ok.coverage.ratio, 0.5);
+
+  // Adapters without a `configured` field (third-party/test doubles) keep the
+  // old contract: assumed configured, `ready` decides.
+  const legacy = await fetchSem({ embed() {} }, index(5, 10));
+  assert.equal(legacy.configured, true);
+  assert.equal(legacy.reason, null);
+  assert.equal(legacy.ready, true);
+
+  // No stats provider (no vector index) must not throw — coverage falls back
+  // to zeros and an empty store is never "degraded".
+  const noIndex = await fetchSem(openai(true, true), null);
+  assert.deepEqual(noIndex.coverage, { embedded: 0, total: 0, ratio: null });
+  assert.equal(noIndex.degraded, false);
+});
+
 // --- Bug8: llm-audit API (pagination + stats) --------------------------------
 
 test("GET /api/dsh-mneme/semantic/llm-audit returns paginated rows", async () => {
@@ -577,19 +644,20 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   assert.equal(res.statusCode, 200);
   const data = JSON.parse(res.body);
   assert.deepEqual(data.overrides, {});
-  // effective 覆盖全部 42 个白名单键（含 v0.7.20 heatEnabled、Issue #89 新增
+  // effective 覆盖全部 51 个白名单键（含 v0.7.20 heatEnabled、Issue #89 新增
   // dreamSkipInvalid/allowCrossTypeMerge/dreamMinIntervalMinutes、面板可调的
   // dreamMaxTokens、睡眠路由 sleepProvider/sleepModel、PR1 新增的
-  // recallFusion/signalTransparency，以及 issue #109 新增的实体抽取路由
-  // entityExtractionProvider/entityExtractionModel/entityExtractionReasoning），
-  // 未覆盖时取 bundle 配置的解析默认值；
+  // recallFusion/signalTransparency、issue #109 新增的实体抽取路由
+  // entityExtractionProvider/entityExtractionModel/entityExtractionReasoning、
+  // issue #127 新增的 summarize 五键、issue #126 新增的 sleepActionSet，以及
+  // issue #125 新增的候选集三键），未覆盖时取 bundle 配置的解析默认值；
   // dreamProvider/dreamModel 无 schema 默认值（Config({}) 解析为 undefined），
-  // 不编造给前端 → 42 - 2 = 40
-  assert.equal(Object.keys(data.effective).length, 40);
+  // 不编造给前端 → 51 - 2 = 49
+  assert.equal(Object.keys(data.effective).length, 49);
   assert.equal(data.effective.dreamSkipInvalid, true);
   assert.equal(data.effective.allowCrossTypeMerge, false);
   assert.equal(data.effective.dreamMinIntervalMinutes, 0);
-  assert.equal(data.effective.dreamMaxTokens, 32768);
+  assert.equal(data.effective.dreamMaxTokens, 131072);
   assert.equal(data.effective.sleepProvider, "");
   assert.equal(data.effective.sleepModel, "");
   assert.equal(data.effective.autoInject, true);
@@ -615,6 +683,18 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   assert.equal(data.effective.entityExtractionProvider, "");
   assert.equal(data.effective.entityExtractionModel, "");
   assert.equal(data.effective.entityExtractionReasoning, "none");
+  // issue #127：summarize 节流五键（均有默认值，故计入 effective 计数）
+  assert.equal(data.effective.summarizeMinIntervalMinutes, 0);
+  assert.equal(data.effective.summarizeMaxEntriesPerRun, 0);
+  assert.equal(data.effective.summarizeDedupeMode, "off");
+  assert.equal(data.effective.summarizeDedupeMinSim, 0.92);
+  assert.equal(data.effective.summarizeDedupeWindowHours, 24);
+  // issue #126：sleep 动作集（默认 conflict = 现状；面板可切 full）
+  assert.equal(data.effective.sleepActionSet, "conflict");
+  // issue #125：候选集三键（默认 window / 0 / 0.85）
+  assert.equal(data.effective.dreamCandidateMode, "window");
+  assert.equal(data.effective.dreamCandidateMax, 0);
+  assert.equal(data.effective.dreamCandidateMinSim, 0.85);
 });
 
 test("PUT /api/dsh-mneme/features round-trips, overrides effective and persists", async () => {

package/test/client.test.js

@@ -121,10 +121,10 @@ test("trigger renders a wide row or a rail icon from the wide flag", () => {
   );
 });
 
-// The entry lives ABOVE the workspaces region: the real button is portalled
-// just before the host's regionArea container (below New Session, above the
-// workspace list), while the sidebar.footer.action registration remains as
-// the React anchor and the in-place fallback when the host markup changes.
+// The entry lives at the top of the plugin-entry group: the real button is
+// portalled right after the host's New-Session row (above the entries other
+// plugins inject there), while the sidebar.footer.action registration remains
+// as the React anchor and the in-place fallback when the host markup changes.
 test("sidebar entry portals above the workspaces region with footer fallback", () => {
   assert.ok(
     clientSource.includes('ctx.slots.inject("sidebar.footer.action"'),
@@ -139,8 +139,8 @@ test("sidebar entry portals above the workspaces region with footer fallback", (
     "the portal must anchor at the host's regionArea container"
   );
   assert.ok(
-    clientSource.includes("insertBefore(created, region)"),
-    "the entry must sit immediately above the workspaces region"
+    clientSource.includes("insertBefore(created, target)"),
+    "the entry must be placed through the idempotent place() helper"
   );
   assert.ok(
     clientSource.includes("if (!host) return fallback;"),
@@ -160,13 +160,40 @@ test("sidebar entry portals above the workspaces region with footer fallback", (
   );
 });
 
+// Issue #130: ecosystem plugins (task board, skill explorer, …) inject their
+// own entries right after the New-Session row, and late inserters land above
+// earlier ones — a fixed "before regionArea" slot degrades into the tail of
+// that group, detaching the memory button from its familiar top spot. The
+// entry therefore (a) resolves the same anchor as the ecosystem's shared
+// sidebar-entry-core (logoRow row, legacy direct-child button), (b) re-asserts
+// its slot from the existing observer, and (c) stays idempotent — the anchor
+// check short-circuits before any DOM write, so observers never ping-pong.
+test("entry re-asserts the New-Session-adjacent slot against ecosystem entries", () => {
+  assert.ok(
+    clientSource.includes(`btn.closest('[class*="logoRow"]')`),
+    "the anchor must resolve the New-Session logo row like the ecosystem core"
+  );
+  assert.ok(
+    clientSource.includes("const target = anchor ? anchor.nextSibling : region;"),
+    "the entry must sit right after the New-Session row, falling back before regionArea"
+  );
+  assert.ok(
+    clientSource.includes("if (created.parentElement === parent && created.nextSibling === target) return;"),
+    "placement must be idempotent so the observer never writes on steady state"
+  );
+  assert.ok(
+    /place\(cur\);\s*\n\s*const cls = findNative\(cur\)/.test(clientSource),
+    "the observer must re-place the entry on childList churn, not just re-sync the class"
+  );
+});
+
 // Three alignment/softness guarantees born from field feedback: (a) the
 // portalled entry keeps tracking the live New-Session class (host and skin
 // rewrite it asynchronously, so a mount-time snapshot goes stale), (b) it
-// fills the same width as that button and inherits its native centering,
+// inherits that button's width and margins along with its native centering,
 // (c) the toolbar dropdown escapes the transform stacking trap — the
 // container needs the z-index because transform creates the context.
-test("entry tracks native class, fills native width, and lifts the toolbar dropdown", () => {
+test("entry tracks native class, inherits native sizing, and lifts the toolbar dropdown", () => {
   assert.ok(
     clientSource.includes("new MutationObserver"),
     "the entry must re-sync the copied class via MutationObserver"
@@ -175,9 +202,14 @@ test("entry tracks native class, fills native width, and lifts the toolbar dropd
     clientSource.includes('attributeFilter: ["class"]'),
     "the observer must watch class attribute changes"
   );
+  assert.doesNotMatch(
+    clientSource,
+    /\.mneme-topentry-native\{(?:[^}]*;)?width:/,
+    "the entry must use the native button width, which reserves its horizontal margins"
+  );
   assert.ok(
-    /\.mneme-topentry-native\{width:100%;/.test(clientSource),
-    "the entry button must fill the same width as the New-Session row"
+    clientSource.includes(".mneme-topentry{display:flex;flex-direction:column}"),
+    "the entry wrapper must stretch the native button within a column flex layout"
   );
   assert.equal(
     clientSource.includes(".mneme-topentry-native .mneme-topentry-label{flex:1;min-width:0;text-align:left;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}"),
@@ -593,3 +625,55 @@ test("settings feedback card: prefilled issue + mailto + browse, version from /i
     assert.ok(occurrences >= 2, `i18n key memory.settings.${key} must exist in both zh and en (got ${occurrences})`);
   }
 });
+
+// UI 文案必须双语齐全（中英各一条）。用户明确要求所有 UI 文字都做 i18n，
+// 这条守卫用「每个键恰好出现两次」兜住：出现奇数次就是漏译，>2 次说明重复。
+test("i18n keys are bilingual: every key appears exactly twice (zh + en)", () => {
+  const counts = new Map();
+  for (const match of clientSource.matchAll(/^\s*"([a-zA-Z0-9_.]+)"\s*:\s*"/gm)) {
+    counts.set(match[1], (counts.get(match[1]) ?? 0) + 1);
+  }
+  const odd = [...counts.entries()].filter(([, n]) => n !== 2).map(([key, n]) => `${key}×${n}`);
+  assert.deepEqual(odd, [], `这些 i18n 键没有做到中英各一条：${odd.join(", ")}`);
+  assert.ok(counts.size > 100, `解析到的键太少（${counts.size}），正则可能没匹配到 i18n 表`);
+});
+
+// issue #135：向量状态卡必须区分「没配」与「配了却一条都没嵌上」。此前卡片只看
+// ready，而未配置的 legacy embedder（ready 恒 true）一路显示成正常 provider。
+test("vector status card surfaces the configured/degraded split", () => {
+  // 1. 读后端新字段，缺失（旧服务端）时退化成旧行为而不是误报未配置
+  assert.ok(
+    clientSource.includes('typeof j?.configured === "boolean" ? j.configured : null'),
+    "the card must read `configured` and tolerate older servers that omit it"
+  );
+  assert.ok(
+    clientSource.includes("j?.degraded === true"),
+    "the card must read `degraded`"
+  );
+  // 2. 三态互斥：未配置优先于初始化中，降级只在既非未配置也非初始化时成立
+  assert.ok(
+    clientSource.includes("const unconfigured = !off && state.configured === false;"),
+    "unconfigured must be its own state, not folded into ready"
+  );
+  assert.ok(
+    clientSource.includes("const pending = !off && !unconfigured && state.ready !== true;"),
+    "an unconfigured embedder must not be reported as initializing"
+  );
+  assert.ok(
+    clientSource.includes("const degraded = !off && !unconfigured && !pending && state.degraded === true;"),
+    "degraded must only apply to a configured, settled embedder"
+  );
+  // 3. 三个状态各自的标签/说明走 i18n，双语齐备
+  for (const key of ["vectorUnconfigured", "vectorUnconfiguredHint", "vectorDegradedHint"]) {
+    const occurrences = clientSource.split(`"memory.status.${key}"`).length - 1;
+    assert.ok(occurrences >= 2, `i18n key memory.status.${key} must exist in both zh and en (got ${occurrences})`);
+  }
+  assert.ok(
+    clientSource.includes('t("memory.status.vectorUnconfigured")'),
+    "the unconfigured state must render its own label"
+  );
+  assert.ok(
+    clientSource.includes('t("memory.status.vectorDegradedHint")'),
+    "the degraded state must render its own caption (0 of {m} indexed)"
+  );
+});

package/test/config.test.js

@@ -46,5 +46,21 @@ test("startup probe: the reranker module never statically imports transformers/o
     !src.includes('from "@huggingface/transformers"'),
     "no static transformers.js import in reranker.js"
   );
-  assert.match(src, /await import\("@huggingface\/transformers"\)/, "transformers.js loads lazily via dynamic import");
+  // issue #131 之后，懒加载的落点从 reranker 内部搬到了 src/runtime/loader.js
+  // （三层解析：自管 payload → 宿主裸 specifier）。判据随之改成两条，意图不变：
+  // reranker 不得静态导入，且必须经由 loader 间接加载；动态 import 只允许出现在
+  // loader 里（它是唯一知道「运行时从哪来」的模块）。
+  assert.match(src, /from "\.\/runtime\/loader\.js"/, "reranker 经 runtime/loader.js 取运行时");
+  assert.match(src, /loadTransformers\(/, "reranker 必须走三层解析，而不是自己拼 import");
+  assert.ok(
+    !/^\s*import[^\n]*@huggingface\/transformers/m.test(src),
+    "reranker 不允许任何形式的静态 transformers 导入"
+  );
+
+  const loaderSrc = readFileSync(new URL("../src/runtime/loader.js", import.meta.url), "utf8");
+  assert.match(loaderSrc, /import\(specifier\)/, "loader 用动态 import 保持懒加载");
+  assert.ok(
+    !/^\s*import[^\n]*@huggingface\/transformers/m.test(loaderSrc),
+    "loader 不得静态导入 transformers，否则惰性加载就失效了"
+  );
 });