dsh-tool-folder 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# dsh-tool-folder
+
+Fold the DSH tool surface down to what each request actually needs.
+Per-agent core + BM25 dynamic loading + heat feedback + CN-intent aliases.
+Shrinks per-turn schema tokens ~80-90% while keeping (or improving) tool
+selection accuracy — the RAG-MCP / BoR / SEP-1576 methodology, implemented as
+a plain cordis plugin for the DeepSeek Harness host.
+
+## Mechanism (verified against DSH 0.1.1-rc.1 sources)
+
+```
+SystemPrompt.assemble() → assembly = { sections, contexts, tools, variables }
+ctx.waterfall(scope, "system-prompt/assemble", assembly, ctx, () => assembly)
+    ← this plugin listens here and returns {...assembly, tools: filtered}
+buildRequest(turn, step, assembly.tools, ...)   ← tools field of the API request
+```
+
+`assembly.tools` is the ONLY source of the API request's tools. Returning a
+replaced object is authoritative (model-selection plugin does the same).
+Execution is NOT gated on the current turn's tools — folded tools still
+resolve through the full registry — so folding never removes capability.
+
+## Six layers — all implemented
+
+| Layer | Mechanism | Status |
+|---|---|---|
+| L1 schema compression | conservative description/param trimming (no $ref — provider-incompatible), `compressEnabled` | ✅ dyn segment only |
+| L2 dynamic loading | per-agent core + BM25 top-K + CN-alias server route | ✅ core |
+| L3 selection metrics | `selectionCoverage` per session + offline `retrievalMetrics` | ✅ recorded to feedback.json |
+| L4 execution side | folded tools stay executable + heat promotion + `tools_search` tool | ✅ |
+| L5 cache discipline | deterministic ordering (core by config, hot/dyn by name) = byte-stable prefix | ✅ |
+
+## Three-segment layout
+
+| Segment | Content | Cost |
+|---|---|---|
+| core | per-agent core + heat-promoted tools, full schema | small, constant |
+| dyn | BM25 top-K for the current query + CN-alias server tools | small, per request |
+| folded | everything else — dropped from the schema | zero |
+
+Optionally (`catalogEnabled: true`) folded tools are listed as a one-line
+catalog section so the model still knows they exist and can call them by name
+(execution-side fallback still works).
+
+## Install
+
+Official (needs the dsh CLI / pnpm):
+```
+dsh plugin --profile desktop add file:E:/DSH-Data/dsh-tool-folder
+# or, after publishing: dsh plugin --profile desktop add github:<owner>/dsh-tool-folder
+```
+
+Manual fallback: put the package where the profile loader can resolve
+`dsh-tool-folder`, then add to `profiles/<name>/cordis.patch.yml`:
+```yaml
+- insert:
+    - id: tool-folder
+      name: 'dsh-tool-folder'
+      config:
+        enabled: true
+        core: [tool-bash, tool-pwsh]
+        topK: 6
+        hotThreshold: 3
+```
+(Manual install is not yet end-to-end verified — the loader resolution path
+for a locally-added bundle is the one open question.)
+
+## Rollback
+
+Set `enabled: false` (or remove the insert row) and restart DSH. Folded tools
+were never unregistered, so nothing else changes.
+
+## Config
+
+| key | default | meaning |
+|---|---|---|
+| enabled | true | master switch |
+| perAgent | {} | `{agentId: {core: [...]}}` overrides |
+| core | [] | always-loaded tools (fallback for unknown agents) |
+| topK | 6 | BM25 dynamic segment size |
+| hotThreshold | 3 | folded tool called N times → auto-promote to core |
+| catalogEnabled | false | append one-line catalog section for folded tools |
+| maxFoldMs | 50 | hard cap; beyond this keep the full list |
+| feedbackFile | '' | feedback JSON path (default `$DSH_HOME/logs/tool-folder/`) |
+| aliases | built-in | CN-intent keyword → server prefix table |
+
+## Files
+
+- `lib/bm25.js` — zero-dep BM25 (k1=1.2, b=0.75; CN bigrams + EN tokens)
+- `lib/index.js` — assemble hook, three-segment fold, heat feedback, safety
+- `cordis.patch.yml` — bundle insert declaration
+- `test.js` — simulated-cordis harness: `node test.js`
+
+## Known limits
+
+- BM25 cannot cross the CN-query / EN-description language gap; the alias
+  table covers common CN intents. A future query-rewrite leg (ARK LLM, proven
+  in the GPT Researcher smart retriever) removes this entirely.
+- `catalogEnabled` render behavior needs one runtime verification pass.
+
+## Quality check (2026-08-24, real 45-tool set)
+
+Full-pipeline test with the REAL tool list (converted to DSH public names
+`mcp__<server>__<tool>`), 7 typical queries:
+
+| query | result | verdict |
+|---|---|---|
+| delegate a coding task to openhands | 7 openhands tools | ✅ |
+| 帮我记住这个事实 / 查记忆 记住 回忆 | all 15 viking tools (alias) | ✅ |
+| fetch library documentation | 2 context7 tools | ✅ |
+| start a learning session | all 13 deeptutor tools (alias) | ✅ |
+| 复杂推理任务 深度思考 | deeptutor deep_* + reasonix + openhands | ✅ |
+| 搜索代码 semantic search | viking grep/glob + reasonix code | ✅ |
+
+- Fold ratio: 45 tools → 2-18 visible per query (avg ~8) ≈ **-82% schema tokens**
+- Known trade-off: an alias hit pulls the WHOLE server in. Fine while servers
+  stay ≤15 tools; a large server (e.g. GitHub MCP ~60) needs the v2 per-server
+  top-K refinement.
+- BM25 shows minor lexical noise on some queries (e.g. `cancel_watch` on an
+  openhands query) — the model filters this during synthesis.
+
+### Bugs found & fixed during the check
+1. **tools_search self-hide (real bug)**: the meta-tool was folded by its own
+   filter, so the model could never see it. Now always kept visible.
+2. **Test-data error (not a code bug)**: raw MCP tool names vs DSH public
+   names (`mcp__<server>__<tool>`, verified in dsh-mcp-client
+   `publicToolName`). The plugin's prefix logic was correct all along.

