dsh-tool-folder 0.2.0 → 0.2.1

package/README.md

@@ -149,6 +149,19 @@ were never unregistered, so nothing else changes.
 
 ## Changelog
 
+### v0.2.1 — heat decay + exact-name priority (2026-08-30)
+1. **Hot heat decay** (`hotWindowDays`, default 3): a tool is promoted to
+   always-visible only when its call count stays inside the sliding window —
+   the old code promoted forever, so any tool used 3 times was permanently
+   resident and the fold silently decayed to zero over time. Legacy
+   `feedback.json` number entries are read as out-of-window → their stale
+   heat expires naturally. Set `hotWindowDays: 0` to keep the old behavior.
+2. **Exact-name priority in `tools_search`**: exact tool-name match always
+   ranks first, a ≥4-char query that is a name substring is pulled ahead of
+   BM25/semantic hits (deterministic fallback chain). Results stay
+   deduplicated.
+3. 40 tests green (11 new: window decay / legacy compat / priority order).
+
 ### v0.2.0 — first npm release (2026-08-30)
 This is the first version published to npm. It bundles the v0.1.7 firewall
 scope fix (exec-only hard block) and the v0.1.8 semantic leg +

package/lib/index.js

@@ -33,7 +33,7 @@ import path from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { buildIndex, search } from "./bm25.js";
 import { compressTool, normalizeDescription, sanitizeLossless } from "./schema.js";
-import { selectionCoverage } from "./metrics.js";
+import { selectionCoverage, isHotTool, prioritizeExact } from "./metrics.js";
 import { ChainGuard, verdict } from "./chainguard.js";
 import { matchCategory } from "./category.js";
 import { toonifyValue } from "./toonify.js";
