dsh-tdai-memory 0.3.6 → 0.4.1

package/README.md

@@ -1,5 +1,9 @@
 # dsh-tdai-memory
 
+## Configuration page (DSH 0.2.0-rc.2 and later)
+
+Open **Plugins → Installed → dsh-tdai-memory** from the homepage sidebar to configure and save this plugin. The page uses the official `plugins.bundle.config` interface, without a duplicate entry in global Settings. Web and Desktop share the page. This version requires DSH 0.2.0-rc.2 or a later 0.2.x host; existing configuration is retained.
+
 [![中文文档](https://img.shields.io/badge/%E4%B8%AD%E6%96%87%E6%96%87%E6%A1%A3-blue)](README.zh.md)
 
 **GitHub**: [Scorp1o117/dsh-tdai-memory](https://github.com/Scorp1o117/dsh-tdai-memory) · **npm**: [dsh-tdai-memory](https://www.npmjs.com/package/dsh-tdai-memory)
@@ -11,22 +15,22 @@ Part of the [DeepSeek Harness Enhancement Suite](https://github.com/Scorp1o117/d
 A port of **TencentDB Agent Memory** (Tencent Cloud's open-source four-layer
 memory system, originally an OpenClaw plugin) into DeepSeek Harness.
 
-## Compatibility (v0.3.6)
-
-Verified with DSH `0.1.7-rc.2` (Web) and `0.2.0-rc.2` (Desktop runtime) in isolated profiles. The Desktop app uses its own `desktop` profile. Other DSH prereleases remain unverified.
-
-## Desktop install
-
-Use the Desktop-installed `dsh` command (Application → Manage dsh Command), or the app’s Plugins page. Then install into the Desktop profile:
-
-```powershell
-dsh plugin --profile desktop add dsh-tdai-memory@0.3.6
-```
-
-Restart the Desktop app to load the client bundle. Desktop keeps its profile under `$DSH_HOME/profiles/desktop`.
-
-
-## Features
+## Compatibility (v0.4.1)
+
+Verified with DSH `0.1.7-rc.2` (Web) and `0.2.0-rc.2` (Desktop runtime) in isolated profiles. The Desktop app uses its own `desktop` profile. Other DSH prereleases remain unverified.
+
+## Desktop install
+
+Use the Desktop-installed `dsh` command (Application → Manage dsh Command), or the app’s Plugins page. Then install into the Desktop profile:
+
+```powershell
+dsh plugin --profile desktop add dsh-tdai-memory@0.3.6
+```
+
+Restart the Desktop app to load the client bundle. Desktop keeps its profile under `$DSH_HOME/profiles/desktop`.
+
+
+## Features
 
 - **L0 conversation capture**: every turn (turn end, request boundary) is
   written to raw conversation storage (JSONL + SQLite + FTS + vectors)
@@ -65,14 +69,14 @@ Hard-won wiring details:
 
 ## Configuration (profile patch + settings)
 
-Configuration is stored in the `tdai-memory` entry of the active Profile patch.
-On first launch, DSH imports the old `$DSH_HOME/settings.yaml` values into that
-entry. The **Web UI Settings → 记忆**
+Configuration is stored in the `tdai-memory` entry of the active Profile patch.
+On first launch, DSH imports the old `$DSH_HOME/settings.yaml` values into that
+entry. The **Web UI Settings → 记忆**
 section edits every field (v0.2.0, write-only keys); TdaiCore is built at
 startup, so changes apply **after a restart**.
 
-```yaml
-# $DSH_HOME/profiles/web/cordis.patch.yml
+```yaml
+# $DSH_HOME/profiles/web/cordis.patch.yml
 - id: tdai-memory
   name: 'dsh-tdai-memory'
   config:
@@ -103,11 +107,11 @@ then mount it in `$DSH_HOME/profiles/web/cordis.patch.yml`:
 - insert:
     - id: tdai-memory
       name: 'dsh-tdai-memory'
-      config: {}          # fill through Settings → 记忆
+      config: {}          # fill through Settings → 记忆
 ```
 
-and restart `dsh web`. LLM/embedding API keys can be set in the Web UI
-settings page (记忆 / Memory) or in the `tdai-memory` Profile patch entry.
+and restart `dsh web`. LLM/embedding API keys can be set in the Web UI
+settings page (记忆 / Memory) or in the `tdai-memory` Profile patch entry.
 
 > **Note for users**
 > - This plugin is a standard **profile bundle** (`dsh.bundle.patch`):
@@ -136,6 +140,14 @@ not need it. Users who select the local backend should install and approve
   stored=0); off by default; enable only with a more reliable model
 - **L1 memory vectors**: written with storage (8088 embedding is fast); L0
   vectors run as a background task, drained by `destroy()` on headless exit
+- **Search tools** (`toolsEnabled`, on by default): the switch lives in the
+  Plugins page and applies in place — the row config is `volatile`, so the
+  plugin re-syncs its registration without a restart. If both tools are
+  missing, look for the plugin's
+  `[tdai-memory] tools registered: tdai_memory_search, tdai_conversation_search`
+  log line (v0.4.1+). Before v0.4.1 it read `config.toolsEnabled` off the
+  Volatile wrapper cordis hands to `apply` — a property that never exists — so
+  the failure was completely silent (issue #3)
 - **Upgrades**: after pulling new upstream code, rerun
   `npx tsc -p dsh-tsconfig.json` in the tdai project dir (output in `dist-dsh/`)
 
@@ -143,3 +155,5 @@ not need it. Users who select the local backend should install and approve
 
 MIT
 
+
+Saves use the configuration form API. Rejected writes retain the draft and show an error. Changing a model preserves credentials, and disabling a default-on option explicitly stores `false`.

package/README.zh.md

@@ -1,5 +1,9 @@
 # dsh-tdai-memory
 
+## 配置入口（DSH 0.2.0-rc.2 起）
+
+在首页侧边栏打开 **插件 → 已安装 → dsh-tdai-memory**，直接在插件详情页配置并保存。配置页注册到官方的 `plugins.bundle.config` 接口；全局设置页不再重复显示配置入口。Web 与桌面版使用相同界面，本版要求 DSH 0.2.0-rc.2 或更新的 0.2.x 版本。现有配置无需迁移。
+
 **GitHub**: [Scorp1o117/dsh-tdai-memory](https://github.com/Scorp1o117/dsh-tdai-memory) · **npm**: [dsh-tdai-memory](https://www.npmjs.com/package/dsh-tdai-memory) · [English](README.md)
 
 [![Enhancement Suite](https://img.shields.io/badge/part%20of-Enhancement%20Suite-3964fe)](https://github.com/Scorp1o117/dsh-enhancement-suite) [![npm](https://img.shields.io/npm/v/dsh-enhancement-suite)](https://www.npmjs.com/package/dsh-enhancement-suite)
@@ -8,22 +12,22 @@
 
 把 **TencentDB Agent Memory**（腾讯云开源的四层记忆系统，原为 OpenClaw 插件）移植进 DeepSeek Harness。
 
-## 兼容性（v0.3.6）
-
-已在 DSH `0.1.7-rc.2`（Web）与 `0.2.0-rc.2`（桌面端运行时）的一次性 Profile 验证。桌面端使用独立的 `desktop` Profile；其他预发布版本暂未验证。
-
-## 桌面端安装
-
-在桌面端的“插件”页面安装，或使用桌面端“应用 → 管理 dsh 命令”注册的命令：
-
-```powershell
-dsh plugin --profile desktop add dsh-tdai-memory@0.3.6
-```
-
-重启桌面端以加载客户端插件。配置位于 `$DSH_HOME/profiles/desktop`。
-
-
-## 能力
+## 兼容性（v0.4.1）
+
+已在 DSH `0.1.7-rc.2`（Web）与 `0.2.0-rc.2`（桌面端运行时）的一次性 Profile 验证。桌面端使用独立的 `desktop` Profile；其他预发布版本暂未验证。
+
+## 桌面端安装
+
+在桌面端的“插件”页面安装，或使用桌面端“应用 → 管理 dsh 命令”注册的命令：
+
+```powershell
+dsh plugin --profile desktop add dsh-tdai-memory@0.3.6
+```
+
+重启桌面端以加载客户端插件。配置位于 `$DSH_HOME/profiles/desktop`。
+
+
+## 能力
 
 - **L0 对话捕获**：每轮对话（turn 结束、请求边界）自动写入原始对话（JSONL + SQLite + FTS + 向量）
 - **L1 结构化记忆**：后台管线用 LLM 从对话中提取事实/偏好/事件（persona / episodic / instruction），写入 `records/` + SQLite + FTS + 向量
@@ -56,7 +60,7 @@ dsh plugin --profile desktop add dsh-tdai-memory@0.3.6
 
 ## 配置（profile patch + settings）
 
-配置以 **settings 命名空间**驱动：profile patch 作为 base 层，`$DSH_HOME/settings.yaml` 的 `tdai-memory:` 节覆盖（LLM/embedding 密钥已迁到 settings.yaml）。Web UI 设置 → 记忆 可编辑全部字段（v0.2.0，含写-only 密钥）；TdaiCore 启动时构建，改动**重启后生效**。
+配置以 **settings 命名空间**驱动：profile patch 作为 base 层，`$DSH_HOME/settings.yaml` 的 `tdai-memory:` 节覆盖（LLM/embedding 密钥已迁到 settings.yaml）。首页侧边栏插件 → dsh-tdai-memory 可编辑全部字段（v0.2.0，含写-only 密钥）；TdaiCore 启动时构建，改动**重启后生效**。
 
 ```yaml
 # $DSH_HOME/settings.yaml
@@ -92,5 +96,8 @@ tdai-memory:
 - **提取模型**：`mimo-v2.5` 提取正确但单次 20-30s（后台执行，不阻塞对话）；`deepseek-v4-flash` 快但 JSON 输出不合规（提取 0 条）
 - **dedup**：LLM 冲突检测输出解析不稳（曾导致 stored=0），默认关闭；开启需换更稳的模型
 - **L1 记忆向量**：随存储写入（8088 embedding 快）；L0 向量走后台任务，headless 退出时由 `destroy()` drain
+- **搜索工具**（`toolsEnabled`，默认开启）：开关在插件页，切换后**原地生效**（行配置是 `volatile`，无需重启即重新注册）。若两个工具完全缺失，可查插件日志 `[tdai-memory] tools registered: …`（v0.4.1 起）；v0.4.1 之前它读的是 cordis 交给 `apply` 的 Volatile 包装对象上的 `config.toolsEnabled` —— 那个属性永远不存在，因此整个失败过程完全静默（issue #3）
 - **升级**：上游拉新代码后，在 tdai 项目目录重跑 `npx tsc -p dsh-tsconfig.json`（产物在 `dist-dsh/`）
 
+
+保存使用配置表单 API；宿主拒绝写入时保留草稿并提示错误。只修改模型不会覆盖密钥，关闭默认开启的选项会显式保存 `false`。

package/client.js

@@ -1,7 +1,7 @@
 /**
  * dsh-tdai-memory — browser half.
  *
- * A "记忆" section inside the Web UI settings page: edits the `tdai-memory`
+ * A configuration page inside the sidebar Plugins page: edits `tdai-memory`
  * settings namespace (data dir, extraction LLM, embeddings, capture/extract/
  * recall switches, tools) through the settings scope transport plus nested
  * `settings.mutate` ops. TdaiCore is built at startup, so changes apply
@@ -47,7 +47,7 @@ window.__ModuleLoader__.load({
 
     // ── locale ────────────────────────────────────────────────────────────
     var NS = "tdaiMemory";
-    var inject = ["slots", "locale", "configForms", "connection"];
+    var inject = ["slots", "locale", "configForms"];
     var zh = {
       nav: "记忆",
       intro: "TDAI 记忆配置：L0 捕获 → L1 结构化提取 → 召回注入。密钥只写不读。TdaiCore 在启动时构建，修改后需重启生效。",
@@ -88,6 +88,7 @@ window.__ModuleLoader__.load({
       saved: "已保存（重启后生效）",
       saving: "保存中…",
       error: "保存失败",
+      notApplied: "写入未生效，请检查配置后重试",
       unavailable: "设置命名空间不可用（服务端未注册 tdai-memory 命名空间？）",
       overridden: "已覆盖",
       loading: "加载中…"
@@ -132,6 +133,7 @@ window.__ModuleLoader__.load({
       saved: "Saved (applies after restart)",
       saving: "Saving…",
       error: "Save failed",
+      notApplied: "Write did not take effect; check the configuration and retry",
       unavailable: "Settings namespace unavailable (tdai-memory namespace not registered server-side?)",
       overridden: "overridden",
       loading: "Loading…"
@@ -176,7 +178,6 @@ window.__ModuleLoader__.load({
     function MemorySection(props) {
       var t = props.t;
       var scope = props.scope;
-      var api = props.api;
       var [snapshot, setSnapshot] = react.useState(function () { return scope.getSnapshot(); });
       var ready = snapshot.status === "ready" && snapshot.value !== void 0;
       var [draft, setDraft] = react.useState({});
@@ -216,6 +217,7 @@ window.__ModuleLoader__.load({
       var user = snapshot.user || {};
 
       function fieldDraft(f) {
+        if (f.secret) return draft[f.key] || "";
         if (f.type === "checkbox") return draft[f.key] !== void 0 ? draft[f.key] : Boolean(getPath(value, f.path));
         return draft[f.key] !== void 0 ? draft[f.key] : String(getPath(value, f.path) ?? "");
       }
@@ -226,6 +228,7 @@ window.__ModuleLoader__.load({
       }
 
       function onSave() {
+        if (busy || !snapshot.writable) return;
         setBusy(true); setNotice(null); setError(null);
         var ops = [];
         for (var i = 0; i < FIELDS.length; i += 1) {
@@ -240,7 +243,7 @@ window.__ModuleLoader__.load({
           }
           if (f.type === "checkbox") {
             if (Boolean(d) === Boolean(current)) continue;
-            ops.push(Boolean(d) ? { op: "set", path: f.path, value: true } : { op: "unset", path: f.path });
+            ops.push({ op: "set", path: f.path, value: Boolean(d) });
             continue;
           }
           if (String(d) === String(current ?? "")) continue;
@@ -248,35 +251,27 @@ window.__ModuleLoader__.load({
           ops.push(String(d).trim() === "" ? { op: "unset", path: f.path } : { op: "set", path: f.path, value: f.type === "number" ? Number(d) : d });
         }
         if (ops.length === 0) { setBusy(false); setNotice(t("saved")); return; }
-        api.settings.mutate({
-          ns: "tdai-memory",
-          ops: ops,
-          ...snapshot.revision === void 0 ? {} : { expectedRevision: snapshot.revision }
-        }).then(function (response) {
-          setBusy(false);
-          if (!response.result.ok) {
-            var detail = response.result.error || {};
-            setError(t("error") + ": " + String(detail.message || detail.code || "unknown"));
-            return;
-          }
-          setNotice(t("saved"));
-          if (response.result.value) setDraft(Object.assign({}, valueToDraft(response.result.value)));
-        }).catch(function (e) {
-          setBusy(false); setError(t("error") + ": " + String(e && e.message || e));
-        });
+        commit(ops);
       }
 
       function onReset() {
+        if (busy || !snapshot.writable) return;
         setBusy(true); setNotice(null); setError(null);
-        api.settings.mutate({
-          ns: "tdai-memory",
-          ops: FIELDS.map(function (f) { return { op: "unset", path: f.path }; }),
-          ...snapshot.revision === void 0 ? {} : { expectedRevision: snapshot.revision }
-        }).then(function (response) {
+        commit(FIELDS.map(function (f) { return { op: "unset", path: f.path }; }));
+      }
+
+      function commit(ops) {
+        // The form owns the transport and the recovery read. A refused Host
+        // write resolves false; it must not be displayed as a successful save.
+        Promise.resolve().then(function () {
+          return scope.mutate(ops, snapshot.revision);
+        }).then(function (ok) {
+          var next = scope.getSnapshot();
+          setSnapshot(next);
           setBusy(false);
-          if (!response.result.ok) { setError(t("error")); return; }
+          if (!ok) { setError(t("error") + ": " + t("notApplied")); return; }
           setNotice(t("saved"));
-          if (response.result.value) setDraft(Object.assign({}, valueToDraft(response.result.value)));
+          if (next.value) setDraft(valueToDraft(next.value));
         }).catch(function (e) {
           setBusy(false); setError(t("error") + ": " + String(e && e.message || e));
         });
@@ -336,7 +331,7 @@ window.__ModuleLoader__.load({
       var out = {};
       for (var i = 0; i < FIELDS.length; i += 1) {
         var f = FIELDS[i];
-        out[f.key] = f.type === "checkbox" ? Boolean(getPath(value, f.path)) : String(getPath(value, f.path) ?? "");
+        out[f.key] = f.secret ? "" : f.type === "checkbox" ? Boolean(getPath(value, f.path)) : String(getPath(value, f.path) ?? "");
       }
       return out;
     }
@@ -346,16 +341,13 @@ window.__ModuleLoader__.load({
       var t = ctx.locale.bind(NS);
       ctx.effect(function () { return ctx.locale.register(NS, { zh: zh, en: en }); }, "dsh-tdai-memory: dictionaries");
       var scope = ctx.configForms.get("tdai-memory");
-      var api = ctx.connection.api;
-      ctx.slots.inject("settings.section", function () {
+      ctx.slots.inject("plugins.bundle.config", function () {
         return ctx.slots.register({
-          name: "settings.section",
-          id: "tdai-memory",
-          order: 26,
-          label: function () { return t("nav"); },
+          name: "plugins.bundle.config",
+          key: "dsh-tdai-memory",
           locale: NS
         }, function (props) {
-          return h(MemorySection, Object.assign({}, props, { scope: scope, api: api }));
+          return h(MemorySection, Object.assign({}, props, { scope: scope, t: t }));
         });
       });
     }

package/index.js

@@ -106,18 +106,31 @@ function extractText(content) {
     .trim();
 }
 
+/**
+ * Resolve the config value handed to `apply`.
+ *
+ * The row schema ends in `.volatile()` (hot-reloadable config). Config
+ * validation runs through the standard-schema path, which returns the
+ * validated object wrapped in a cosmokit `Volatile`: a frozen `{ get() }`
+ * reference whose OWN properties are always `undefined`. Reading
+ * `config.toolsEnabled` off it can therefore never be true — the tools guard
+ * did exactly that and silently stopped registering the search tools in
+ * v0.3.4 (issue #3). Read config through this helper only.
+ *
+ * The wrapper is a live reference (`updateVolatile` swaps its inner value), so
+ * calling this at use time — not once at startup — sees volatile edits.
+ */
+function runtimeConfigOf(config) {
+  return typeof config?.get === "function" ? config.get() : config;
+}
+
 function apply(ctx, config) {
   // ── build-once state (rebuildable) ───────────────────────────────────────
-  // TdaiCore is built from the RESOLVED settings value (composition entry as
-  // base, `tdai-memory` settings section / settings.yaml as user layer), so
-  // keys stored in settings.yaml (llm.apiKey etc.) are honored. The settings
-  // inject callback that drives `installSettingsSection`'s setSource is
-  // scheduled by cordis as a plugin start — it ALWAYS runs after any 0ms
-  // timer — so the no-settings fallback below cannot be allowed to win the
-  // race. Instead of racing, we let the fallback build from the entry config
-  // first (guaranteeing a working core even without settings), and REBUILD
-  // from the resolved settings when the settings mount arrives. The fallback
-  // is a one-shot; the settings build always wins afterwards.
+  // TdaiCore is built once from the resolved row config: the composition entry
+  // as base with the Plugins-page values merged in by the host (settings.yaml is
+  // no longer a config source since v0.4.0 — see client.js `configForms`). The
+  // build is deferred past the 0ms window so web/headless boots are never
+  // blocked on TdaiCore's stores and embedding client.
   let core = null;
   let tdaiConfig = null;
   let dataDir = "";
@@ -339,69 +352,137 @@ function apply(ctx, config) {
   }
 
   // ── tools ────────────────────────────────────────────────────────────────
-  if (config.toolsEnabled) {
-    ctx.tools.register(defineTool({
-      name: "tdai_memory_search",
-      description:
-        "Search structured long-term memories (facts, preferences, and experiences extracted from past conversations). " +
-        "Use this to recall what the user told you or what happened in earlier sessions.",
-      parameters: {
-        query: { type: "string", required: true, description: "The memory to search for." },
-        limit: { type: "integer", description: "Maximum results (default 5)." },
-      },
-      output: {
-        schema: { type: "string" },
-        render: (_args, value) => [{ type: "text", text: value }],
-      },
-      async execute(args) {
-        const result = await core.searchMemories({ query: args.query, limit: args.limit ?? 5 });
-        return result.text;
-      },
-    }));
-    ctx.tools.register(defineTool({
-      name: "tdai_conversation_search",
-      description:
-        "Search raw past conversation logs (L0) by keyword. Use this to look up exact quotes or details " +
-        "that structured memory search does not cover.",
-      parameters: {
-        query: { type: "string", required: true, description: "Text to find in past conversations." },
-        limit: { type: "integer", description: "Maximum results (default 5)." },
-      },
-      output: {
-        schema: { type: "string" },
-        render: (_args, value) => [{ type: "text", text: value }],
-      },
-      async execute(args) {
-        const result = await core.searchConversations({ query: args.query, limit: args.limit ?? 5 });
-        return result.text;
-      },
-    }));
+  // `toolsEnabled` defaults to true (schema `.default(true)`), so only an
+  // explicit `false` turns the two search tools off. Read through
+  // `runtimeConfigOf` — the volatile row config has no plain properties (#3).
+  let toolsRegistered = false;
+  let toolsDeferred = false;
+  let toolsDisposers = [];
+
+  /** The core, or a clear error while the first build is still in flight. */
+  function requireCore() {
+    if (!core) throw new Error("tdai-memory is still initializing; retry this call in a moment");
+    return core;
   }
 
-  // ── settings-backed configuration ─────────────────────────────────────────
-  // The composition entry stays the base layer; a registered `tdai-memory`
-  // settings section overlays it (settings.yaml). The source is a GETTER
-  // (`() => scope.get()`), not the config object — we must call it to obtain
-  // the resolved settings. The settings mount (cordis inject) always arrives
-  // after our fallback timer, so the fallback builds the core from the entry
-  // config first (one-shot) and the settings build REBUILDS the core with the
-  // resolved values (apiKey included).
-  // Compat shim: dsh-settings 0.1.2-rc.1 removed the module-level
-  // `installSettingsSection` export (the provider now lives at ctx.settings).
-  // Inline the same logic via ctx.inject(["settings"]) — works on both
-  // 0.1.1 (module export wrapper) and 0.1.2 (ctx.settings) hosts.
+  function registerTools(tools) {
+    if (toolsRegistered) return;
+    if (typeof tools?.register !== "function") {
+      ctx.logger.warn("[tdai-memory] tools service does not expose register(); search tools stay unavailable");
+      return;
+    }
+    toolsRegistered = true;
+    toolsDisposers = [
+      tools.register(defineTool({
+        name: "tdai_memory_search",
+        description:
+          "Search structured long-term memories (facts, preferences, and experiences extracted from past conversations). " +
+          "Use this to recall what the user told you or what happened in earlier sessions.",
+        parameters: {
+          query: { type: "string", required: true, description: "The memory to search for." },
+          limit: { type: "integer", description: "Maximum results (default 5)." },
+        },
+        output: {
+          schema: { type: "string" },
+          render: (_args, value) => [{ type: "text", text: value }],
+        },
+        async execute(args) {
+          const result = await requireCore().searchMemories({ query: args.query, limit: args.limit ?? 5 });
+          return result.text;
+        },
+      })),
+      tools.register(defineTool({
+        name: "tdai_conversation_search",
+        description:
+          "Search raw past conversation logs (L0) by keyword. Use this to look up exact quotes or details " +
+          "that structured memory search does not cover.",
+        parameters: {
+          query: { type: "string", required: true, description: "Text to find in past conversations." },
+          limit: { type: "integer", description: "Maximum results (default 5)." },
+        },
+        output: {
+          schema: { type: "string" },
+          render: (_args, value) => [{ type: "text", text: value }],
+        },
+        async execute(args) {
+          const result = await requireCore().searchConversations({ query: args.query, limit: args.limit ?? 5 });
+          return result.text;
+        },
+      })),
+    ];
+    ctx.logger.info("[tdai-memory] tools registered: tdai_memory_search, tdai_conversation_search");
+  }
+
+  function unregisterTools() {
+    for (const dispose of toolsDisposers.splice(0)) {
+      try {
+        dispose();
+      } catch (error) {
+        ctx.logger.warn(`[tdai-memory] tool dispose failed: ${String(error)}`);
+      }
+    }
+    toolsRegistered = false;
+    ctx.logger.info("[tdai-memory] tools unregistered (toolsEnabled=false)");
+  }
+
+  /** Align tool registration with the live `toolsEnabled` value. */
+  function syncTools() {
+    if (runtimeConfigOf(config)?.toolsEnabled === false) {
+      if (toolsRegistered) unregisterTools();
+      return;
+    }
+    if (toolsRegistered || toolsDeferred) return;
+    // `tools` is in this plugin's `inject`, so the service is normally live
+    // here; `ctx.inject` is the fallback for hosts that mount it later. The old
+    // one-shot `ctx.tools` property read registered nothing and said nothing.
+    const tools = ctx.tools ?? ctx.get?.("tools");
+    if (tools === undefined) {
+      toolsDeferred = true;
+      ctx.logger.warn("[tdai-memory] tools service not ready; deferring search-tool registration");
+      ctx.inject(["tools"], (toolCtx) => {
+        toolsDeferred = false;
+        const deferred = toolCtx.tools ?? toolCtx.get?.("tools");
+        if (deferred === undefined) {
+          ctx.logger.warn("[tdai-memory] tools service still unavailable; search tools stay unavailable");
+          return;
+        }
+        registerTools(deferred);
+      });
+      return;
+    }
+    registerTools(tools);
+  }
+
+  // `toolsEnabled` is a volatile config path, so flipping it (Plugins page)
+  // updates the running fiber in place instead of remounting this plugin: the
+  // loader reports that as `loader/volatile-update`, and this keeps the
+  // registration in sync with the new value.
+  ctx.on("loader/volatile-update", () => {
+    try {
+      syncTools();
+    } catch (error) {
+      ctx.logger.warn(`[tdai-memory] tool sync failed: ${String(error)}`);
+    }
+  });
+
+  syncTools();
+
+  // ── configuration changes ─────────────────────────────────────────────────
+  // Configuration lives in the Plugins page (client.js → configForms), i.e. in
+  // this row's own config. Because the row schema is `.volatile()`, an edit is
+  // applied to the running fiber in place — the loader reports it as
+  // `loader/volatile-update` (the tools above re-sync on it) — while TdaiCore
+  // is built at startup, so an edit that must reach the core needs a plugin
+  // reload. Legacy settings documents are only reported here.
   ctx.on("settings/document-updated", (id) => {
     if (id === NS) ctx.logger.warn("[tdai-memory] settings updated; restart to apply (TdaiCore is built at startup)");
   });
 
-  // Fallback when no settings service ever mounts: build from the entry
-  // config. One-shot — if the settings mount arrives later, its build
-  // supersedes this one. Delayed past the 0ms window so headless/web boots
-  // are never blocked on this timer.
+  // Deferred first build (see the note at the top of apply).
   setTimeout(() => {
     if (!builtOnce) {
       builtOnce = true;
-      void build(typeof config.get === "function" ? config.get() : config);
+      void build(runtimeConfigOf(config));
     }
   }, 500);
 

package/package.json

@@ -1,97 +1,97 @@
-{
-    "name": "dsh-tdai-memory",
-    "version": "0.3.6",
-    "description": "DeepSeek Harness 的 TencentDB Agent Memory 移植：L0 对话捕获 → L1 结构化记忆提取 → L2 场景/L3 画像，自动召回注入 + 记忆/对话搜索工具；复用现有 ~/.memory-tencentdb/memory-tdai 数据；附 Web UI 设置栏。",
-    "type": "module",
-    "main": "index.js",
-    "exports": {
-        ".": "./index.js",
-        "./client": "./client.js",
-        "./package.json": "./package.json"
-    },
-    "dsh": {
-        "bundle": {
-            "patch": "./cordis.patch.yml"
-        },
-        "client": {
-            "platform": "web"
-        },
-        "compatibility": {
-            "dsh": ">=0.1.7-rc.1 <0.2.0 || 0.2.0-rc.2",
-            "dshReleases": {
-                "0.1.5-rc.2": "incompatible",
-                "0.1.5-rc.3": "incompatible",
-                "0.1.6-alpha.1": "unknown",
-                "0.1.6-alpha.2": "unknown",
-                "0.1.7-alpha.1": "unknown",
-                "0.1.7-alpha.2": "unknown",
-                "0.1.7-rc.1": "compatible",
-                "0.1.7-rc.2": "compatible",
-                "0.2.0-rc.2": "compatible"
-            },
-            "node": ">=22.18",
-            "profiles": [
-                "web",
-                "desktop"
-            ]
-        }
-    },
-    "homepage": "https://github.com/Scorp1o117/dsh-tdai-memory",
-    "files": [
-        "index.js",
-        "recall-inject.js",
-        "client.js",
-        "cordis.patch.yml",
-        "vendor",
-        "README.md",
-        "README.zh.md",
-        "LICENSE",
-        "THIRD-PARTY-NOTICES.md"
-    ],
-    "keywords": [
-        "dsh",
-        "dsh-plugin",
-        "deepseek-harness",
-        "memory",
-        "tencentdb",
-        "agent-memory",
-        "rag",
-        "vector-search",
-        "persona"
-    ],
-    "license": "MIT",
-    "engines": {
-        "node": ">=22.18"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/Scorp1o117/dsh-tdai-memory.git"
-    },
-    "bugs": {
-        "url": "https://github.com/Scorp1o117/dsh-tdai-memory/issues"
-    },
-    "dependencies": {
-        "@ai-sdk/openai": "^3.0.53",
-        "@deepseek-ai/schemastery": "^3.18.4",
-        "@node-rs/jieba": "^2.0.1",
-        "@tencentdb-agent-memory/tcvdb-text": "^0.1.1",
-        "ai": "^6.0.164",
-        "json5": "^2.2.3",
-        "sqlite-vec": "0.1.7-alpha.2",
-        "undici": "^8.1.0"
-    },
-    "peerDependencies": {
-        "react": "^18.2.0",
-        "@deepseek-ai/dsh-tools": "^0.1.7-rc.1 || 0.2.0-rc.2",
-        "@deepseek-ai/dsh-settings": "^0.1.7-rc.1 || 0.2.0-rc.2",
-        "node-llama-cpp": "^3.19.1"
-    },
-    "peerDependenciesMeta": {
-        "node-llama-cpp": {
-            "optional": true
-        }
-    },
-    "scripts": {
-        "test": "node tests/settings-scope-compat.test.mjs && node tests/install-contract.test.mjs"
-    }
-}
+{
+    "name": "dsh-tdai-memory",
+    "version": "0.4.1",
+    "description": "DeepSeek Harness 的 TencentDB Agent Memory 移植：L0 对话捕获 → L1 结构化记忆提取 → L2 场景/L3 画像，自动召回注入 + 记忆/对话搜索工具；复用现有 ~/.memory-tencentdb/memory-tdai 数据；附 Web UI 设置栏。",
+    "type": "module",
+    "main": "index.js",
+    "exports": {
+        ".": "./index.js",
+        "./client": "./client.js",
+        "./package.json": "./package.json"
+    },
+    "dsh": {
+        "bundle": {
+            "patch": "./cordis.patch.yml"
+        },
+        "client": {
+            "platform": "web"
+        },
+        "compatibility": {
+            "dsh": ">=0.2.0-rc.2 <0.3.0",
+            "dshReleases": {
+                "0.1.5-rc.2": "incompatible",
+                "0.1.5-rc.3": "incompatible",
+                "0.1.6-alpha.1": "unknown",
+                "0.1.6-alpha.2": "unknown",
+                "0.1.7-alpha.1": "unknown",
+                "0.1.7-alpha.2": "unknown",
+                "0.1.7-rc.1": "incompatible",
+                "0.1.7-rc.2": "incompatible",
+                "0.2.0-rc.2": "compatible"
+            },
+            "node": ">=22.18",
+            "profiles": [
+                "web",
+                "desktop"
+            ]
+        }
+    },
+    "homepage": "https://github.com/Scorp1o117/dsh-tdai-memory",
+    "files": [
+        "index.js",
+        "recall-inject.js",
+        "client.js",
+        "cordis.patch.yml",
+        "vendor",
+        "README.md",
+        "README.zh.md",
+        "LICENSE",
+        "THIRD-PARTY-NOTICES.md"
+    ],
+    "keywords": [
+        "dsh",
+        "dsh-plugin",
+        "deepseek-harness",
+        "memory",
+        "tencentdb",
+        "agent-memory",
+        "rag",
+        "vector-search",
+        "persona"
+    ],
+    "license": "MIT",
+    "engines": {
+        "node": ">=22.18"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Scorp1o117/dsh-tdai-memory.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Scorp1o117/dsh-tdai-memory/issues"
+    },
+    "dependencies": {
+        "@ai-sdk/openai": "^3.0.53",
+        "@deepseek-ai/schemastery": "^3.18.4",
+        "@node-rs/jieba": "^2.0.1",
+        "@tencentdb-agent-memory/tcvdb-text": "^0.1.1",
+        "ai": "^6.0.164",
+        "json5": "^2.2.3",
+        "sqlite-vec": "0.1.7-alpha.2",
+        "undici": "^8.1.0"
+    },
+    "peerDependencies": {
+        "react": "^18.2.0",
+        "@deepseek-ai/dsh-tools": ">=0.2.0-rc.2 <0.3.0",
+        "@deepseek-ai/dsh-settings": ">=0.2.0-rc.2 <0.3.0",
+        "node-llama-cpp": "^3.19.1"
+    },
+    "peerDependenciesMeta": {
+        "node-llama-cpp": {
+            "optional": true
+        }
+    },
+    "scripts": {
+        "test": "node tests/settings-scope-compat.test.mjs && node tests/install-contract.test.mjs && node --test tests/plugin-page.test.mjs tests/client-write-flow.test.mjs tests/tools-registration.test.mjs"
+    }
+}