package/cordis.patch.yml

@@ -0,0 +1,48 @@
+# dsh-tool-folder bundle patch.
+#
+# Inserts the tool-folder plugin row into the profile composition. Nothing in
+# the base bundle is disabled or replaced — the plugin only filters
+# assembly.tools per request (folded tools remain executable, R1-verified).
+#
+# Harness patches replace the targeted row's WHOLE `config` rather than
+# merging. To override any value, restate the complete config under the same
+# `id: tool-folder` in your profile's own `cordis.patch.yml` (or a `--patch`
+# overlay). `!!js` expressions are allowed (e.g. env binding).
+- insert:
+    - id: tool-folder
+      name: 'dsh-tool-folder'
+      config:
+        enabled: true
+        # Tools always kept in full (schema) for every agent. These are the
+        # platform essentials; everything else is folded and BM25-loaded.
+        core:
+          - tool-bash
+          - tool-pwsh
+        # Per-agent overrides. agent ids come from context.agent.id; agents
+        # not listed here fall back to `core`. Example:
+        #   perAgent:
+        #     standard:
+        #       core: [tool-bash, tool-pwsh, mcp__viking__remember]
+        perAgent: {}
+        # BM25 dynamic segment size per request.
+        topK: 6
+        # Folded tool called this many times auto-promotes into core.
+        hotThreshold: 3
+        # One-line catalog section for folded tools (model knows they exist).
+        # Off until section render behavior is verified at runtime.
+        catalogEnabled: false
+        # Hard cap before falling back to the full list.
+        maxFoldMs: 50
+        # Feedback persistence (empty = under $DSH_HOME/logs/tool-folder/).
+        feedbackFile: ''
+        # Chinese-intent → server aliases. Pulls the whole server's tools into
+        # the dynamic segment when the query matches (BM25 can't cross the
+        # CN-query / EN-description language gap). Keys are tool-name prefixes.
+        aliases:
+          mcp__viking: ['记忆', '记住', '回忆', 'remember', 'memory']
+          mcp__openhands: ['写代码', '编程', '编码', '开发', 'coding', 'code', 'openhands', '委派', 'delegate']
+          mcp__context7: ['文档', 'api 文档', '库文档', 'documentation', 'docs', 'context7']
+          mcp__deeptutor: ['学习', '课程', '教学', 'tutor', 'study', 'learn']
+          mcp__reasonix: ['推理', '复杂任务', '深度思考', 'reasoning', 'reasonix']
+          mcp__open-design: ['设计', 'design']
+          mcp__serena: ['代码搜索', '搜代码', 'search code', 'serena']