@@ -59,6 +59,8 @@ export const Config = z.object({
   deny: z.array(z.string()).default([]).description("禁用工具：精确名或 prefix* 前缀，命中不注入+拒绝执行"),
   topK: z.number().min(0).max(50).default(6).description("BM25 动态检索每轮最多注入的工具数"),
   hotThreshold: z.number().min(1).default(3).description("被折叠工具调用几次后自动晋升为常驻"),
+  hotWindowDays: z.number().min(0).max(365).default(3)
+    .description("hot 热度的滑动窗口（天）：窗口内达标才常驻，超窗自动衰减；0=永不过期"),
   catalogEnabled: z.boolean().default(true).description("折叠安全网：把被藏工具列表写进提示词，模型知道它们存在"),
   compressLevel: z.union(COMPRESS_LEVELS).default("off").description("L1 schema 压缩级别：off 不压缩 / light 裁描述 / standard 裁描述+参数说明 / aggressive 删可选参数"),
   compressEnabled: z.boolean().default(false).description("兼容开关：compressLevel=off 且此开=true 时按 standard 处理"),
@@ -84,6 +86,7 @@ const DEFAULTS = {
   deny: [], // never inject + refuse execution (exact name or "prefix*")
   topK: 6,
   hotThreshold: 3,
+  hotWindowDays: 3, // v0.2.1: sliding-window heat decay (0 = never expire)
   catalogEnabled: true, // safety net: folded tools stay discoverable by name
   compressEnabled: false, // deprecated compat: compressLevel "off" + true → "standard"
   compressLevel: "off", // "off" | "light" | "standard" | "aggressive"
@@ -403,7 +406,13 @@ export function apply(ctx, config) {
         const q = String(args.query || "");
         const lim = args.limit ?? 8;
         if (!index || !q) return { query: q, results: [], total: 0 };
-        const bm25Hits = search(index, q, lim * 2).map((i) => ({ id: allTools[i].name }));
+        // v0.2.1: exact-name > name-substring > BM25 priority (deterministic
+        // fallback chain, borrowed from Hermes-style tool search).
+        const bm25Hits = prioritizeExact(
+          allTools,
+          q,
+          search(index, q, lim * 2).map((i) => ({ id: allTools[i].name })),
+        );
         let fused = bm25Hits;
         // Semantic leg (P0-1): RRF-fuse BM25 with local bge-m3 similarity.
         // Any failure (Ollama down / timeout / cache miss on error) degrades
@@ -519,10 +528,12 @@ export function apply(ctx, config) {
 
       const agentId = context?.agent?.id || "default";
       const coreNames = new Set(cfg.perAgent?.[agentId]?.core || cfg.core || []);
+      // v0.2.1: hot = sliding-window decay (hotWindowDays). Tools not called
+      // inside the window lose their historical heat — the old code promoted
+      // forever, which slowly nullified the fold.
       const hotNames = new Set(
-        Object.entries(feedback.calls || {})
-          .filter(([, c]) => c >= cfg.hotThreshold)
-          .map(([n]) => n),
+        Object.keys(feedback.calls || {}).filter((n) =>
+          isHotTool(feedback.calls, n, cfg.hotThreshold, cfg.hotWindowDays * 86400000)),
       );
 
       const stamp = tools.map((t) => t.name).join("\u0001");
@@ -673,8 +684,14 @@ export function apply(ctx, config) {
           });
         }
 
-        // Heat counting (L4 feedback).
-        feedback.calls[name] = (feedback.calls[name] || 0) + 1;
+        // Heat counting (L4 feedback). v0.2.1: upgrade to { n, ts } so the
+        // hot gate can decay stale heat; legacy number entries are kept
+        // readable by isHotTool (ts=0 → outside any positive window).
+        const prev = feedback.calls[name];
+        feedback.calls[name] = {
+          n: (typeof prev === "number" ? prev : prev?.n || 0) + 1,
+          ts: Date.now(),
+        };
 
         // Firewall: record the call sequence and flag exfil chains.
         if (cfg.firewallEnabled !== false) {

package/lib/metrics.js

@@ -59,3 +59,68 @@ export function selectionCoverage(visibleNames, calledNames) {
     uncovered,
   };
 }
+
+/**
+ * Hot-promotion gate with sliding-window decay (v0.2.1).
+ * feedback.calls entries may be:
+ *   - new shape { n, ts } — n calls, ts = last call epoch ms;
+ *   - legacy shape (number) — pre-v0.2.1 counts with no timestamp.
+ * A tool is hot when n >= hotThreshold AND (windowMs <= 0 OR the last call
+ * is inside the window). Legacy numbers carry ts=0 → outside any positive
+ * window → not hot (a tool that hasn't been called since the upgrade
+ * naturally loses its historical heat — this is the decay the old code
+ * lacked). windowMs=0 keeps the legacy forever-hot behavior for opt-out.
+ * @param {object|null} calls - feedback.calls map.
+ * @param {string} name - tool name.
+ * @param {number} hotThreshold - min calls to be hot.
+ * @param {number} windowMs - decay window; <=0 disables time checks.
+ * @returns {boolean}
+ */
+export function isHotTool(calls, name, hotThreshold, windowMs) {
+  if (!calls || typeof calls !== "object") return false;
+  const v = calls[name];
+  if (v == null) return false;
+  const n = typeof v === "number" ? v : v.n;
+  const ts = typeof v === "number" ? 0 : v.ts;
+  if (!(n >= hotThreshold)) return false;
+  if (windowMs > 0 && !(ts > 0 && Date.now() - ts <= windowMs)) return false;
+  return true;
+}
+
+/**
+ * Deterministic retrieval priority (v0.2.1, borrowed from Hermes-style
+ * "exact name > name token > description" fallback chains): the query's
+ * exact tool-name match always ranks first; a ≥4-char query that is a
+ * substring of a tool name is pulled ahead of BM25/semantic hits. Everything
+ * else keeps the given hit order, deduplicated.
+ * @param {Array<{name: string}>} docs - the tool corpus (allTools).
+ * @param {string} q - the search query.
+ * @param {Array<{id: string, score: number}>} hits - ranked hits.
+ * @returns {Array<{id: string, score: number}>} re-ordered hits.
+ */
+export function prioritizeExact(docs, q, hits) {
+  const query = String(q || "").trim().toLowerCase();
+  if (!query || !Array.isArray(docs) || !Array.isArray(hits)) return hits;
+  const ordered = [];
+  const seen = new Set();
+  const exact = docs.find((d) => String(d.name || "").toLowerCase() === query);
+  if (exact) {
+    ordered.push({ id: exact.name, score: 0 });
+    seen.add(exact.name);
+  }
+  if (query.length >= 4) {
+    for (const d of docs) {
+      if (seen.has(d.name)) continue;
+      if (String(d.name || "").toLowerCase().includes(query)) {
+        ordered.push({ id: d.name, score: 0 });
+        seen.add(d.name);
+      }
+    }
+  }
+  for (const h of hits) {
+    if (!h || seen.has(h.id)) continue;
+    ordered.push(h);
+    seen.add(h.id);
+  }
+  return ordered;
+}

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "dsh-tool-folder",
-  "version": "0.2.0",
-  "description": "Fold the DSH tool surface per request + ChainGuard firewall (high-risk block + exfil-chain detection + anti-obfuscation) + BM25/bge-m3 hybrid tools_search. Shrinks schema tokens 80-90% while keeping selection accuracy. v0.2.0 adds a semantic retrieval leg (local Ollama bge-m3, RRF hybrid) and ChainGuard obfuscation detection (concat-rebuild / -enc / certutil / bitsadmin / homoglyphs).",
-  "keywords": [
-    "dsh-plugin",
-    "dsh",
-    "deepseek-harness",
-    "cordis",
-    "tool-selection",
-    "token-optimization",
-    "bm25",
-    "semantic-search",
-    "security",
-    "firewall",
-    "obfuscation"
-  ],
-  "type": "module",
-  "main": "lib/index.js",
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "license": "MIT",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
-  },
-  "scripts": {
-    "test": "node --test \"test/*.test.js\""
-  },
-  "exports": {
-    ".": "./lib/index.js",
-    "./lib/*": "./lib/*"
-  }
-}
+{
+    "name":  "dsh-tool-folder",
+    "version":  "0.2.1",
+    "description":  "Fold the DSH tool surface per request + ChainGuard firewall (high-risk block + exfil-chain detection + anti-obfuscation) + BM25/bge-m3 hybrid tools_search. Shrinks schema tokens 80-90% while keeping selection accuracy. v0.2.0 adds a semantic retrieval leg (local Ollama bge-m3, RRF hybrid) and ChainGuard obfuscation detection (concat-rebuild / -enc / certutil / bitsadmin / homoglyphs).",
+    "keywords":  [
+                     "dsh-plugin",
+                     "dsh",
+                     "deepseek-harness",
+                     "cordis",
+                     "tool-selection",
+                     "token-optimization",
+                     "bm25",
+                     "semantic-search",
+                     "security",
+                     "firewall",
+                     "obfuscation"
+                 ],
+    "type":  "module",
+    "main":  "lib/index.js",
+    "files":  [
+                  "lib",
+                  "cordis.patch.yml",
+                  "README.md"
+              ],
+    "dsh":  {
+                "bundle":  {
+                               "patch":  "./cordis.patch.yml"
+                           }
+            },
+    "license":  "MIT",
+    "engines":  {
+                    "node":  "\u003e=18"
+                },
+    "dependencies":  {
+                         "@deepseek-ai/schemastery":  "^3.18.1"
+                     },
+    "peerDependencies":  {
+                             "@deepseek-ai/cordis":  "^4.0.1",
+                             "@deepseek-ai/dsh-tools":  "^0.1.0-rc.6"
+                         },
+    "scripts":  {
+                    "test":  "node --test \"test/*.test.js\""
+                },
+    "exports":  {
+                    ".":  "./lib/index.js",
+                    "./lib/*":  "./lib/*"
+                }
+}