@tool-bridge/server 0.17.0 → 0.19.0

package/dist/{chunk-RVWZN3CI.js → chunk-OKRZPQ3R.js}

@@ -14873,6 +14873,10 @@ function secretRefsInConfig(config2) {
   const refs = [];
   const oauthMcp = c.kind === "mcp" && c.auth === "oauth";
   if (!oauthMcp && typeof c.authRef === "string" && c.authRef.length > 0) refs.push(c.authRef);
+  if (oauthMcp && c.oauthClient !== null && typeof c.oauthClient === "object") {
+    const secretRef = c.oauthClient.clientSecretRef;
+    if (typeof secretRef === "string" && secretRef.length > 0) refs.push(secretRef);
+  }
   if (typeof c.skRef === "string" && c.skRef.length > 0) refs.push(c.skRef);
   return refs;
 }
@@ -15589,7 +15593,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       opts: HTBP_LIST_OPTIONS_SCHEMA.optional()
     }),
     returns: "Page<ContextEntryMeta>",
-    scope: "read"
+    scope: "read",
+    effect: "read"
   },
   ({ opts, path }, { provider }) => provider.list(path ?? "", opts)
 ).register(
@@ -15600,7 +15605,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       path: external_exports.string().describe("entry path inside the namespace")
     }),
     returns: "ContextEntry",
-    scope: "read"
+    scope: "read",
+    effect: "read"
   },
   ({ path }, { provider }) => provider.get(path)
 ).register(
@@ -15612,7 +15618,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       entry: entrySchema
     }),
     returns: "ContextEntryMeta",
-    scope: "write"
+    scope: "write",
+    effect: "write"
   },
   ({ entry, path }, { provider }) => provider.write(path, entry)
 ).register(
@@ -15624,7 +15631,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       patch: patchSchema
     }),
     returns: "ContextEntryMeta",
-    scope: "write"
+    scope: "write",
+    effect: "write"
   },
   ({ patch, path }, { provider }) => provider.update(path, patch)
 ).register(
@@ -15647,7 +15655,8 @@ var contextCommands = new HtbpCommandRegistry().register(
       opts: searchOptionsSchema.optional()
     }),
     returns: "Page<ContextEntryMeta>",