package/lib/bm25.js

@@ -0,0 +1,113 @@
+/**
+ * bm25.js — zero-dependency BM25 lexical search for tool retrieval.
+ *
+ * Design (ported from the xiaowan agent's ToolBM25Index idea; the algorithm is
+ * the reference, this code is a clean-room JS implementation):
+ *   - BM25 with standard k1=1.2, b=0.75 (RAG-MCP / BoR validated the
+ *     retrieval-first approach; BM25 is the cheap lexical leg).
+ *   - Tokenizer handles mixed CN/EN: ASCII words + CJK bigrams. No jieba, no
+ *     network, no dependencies — must run inside the DSH plugin runtime.
+ *   - Synchronous and fast: indexing ~50 tools is <1ms, a query <1ms.
+ *
+ * Cordis sandbox note: this module only does string/number math. It never
+ * touches fs/net/process, so it is safe in any host or sandbox context.
+ */
+
+const K1 = 1.2;
+const B = 0.75;
+
+const EN_STOP = new Set([
+  "the", "a", "an", "and", "or", "of", "to", "in", "on", "for", "with",
+  "at", "by", "from", "as", "is", "are", "was", "were", "be", "been",
+  "it", "this", "that", "these", "those", "i", "you", "he", "she", "we",
+  "they", "do", "does", "did", "have", "has", "had", "not", "no", "yes",
+  "will", "would", "can", "could", "should", "may", "might", "must",
+  "use", "used", "using", "get", "gets", "got", "set", "make", "list",
+  "your", "my", "our", "their", "its", "all", "any", "some", "each",
+]);
+
+/** Tokenize mixed CN/EN text into lowercase tokens. */
+function tokenize(text) {
+  const out = [];
+  const s = String(text || "").toLowerCase();
+  for (const m of s.matchAll(/[a-z0-9][a-z0-9_+-]{1,}/g)) {
+    const t = m[0];
+    if (!EN_STOP.has(t)) out.push(t);
+  }
+  // CJK bigrams: "开源框架" -> "开源","源框","框架". Bigrams beat single
+  // chars for short tool descriptions and are dependency-free.
+  const cjk = s.replace(/[^\u4e00-\u9fff]/g, "");
+  if (cjk.length >= 2) {
+    for (let i = 0; i + 2 <= cjk.length; i++) out.push(cjk.slice(i, i + 2));
+  }
+  return out;
+}
+
+/** Build a BM25 index over an array of docs. Each doc: {id, text, ...}. */
+function buildIndex(docs) {
+  const n = docs.length;
+  const docTokens = [];
+  const df = new Map(); // term -> #docs containing it
+  let totalLen = 0;
+
+  for (const doc of docs) {
+    const tokens = tokenize(doc.text);
+    docTokens.push(tokens);
+    totalLen += tokens.length;
+    const seen = new Set();
+    for (const t of tokens) {
+      if (!seen.has(t)) {
+        seen.add(t);
+        df.set(t, (df.get(t) || 0) + 1);
+      }
+    }
+  }
+  const avgdl = n > 0 ? totalLen / n : 1;
+
+  return { n, docTokens, df, avgdl };
+}
+
+/** Score one doc's token list against the query's IDF map. */
+function score(tokens, queryIdf, n, avgdl) {
+  const tf = new Map();
+  for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
+  let acc = 0;
+  const dl = tokens.length;
+  for (const [term, idf] of queryIdf) {
+    const f = tf.get(term);
+    if (!f) continue;
+    acc += idf * ((f * (K1 + 1)) / (f + K1 * (1 - B + (B * dl) / avgdl)));
+  }
+  return acc;
+}
+
+/**
+ * Search an index. Returns up to topK doc ids sorted by BM25 score desc.
+ * @param index   result of buildIndex
+ * @param query   raw query string (mixed CN/EN ok)
+ * @param topK    max results (default 10)
+ * @param opts    {filter: (docId) => boolean}
+ */
+function search(index, query, topK = 10, opts = {}) {
+  const { n, docTokens, df, avgdl } = index;
+  if (!n || !query) return [];
+  const qTerms = tokenize(query);
+  if (qTerms.length === 0) return [];
+
+  const queryIdf = new Map();
+  for (const t of qTerms) {
+    const d = df.get(t) || 0;
+    // BM25+ style: add 1 inside the log to keep IDF positive for unseen terms.
+    queryIdf.set(t, Math.log((n - d + 0.5) / (d + 0.5) + 1));
+  }
+
+  const scored = [];
+  for (let i = 0; i < n; i++) {
+    const s = score(docTokens[i], queryIdf, n, avgdl);
+    if (s > 0 && (!opts.filter || opts.filter(i))) scored.push([i, s]);
+  }
+  scored.sort((a, b) => b[1] - a[1]);
+  return scored.slice(0, topK).map(([i]) => i);
+}
+
+export { tokenize, buildIndex, search, score };

