dsh-skill-folder 0.3.0

package/lib/render.js

@@ -0,0 +1,102 @@
+/**
+ * render.js — CatalogRenderer.
+ *
+ * Render the folded catalog text. The surrounding framing is copied VERBATIM
+ * from the host's renderCatalogMessage / renderCatalogUpdate
+ * (@deepseek-ai/dsh-tool-skill/lib/index.js :216-264) so the model sees the
+ * same <system-reminder>/<available_skills>/loading/direct-call guidance —
+ * only the entry lines and an optional footer differ.
+ *
+ *   - core entries: description unlimited (safety bottom line).
+ *   - dynamic entries: description truncated to maxDescLength (default 100).
+ *   - footer (safety net): names of unselected, non-denied skills so the
+ *     model knows they exist ("never lose a skill").
+ *
+ * Deterministic: entry order is whatever selectEntries produced
+ * ([...core(config), ...dynamic(name)]); footer order follows pool order.
+ */
+
+/** Escape model-facing prose embedded inside skill markup (host parity). */
+function escapeText(value) {
+  return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+/**
+ * Normalize whitespace and length-bound a description.
+ * @param {string} value
+ * @param {number} max - max length; pass Infinity for core (unlimited).
+ * @returns {string}
+ */
+export function desc(value, max) {
+  const normalized = String(value || "").replaceAll(/\s+/g, " ").trim();
+  if (max === Infinity) return normalized;
+  const limit = Number.isFinite(Number(max)) ? Math.max(0, Math.floor(Number(max))) : 100;
+  if (limit === 0) return "";
+  if (normalized.length <= limit) return normalized;
+  if (limit <= 3) return normalized.slice(0, limit);
+  return `${normalized.slice(0, limit - 3)}...`;
+}
+
+/**
+ * Render the folded catalog text.
+ * @param {Array<{name: string, description: string}>} selected - core + dynamic entries.
+ * @param {Array<{name: string, description: string}>} footer - unselected, non-denied entries.
+ * @param {object} opts - { update?: boolean, maxDescLength?: number, core?: Array<string>|Set<string> }
+ * @returns {string}
+ */
+export function renderCatalogText(selected, footer, opts = {}) {
+  const maxDescLength = opts.maxDescLength ?? 100;
+  const coreNames =
+    opts.core instanceof Set
+      ? opts.core
+      : Array.isArray(opts.core)
+        ? new Set(opts.core)
+        : new Set();
+  const update = opts.update === true;
+  const entries = Array.isArray(selected) ? selected : [];
+  const extra = Array.isArray(footer) ? footer : [];
+
+  const lines = entries.map((entry) => {
+    const max = coreNames.has(entry.name) ? Infinity : maxDescLength;
+    return `- \`${entry.name}\`: ${escapeText(desc(entry.description, max))}`;
+  });
+
+  const header = update
+    ? [
+        "<system-reminder>",
+        "The available skill catalog changed. This complete catalog replaces every earlier available-skills list in this session:",
+        "",
+        "<available_skills>",
+      ]
+    : [
+        "<system-reminder>",
+        "A skill is a reusable set of task-specific instructions. The following skills are available in this session:",
+        "",
+        "<available_skills>",
+      ];
+
+  const body = update
+    ? [
+        "</available_skills>",
+        "",
+        "Use only names in this replacement catalog. If the user names a listed skill, or the task clearly matches its description, call the `skill` tool with the exact name before acting.",
+        "A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.",
+      ]
+    : [
+        "</available_skills>",
+        "",
+        "If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.",
+        "If the task clearly needs a capability but no skill description clearly matches, call the `skill_search` tool with a short intent to find the most relevant skill.",
+        "A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.",
+      ];
+
+  const parts = [...header, ...lines, ...body];
+  if (extra.length > 0) {
+    const names = extra.map((e) => `\`${e.name}\``).join(", ");
+    parts.push(
+      `Additional skills exist in this session: ${names}. Call the \`skill\` tool with the exact name to load one if the task calls for it.`,
+    );
+  }
+  parts.push("</system-reminder>");
+  return parts.join("\n");
+}

package/lib/select.js

@@ -0,0 +1,66 @@
+/**
+ * select.js — StaticEntrySelector (KV-cache-stable).
+ *
+ * v0.2.0: static selection — the rendered catalog depends ONLY on the skill
+ * set (which is fixed for a session), NEVER on the per-step query. This keeps
+ * the catalog message byte-identical across turns, so the prompt-cache prefix
+ * never invalidates (the dynamic per-query variant destroyed the KV cache).
+ *
+ * Ordering:
+ *   1. pool   = entries minus deny (exact name or "prefix*" pattern).
+ *              NOTE: core entries are NEVER denied — core is the safety
+ *              bottom line; deny only filters non-core skills (a deny that
+ *              names a core skill is ignored, so an admin cannot
+ *              accidentally hide a security-critical skill).
+ *   2. core   = cfg.core entries taken from the pool in CONFIG order
+ *               (missing names are silently skipped — never throw).
+ *   3. rest   = remaining pool entries sorted by name ascending
+ *               (byte-stable, deterministic rendering).
+ *   selected = [...core(config order), ...rest(name order)].
+ *
+ * There is no footer split: everything non-denied is listed (truncated
+ * descriptions), so the model sees every available skill — matching
+ * Anthropic's "metadata tier always loaded" progressive disclosure.
+ * Skill bodies are still loaded on demand via the `skill` tool.
+ */
+import { matchesAnyPattern } from "./pattern.js";
+
+/**
+ * @param {Array<{name: string, description: string}>} entries - catalog source.entries (host-normalized).
+ * @param {object} cfg - merged config (core/deny).
+ * @returns {Array<{name: string, description: string}>} static ordered selection.
+ */
+export function selectEntries(entries, cfg) {
+  const source = Array.isArray(entries) ? entries : [];
+  const coreOrder = Array.isArray(cfg.core)
+    ? cfg.core.map((n) => String(n).trim()).filter(Boolean)
+    : [];
+  const coreSet = new Set(coreOrder);
+  const denyPatterns = Array.isArray(cfg.deny)
+    ? cfg.deny.map((n) => String(n).trim()).filter(Boolean)
+    : [];
+  // Core skills are exempt from deny (safety bottom line): a deny naming a
+  // core skill is ignored rather than hiding a security-critical skill.
+  const pool = source.filter(
+    (e) => coreSet.has(e.name) || !matchesAnyPattern(e.name, denyPatterns),
+  );
+
+  // P0 core — config order, duplicates deduped, missing silently skipped.
+  const core = [];
+  const picked = new Set();
+  for (const name of coreOrder) {
+    if (picked.has(name)) continue;
+    const entry = pool.find((e) => e.name === name);
+    if (entry) {
+      core.push(entry);
+      picked.add(entry.name);
+    }
+  }
+
+  // Remaining, name-ascending (byte-stable).
+  const rest = pool
+    .filter((e) => !picked.has(e.name))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  return [...core, ...rest];
+}

package/lib/semantic.js

@@ -0,0 +1,239 @@
+/**
+ * semantic.js — local semantic retrieval leg via Ollama bge-m3 (2026-08-30).
+ *
+ * Complements the BM25 lexical leg (bm25.js) with a cross-lingual semantic
+ * leg: Chinese intents can hit English-only tool/skill descriptions that
+ * share no surface tokens (the documented BM25 gap). Uses the machine's
+ * local Ollama (`http://127.0.0.1:11434/api/embed`, model bge-m3 — 1024 dims,
+ * ~1.2GB, already installed per ~/.dsh config). No npm deps, no network egress.
+ *
+ * Hard-fail design: every external path (fetch, fs cache) is optional. If
+ * Ollama is down, the cache is unreadable, or anything throws, callers get
+ * null/[] and their existing BM25 path just keeps working.
+ *
+ * Cache: document embeddings are keyed by text and persisted to
+ * `~/.dsh/state/semantic-cache.json` (fingerprint = hash of all doc texts), so
+ * the ~10s cold start for 300+ tools happens once, not per session.
+ * Query embeddings are cached in memory only (per-process, tiny).
+ */
+
+const OLLAMA_BASE = "http://127.0.0.1:11434";
+const DEFAULT_MODEL = "bge-m3";
+const EMBED_TIMEOUT_MS = 8000;
+const CACHE_FILE = ".dsh/state/semantic-cache.json";
+
+import fs from "node:fs";
+
+/* ------------------------------------------------------------------ */
+/* hash + fs helpers (all fail-safe)                                   */
+/* ------------------------------------------------------------------ */
+
+/** FNV-1a 32-bit hex — fast, dependency-free fingerprint. */
+function hash(text) {
+  let h = 0x811c9dc5;
+  const s = String(text || "");
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = (h * 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+
+function homeDir() {
+  return process.env.USERPROFILE || process.env.HOME || "";
+}
+
+function readCacheFile() {
+  try {
+    const p = homeDir() + "/" + CACHE_FILE;
+    if (!p || !fs.existsSync(p)) return null;
+    const raw = fs.readFileSync(p, "utf8");
+    const j = JSON.parse(raw);
+    if (j && typeof j === "object") return j;
+  } catch {
+    /* unreadable → miss */
+  }
+  return null;
+}
+
+function writeCacheFile(obj) {
+  try {
+    const p = homeDir() + "/" + CACHE_FILE;
+    const dir = p.slice(0, p.lastIndexOf("/"));
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(obj), "utf8");
+  } catch {
+    /* cache write is best-effort */
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Ollama embedding (fail-safe fetch)                                  */
+/* ------------------------------------------------------------------ */
+
+let _model = DEFAULT_MODEL;
+let _base = OLLAMA_BASE;
+
+/**
+ * Configure the endpoint (called by plugin apply with cfg.ollamaBase/model).
+ * @param {{ollamaBase?: string, embedModel?: string}} cfg
+ */
+export function configureSemantic(cfg = {}) {
+  if (cfg && typeof cfg === "object") {
+    if (typeof cfg.ollamaBase === "string" && cfg.ollamaBase) _base = cfg.ollamaBase;
+    if (typeof cfg.embedModel === "string" && cfg.embedModel) _model = cfg.embedModel;
+  }
+}
+
+/** One embedding vector for a text, or null on any failure. */
+export async function embedText(text, timeoutMs = EMBED_TIMEOUT_MS) {
+  const s = String(text || "").trim();
+  if (!s) return null;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetch(_base + "/api/embed", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: _model, input: s }),
+        signal: ctrl.signal,
+      });
+      if (!res.ok) return null;
+      const j = await res.json();
+      const v = j?.embeddings?.[0];
+      return Array.isArray(v) && v.length > 0 ? v : null;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return null; // offline / timeout / bad response → lexical leg only
+  }
+}
+
+/** Cosine similarity in [0,1] (both vectors plain arrays). */
+export function cosine(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length === 0 || a.length !== b.length) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+
+/* ------------------------------------------------------------------ */
+/* Semantic index with persistent doc-embedding cache                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Build a semantic index over docs. Doc embeddings come from the on-disk
+ * cache when the fingerprint matches; otherwise they are computed once and
+ * persisted. Never blocks forever: total batch time is bounded and a failure
+ * returns an index whose vectors are simply empty (lexical leg still works).
+ *
+ * @param {Array<{id: string, text: string}>} docs
+ * @param {number} [timeoutMs] per-embed timeout
+ * @returns {Promise<{vectors: Map<string, number[]>, available: boolean}>}
+ */
+export async function buildSemanticIndex(docs, timeoutMs = EMBED_TIMEOUT_MS) {
+  const out = { vectors: new Map(), available: false };
+  const list = Array.isArray(docs) ? docs.filter((d) => d && d.id && d.text) : [];
+  if (list.length === 0) return out;
+
+  // Fast path: cache hit.
+  const fp = hash(list.map((d) => d.id + "\u0000" + d.text).join("\u0001"));
+  const cache = readCacheFile();
+  const cached = cache && cache.fp === fp && cache.vec && typeof cache.vec === "object" ? cache.vec : null;
+  if (cached) {
+    for (const d of list) {
+      const v = cached[d.id];
+      if (Array.isArray(v) && v.length > 0) out.vectors.set(d.id, v);
+    }
+    if (out.vectors.size === list.length) {
+      out.available = true;
+      return out;
+    }
+  }
+
+  // Miss: embed each doc (sequential — CPU-bound local model, avoids
+  // overloading Ollama), bounded by an overall deadline.
+  const deadline = Date.now() + 60_000;
+  const fresh = {};
+  let ok = 0;
+  for (const d of list) {
+    if (Date.now() > deadline) break;
+    const v = await embedText(d.text, timeoutMs);
+    if (v) {
+      fresh[d.id] = v;
+      out.vectors.set(d.id, v);
+      ok++;
+    }
+  }
+  if (ok === list.length) {
+    out.available = true;
+    writeCacheFile({ fp, vec: fresh }); // persist only on full success
+  }
+  return out;
+}
+
+/**
+ * Rank docs by semantic similarity to a query.
+ * @param {Map<string, number[]>} vectors  id → vector
+ * @param {Array<{id: string, text: string}>} docs
+ * @param {string} query
+ * @returns {Promise<Array<{id: string, score: number}>>} sorted desc, score = cosine
+ */
+export async function searchSemantic(vectors, docs, query) {
+  const q = String(query || "").trim();
+  if (!q || !vectors || vectors.size === 0) return [];
+  const qv = await embedText(q);
+  if (!qv) return [];
+  const scored = [];
+  for (const d of docs) {
+    const v = vectors.get(d.id);
+    if (!v) continue;
+    const c = cosine(qv, v);
+    if (c > 0) scored.push({ id: d.id, score: c });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored;
+}
+
+/* ------------------------------------------------------------------ */
+/* RRF hybrid: merge a BM25 ranking and a semantic ranking             */
+/* ------------------------------------------------------------------ */
+
+const RRF_K = 60;
+
+/**
+ * Reciprocal-rank fusion of two ranked id lists.
+ * @param {Array<{id: string}>} bm25Ranked  BM25 hits in rank order
+ * @param {Array<{id: string}>} semRanked   semantic hits in rank order
+ * @param {number} topK
+ * @returns {Array<{id: string, rrf: number, from: string}>} fused, sorted desc
+ */
+export function rrfFuse(bm25Ranked, semRanked, topK) {
+  const scores = new Map();
+  const from = new Map();
+  bm25Ranked.forEach((h, i) => {
+    const key = h.id;
+    scores.set(key, (scores.get(key) || 0) + 1 / (RRF_K + i + 1));
+    from.set(key, (from.get(key) || "") + "bm25 ");
+  });
+  semRanked.forEach((h, i) => {
+    const key = h.id;
+    scores.set(key, (scores.get(key) || 0) + 1 / (RRF_K + i + 1));
+    from.set(key, (from.get(key) || "") + "sem ");
+  });
+  const k = Number(topK);
+  const n = Number.isFinite(k) && k > 0 ? Math.floor(k) : 5;
+  return [...scores.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, n)
+    .map(([id, r]) => ({ id, rrf: r, from: from.get(id)?.trim() || "" }));
+}

package/lib/skill-search.js

@@ -0,0 +1,155 @@
+/**
+ * skill-search.js — pure retrieval logic (BM25 over name + description +
+ * aliases). Zero dependencies — testable standalone. The defineTool wrapper
+ * lives in index.js so this module never pulls host packages.
+ *
+ * v0.3.0 (2026-08-30): semantic hybrid leg. `searchSkillsHybrid` fuses BM25
+ * with a local bge-m3 semantic ranking (RRF) — Chinese intents can hit
+ * English-only skills that share no surface tokens. The semantic index is
+ * injected by the caller (built lazily, disk-cached); the pure `searchSkills`
+ * stays as the sync/offline fallback.
+ */
+import { buildIndex, search } from "./bm25.js";
+import { matchesAnyPattern } from "./pattern.js";
+import { rrfFuse } from "./semantic.js";
+
+/**
+ * Filter a snapshot skill list to the searchable pool (model-invocable +
+ * deny removed). Pure function: the model-invocation predicate is injected
+ * so this module stays zero-dependency; the host wrapper passes the same
+ * rule the host catalog uses (`skill.invocation.modelInvocable === true`,
+ * dsh-tool-skill :195). Defaults to allow-all for standalone/test use.
+ * @param {Array<{name: string, description: string, invocation?: object}>} skills
+ * @param {object} cfg - merged config (deny).
+ * @param {(skill: object) => boolean} [isModelInvocableFn] - injected predicate.
+ * @returns {Array<{name: string, description: string}>}
+ */
+export function filterPool(skills, cfg, isModelInvocableFn) {
+  const denyPatterns = Array.isArray(cfg.deny)
+    ? cfg.deny.map((n) => String(n).trim()).filter(Boolean)
+    : [];
+  const canInvoke = typeof isModelInvocableFn === "function" ? isModelInvocableFn : () => true;
+  return (Array.isArray(skills) ? skills : [])
+    .filter((s) => s && typeof s.name === "string")
+    .filter((s) => canInvoke(s))
+    .filter((s) => !matchesAnyPattern(s.name, denyPatterns))
+    .map((s) => ({ name: s.name, description: s.description || "" }));
+}
+
+/**
+ * Rank the pool against an intent using BM25 over name + description +
+ * aliases. Aliases let Chinese intents hit English-only skills.
+ * @param {Array<{name, description}>} pool
+ * @param {string} intent
+ * @param {object} cfg - merged config (aliases).
+ * @param {number} topK - max results; non-finite or <=0 falls back to 5.
+ * @returns {Array<{name: string, description: string, score: number}>}
+ *   score is the BM25 rank (1 = most relevant), monotonic with the list order.
+ */
+export function searchSkills(pool, intent, cfg, topK) {
+  const n = Number(topK);
+  const k = Number.isFinite(n) && n > 0 ? Math.floor(n) : 5;
+  const src = Array.isArray(pool) ? pool : [];
+  const q = String(intent || "").trim();
+  if (!src.length || !q) return [];
+  const aliasMap = cfg.aliases && typeof cfg.aliases === "object" ? cfg.aliases : {};
+  const docs = src.map((s) => {
+    const aliasWords = Array.isArray(aliasMap[s.name]) ? aliasMap[s.name] : [];
+    return { id: s.name, text: `${s.name} ${s.description || ""} ${aliasWords.join(" ")}` };
+  });
+  const index = buildIndex(docs);
+  const hits = search(index, q, k);
+  return hits.map((i, idx) => ({ ...src[i], score: idx + 1 }));
+}
+
+/** Build the BM25 doc corpus for a pool (shared by both search functions). */
+function poolDocs(src, aliasMap) {
+  return src.map((s) => {
+    const aliasWords = Array.isArray(aliasMap[s.name]) ? aliasMap[s.name] : [];
+    return { id: s.name, text: `${s.name} ${s.description || ""} ${aliasWords.join(" ")}` };
+  });
+}
+
+/**
+ * Hybrid search: BM25 + semantic (bge-m3) fused by RRF. The semantic leg is
+ * optional — pass `semIndex` (from buildSemanticIndex) or null; when absent
+ * or unavailable this falls back to pure BM25 (identical to searchSkills).
+ *
+ * @param {Array<{name, description}>} pool
+ * @param {string} intent
+ * @param {object} cfg - merged config (aliases).
+ * @param {number} topK
+ * @param {{vectors: Map<string, number[]>, available: boolean}|null} [semIndex]
+ * @param {(query: string) => Promise<Array<{id: string, score: number}>>} [semSearchFn]
+ *   injectable semantic search (defaults to semantic.searchSemantic with the
+ *   pool docs); tests may stub it.
+ * @returns {Promise<Array<{name: string, description: string, score: number}>>}
+ */
+export async function searchSkillsHybrid(pool, intent, cfg, topK, semIndex, semSearchFn) {
+  const n = Number(topK);
+  const k = Number.isFinite(n) && n > 0 ? Math.floor(n) : 5;
+  const src = Array.isArray(pool) ? pool : [];
+  const q = String(intent || "").trim();
+  if (!src.length || !q) return [];
+  const aliasMap = cfg.aliases && typeof cfg.aliases === "object" ? cfg.aliases : {};
+  const docs = poolDocs(src, aliasMap);
+
+  const bm25Index = buildIndex(docs);
+  const bm25Hits = search(bm25Index, q, k * 2).map((i) => ({ id: src[i].name }));
+
+  let fused = bm25Hits;
+  if (semIndex && semIndex.available && semIndex.vectors && semIndex.vectors.size > 0) {
+    try {
+      const semRanked = semSearchFn
+        ? await semSearchFn(q)
+        : await import("./semantic.js").then((m) => m.searchSemantic(semIndex.vectors, docs, q));
+      fused = rrfFuse(bm25Hits, semRanked.slice(0, k * 2), k);
+    } catch {
+      /* semantic failure → BM25 only */
+    }
+  }
+  const byName = new Map(src.map((s) => [s.name, s]));
+  return fused.map((h, idx) => {
+    const s = byName.get(h.id) || { name: h.id, description: "" };
+    return { ...s, score: idx + 1 };
+  });
+}
+
+/**
+ * Auto-route hint (P1): sync, cheap, conservative. Returns the name of ONE
+ * skill that the user message clearly points at, or null. Uses the alias
+ * table in both directions (alias word in query → skill; query token in
+ * skill name) plus a BM25 top hit as a second candidate — but only when the
+ * top hit shares a surface token with the query (so "你好" never routes).
+ * @param {Array<{name, description}>} pool - filtered searchable pool.
+ * @param {string} userText - the latest user message text.
+ * @param {object} cfg - merged config (aliases).
+ * @returns {string|null} skill name to suggest, or null.
+ */
+export function routeHint(pool, userText, cfg) {
+  const q = String(userText || "").trim();
+  if (!q || !Array.isArray(pool) || pool.length === 0) return null;
+  const aliasMap = cfg.aliases && typeof cfg.aliases === "object" ? cfg.aliases : {};
+  const names = new Set(pool.map((s) => s.name));
+  const ql = q.toLowerCase();
+
+  // Direct alias hit: any alias word appearing in the query.
+  for (const [skill, words] of Object.entries(aliasMap)) {
+    if (!names.has(skill) || !Array.isArray(words)) continue;
+    for (const w of words) {
+      const wl = String(w).toLowerCase().trim();
+      if (wl.length >= 2 && ql.includes(wl)) return skill;
+    }
+  }
+
+  // Query token hits a skill name directly: token "memory" → "viking-memory-guide".
+  const tokens = ql.match(/[a-z0-9][a-z0-9_+-]{1,}/g) || [];
+  for (const t of tokens) {
+    if (t.length < 3) continue;
+    for (const s of pool) {
+      if (s.name.toLowerCase().includes(t)) return s.name;
+    }
+  }
+
+  return null;
+}

package/lib/tool-skill-search.js

@@ -0,0 +1,92 @@
+/**
+ * tool-skill-search.js — defineTool wrapper for `skill_search`.
+ *
+ * Pure retrieval logic lives in ./skill-search.js (zero deps, testable);
+ * this module only wraps it in the host tool contract. Requires the
+ * `skills` service for the live snapshot (injected in index.js).
+ *
+ * v0.3.0 (2026-08-30): semantic hybrid leg — skill_search now fuses BM25
+ * with local bge-m3 similarity (RRF) when the semantic index is available;
+ * any failure degrades to pure BM25.
+ */
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { filterPool, searchSkills, searchSkillsHybrid } from "./skill-search.js";
+
+/**
+ * Build the `skill_search` tool definition.
+ * @param {object} ctx - cordis context (ctx.skills).
+ * @param {object} cfg - merged config (deny/aliases).
+ * @param {object} logger - cordis logger.
+ * @param {() => Promise<{vectors: Map, available: boolean}>} [getSemIndex]
+ *   lazy semantic-index provider (built by index.js); null disables the leg.
+ * @returns {object} defineTool payload.
+ */
+export function buildSkillSearchTool(ctx, cfg, logger, getSemIndex) {
+  return defineTool({
+    name: "skill_search",
+    description:
+      "Search available skills by task intent. Call this when a task clearly needs a capability but you are unsure which skill to load. Returns the most relevant skills; then call the `skill` tool with the exact name to load full instructions.",
+    parameters: {
+      intent: {
+        type: "string",
+        required: true,
+        description:
+          "Short description of the capability you need, e.g. 'debug a crash', 'delegate to subagent', 'review code'.",
+      },
+      k: {
+        type: "number",
+        description: "Max results (default 5).",
+      },
+    },
+    output: {
+      schema: {
+        type: "array",
+        items: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            name: { type: "string" },
+            description: { type: "string" },
+            score: { type: "number", description: "relevance rank, 1 = most relevant" },
+          },
+        },
+      },
+      render: (_a, value) => [
+        {
+          type: "text",
+          text: Array.isArray(value) && value.length
+            ? value.map((s, i) => `${i + 1}. ${s.name} — ${s.description || ""}`).join("\n")
+            : "No matching skills found for this intent.",
+        },
+      ],
+    },
+    async execute(args, exec) {
+      const intent = typeof args?.intent === "string" ? args.intent.trim() : "";
+      if (!intent) return [];
+      const lookup = {
+        cwd: exec?.agent?.session?.header?.cwd,
+        scope: exec?.agent,
+        signal: exec?.signal,
+      };
+      const snapshot = await ctx.skills.snapshot(lookup);
+      const skills = (snapshot && snapshot.skills) || [];
+      const pool = filterPool(skills, cfg, (s) => s.invocation?.modelInvocable === true);
+      let ranked;
+      if (typeof getSemIndex === "function") {
+        // Build the SAME doc corpus searchSkillsHybrid uses internally
+        // (name + description + aliases) so the cache fingerprint matches.
+        const aliasMap = cfg.aliases && typeof cfg.aliases === "object" ? cfg.aliases : {};
+        const docs = pool.map((s) => ({
+          id: s.name,
+          text: `${s.name} ${s.description || ""} ${(Array.isArray(aliasMap[s.name]) ? aliasMap[s.name] : []).join(" ")}`,
+        }));
+        const sem = await getSemIndex(docs);
+        ranked = await searchSkillsHybrid(pool, intent, cfg, args?.k, sem);
+      } else {
+        ranked = searchSkills(pool, intent, cfg, args?.k);
+      }
+      logger?.info?.("skill_search(%s) → %d of %d skills", intent.slice(0, 40), ranked.length, pool.length);
+      return ranked.map((s) => ({ name: s.name, description: s.description || "", score: s.score }));
+    },
+  });
+}