-    scope: "read"
+    scope: "read",
+    effect: "read"
   },
   ({ opts, query }, { provider }) => provider.search(query, opts)
 ).register(
@@ -16620,7 +16629,7 @@ var tbErrorBodySchema = external_exports.object({
 var actionSchema = external_exports.enum(ACTIONS);
 var nodeKindSchema = external_exports.enum(NODE_KINDS);
 var nodeInputConfigSchema = external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
-  "kind-specific config, e.g. mcp: { url, auth?, authRef? } / http: { endpoint, tools } / context: { provider, bucket, \u2026 } / remote: { baseUrl, skRef }; credentials go by authRef/skRef name, never inline"
+  "kind-specific config, e.g. mcp: { url, auth?, authRef?, oauthClient?: { clientId, clientSecretRef? } } / http: { endpoint, tools } / context: { provider, bucket, \u2026 } / remote: { baseUrl, skRef }; credentials go by SecretStore reference name, never inline"
 );
 var nodeInputVirtualizeSchema = external_exports.strictObject({
   prefix: external_exports.string().optional(),
@@ -16693,22 +16702,55 @@ var toolSpecSchema = external_exports.object({
   name: external_exports.string(),
   outputSchema: external_exports.unknown().optional()
 });
-var toolSearchItemSchema = external_exports.object({
+var toolSearchRelevanceSchema = external_exports.strictObject({
+  coverage: external_exports.number().min(0).max(1),
+  matchedTermCount: external_exports.number().int().nonnegative(),
+  rankingVersion: external_exports.literal("keyword-v2"),
+  totalTermCount: external_exports.number().int().positive()
+}).refine(
+  (value) => value.matchedTermCount <= value.totalTermCount && value.coverage === value.matchedTermCount / value.totalTermCount,
+  { message: "coverage must equal matchedTermCount / totalTermCount" }
+);
+var toolSearchSourceSchema = external_exports.strictObject({
+  path: external_exports.string()
+});
+var toolSearchSourceResultSchema = external_exports.strictObject({
+  path: external_exports.string(),
+  status: external_exports.enum([
+    "ok",
+    "unsupported",
+    "timed_out",
+    "unavailable",
+    "cycle",
+    "hop_limit",
+    "budget_exhausted",
+    "invalid_response"
+  ])
+});
+var toolSearchItemSchema = external_exports.strictObject({
   path: external_exports.string(),
+  relevance: toolSearchRelevanceSchema,
+  source: toolSearchSourceSchema.optional(),
   tool: toolSpecSchema
 });
-function pageSchema(itemSchema) {
-  return external_exports.object({
-    cursor: external_exports.string().optional(),
-    items: external_exports.array(itemSchema)
-  });
-}
-var toolSearchPageSchema = pageSchema(toolSearchItemSchema);
+var toolSearchPageSchema = external_exports.strictObject({
+  cursor: external_exports.string().optional(),
+  items: external_exports.array(toolSearchItemSchema),
+  partial: external_exports.boolean().optional(),
+  snapshot: external_exports.string().optional(),
+  sources: external_exports.array(toolSearchSourceResultSchema).optional()
+});
 var toolSearchRequestSchema = external_exports.strictObject({
   opts: external_exports.strictObject({
     cursor: external_exports.string().optional(),
+    detail: external_exports.enum(["compact", "full"]).optional(),
+    effects: external_exports.array(external_exports.enum(["read", "write", "destructive", "unknown"])).min(1).optional(),
+    federation: external_exports.enum(["local", "recursive"]).optional(),
     limit: external_exports.number().int().optional(),
-    mode: external_exports.enum(["keyword", "semantic"]).optional()
+    matching: external_exports.enum(["best", "all"]).optional(),
+    minCoverage: external_exports.number().gt(0).max(1).optional(),
+    mode: external_exports.enum(["keyword", "semantic"]).optional(),
+    pathPrefix: external_exports.string().optional()
   }).optional(),
   query: external_exports.string().trim().min(1)
 });
@@ -17669,7 +17711,7 @@ function deviceShellHelpModel(nodePath, shell = {}) {
         timeoutMs: { type: "number", description: "kill the command after this many ms" }
       }
     },
-    returns: "{ stdout, stderr, exitCode }",
+    returns: "{ stdout, stderr, exitCode, startedAt, completedAt, outcome, signal?, stdoutTruncated, stderrTruncated }",
     scope: "call",
     effect: "destructive",
     confirm: true
@@ -20000,6 +20042,13 @@ var positiveEnvKeys = [
   "TB_MAX_HOPS",
   "TB_REF_THRESHOLD_BYTES",
   "TB_REF_TTL_SEC",
+  "TB_SEARCH_FEDERATION_CONCURRENCY",
+  "TB_SEARCH_FEDERATION_DEADLINE_MS",
+  "TB_SEARCH_FEDERATION_MAX_RESPONSE_BYTES",
+  "TB_SEARCH_FEDERATION_MAX_SOURCES",
+  "TB_SEARCH_FEDERATION_MIN_CHILD_WORK_MS",
+  "TB_SEARCH_FEDERATION_RETURN_RESERVE_MS",
+  "TB_SEARCH_FEDERATION_SESSION_TTL_SEC",
   "TB_STORE_CALL_MAX_BYTES",
   "TB_STORE_CALL_MAX_OBJECT_BYTES",
   "TB_STORE_CALL_MAX_OBJECTS",
@@ -20047,6 +20096,15 @@ function parseRuntimeEnv(env) {
     remote: {
       allowInsecure: allowInsecureHttp,
       allowlist,
+      federatedSearch: {
+        ...parsed.TB_SEARCH_FEDERATION_CONCURRENCY === void 0 ? {} : { maxConcurrency: parsed.TB_SEARCH_FEDERATION_CONCURRENCY },
+        ...parsed.TB_SEARCH_FEDERATION_DEADLINE_MS === void 0 ? {} : { totalDeadlineMs: parsed.TB_SEARCH_FEDERATION_DEADLINE_MS },
+        ...parsed.TB_SEARCH_FEDERATION_MAX_RESPONSE_BYTES === void 0 ? {} : { maxResponseBodyBytes: parsed.TB_SEARCH_FEDERATION_MAX_RESPONSE_BYTES },
+        ...parsed.TB_SEARCH_FEDERATION_MAX_SOURCES === void 0 ? {} : { maxSources: parsed.TB_SEARCH_FEDERATION_MAX_SOURCES },
+        ...parsed.TB_SEARCH_FEDERATION_MIN_CHILD_WORK_MS === void 0 ? {} : { minChildWorkMs: parsed.TB_SEARCH_FEDERATION_MIN_CHILD_WORK_MS },
+        ...parsed.TB_SEARCH_FEDERATION_RETURN_RESERVE_MS === void 0 ? {} : { perHopReturnReserveMs: parsed.TB_SEARCH_FEDERATION_RETURN_RESERVE_MS },
+        ...parsed.TB_SEARCH_FEDERATION_SESSION_TTL_SEC === void 0 ? {} : { sessionTtlMs: parsed.TB_SEARCH_FEDERATION_SESSION_TTL_SEC * 1e3 }
+      },
       maxHops: parsed.TB_MAX_HOPS ?? DEFAULT_MAX_HOPS,
       ...parsed.TB_INSTANCE_ID ? { instanceId: parsed.TB_INSTANCE_ID } : {}
     }
@@ -20095,22 +20153,33 @@ var TOOL_SEARCH_SNAPSHOT_CHUNKS_MAX = Math.ceil(
 var TOOL_SEARCH_REBUILD_CHUNKS_MAX = TOOL_SEARCH_SOURCE_CHUNKS_MAX + TOOL_SEARCH_SNAPSHOT_CHUNKS_MAX;
 var TOOL_SEARCH_TERM_LIMIT = 32;
 var TOOL_SEARCH_UNIT_LIMIT = 98;
+var TOOL_SEARCH_LIMIT_DEFAULT = 10;
 var TOOL_SEARCH_LIKE_PATTERN_BYTES_MAX = 50;
 var TOOL_SEARCH_QUERY_MAX = 1024;
+var TOOL_SEARCH_RANKING_VERSION = "keyword-v2";
 var TOOL_SEARCH_CURSOR_OFFSET_MAX = 1e6;
+var TOOL_SEARCH_EFFECTS = [
+  "read",
+  "write",
+  "destructive",
+  "unknown"
+];
 function assertKeywordToolSearchMode(opts) {
   if (opts?.mode !== void 0 && opts.mode !== "keyword") {
     throw new TBError("invalid_argument", `SearchIndex \u4E0D\u652F\u6301 mode '${String(opts.mode)}'`);
   }
 }
 function normalizeToolSearchLimit(limit) {
-  if (limit === void 0) return LIST_LIMIT_DEFAULT;
+  if (limit === void 0) return TOOL_SEARCH_LIMIT_DEFAULT;
   if (typeof limit !== "number" || !Number.isFinite(limit) || !Number.isInteger(limit)) {
     throw new TBError("invalid_argument", "opts.limit \u5FC5\u987B\u662F\u6574\u6570");
   }
-  if (limit < 1) return LIST_LIMIT_DEFAULT;
+  if (limit < 1) return TOOL_SEARCH_LIMIT_DEFAULT;
   return Math.min(limit, LIST_LIMIT_MAX);
 }
+function searchUnitAllowsPath(unit) {
+  return !/^%[A-Za-z0-9]{1,2}%$/u.test(unit.pattern);
+}
 function stableDigest(value) {
   const bytes = new TextEncoder().encode(JSON.stringify(value));
   let hash2 = 0xcbf29ce484222325n;
@@ -20154,6 +20223,7 @@ function serializedRecord(path, tool, feedback) {
   }
   const record2 = {
     description: truncateUtf8(tool.description ?? "", TOOL_SEARCH_DESCRIPTION_BYTES_MAX),
+    effect: TOOL_SEARCH_EFFECTS.includes(tool.effect) ? tool.effect : "unknown",
     feedback,
     name: tool.name,
     path,
@@ -20164,17 +20234,70 @@ function serializedRecord(path, tool, feedback) {
 function jsonPayload(record2) {
   return {
     description: record2.description,
+    effect: record2.effect,
     feedback: record2.feedback,
     name: record2.name,
     path: record2.path
   };
 }
 function normalizeToolSearchPath(path) {
-  const canonical = normalizePath(path);
+  const canonical = canonicalizePath(path);
   const pathError = validatePath(canonical);
   if (pathError !== null) throw pathError;
   return canonical;
 }
+function normalizeToolSearchOptions(opts) {
+  let effects;
+  if (opts?.effects !== void 0) {
+    if (!Array.isArray(opts.effects) || opts.effects.length === 0) {
+      throw new TBError("invalid_argument", "opts.effects \u5FC5\u987B\u662F\u975E\u7A7A\u6570\u7EC4");
+    }
+    const selected = /* @__PURE__ */ new Set();
+    for (const effect of opts.effects) {
+      if (!TOOL_SEARCH_EFFECTS.includes(effect)) {
+        throw new TBError("invalid_argument", `opts.effects \u542B\u975E\u6CD5 effect '${String(effect)}'`);
+      }
+      selected.add(effect);
+    }
+    effects = TOOL_SEARCH_EFFECTS.filter((effect) => selected.has(effect));
+  }
+  const matching = opts?.matching ?? "best";
+  if (matching !== "best" && matching !== "all") {
+    throw new TBError("invalid_argument", `opts.matching '${String(matching)}' \u975E\u6CD5`);
+  }
+  let minCoverage = opts?.minCoverage;
+  if (minCoverage !== void 0 && (typeof minCoverage !== "number" || !Number.isFinite(minCoverage) || minCoverage <= 0 || minCoverage > 1)) {
+    throw new TBError("invalid_argument", "opts.minCoverage \u5FC5\u987B\u5927\u4E8E 0 \u4E14\u4E0D\u8D85\u8FC7 1");
+  }
+  if (matching === "all") {
+    if (minCoverage !== void 0 && minCoverage !== 1) {
+      throw new TBError("invalid_argument", "opts.matching='all' \u53EA\u5141\u8BB8 minCoverage=1");
+    }
+    minCoverage = 1;
+  }
+  let pathPrefix;
+  if (opts?.pathPrefix !== void 0) {
+    if (typeof opts.pathPrefix !== "string") {
+      throw new TBError("invalid_argument", "opts.pathPrefix \u5FC5\u987B\u662F\u8DEF\u5F84\u5B57\u7B26\u4E32");
+    }
+    pathPrefix = normalizeToolSearchPath(opts.pathPrefix);
+  }
+  return {
+    ...effects === void 0 ? {} : { effects },
+    matching,
+    ...minCoverage === void 0 ? {} : { minCoverage },
+    ...pathPrefix === void 0 ? {} : { pathPrefix }
+  };
+}
+function toolSearchOptionsFingerprint(opts) {
+  const normalized = normalizeToolSearchOptions(opts);
+  return stableDigest([
+    normalized.effects ?? null,
+    normalized.matching,
+    normalized.minCoverage ?? null,
+    normalized.pathPrefix ?? null
+  ]);
+}
 function serializeToolSearchSnapshot(path, tools, feedback = "") {
   const canonical = normalizeToolSearchPath(path);
   const names = /* @__PURE__ */ new Set();
@@ -20230,6 +20353,7 @@ function toolSearchSnapshotDigest(records) {
     record2.path,
     record2.name,
     record2.description,
+    record2.effect,
     record2.feedback,
     record2.toolDigest
   ]));
@@ -20279,54 +20403,93 @@ function scriptRuns(term) {
   }
   return runs;
 }
-function addSearchUnit(units, value, tier) {
+function addSearchUnit(units, value, tier, logicalTermId) {
   const pattern = likePattern(value);
   if (new TextEncoder().encode(pattern).length > TOOL_SEARCH_LIKE_PATTERN_BYTES_MAX) return false;
-  const existing = units.get(pattern);
+  const key = `${logicalTermId}\0${pattern}`;
+  const existing = units.get(key);
   if (existing === void 0 || tier > existing.tier) {
-    units.set(pattern, { pattern, tier });
+    units.set(key, { logicalTermId, pattern, tier });
   }
   return true;
 }
-function addChunkedSearchUnits(units, value, tier) {
+function addChunkedSearchUnits(units, value, tier, logicalTermId) {
   let chunk = "";
   for (const codePoint of value) {
     if (likePatternBytes(chunk + codePoint) <= TOOL_SEARCH_LIKE_PATTERN_BYTES_MAX) {
       chunk += codePoint;
       continue;
     }
-    if (chunk.length > 0) addSearchUnit(units, chunk, tier);
+    if (chunk.length > 0) addSearchUnit(units, chunk, tier, logicalTermId);
     chunk = codePoint;
   }
-  if (chunk.length > 0) addSearchUnit(units, chunk, tier);
+  if (chunk.length > 0) addSearchUnit(units, chunk, tier, logicalTermId);
 }
-function prepareToolSearchUnits(query) {
-  const terms = normalizeToolSearchQuery(query).split(/\s+/u);
-  if (terms.length > TOOL_SEARCH_TERM_LIMIT) {
+function prepareToolSearchQuery(query, unitLimit = TOOL_SEARCH_UNIT_LIMIT) {
+  if (!Number.isInteger(unitLimit) || unitLimit < 1 || unitLimit > TOOL_SEARCH_UNIT_LIMIT) {
+    throw new TBError("invalid_argument", "\u5DE5\u5177\u641C\u7D22 unit limit \u975E\u6CD5");
+  }
+  const rawTerms = normalizeToolSearchQuery(query).split(/\s+/u);
+  if (rawTerms.length > TOOL_SEARCH_TERM_LIMIT) {
     throw new TBError("invalid_argument", `\u641C\u7D22 query \u6700\u591A ${TOOL_SEARCH_TERM_LIMIT} \u4E2A terms`);
   }
+  const seenTerms = /* @__PURE__ */ new Set();
+  const terms = rawTerms.filter((term) => {
+    const key = term.replace(/[A-Z]/g, (char) => char.toLowerCase());
+    if (seenTerms.has(key)) return false;
+    seenTerms.add(key);
+    return true;
+  });
+  if (terms.length > unitLimit) {
+    throw new TBError("invalid_argument", "\u5DE5\u5177\u641C\u7D22 unit limit \u65E0\u6CD5\u8986\u76D6\u5168\u90E8 logical terms");
+  }
   const units = /* @__PURE__ */ new Map();
-  for (const term of terms) {
-    const wholeAdded = addSearchUnit(units, term, 4);
+  for (const [logicalTermId, term] of terms.entries()) {
+    const wholeAdded = addSearchUnit(units, term, 4, logicalTermId);
     const runs = scriptRuns(term);
     if (runs.length > 1) {
       for (const run of runs) {
         const value = run.codePoints.join("");
-        if (run.cjk) addSearchUnit(units, value, 2);
-        else addChunkedSearchUnits(units, value, 2);
+        if (run.cjk) addSearchUnit(units, value, 2, logicalTermId);
+        else addChunkedSearchUnits(units, value, 2, logicalTermId);
       }
     } else if (!wholeAdded && runs[0]?.cjk === false) {
-      addChunkedSearchUnits(units, term, 2);
+      addChunkedSearchUnits(units, term, 2, logicalTermId);
     }
     for (const run of runs) {
       if (!run.cjk) continue;
       for (let index = 0; index < run.codePoints.length - 1; index += 1) {
-        addSearchUnit(units, run.codePoints.slice(index, index + 2).join(""), 2);
+        addSearchUnit(
+          units,
+          run.codePoints.slice(index, index + 2).join(""),
+          2,
+          logicalTermId
+        );
+      }
+      for (const codePoint of run.codePoints) {
+        addSearchUnit(units, codePoint, 1, logicalTermId);
       }
-      for (const codePoint of run.codePoints) addSearchUnit(units, codePoint, 1);
     }
   }
-  return [...units.values()].sort((left, right) => right.tier - left.tier).slice(0, TOOL_SEARCH_UNIT_LIMIT);
+  const ordered = [...units.values()].sort((left, right) => right.tier - left.tier);
+  if (ordered.length <= unitLimit) {
+    return { totalTermCount: terms.length, units: ordered };
+  }
+  const selected = /* @__PURE__ */ new Set();
+  const represented = /* @__PURE__ */ new Set();
+  for (const unit of ordered) {
+    if (represented.has(unit.logicalTermId)) continue;
+    represented.add(unit.logicalTermId);
+    selected.add(unit);
+  }
+  for (const unit of ordered) {
+    if (selected.size >= unitLimit) break;
+    selected.add(unit);
+  }
+  return {
+    totalTermCount: terms.length,
+    units: ordered.filter((unit) => selected.has(unit))
+  };
 }
 function cursorBase64UrlDecode(value) {
   if (value.length === 0 || value.length > 4096) {
@@ -20353,13 +20516,15 @@ async function cursorCryptoKey(secret) {
     ["encrypt", "decrypt"]
   );
 }
-async function encodeToolSearchCursor(query, mode, revision, offset, secret) {
+async function sealToolSearchCursor(query, mode, revision, offset, secret, optionsFingerprint) {
   const payload = {
+    f: optionsFingerprint,
     h: stableDigest(normalizeToolSearchQuery(query)),
+    k: TOOL_SEARCH_RANKING_VERSION,
     m: mode,
     o: offset,
     r: revision,
-    v: 1
+    v: 2
   };
   const iv = crypto.getRandomValues(new Uint8Array(12));
   const ciphertext = new Uint8Array(await crypto.subtle.encrypt(
@@ -20372,7 +20537,17 @@ async function encodeToolSearchCursor(query, mode, revision, offset, secret) {
   sealed.set(ciphertext, iv.length);
   return base64urlEncode(sealed);
 }
-async function decodeToolSearchCursor(cursor, query, mode, revision, secret) {
+async function encodeToolSearchCursor(query, mode, revision, offset, secret, opts) {
+  return await sealToolSearchCursor(
+    query,
+    mode,
+    revision,
+    offset,
+    secret,
+    toolSearchOptionsFingerprint(opts)
+  );
+}
+async function decodeToolSearchCursor(cursor, query, mode, revision, secret, opts) {
   if (cursor === void 0) return 0;
   let value;
   try {
@@ -20393,115 +20568,199 @@ async function decodeToolSearchCursor(cursor, query, mode, revision, secret) {
   }
   const payload = value;
   const keys = Object.keys(payload).sort().join(",");
-  if (keys !== "h,m,o,r,v" || payload.v !== 1 || payload.h !== stableDigest(normalizeToolSearchQuery(query)) || payload.m !== mode || payload.r !== revision || !Number.isSafeInteger(payload.o) || (payload.o ?? -1) < 0 || (payload.o ?? 0) > TOOL_SEARCH_CURSOR_OFFSET_MAX) {
+  if (keys !== "f,h,k,m,o,r,v" || payload.v !== 2 || payload.k !== TOOL_SEARCH_RANKING_VERSION || payload.f !== toolSearchOptionsFingerprint(opts) || payload.h !== stableDigest(normalizeToolSearchQuery(query)) || payload.m !== mode || payload.r !== revision || !Number.isSafeInteger(payload.o) || (payload.o ?? -1) < 0 || (payload.o ?? 0) > TOOL_SEARCH_CURSOR_OFFSET_MAX) {
     throw new TBError("invalid_argument", "\u641C\u7D22 cursor \u5DF2\u5931\u6548\u6216\u4E0E\u5F53\u524D\u67E5\u8BE2\u4E0D\u5339\u914D");
   }
   return payload.o ?? 0;
 }
+async function encodeToolSearchCursorForCandidate(query, mode, candidate, secret) {
+  const fingerprint = candidate.searchOptionsFingerprint ?? toolSearchOptionsFingerprint();
+  if (!/^[a-f0-9]{16}$/.test(fingerprint)) {
+    throw new TBError("invalid_argument", "\u5DE5\u5177\u641C\u7D22\u5019\u9009\u7684 options fingerprint \u975E\u6CD5");
+  }
+  return await sealToolSearchCursor(
+    query,
+    mode,
+    candidate.revision,
+    candidate.resumeOffset,
+    secret,
+    fingerprint
+  );
+}
 
 // ../core/src/search/sqlSearchIndex.ts
 var TOOL_SEARCH_SCHEMA_STATEMENTS = [
-  `CREATE TABLE IF NOT EXISTS tb_search_tools_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_tools_v5 (
     id INTEGER PRIMARY KEY,
     path TEXT NOT NULL,
     name TEXT NOT NULL,
     description TEXT NOT NULL DEFAULT '',
+    effect TEXT NOT NULL CHECK (effect IN ('read', 'write', 'destructive', 'unknown')),
     feedback TEXT NOT NULL DEFAULT '',
     UNIQUE(path, name)
   )`,
-  `CREATE TABLE IF NOT EXISTS tb_search_meta_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_meta_v5 (
     singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
     revision INTEGER NOT NULL DEFAULT 0,
     seeded INTEGER NOT NULL DEFAULT 0,
     cursor_secret TEXT NOT NULL
   )`,
-  `INSERT OR IGNORE INTO tb_search_meta_v4(
+  `INSERT OR IGNORE INTO tb_search_meta_v5(
     singleton, revision, seeded, cursor_secret
   ) VALUES (1, 0, 0, lower(hex(randomblob(32))))`,
-  `CREATE TABLE IF NOT EXISTS tb_search_snapshots_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_snapshots_v5 (
     path TEXT PRIMARY KEY,
     digest TEXT NOT NULL
   )`,
-  `CREATE TRIGGER IF NOT EXISTS tb_search_snapshots_v4_capacity
-  BEFORE INSERT ON tb_search_snapshots_v4
+  `CREATE TRIGGER IF NOT EXISTS tb_search_snapshots_v5_capacity
+  BEFORE INSERT ON tb_search_snapshots_v5
   WHEN NOT EXISTS (
-    SELECT 1 FROM tb_search_snapshots_v4 WHERE path = new.path
-  ) AND (SELECT COUNT(*) FROM tb_search_snapshots_v4) >= ${TOOL_SEARCH_AUDIT_NODE_LIMIT}
+    SELECT 1 FROM tb_search_snapshots_v5 WHERE path = new.path
+  ) AND (SELECT COUNT(*) FROM tb_search_snapshots_v5) >= ${TOOL_SEARCH_AUDIT_NODE_LIMIT}
   BEGIN
     SELECT RAISE(ABORT, 'tb_search_path_capacity');
   END`
 ];
 var TOOL_SEARCH_CAPACITY_MARKER = "tb_search_path_capacity";
 var TOOL_SEARCH_INSERT_SQL = `
-INSERT INTO tb_search_tools_v4 (path, name, description, feedback)
-VALUES (?, ?, ?, ?)
+INSERT INTO tb_search_tools_v5 (path, name, description, effect, feedback)
+VALUES (?, ?, ?, ?, ?)
 `;
-var TOOL_SEARCH_INSERT_SNAPSHOT_SQL = "INSERT INTO tb_search_snapshots_v4(path, digest) VALUES (?, ?)";
-var META_SQL = "SELECT revision, seeded, cursor_secret FROM tb_search_meta_v4 WHERE singleton = 1";
-var SNAPSHOT_DIGESTS_SQL = "SELECT path, digest FROM tb_search_snapshots_v4 ORDER BY path";
+var TOOL_SEARCH_INSERT_SNAPSHOT_SQL = "INSERT INTO tb_search_snapshots_v5(path, digest) VALUES (?, ?)";
+var META_SQL = "SELECT revision, seeded, cursor_secret FROM tb_search_meta_v5 WHERE singleton = 1";
+var SNAPSHOT_DIGESTS_SQL = "SELECT path, digest FROM tb_search_snapshots_v5 ORDER BY path";
 var PATH_STATE_SQL = `
 SELECT snapshots.digest,
-  EXISTS(SELECT 1 FROM tb_search_tools_v4 WHERE path = ?) AS has_tools,
-  (SELECT COUNT(*) FROM tb_search_snapshots_v4) AS path_count
+  EXISTS(SELECT 1 FROM tb_search_tools_v5 WHERE path = ?) AS has_tools,
+  (SELECT COUNT(*) FROM tb_search_snapshots_v5) AS path_count
 FROM (SELECT 1) AS singleton
-LEFT JOIN tb_search_snapshots_v4 AS snapshots ON snapshots.path = ?
+LEFT JOIN tb_search_snapshots_v5 AS snapshots ON snapshots.path = ?
 `;
-var PRESENT_SQL = "SELECT 1 AS present FROM tb_search_tools_v4 WHERE path = ? LIMIT 1";
+var PRESENT_SQL = "SELECT 1 AS present FROM tb_search_tools_v5 WHERE path = ? LIMIT 1";
 var PRESENT_PREFIX_SQL = `
-SELECT 1 AS present FROM tb_search_tools_v4
+SELECT 1 AS present FROM tb_search_tools_v5
 WHERE path = ? OR substr(path, 1, length(?) + 1) = ? || '/'
 LIMIT 1
 `;
-var DELETE_TOOLS_SQL = "DELETE FROM tb_search_tools_v4 WHERE path = ?";
-var DELETE_SNAPSHOT_SQL = "DELETE FROM tb_search_snapshots_v4 WHERE path = ?";
+var DELETE_TOOLS_SQL = "DELETE FROM tb_search_tools_v5 WHERE path = ?";
+var DELETE_SNAPSHOT_SQL = "DELETE FROM tb_search_snapshots_v5 WHERE path = ?";
 var DELETE_TOOLS_PREFIX_SQL = `
-DELETE FROM tb_search_tools_v4
+DELETE FROM tb_search_tools_v5
 WHERE path = ? OR substr(path, 1, length(?) + 1) = ? || '/'
 `;
 var DELETE_SNAPSHOT_PREFIX_SQL = `
-DELETE FROM tb_search_snapshots_v4
+DELETE FROM tb_search_snapshots_v5
 WHERE path = ? OR substr(path, 1, length(?) + 1) = ? || '/'
 `;
-var DELETE_ALL_TOOLS_SQL = "DELETE FROM tb_search_tools_v4";
-var DELETE_ALL_SNAPSHOTS_SQL = "DELETE FROM tb_search_snapshots_v4";
-var BUMP_REVISION_SQL = "UPDATE tb_search_meta_v4 SET revision = revision + 1 WHERE singleton = 1";
-var COMPLETE_REBUILD_SQL = "UPDATE tb_search_meta_v4 SET seeded = 1, revision = revision + 1 WHERE singleton = 1";
-function toolSearchCandidateStatement(units, limit, offset, syntax) {
-  const values = units.map((unit, index) => `(${syntax.placeholder(index + 1)}, ${unit.tier})`).join(", ");
-  const limitParam = syntax.placeholder(units.length + 1);
-  const offsetParam = syntax.placeholder(units.length + 2);
+var DELETE_ALL_TOOLS_SQL = "DELETE FROM tb_search_tools_v5";
+var DELETE_ALL_SNAPSHOTS_SQL = "DELETE FROM tb_search_snapshots_v5";
+var BUMP_REVISION_SQL = "UPDATE tb_search_meta_v5 SET revision = revision + 1 WHERE singleton = 1";
+var COMPLETE_REBUILD_SQL = "UPDATE tb_search_meta_v5 SET seeded = 1, revision = revision + 1 WHERE singleton = 1";
+function toolSearchEffectSql(effect) {
+  switch (effect) {
+    case "read":
+      return "'read'";
+    case "write":
+      return "'write'";
+    case "destructive":
+      return "'destructive'";
+    case "unknown":
+      return "'unknown'";
+    default:
+      throw new TBError("invalid_argument", `\u5DE5\u5177\u641C\u7D22 effect '${String(effect)}' \u975E\u6CD5`);
+  }
+}
+function toolSearchCandidateStatement(units, totalTermCount, limit, offset, constraints, syntax) {
+  if (!Number.isInteger(totalTermCount) || totalTermCount < 1 || units.some((unit) => !Number.isInteger(unit.logicalTermId) || unit.logicalTermId < 0 || unit.logicalTermId >= totalTermCount)) {
+    throw new TBError("invalid_argument", "\u5DE5\u5177\u641C\u7D22 logical term \u8BA1\u5212\u975E\u6CD5");
+  }
+  const values = units.map((unit, index) => `(${unit.logicalTermId}, ${syntax.placeholder(index + 1)}, ${unit.tier}, ${searchUnitAllowsPath(unit) ? 1 : 0})`).join(", ");
+  const hasPrefix = constraints.pathPrefix !== void 0;
+  const prefixParam = hasPrefix ? syntax.placeholder(units.length + 1) : void 0;
+  const trailingStart = units.length + (hasPrefix ? 2 : 1);
+  const limitParam = syntax.placeholder(trailingStart);
+  const offsetParam = syntax.placeholder(trailingStart + 1);
+  const requiredMatchedTerms = constraints.minCoverage === void 0 ? 1 : Math.ceil(constraints.minCoverage * totalTermCount);
   const like = syntax.likeOperator;
+  const effectLiterals = constraints.effects?.map(toolSearchEffectSql);
+  const prefixCte = hasPrefix ? `, prefix_filter(value) AS (VALUES (${prefixParam}))` : "";
+  const filterPredicates = [
+    ...hasPrefix ? [
+      `(
+            tools.path = prefix_filter.value
+            OR substr(tools.path, 1, length(prefix_filter.value) + 1)
+              = prefix_filter.value || '/'
+          )`
+    ] : [],
+    ...effectLiterals === void 0 ? [] : [`tools.effect IN (${effectLiterals.join(", ")})`]
+  ];
+  const filteredToolsCte = filterPredicates.length > 0 ? `,
+      filtered_tools AS (
+        SELECT tools.*
+        FROM tb_search_tools_v5 AS tools
+        ${hasPrefix ? "CROSS JOIN prefix_filter" : ""}
+        WHERE ${filterPredicates.join("\n          AND ")}
+      )` : "";
+  const candidateTable = filterPredicates.length > 0 ? "filtered_tools" : "tb_search_tools_v5";
   return {
-    params: [...units.map((unit) => unit.pattern), limit + 1, offset],
+    params: [
+      ...units.map((unit) => unit.pattern),
+      ...hasPrefix ? [constraints.pathPrefix] : [],
+      limit + 1,
+      offset
+    ],
     sql: `
-      WITH units(pattern, tier) AS (VALUES ${values})
-      SELECT * FROM (
-        SELECT tools.id, tools.path, tools.name,
-          (
-            SELECT COALESCE(SUM(units.tier * CASE
-              WHEN tools.name ${like} units.pattern ESCAPE '!' THEN 10
-              WHEN tools.path ${like} units.pattern ESCAPE '!' THEN 5
-              WHEN tools.description ${like} units.pattern ESCAPE '!' THEN 3
-              WHEN tools.feedback ${like} units.pattern ESCAPE '!' THEN 1
-              ELSE 0
-            END), 0)
-            FROM units
-          ) AS score
-        FROM tb_search_tools_v4 AS tools
-      ) AS scored_tools
-      WHERE score > 0
-      ORDER BY score DESC, path, name
+      WITH units(logical_term_id, pattern, tier, path_allowed) AS (VALUES ${values})${prefixCte}${filteredToolsCte},
+      unit_matches AS (
+        SELECT tools.id, tools.path, tools.name, units.logical_term_id,
+          units.tier * CASE
+            WHEN tools.name ${like} units.pattern ESCAPE '!' THEN 10
+            WHEN units.path_allowed = 1
+              AND tools.path ${like} units.pattern ESCAPE '!' THEN 5
+            WHEN tools.description ${like} units.pattern ESCAPE '!' THEN 3
+            WHEN tools.feedback ${like} units.pattern ESCAPE '!' THEN 1
+            ELSE 0
+          END AS unit_score
+        FROM ${candidateTable} AS tools
+        CROSS JOIN units
+      ),
+      term_matches AS (
+        SELECT id, path, name, logical_term_id, MAX(unit_score) AS term_score
+        FROM unit_matches
+        WHERE unit_score > 0
+        GROUP BY id, path, name, logical_term_id
+      ),
+      scored_tools AS (
+        SELECT id, path, name,
+          CAST(COUNT(*) AS INTEGER) AS matched_term_count,
+          CAST(SUM(term_score) AS INTEGER) AS score
+        FROM term_matches
+        GROUP BY id, path, name
+      )
+      SELECT id, path, name, matched_term_count, ${totalTermCount} AS total_term_count
+      FROM scored_tools
+      WHERE matched_term_count >= ${requiredMatchedTerms}
+      ORDER BY matched_term_count DESC, score DESC, path, name
       LIMIT ${limitParam} OFFSET ${offsetParam}
     `
   };
 }
 var sqliteSearchDialect = {
-  candidateStatement: (query, limit, offset) => toolSearchCandidateStatement(
-    prepareToolSearchUnits(query),
-    limit,
-    offset,
-    { likeOperator: "LIKE", placeholder: () => "?" }
-  ),
+  candidateStatement: (query, limit, offset, rawConstraints) => {
+    const constraints = normalizeToolSearchOptions(rawConstraints);
+    const prepared = prepareToolSearchQuery(
+      query,
+      constraints.pathPrefix === void 0 ? TOOL_SEARCH_UNIT_LIMIT : TOOL_SEARCH_UNIT_LIMIT - 1
+    );
+    return toolSearchCandidateStatement(
+      prepared.units,
+      prepared.totalTermCount,
+      limit,
+      offset,
+      constraints,
+      { likeOperator: "LIKE", placeholder: () => "?" }
+    );
+  },
   schemaStatements: TOOL_SEARCH_SCHEMA_STATEMENTS,
   statements: {
     bumpRevision: BUMP_REVISION_SQL,
@@ -20555,6 +20814,10 @@ var SqlSearchIndex = class {
     await this.driver.ensureSchema();
     return (await this.meta()).seeded === 1;
   }
+  async revision() {
+    await this.driver.ensureSchema();
+    return (await this.meta()).revision;
+  }
   async replace(path, tools, opts = {}) {
     const canonical = normalizeToolSearchPath(path);
     const records = serializeToolSearchSnapshot(canonical, tools, opts.feedback ?? "");
@@ -20633,6 +20896,8 @@ var SqlSearchIndex = class {
   async search(query, opts) {
     assertKeywordToolSearchMode(opts);
     const normalized = normalizeToolSearchQuery(query);
+    const constraints = normalizeToolSearchOptions(opts);
+    const optionsFingerprint = toolSearchOptionsFingerprint(constraints);
     const mode = opts?.mode ?? "keyword";
     await this.driver.ensureSchema();
     const meta3 = await this.meta();
@@ -20642,20 +20907,28 @@ var SqlSearchIndex = class {
       normalized,
       mode,
       revision,
-      meta3.cursor_secret
+      meta3.cursor_secret,
+      constraints
     );
     const limit = Math.min(normalizeToolSearchLimit(opts?.limit), TOOL_SEARCH_BATCH_LIMIT);
     const rows = await this.driver.all(
-      this.dialect.candidateStatement(normalized, limit, offset)
+      this.dialect.candidateStatement(normalized, limit, offset, constraints)
     );
-    const hasMore = rows.length > limit;
-    const page = hasMore ? rows.slice(0, limit) : rows;
+    const firstBand = rows[0]?.matched_term_count;
+    const bandEnd = constraints.matching === "best" && firstBand !== void 0 ? rows.findIndex((row) => row.matched_term_count !== firstBand) : -1;
+    const pageLength = bandEnd >= 0 ? Math.min(limit, bandEnd) : Math.min(limit, rows.length);
+    const page = rows.slice(0, pageLength);
+    const hasMore = rows.length > page.length;
     const items = page.map((row, index) => ({
+      coverage: row.matched_term_count / row.total_term_count,
+      matchedTermCount: row.matched_term_count,
       name: row.name,
       path: row.path,
       ref: String(row.id),
       resumeOffset: offset + index + 1,
-      revision
+      revision,
+      searchOptionsFingerprint: optionsFingerprint,
+      totalTermCount: row.total_term_count
     }));
     const last = items[items.length - 1];
     return hasMore && last !== void 0 ? {
@@ -20665,7 +20938,8 @@ var SqlSearchIndex = class {
         mode,
         revision,
         last.resumeOffset,
-        meta3.cursor_secret
+        meta3.cursor_secret,
+        constraints
       )
     } : { items };
   }
@@ -20675,11 +20949,10 @@ var SqlSearchIndex = class {
     if (candidate.revision !== meta3.revision) {
       throw new TBError("invalid_argument", "\u641C\u7D22 cursor \u5DF2\u5931\u6548");
     }
-    return await encodeToolSearchCursor(
+    return await encodeToolSearchCursorForCandidate(
       query,
       mode,
-      meta3.revision,
-      candidate.resumeOffset,
+      candidate,
       meta3.cursor_secret
     );
   }
@@ -20687,11 +20960,12 @@ var SqlSearchIndex = class {
 
 // ../core/src/search/pgSearchDialect.ts
 var PG_SEARCH_SCHEMA_STATEMENTS = [
-  `CREATE TABLE IF NOT EXISTS tb_search_tools_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_tools_v5 (
     id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
     path text NOT NULL,
     name text NOT NULL,
     description text NOT NULL DEFAULT '',
+    effect text NOT NULL CHECK (effect IN ('read', 'write', 'destructive', 'unknown')),
     feedback text NOT NULL DEFAULT '',
     UNIQUE(path, name)
   )`,
@@ -20699,7 +20973,7 @@ var PG_SEARCH_SCHEMA_STATEMENTS = [
   // 样本上对单 unit 多列 ILIKE 一律选 Seq Scan；GIN 让写入和体积显著增加却未改善
   // 检索。4000 行只是代表样本，不是严格工具行上限（节点内还受 20KB JSON 约束）；
   // 查询单元数或容量边界变化时，应重跑 searchBench 并重新评估查询形状与索引。
-  `CREATE TABLE IF NOT EXISTS tb_search_meta_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_meta_v5 (
     singleton integer PRIMARY KEY CHECK (singleton = 1),
     revision bigint NOT NULL DEFAULT 0,
     seeded integer NOT NULL DEFAULT 0,
@@ -20707,32 +20981,32 @@ var PG_SEARCH_SCHEMA_STATEMENTS = [
   )`,
   // cursor_secret 需 64 hex(32 字节)。两个内置 gen_random_uuid() 去连字符正好 64
   // hex,避免依赖 pgcrypto 的 gen_random_bytes(自托管 PG 未必预装 pgcrypto)。
-  `INSERT INTO tb_search_meta_v4(singleton, revision, seeded, cursor_secret)
+  `INSERT INTO tb_search_meta_v5(singleton, revision, seeded, cursor_secret)
     VALUES (
       1, 0, 0,
       replace(gen_random_uuid()::text, '-', '') || replace(gen_random_uuid()::text, '-', '')
     )
     ON CONFLICT (singleton) DO NOTHING`,
-  `CREATE TABLE IF NOT EXISTS tb_search_snapshots_v4 (
+  `CREATE TABLE IF NOT EXISTS tb_search_snapshots_v5 (
     path text PRIMARY KEY,
     digest text NOT NULL
   )`,
-  `CREATE OR REPLACE FUNCTION tb_search_snapshots_v4_capacity()
+  `CREATE OR REPLACE FUNCTION tb_search_snapshots_v5_capacity()
     RETURNS trigger AS $$
     BEGIN
-      IF (SELECT COUNT(*) FROM tb_search_snapshots_v4) >= ${TOOL_SEARCH_AUDIT_NODE_LIMIT} THEN
+      IF (SELECT COUNT(*) FROM tb_search_snapshots_v5) >= ${TOOL_SEARCH_AUDIT_NODE_LIMIT} THEN
         RAISE EXCEPTION '${TOOL_SEARCH_CAPACITY_MARKER}';
       END IF;
       RETURN NEW;
     END;
     $$ LANGUAGE plpgsql`,
-  `DROP TRIGGER IF EXISTS tb_search_snapshots_v4_capacity_trg ON tb_search_snapshots_v4`,
-  `CREATE TRIGGER tb_search_snapshots_v4_capacity_trg
-    BEFORE INSERT ON tb_search_snapshots_v4
-    FOR EACH ROW EXECUTE FUNCTION tb_search_snapshots_v4_capacity()`
+  `DROP TRIGGER IF EXISTS tb_search_snapshots_v5_capacity_trg ON tb_search_snapshots_v5`,
+  `CREATE TRIGGER tb_search_snapshots_v5_capacity_trg
+    BEFORE INSERT ON tb_search_snapshots_v5
+    FOR EACH ROW EXECUTE FUNCTION tb_search_snapshots_v5_capacity()`
 ];
 var PG_SEARCH_WRITE_LOCK_KEY = 2069799624;
-var PG_SEARCH_INSERT_SNAPSHOT_SQL = "INSERT INTO tb_search_snapshots_v4(path, digest) VALUES ($1, $2)";
+var PG_SEARCH_INSERT_SNAPSHOT_SQL = "INSERT INTO tb_search_snapshots_v5(path, digest) VALUES ($1, $2)";
 function pgBulkInsertSql(table, columns, rows) {
   const tuples = [];
   for (let r = 0; r < rows; r++) {
@@ -20741,50 +21015,65 @@ function pgBulkInsertSql(table, columns, rows) {
   }
   return `INSERT INTO ${table} (${columns.join(", ")}) VALUES ${tuples.join(", ")}`;
 }
-var PG_SEARCH_TOOLS_TABLE = "tb_search_tools_v4";
-var PG_SEARCH_TOOLS_COLUMNS = ["path", "name", "description", "feedback"];
-var PG_SEARCH_SNAPSHOTS_TABLE = "tb_search_snapshots_v4";
+var PG_SEARCH_TOOLS_TABLE = "tb_search_tools_v5";
+var PG_SEARCH_TOOLS_COLUMNS = [
+  "path",
+  "name",
+  "description",
+  "effect",
+  "feedback"
+];
+var PG_SEARCH_SNAPSHOTS_TABLE = "tb_search_snapshots_v5";
 var PG_SEARCH_SNAPSHOTS_COLUMNS = ["path", "digest"];
 var PG_SEARCH_INSERT_ROWS_MAX = 1e3;
 var META_SQL2 = `
 SELECT revision::int AS revision, seeded::int AS seeded, cursor_secret
-FROM tb_search_meta_v4 WHERE singleton = 1
+FROM tb_search_meta_v5 WHERE singleton = 1
 `;
-var SNAPSHOT_DIGESTS_SQL2 = "SELECT path, digest FROM tb_search_snapshots_v4 ORDER BY path";
+var SNAPSHOT_DIGESTS_SQL2 = "SELECT path, digest FROM tb_search_snapshots_v5 ORDER BY path";
 var PATH_STATE_SQL2 = `
 SELECT snapshots.digest,
-  EXISTS(SELECT 1 FROM tb_search_tools_v4 WHERE path = $1)::int AS has_tools,
-  (SELECT COUNT(*) FROM tb_search_snapshots_v4)::int AS path_count
+  EXISTS(SELECT 1 FROM tb_search_tools_v5 WHERE path = $1)::int AS has_tools,
+  (SELECT COUNT(*) FROM tb_search_snapshots_v5)::int AS path_count
 FROM (SELECT 1) AS singleton
-LEFT JOIN tb_search_snapshots_v4 AS snapshots ON snapshots.path = $2
+LEFT JOIN tb_search_snapshots_v5 AS snapshots ON snapshots.path = $2
 `;
-var PRESENT_SQL2 = "SELECT 1 AS present FROM tb_search_tools_v4 WHERE path = $1 LIMIT 1";
+var PRESENT_SQL2 = "SELECT 1 AS present FROM tb_search_tools_v5 WHERE path = $1 LIMIT 1";
 var PRESENT_PREFIX_SQL2 = `
-SELECT 1 AS present FROM tb_search_tools_v4
+SELECT 1 AS present FROM tb_search_tools_v5
 WHERE path = $1 OR substr(path, 1, length($2) + 1) = $3 || '/'
 LIMIT 1
 `;
-var DELETE_TOOLS_SQL2 = "DELETE FROM tb_search_tools_v4 WHERE path = $1";
-var DELETE_SNAPSHOT_SQL2 = "DELETE FROM tb_search_snapshots_v4 WHERE path = $1";
+var DELETE_TOOLS_SQL2 = "DELETE FROM tb_search_tools_v5 WHERE path = $1";
+var DELETE_SNAPSHOT_SQL2 = "DELETE FROM tb_search_snapshots_v5 WHERE path = $1";
 var DELETE_TOOLS_PREFIX_SQL2 = `
-DELETE FROM tb_search_tools_v4
+DELETE FROM tb_search_tools_v5
 WHERE path = $1 OR substr(path, 1, length($2) + 1) = $3 || '/'
 `;
 var DELETE_SNAPSHOT_PREFIX_SQL2 = `
-DELETE FROM tb_search_snapshots_v4
+DELETE FROM tb_search_snapshots_v5
 WHERE path = $1 OR substr(path, 1, length($2) + 1) = $3 || '/'
 `;
-var DELETE_ALL_TOOLS_SQL2 = "DELETE FROM tb_search_tools_v4";
-var DELETE_ALL_SNAPSHOTS_SQL2 = "DELETE FROM tb_search_snapshots_v4";
-var BUMP_REVISION_SQL2 = "UPDATE tb_search_meta_v4 SET revision = revision + 1 WHERE singleton = 1";
-var COMPLETE_REBUILD_SQL2 = "UPDATE tb_search_meta_v4 SET seeded = 1, revision = revision + 1 WHERE singleton = 1";
+var DELETE_ALL_TOOLS_SQL2 = "DELETE FROM tb_search_tools_v5";
+var DELETE_ALL_SNAPSHOTS_SQL2 = "DELETE FROM tb_search_snapshots_v5";
+var BUMP_REVISION_SQL2 = "UPDATE tb_search_meta_v5 SET revision = revision + 1 WHERE singleton = 1";
+var COMPLETE_REBUILD_SQL2 = "UPDATE tb_search_meta_v5 SET seeded = 1, revision = revision + 1 WHERE singleton = 1";
 var pgSearchDialect = {
-  candidateStatement: (query, limit, offset) => toolSearchCandidateStatement(
-    prepareToolSearchUnits(query),
-    limit,
-    offset,
-    { likeOperator: "ILIKE", placeholder: (index) => `$${index}` }
-  ),
+  candidateStatement: (query, limit, offset, rawConstraints) => {
+    const constraints = normalizeToolSearchOptions(rawConstraints);
+    const prepared = prepareToolSearchQuery(
+      query,
+      constraints.pathPrefix === void 0 ? TOOL_SEARCH_UNIT_LIMIT : TOOL_SEARCH_UNIT_LIMIT - 1
+    );
+    return toolSearchCandidateStatement(
+      prepared.units,
+      prepared.totalTermCount,
+      limit,
+      offset,
+      constraints,
+      { likeOperator: "ILIKE", placeholder: (index) => `$${index}` }
+    );
+  },
   schemaStatements: PG_SEARCH_SCHEMA_STATEMENTS,
   statements: {
     bumpRevision: BUMP_REVISION_SQL2,
@@ -21494,7 +21783,15 @@ function virtualizeTools(v, upstream) {
   const hidden = new Set(v?.hide ?? []);
   for (const tool of upstream) {
     if (hidden.has(tool.name)) continue;
-    const name = v ? virtualName(v, tool.name) : tool.name;
+    const projectedName = v ? virtualName(v, tool.name) : tool.name;
+    const name = canonicalizeSegment(projectedName);
+    const previous = reverse.get(name);
+    if (previous !== void 0) {
+      throw new TBError(
+        "invalid_argument",
+        `\u5DE5\u5177\u540D '${previous}' \u4E0E '${tool.name}' \u89C4\u8303\u5316\u540E\u51B2\u7A81:'${name}',\u8BF7\u663E\u5F0F rename`
+      );
+    }
     const description = v?.describe?.[tool.name] ?? tool.description;
     exposed.push({ ...tool, name, description });
     reverse.set(name, tool.name);
@@ -22252,6 +22549,9 @@ export {
   nodeInputSchema,
   helpJsonSchema,
   treeJsonSchema,
+  toolSearchRelevanceSchema,
+  toolSearchSourceSchema,
+  toolSearchSourceResultSchema,
   toolSearchPageSchema,
   toolSearchRequestSchema,
   registryNodeSchema,
@@ -22320,11 +22620,15 @@ export {
   TOOL_SEARCH_BATCH_LIMIT,
   TOOL_SEARCH_WORK_LIMIT,
   TOOL_SEARCH_AUDIT_NODE_LIMIT,
+  TOOL_SEARCH_DESCRIPTION_BYTES_MAX,
   TOOL_SEARCH_PAGE_BYTES,
+  TOOL_SEARCH_RANKING_VERSION,
   normalizeToolSearchLimit,
   normalizeToolSearchPath,
+  normalizeToolSearchOptions,
   serializeToolSearchSnapshot,
   toolSearchSnapshotDigest,
+  prepareToolSearchQuery,
   TOOL_SEARCH_SCHEMA_STATEMENTS,
   TOOL_SEARCH_INSERT_SQL,
   TOOL_SEARCH_INSERT_SNAPSHOT_SQL,