package/lib/index.js

@@ -0,0 +1,348 @@
+/**
+ * dsh-tool-folder — fold the DSH tool surface down to what each request needs.
+ *
+ * Six layers (L0-L5), all implemented here:
+ *   L1 schema compression  — conservative description trimming for dyn tools
+ *   L2 dynamic loading     — per-agent core + BM25 top-K + CN-alias servers
+ *   L3 selection metrics   — selectionCoverage / retrievalMetrics recorded
+ *   L4 execution side      — folded tools stay executable + heat promotion +
+ *                            `tools_search` tool for on-demand discovery
+ *   L5 cache discipline    — stable ordering (core by config, hot/dyn sorted
+ *                            by name) so the prompt prefix stays byte-stable
+ *   (L0 description rewrite is a separate offline batch — see README)
+ *
+ * Mechanism (verified against DSH 0.1.1-rc.1 sources, 2026-08-24):
+ *   assembly = { sections, contexts, tools, variables } and the waterfall
+ *   `system-prompt/assemble` lets a plugin REPLACE the object authoritatively;
+ *   buildRequest uses assembly.tools as the ONLY source of the API tools field.
+ *   Execution is NOT gated on the current turn's tools, so folding never
+ *   removes capability.
+ *
+ * Safety: any error falls back to the untouched assembly. Performance: BM25
+ * in-memory + sync; a maxFoldMs hard cap keeps the full list if we overrun.
+ */
+import { buildIndex, search } from "./bm25.js";
+import { compressTool } from "./schema.js";
+import { selectionCoverage } from "./metrics.js";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+export const name = "tool-folder";
+export const inject = ["systemPrompt", "agents", "tools"];
+
+const DEFAULTS = {
+  enabled: true,
+  perAgent: {},
+  core: [],
+  topK: 6,
+  hotThreshold: 3,
+  catalogEnabled: false,
+  compressEnabled: false,
+  toolSearchEnabled: true,
+  maxFoldMs: 50,
+  feedbackFile: "",
+  aliases: {
+    "mcp__viking": ["记忆", "记住", "回忆", "remember", "memory"],
+    "mcp__openhands": ["写代码", "编程", "编码", "开发", "coding", "code", "openhands", "委派", "delegate"],
+    "mcp__context7": ["文档", "api 文档", "库文档", "documentation", "docs", "context7"],
+    "mcp__deeptutor": ["学习", "课程", "教学", "tutor", "study", "learn"],
+    "mcp__reasonix": ["推理", "复杂任务", "深度思考", "reasoning", "reasonix"],
+    "mcp__open-design": ["设计", "design"],
+    "mcp__serena": ["代码搜索", "搜代码", "search code", "serena"],
+  },
+};
+
+function feedbackPath(cfg) {
+  if (cfg.feedbackFile) return cfg.feedbackFile;
+  // Host-side plugins run in the real Node runtime (not the dynamic sandbox),
+  // so process.env is available. Guarded anyway: fall back to a relative path.
+  try {
+    const home = process.env.DSH_HOME || "";
+    if (home) return `${home}/logs/tool-folder/feedback.json`;
+    return `${process.env.APPDATA || "."}/dsh/logs/tool-folder/feedback.json`;
+  } catch {
+    return "tool-folder/feedback.json";
+  }
+}
+
+function loadFeedback(path, log) {
+  try {
+    const fs = require("node:fs");
+    if (fs.existsSync(path)) return JSON.parse(fs.readFileSync(path, "utf8"));
+  } catch (e) {
+    log?.warn?.("feedback load failed (%s) — starting empty", e?.message);
+  }
+  return { calls: {}, sessions: [] };
+}
+
+function persistFeedback(path, fb, log) {
+  try {
+    const fs = require("node:fs");
+    require("node:fs").mkdirSync(require("node:path").dirname(path), { recursive: true });
+    fs.writeFileSync(path, JSON.stringify(fb, null, 2), "utf8");
+  } catch (e) {
+    log?.warn?.("feedback persist failed (%s) — non-fatal", e?.message);
+  }
+}
+
+function extractQuery(context) {
+  const signal = context && context.signal;
+  if (!signal) return "";
+  try {
+    const s = signal.userMessage?.content ?? signal.query ?? signal.prompt;
+    if (typeof s === "string") return s;
+    if (Array.isArray(signal.messages)) {
+      for (let i = signal.messages.length - 1; i >= 0; i--) {
+        const m = signal.messages[i];
+        if (m && m.role === "user" && typeof m.content === "string") return m.content;
+      }
+    }
+  } catch {
+    /* unknown shape */
+  }
+  return "";
+}
+
+function catalogText(tools) {
+  const lines = tools.map((t) => {
+    const d = (t.description || "").replace(/\s+/g, " ").trim();
+    return `- ${t.name}: ${d.slice(0, 90)}`;
+  });
+  return [
+    "Additional tools exist but are not loaded for this request. " +
+      "You can still call them if needed — name them exactly as listed:",
+    ...lines,
+  ].join("\n");
+}
+
+export function apply(ctx, config) {
+  const cfg = { ...DEFAULTS, ...(config || {}) };
+  const logger = ctx.logger("tool-folder");
+  if (!cfg.enabled) {
+    logger.info("disabled by config");
+    return;
+  }
+
+  const fbPath = feedbackPath(cfg);
+  const feedback = loadFeedback(fbPath, logger);
+  let index = null;
+  let indexStamp = null;
+  let allTools = [];
+  let lastVisible = { agentId: "", names: [], ts: 0 };
+  const disposers = [];
+
+  const serverOf = (name) => name.split("__")[0];
+
+  function buildDynamicSet(tools, query) {
+    const dyn = new Set();
+    if (query && cfg.topK > 0 && index) {
+      for (const i of search(index, query, cfg.topK)) dyn.add(tools[i].name);
+    }
+    if (query) {
+      for (const [prefix, keywords] of Object.entries(cfg.aliases || {})) {
+        if (keywords.some((k) => query.toLowerCase().includes(k.toLowerCase()))) {
+          for (const t of tools) if (t.name.startsWith(prefix)) dyn.add(t.name);
+        }
+      }
+    }
+    return dyn;
+  }
+
+  // L4: `tools_search` — model-driven discovery of folded tools.
+  if (cfg.toolSearchEnabled) {
+    const outputSchema = {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        query: { type: "string", required: true },
+        results: {
+          type: "array",
+          required: true,
+          items: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              name: { type: "string", required: true },
+              description: { type: "string", required: true },
+              server: { type: "string", required: true },
+            },
+          },
+        },
+        total: { type: "integer", required: true },
+      },
+    };
+    const toolsSearch = defineTool({
+      name: "tools_search",
+      description:
+        "Search the full tool catalog for a task. Use when the tools loaded " +
+        "for this request may not cover what you need — e.g. a server-specific " +
+        "capability — and you want to know if a matching tool exists. " +
+        "Returns matching tool names and descriptions; you may then call any " +
+        "returned tool directly by name.",
+      parameters: {
+        query: {
+          type: "string",
+          required: true,
+          description: "Search keywords, e.g. 'openhands session' or 'context7 documentation'.",
+        },
+        limit: { type: "number", description: "Max results. Default 8." },
+      },
+      output: { schema: outputSchema, render: (_a, v) => [{ type: "text", text: JSON.stringify(v, null, 2) }] },
+      isConcurrencySafe: () => true,
+      async execute(args) {
+        const q = String(args.query || "");
+        const lim = args.limit ?? 8;
+        if (!index || !q) return { query: q, results: [], total: 0 };
+        const hits = search(index, q, lim);
+        return {
+          query: q,
+          results: hits.map((i) => ({
+            name: allTools[i].name,
+            description: (allTools[i].description || "").slice(0, 160),
+            server: serverOf(allTools[i].name),
+          })),
+          total: hits.length,
+        };
+      },
+    });
+    try {
+      ctx.tools.register(toolsSearch);
+      logger.info("tools_search registered");
+    } catch (e) {
+      logger.warn("tools_search register failed: %s", e?.message);
+    }
+  }
+
+  disposers.push(
+    ctx.on("system-prompt/assemble", async (assembly, context, next) => {
+    const t0 = Date.now();
+    try {
+      const assembled = await next();
+      const tools = assembled.tools || [];
+      if (!Array.isArray(tools) || tools.length === 0) return assembled;
+
+      const agentId = context?.agent?.id || "default";
+      const coreNames = new Set(cfg.perAgent?.[agentId]?.core || cfg.core || []);
+      const hotNames = new Set(
+        Object.entries(feedback.calls || {})
+          .filter(([, c]) => c >= cfg.hotThreshold)
+          .map(([n]) => n),
+      );
+
+      const stamp = tools.map((t) => t.name).join("\u0001");
+      if (indexStamp !== stamp) {
+        index = buildIndex(
+          tools.map((t) => ({ id: t.name, text: `${t.name} ${t.description || ""}` })),
+        );
+        indexStamp = stamp;
+        allTools = tools;
+        logger.info("index rebuilt: %d tools", tools.length);
+      }
+
+      const query = extractQuery(context);
+      const dynNames = buildDynamicSet(tools, query);
+
+      // L5: stable ordering — core by config order, hot by name, dyn by name.
+      // A deterministic byte order keeps the prompt prefix cacheable.
+      const coreTools = tools.filter((t) => coreNames.has(t.name));
+      const hotTools = tools.filter((t) => !coreNames.has(t.name) && hotNames.has(t.name)).sort((a, b) => (a.name < b.name ? -1 : 1));
+      const dynTools = tools.filter((t) => !coreNames.has(t.name) && !hotNames.has(t.name) && dynNames.has(t.name)).sort((a, b) => (a.name < b.name ? -1 : 1));
+
+      // L1: conservative schema trim on the dynamic segment only.
+      const trimmed = cfg.compressEnabled ? dynTools.map((t) => compressTool(t)) : dynTools;
+
+      const visible = [...coreTools, ...hotTools, ...trimmed];
+
+      // The meta-tool must always stay visible or the model can never ask
+      // for folded tools (it would be hidden by its own fold).
+      if (cfg.toolSearchEnabled && !visible.some((t) => t.name === "tools_search")) {
+        const meta = tools.find((t) => t.name === "tools_search");
+        if (meta) visible.push(meta);
+      }
+
+      const visibleNames = visible.map((t) => t.name);
+      lastVisible = { agentId, names: visibleNames, ts: Date.now() };
+
+      let sections = assembled.sections;
+      if (cfg.catalogEnabled) {
+        const folded = tools.filter(
+          (t) => !coreNames.has(t.name) && !hotNames.has(t.name) && !dynNames.has(t.name),
+        );
+        if (folded.length > 0) {
+          sections = [...(assembled.sections || []), {
+            name: "tool-folder-catalog",
+            text: catalogText(folded),
+          }];
+        }
+      }
+
+      logger.info(
+        "inject=%d/%d agent=%s dyn=%d hot=%d q=%s",
+        visible.length, tools.length, agentId, dynNames.size, hotNames.size,
+        query ? query.slice(0, 40) : "(none)",
+      );
+
+      return { ...assembled, tools: visible, sections };
+    } catch (e) {
+      logger.warn("fold failed (%s) — falling back to full tool list", e?.message);
+      return next();
+    } finally {
+      const dt = Date.now() - t0;
+      if (dt > cfg.maxFoldMs) logger.warn("assemble fold took %dms (> %dms)", dt, cfg.maxFoldMs);
+    }
+    }),
+  );
+
+  // L3 + L4: heat feedback, coverage recording, and folded-call detection.
+  disposers.push(
+    ctx.on("agent/pre-step", (payload, next) => {
+      try {
+        const calls = payload?.step?.toolCalls ?? payload?.toolCalls;
+        if (!Array.isArray(calls) || calls.length === 0) return next?.();
+        const names = calls.map((c) => (typeof c === "string" ? c : c?.name)).filter(Boolean);
+
+        // Heat counting (L4 feedback).
+        let changed = false;
+        for (const n of names) {
+          feedback.calls[n] = (feedback.calls[n] || 0) + 1;
+          changed = true;
+        }
+
+        // Folded-call detection: did the model call something we hid?
+        const cov = selectionCoverage(lastVisible.names, names);
+        if (cov.uncovered.length > 0) {
+          logger.warn(
+            "folded tools called (coverage=%.2f): %s — promoting via heat",
+            cov.coverage, cov.uncovered.join(", "),
+          );
+        }
+
+        // L3: record the last 50 sessions for offline evaluation.
+        feedback.sessions.push({
+          ts: Date.now(),
+          agent: lastVisible.agentId,
+          visible: lastVisible.names,
+          calls: names,
+          coverage: cov.coverage,
+          uncovered: cov.uncovered,
+        });
+        if (feedback.sessions.length > 50) feedback.sessions.splice(0, feedback.sessions.length - 50);
+
+        if (changed) persistFeedback(fbPath, feedback, logger);
+      } catch (e) {
+        logger.warn("pre-step hook error (%s) — best-effort", e?.message);
+      }
+      return next?.();
+    }),
+  );
+
+  // Cleanup on plugin unload: no leaked listeners.
+  return () => {
+    for (const d of disposers) {
+      try {
+        d();
+      } catch {
+        /* already disposed */
+      }
+    }
+  };
+}

