@chatpanel/pii 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/pii",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "The canonical ChatPanel privacy engine — reversible PII redaction + pseudonymization with local entity detection. Pure, dependency-free ESM shared by the ChatPanel extension, gateway, and bridge.",
   "type": "module",
   "main": "index.js",

package/tool-harness.js

@@ -41,6 +41,30 @@ export function restoreToolArgs(value, vault) {
   return value;
 }
 
+// System-prompt note that tells the model how to behave around placeholders when
+// tools are armed. WITHOUT this, privacy-aware models (Codex, Claude) recognize a
+// [[LOCATION_1]] token as redacted and REFUSE to use it for a lookup ("I can't see
+// your real city") — the opposite of what we want. Weak models call the tool blindly
+// and it works (the harness restores the real value), so the note levels them up.
+export function placeholderToolNote({ toolData = 'real' } = {}) {
+  const intro =
+    'PRIVACY PLACEHOLDERS: some values in this conversation are tokens like [[PERSON_1]], '
+    + '[[LOCATION_1]], [[ORG_1]] that stand in for the user\'s real private data. ';
+  const remote = toolData === 'redactRemote'
+    ? 'When you call a LOCAL tool the placeholder is automatically replaced with the real '
+      + 'value before the tool runs; REMOTE (MCP) tools deliberately receive the placeholder '
+      + 'to keep private data off third-party servers. '
+    : 'When you call ANY tool, these placeholders are AUTOMATICALLY replaced with the real '
+      + 'values before the tool executes — the tool receives the TRUE value and returns correct '
+      + 'results. ';
+  const rules =
+    'So: CALL THE TOOL using the placeholder exactly as written, as if it were the real value. '
+    + 'Do NOT say you cannot see the real value, do NOT ask the user to re-type it, and do NOT '
+    + 'refuse on privacy grounds — the lookup will work. The real values are restored in your '
+    + 'final answer automatically, so write your answer using the placeholders too.';
+  return intro + remote + rules;
+}
+
 export function makeToolHarness({ vault = null, toolData = 'real', redactOpts = null, redactResults = true } = {}) {
   const on = !!vault;                       // privacy enabled for this turn?
   const redactRemote = toolData === 'redactRemote';

package/tool-rank.js

@@ -19,6 +19,11 @@ const STOP = new Set([
 const defName = (s) => (s && s.name) || '';
 const defDesc = (s) => (s && s.description) || '';
 
+// Names of GENERAL entry-point tools — preferred when a query doesn't pin a specific
+// tool. Matches the tool segment (after the server prefix): e.g. ...__wikipedia_search,
+// ...__ask_pipeworx, ...__get_summary, ...__search_wikipedia.
+const GENERAL_TOOL_RE = /(?:^|_)(search|ask|lookup|find|answer|summary|wiki)(?:_|$)/i;
+
 // Returns specs scored + sorted most-relevant first, as [{ s, i, n }] (i = original
 // index, n = score). Stable for ties (preserves original order).
 export function scoreToolSpecs(specs, query, { name = defName, description = defDesc } = {}) {
@@ -37,6 +42,12 @@ export function scoreToolSpecs(specs, query, { name = defName, description = def
     for (const part of names[i].split(/[^a-z0-9]+/)) {
       if (part.length > 2 && q.includes(part)) n += 2 + idf(part); // tool explicitly named
     }
+    // General-purpose ENTRY-POINT tools (search / ask / lookup / get-summary / answer)
+    // are the right default when the query doesn't keyword-match a specific tool —
+    // e.g. "which state is Seattle in" → a wikipedia SEARCH/ASK tool, not one of 20
+    // dataset-query tools. A small tie-breaker boost (below a real keyword match) so
+    // those generic tools win when nothing else distinguishes them.
+    if (GENERAL_TOOL_RE.test(names[i])) n += 1.5;
     return n;
   };
   return list.map((s, i) => ({ s, i, n: score(i) })).sort((a, b) => (b.n - a.n) || (a.i - b.i));
@@ -51,12 +62,41 @@ export function rankToolSpecs(specs, query, accessors) {
 // retaining everything that does (e.g. local page/history tools). `cap` therefore
 // bounds the NARROWABLE (MCP) tools; kept tools ride along free. Returns the list
 // unchanged when there's no cap or the narrowable set already fits.
+// The MCP server a tool belongs to: mcp_<server>__<tool> → "mcp_<server>". Tools
+// without that shape are their own "server" (never grouped together).
+function serverKey(n) {
+  const s = String(n || '');
+  const i = s.indexOf('__');
+  return i > 0 ? s.slice(0, i) : s;
+}
+
 export function narrowSpecs(specs, query, { cap = 0, keep, name = defName, description = defDesc } = {}) {
   const list = specs || [];
   if (!cap || cap < 1) return list;
   const kept = keep ? list.filter(keep) : [];
   const rest = keep ? list.filter((s) => !kept.includes(s)) : list;
   if (rest.length <= cap) return list;
-  const top = new Set(rankToolSpecs(rest, query, { name, description }).slice(0, cap));
-  return list.filter((s) => kept.includes(s) || top.has(s)); // preserve original order
+  // SERVER-DIVERSE selection: rank all narrowable tools, then pick ROUND-ROBIN across
+  // servers — each server's best tool first, then seconds, … up to `cap`. This keeps
+  // a relevant server (e.g. wikipedia) from being crowded out of the top-K by another
+  // server that happens to have many tools. Servers are visited best-first (the order
+  // their top-ranked tool appears in the global ranking).
+  const ranked = rankToolSpecs(rest, query, { name, description });
+  const queues = new Map(); // serverKey -> [tools] in rank order (insertion = best-first)
+  for (const s of ranked) {
+    const k = serverKey(name(s));
+    if (!queues.has(k)) queues.set(k, []);
+    queues.get(k).push(s);
+  }
+  const lanes = [...queues.values()];
+  const chosen = new Set();
+  for (let round = 0; chosen.size < cap; round++) {
+    let advanced = false;
+    for (const lane of lanes) {
+      if (chosen.size >= cap) break;
+      if (lane.length > round) { chosen.add(lane[round]); advanced = true; }
+    }
+    if (!advanced) break;
+  }
+  return list.filter((s) => kept.includes(s) || chosen.has(s)); // preserve original order
 }