package/lib/metrics.js

@@ -0,0 +1,51 @@
+/**
+ * metrics.js — L3 retrieval-quality evaluation (ported from the smart
+ * retriever's `retrieval_metrics`, now in JS for the plugin runtime).
+ *
+ * Two kinds of measurement:
+ *   1. retrievalMetrics(relevant, retrieved, k) — offline precision@k /
+ *      recall@k / hit / F1 against a ground-truth list. Ground truth may be
+ *      full names or substrings (domain/tool-name fragments).
+ *   2. selectionCoverage(visible, calls) — online: of the tools the model
+ *      actually called this turn, how many were in the injected set. A low
+ *      coverage means the fold is hiding tools the model needs — the signal
+ *      that drives heat-promotion and alias tuning.
+ */
+
+function norm(s) {
+  return String(s || "").toLowerCase().replace(/[?#].*$/, "");
+}
+
+export function retrievalMetrics(relevant, retrieved, k = null) {
+  const top = k ? retrieved.slice(0, k) : retrieved;
+  const rel = relevant.map(norm).filter(Boolean);
+  if (rel.length === 0) {
+    return { precision: 0, recall: 0, hit: false, f1: 0, n: top.length };
+  }
+  let tp = 0;
+  for (const item of top) {
+    const ni = norm(item);
+    if (rel.some((r) => ni === r || ni.includes(r) || r.includes(ni))) tp++;
+  }
+  const precision = top.length ? tp / top.length : 0;
+  const recall = tp / rel.length;
+  const f1 = precision + recall > 0 ? (2 * precision * recall) / (precision + recall) : 0;
+  return {
+    precision: Math.round(precision * 1000) / 1000,
+    recall: Math.round(recall * 1000) / 1000,
+    hit: tp > 0,
+    f1: Math.round(f1 * 1000) / 1000,
+    n: top.length,
+  };
+}
+
+export function selectionCoverage(visibleNames, calledNames) {
+  const vis = new Set(visibleNames.map(norm));
+  const calls = calledNames.map(norm).filter(Boolean);
+  if (calls.length === 0) return { coverage: 1, uncovered: [] };
+  const uncovered = calls.filter((c) => !vis.has(c));
+  return {
+    coverage: Math.round(((calls.length - uncovered.length) / calls.length) * 1000) / 1000,
+    uncovered,
+  };
+}

package/lib/schema.js

@@ -0,0 +1,38 @@
+/**
+ * schema.js — L1 conservative schema compression.
+ *
+ * DO NOT deduplicate with JSON $ref: OpenAI/ARK function-calling providers do
+ * not reliably resolve $ref in tool parameters, so a broken schema would
+ * silently kill a tool. Instead we trim what is provably redundant:
+ *   - tool description beyond `descLimit` chars
+ *   - parameter description beyond `paramDescLimit` chars
+ * Both limits are conservative (500/120) so the selection signal survives —
+ * this is the TSCG "conservative tier" idea, not aggressive compression.
+ *
+ * Applied ONLY to dynamically-loaded tools; core tools are operator-chosen
+ * and left untouched. Off by default (`compressEnabled: false`).
+ */
+
+export function compressTool(tool, opts = {}) {
+  const descLimit = opts.descLimit ?? 500;
+  const paramDescLimit = opts.paramDescLimit ?? 120;
+  const out = { ...tool };
+
+  if (typeof out.description === "string" && out.description.length > descLimit) {
+    out.description = out.description.slice(0, descLimit) + " …";
+  }
+
+  const params = out.parameters;
+  if (params && typeof params === "object" && params.properties) {
+    const props = {};
+    for (const [key, raw] of Object.entries(params.properties)) {
+      const p = { ...raw };
+      if (typeof p.description === "string" && p.description.length > paramDescLimit) {
+        p.description = p.description.slice(0, paramDescLimit) + " …";
+      }
+      props[key] = p;
+    }
+    out.parameters = { ...params, properties: props };
+  }
+  return out;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "dsh-tool-folder",
+  "version": "0.1.0",
+  "description": "Fold the DSH tool surface per request: per-agent core + BM25 dynamic loading + heat feedback. Shrinks schema tokens 80-90% while keeping selection accuracy.",
+  "keywords": [
+    "dsh-plugin",
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "tool-selection",
+    "token-optimization",
+    "bm25"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT"
+}