@herbertgao/pi-extensions 2026.9.11 → 2026.9.13

package/node_modules/pi-mcp-adapter/request-headers-command.ts

@@ -298,25 +298,28 @@ async function invokeRequestHeadersCommand(
 export function createRequestHeadersCommandFetch(
   config: HttpRequestHeadersCommand,
   delegate: FetchLike = globalThis.fetch,
-): FetchLike {
+) {
   // Validate static configuration before the first request.
   resolvedCommand(config);
   return async (input: URL | RequestInfo, init?: RequestInit): Promise<Response> => {
     const request = new Request(input, init);
+    const signal = init?.signal === null
+      ? request.signal
+      : init?.signal ?? (input instanceof Request ? input.signal : request.signal);
     const body = Buffer.from(await request.clone().arrayBuffer());
     const derived = await invokeRequestHeadersCommand(config, {
       version: 1,
       method: request.method.toUpperCase(),
       url: request.url,
       bodyBase64: body.toString("base64"),
-    }, request.signal);
+    }, signal);
     const headers = new Headers(request.headers);
     derived.forEach((value, name) => headers.set(name, value));
     return delegate(new URL(request.url), {
       method: request.method,
       headers,
       ...(request.method === "GET" || request.method === "HEAD" ? {} : { body }),
-      signal: request.signal,
+      signal,
       cache: request.cache,
       credentials: request.credentials,
       integrity: request.integrity,

package/node_modules/pi-mcp-adapter/search-ranking.ts

@@ -10,6 +10,12 @@ import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
  */
 const MIN_STEM_LENGTH = 4;
 
+// Keep ASCII tokens unchanged; bound adjacent bigrams for non-ASCII Unicode word runs.
+// Whole-run fallbacks preserve single characters and prevent truncated queries from matching only a prefix.
+const MAX_UNICODE_BIGRAMS_PER_RUN = 64;
+const SEARCH_RUN = /[a-z0-9]+|(?:(?![a-z0-9])[\p{L}\p{N}\p{M}])+/gu;
+const ASCII_RUN = /^[a-z0-9]+$/;
+
 const FIELD_WEIGHTS = {
   name: 12,
   originalName: 10,
@@ -82,7 +88,32 @@ export function normalizeSearchText(value: string): string {
 }
 
 export function tokenize(value: string): string[] {
-  return normalizeSearchText(value).split(/[^a-z0-9]+/).filter(Boolean);
+  const tokens: string[] = [];
+  for (const run of normalizeSearchText(value).match(SEARCH_RUN) ?? []) {
+    if (ASCII_RUN.test(run)) {
+      tokens.push(run);
+      continue;
+    }
+    const characters = [...run];
+    if (characters.length === 1 || characters.length > MAX_UNICODE_BIGRAMS_PER_RUN + 1) {
+      tokens.push(run);
+      continue;
+    }
+    let previous = "";
+    for (const character of characters) {
+      if (previous) {
+        tokens.push(previous + character);
+      }
+      previous = character;
+    }
+  }
+  return tokens;
+}
+
+function matchesAsciiStem(fieldToken: string, queryToken: string): boolean {
+  return ASCII_RUN.test(fieldToken)
+    && ASCII_RUN.test(queryToken)
+    && (fieldToken.startsWith(queryToken) || (fieldToken.length >= MIN_STEM_LENGTH && queryToken.startsWith(fieldToken)));
 }
 
 function prepareToolSearch(tool: ToolMetadata, server: string, keywords?: string[]): PreparedToolSearch {
@@ -132,7 +163,7 @@ function scorePreparedToolMatch(
       if (fieldTokens.includes(token)) {
         score += weight * 4;
         matchedTokens.add(token);
-      } else if (fieldTokens.some(fieldToken => fieldToken.startsWith(token) || (fieldToken.length >= MIN_STEM_LENGTH && token.startsWith(fieldToken)))) {
+      } else if (fieldTokens.some(fieldToken => matchesAsciiStem(fieldToken, token))) {
         score += weight * 2;
         matchedTokens.add(token);
       } else if (value.includes(token)) {
@@ -167,7 +198,7 @@ function scorePreparedToolMatch(
       if (prepared.keywordTokens.includes(token)) {
         score += weight * 4;
         matchedTokens.add(token);
-      } else if (prepared.keywordTokens.some(keywordToken => keywordToken.startsWith(token) || (keywordToken.length >= MIN_STEM_LENGTH && token.startsWith(keywordToken)))) {
+      } else if (prepared.keywordTokens.some(keywordToken => matchesAsciiStem(keywordToken, token))) {
         score += weight * 2;
         matchedTokens.add(token);
       } else if (prepared.keywordPhrases.some(phrase => phrase.includes(token))) {
@@ -266,13 +297,13 @@ export function paginate<T>(items: T[], offset: number, limit: number): { items:
   };
 }
 
-export function rankSuggestions(state: McpExtensionState, name: string, limit: number): string[] {
+export function rankSuggestions(state: McpExtensionState, name: string, limit: number, server?: string): string[] {
   const stripped = Object.keys(state.config.mcpServers)
-    .flatMap(server => (["server", "short", "mcp"] as const)
-      .map(prefix => getServerPrefix(server, prefix)))
+    .flatMap(serverName => (["server", "short", "mcp"] as const)
+      .map(prefix => getServerPrefix(serverName, prefix)))
     .filter((candidate): candidate is string => Boolean(candidate) && name.startsWith(`${candidate}_`))
     .sort((a, b) => b.length - a.length)
     .map(candidate => name.slice(candidate.length + 1));
   const query = stripped[0] ?? name;
-  return rankToolMatches(state, query, undefined, false).slice(0, limit).map(match => match.tool.name);
+  return rankToolMatches(state, query, server, false).slice(0, limit).map(match => match.tool.name);
 }

package/node_modules/pi-mcp-adapter/secure-keyring.ts

@@ -0,0 +1,170 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface SecureKeyringStore {
+  read(account: string): string | undefined;
+  write(account: string, payload: string): void;
+  remove(account: string): void;
+}
+
+type KeyringEntry = {
+  getPassword(): string | null;
+  setPassword(password: string): void;
+  deleteCredential(): boolean;
+};
+type KeyringEntryConstructor = new (service: string, account: string) => KeyringEntry;
+type KeyringModule = { Entry: KeyringEntryConstructor };
+type KeyringRequire = ((id: string) => unknown) & { resolve(id: string): string };
+
+const require = createRequire(import.meta.url);
+const TEST_STORE_ENV = "PI_MCP_ADAPTER_TEST_AUTH_STORE";
+const memoryEntries = new Map<string, string>();
+let memoryReadCount = 0;
+let KeyringEntryClass: KeyringEntryConstructor | undefined;
+
+function key(service: string, account: string): string {
+  return `${service}\0${account}`;
+}
+
+function nativeStore(service: string): SecureKeyringStore {
+  const entry = (account: string): KeyringEntry => {
+    try {
+      KeyringEntryClass ??= loadKeyringEntryClass();
+      return new KeyringEntryClass(service, account);
+    } catch (error) {
+      throw new Error("OS secure credential storage is unavailable. Configure or unlock the OS credential store and retry.", { cause: error });
+    }
+  };
+  const run = (operation: "read" | "write" | "remove", account: string, payload?: string): string | undefined => {
+    try {
+      const credential = entry(account);
+      if (operation === "read") return credential.getPassword() ?? undefined;
+      if (operation === "write") credential.setPassword(payload!);
+      else credential.deleteCredential();
+      return undefined;
+    } catch (error) {
+      if (!shouldRecoverKeyring(error)) throw error;
+      return recoverKeyring(operation, service, account, payload);
+    }
+  };
+  return {
+    read: account => run("read", account),
+    write: (account, payload) => { run("write", account, payload); },
+    remove: account => { run("remove", account); },
+  };
+}
+
+function shouldRecoverKeyring(error: unknown): boolean {
+  if (process.platform !== "linux" || process.env.PI_MCP_ADAPTER_DISABLE_KEYRING_RECOVERY === "1") return false;
+  const seen = new Set<unknown>();
+  for (let depth = 0; depth < 16 && error !== undefined && !seen.has(error); depth++) {
+    seen.add(error);
+    const candidate = typeof error === "object" && error !== null
+      ? error as { name?: unknown; message?: unknown; code?: unknown; cause?: unknown }
+      : { message: error };
+    if ([candidate.name, candidate.message, candidate.code].some(value =>
+      typeof value === "string" && /\b(?:KeyRevoked|key\s+(?:has been\s+)?revoked)\b/i.test(value))) return true;
+    error = candidate.cause;
+  }
+  return false;
+}
+
+function recoverKeyring(operation: "read" | "write" | "remove", service: string, account: string, payload?: string): string | undefined {
+  try {
+    const adjacentHelper = new URL("./mcp-keyring-helper.cjs", import.meta.url);
+    const helper = existsSync(adjacentHelper) ? adjacentHelper : new URL("../mcp-keyring-helper.cjs", import.meta.url);
+    const result = spawnSync("keyctl", ["session", "-", process.execPath, fileURLToPath(helper)], {
+      input: `${JSON.stringify({ operation, service, account, payload })}\n`,
+      encoding: "utf8",
+      stdio: "pipe",
+      shell: false,
+      timeout: 10_000,
+      killSignal: "SIGKILL",
+      maxBuffer: 1024 * 1024,
+      windowsHide: true,
+    });
+    if (result.error || result.status !== 0 || result.signal) throw new Error();
+    const response: unknown = JSON.parse(result.stdout);
+    if (typeof response !== "object" || response === null || Array.isArray(response)) throw new Error();
+    const value = response as { ok?: unknown; found?: unknown; value?: unknown };
+    if (value.ok !== true) throw new Error();
+    const allowedKeys = operation === "read" ? ["ok", "found", "value"] : ["ok"];
+    if (Object.keys(response).some(key => !allowedKeys.includes(key))) throw new Error();
+    if (operation === "read") {
+      if (value.found === true && typeof value.value === "string") return value.value;
+      if (value.found === false && value.value === undefined) return undefined;
+      throw new Error();
+    }
+    return undefined;
+  } catch {
+    throw new Error("Linux keyring recovery failed. Configure or unlock the OS credential store and retry.");
+  }
+}
+
+export function createSecureKeyringStore(service: string): SecureKeyringStore {
+  const mode = process.env[TEST_STORE_ENV];
+  if (mode === "memory" || mode === "sizelimited") {
+    return {
+      read(account) { memoryReadCount++; return memoryEntries.get(key(service, account)); },
+      write(account, payload) {
+        if (mode === "sizelimited" && payload.length > 1280) throw new Error("secure credential value exceeds platform limit");
+        memoryEntries.set(key(service, account), payload);
+      },
+      remove(account) { memoryEntries.delete(key(service, account)); },
+    };
+  }
+  if (mode === "unavailable") {
+    return {
+      read() { memoryReadCount++; throw new Error("simulated secure credential store unavailable"); },
+      write() { throw new Error("simulated secure credential store unavailable"); },
+      remove() { throw new Error("simulated secure credential store unavailable"); },
+    };
+  }
+  return nativeStore(service);
+}
+
+function loadKeyringEntryClass(keyringRequire: KeyringRequire = require, platform: NodeJS.Platform = process.platform, arch: NodeJS.Architecture = process.arch): KeyringEntryConstructor {
+  try {
+    return (keyringRequire("@napi-rs/keyring") as KeyringModule).Entry;
+  } catch (loaderError) {
+    try {
+      return loadKeyringNativeBindingFallback(keyringRequire, platform, arch).Entry;
+    } catch (fallbackError) {
+      const message = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+      throw new Error(`Failed to load @napi-rs/keyring; absolute-path native binding fallback also failed: ${message}`, { cause: loaderError });
+    }
+  }
+}
+
+function loadKeyringNativeBindingFallback(keyringRequire: KeyringRequire, platform: NodeJS.Platform, arch: NodeJS.Architecture): KeyringModule {
+  let lastError: unknown;
+  for (const suffix of getKeyringNativeBindingSuffixes(platform, arch)) {
+    try {
+      const packageName = `@napi-rs/keyring-${suffix}`;
+      const packageJsonPath = keyringRequire.resolve(`${packageName}/package.json`);
+      return keyringRequire(join(dirname(packageJsonPath), `keyring.${suffix}.node`)) as KeyringModule;
+    } catch (error) { lastError = error; }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+
+function getKeyringNativeBindingSuffixes(platform: NodeJS.Platform, arch: NodeJS.Architecture): string[] {
+  if (platform === "darwin") return arch === "arm64" ? ["darwin-arm64"] : arch === "x64" ? ["darwin-x64"] : [];
+  if (platform === "win32") return arch === "arm64" ? ["win32-arm64-msvc"] : arch === "x64" ? ["win32-x64-msvc"] : arch === "ia32" ? ["win32-ia32-msvc"] : [];
+  if (platform === "linux") {
+    if (arch === "arm64") return ["linux-arm64-gnu", "linux-arm64-musl"];
+    if (arch === "arm") return ["linux-arm-gnueabihf"];
+    if (arch === "riscv64") return ["linux-riscv64-gnu"];
+    if (arch === "x64") return ["linux-x64-gnu", "linux-x64-musl"];
+  }
+  return platform === "freebsd" && arch === "x64" ? ["freebsd-x64"] : [];
+}
+
+export function resetTestSecureKeyring(): void { memoryEntries.clear(); memoryReadCount = 0; }
+export function getTestSecureKeyringReadCount(): number { return memoryReadCount; }
+export function getTestSecureKeyringEntries(): [string, string][] { return [...memoryEntries.entries()]; }
+export function setTestSecureKeyringEntry(service: string, account: string, payload: string): void { memoryEntries.set(key(service, account), payload); }
+export function removeTestSecureKeyringEntry(service: string, account: string): void { memoryEntries.delete(key(service, account)); }

package/node_modules/pi-mcp-adapter/semantic-search.ts

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+import { areJevSourcesAllowed, evaluateJev, resolveSemanticJevSettings } from "./jev-client.ts";
+import type { JevEvaluateInput, JevEvaluationEnvelope } from "./jev-contracts.ts";
+import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
+import { rankToolMatches, type RankedToolMatch } from "./search-ranking.ts";
+import type { McpExtensionState } from "./state.ts";
+import type { ToolMetadata } from "./types.ts";
+import { isServerDisabled } from "./types.ts";
+
+export type SemanticSearchEvaluator = (
+  state: McpExtensionState,
+  input: JevEvaluateInput,
+  options: { purpose: "semantic-search"; signal?: AbortSignal; observedSources?: readonly string[] },
+) => Promise<JevEvaluationEnvelope>;
+
+export type SemanticSearchBackend =
+  | { requested: "semantic"; used: "semantic"; degraded: false; model: string; usage: { inputTokens: number; outputTokens: number }; abstained: boolean }
+  | { requested: "semantic"; used: "lexical"; degraded: true; reason: "timeout" | "rate_limited" | "service_unavailable" };
+
+export type SemanticSearchResult =
+  | { ok: true; matches: RankedToolMatch[]; backend: SemanticSearchBackend }
+  | { ok: false; error: { code: string; message: string } };
+
+interface Candidate {
+  id: string;
+  server: string;
+  description: string;
+  tool: ToolMetadata;
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.length <= maxBytes) return value;
+  let end = maxBytes;
+  while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) end -= 1;
+  return bytes.subarray(0, end).toString("utf8");
+}
+
+function stableHash(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function eligibleMatches(state: McpExtensionState, server: string | undefined, allowed: Set<string>): RankedToolMatch[] {
+  const matches: RankedToolMatch[] = [];
+  for (const [serverName, metadata] of state.toolMetadata) {
+    if ((server && serverName !== server) || !allowed.has(serverName)
+      || isServerDisabled(state.config.mcpServers[serverName]) || isServerInActiveFailureBackoff(state, serverName)) continue;
+    for (const tool of metadata) matches.push({ server: serverName, tool, score: 0 });
+  }
+  return matches;
+}
+
+function roundRobinNonLexical(query: string, matches: RankedToolMatch[]): RankedToolMatch[] {
+  const buckets = new Map<string, RankedToolMatch[]>();
+  for (const match of matches) {
+    const bucket = buckets.get(match.server) ?? [];
+    bucket.push(match);
+    buckets.set(match.server, bucket);
+  }
+  const servers = [...buckets.keys()].sort((a, b) => a.localeCompare(b));
+  for (const bucket of buckets.values()) {
+    bucket.sort((a, b) => stableHash(query + a.tool.name).localeCompare(stableHash(query + b.tool.name)) || a.tool.name.localeCompare(b.tool.name));
+  }
+  if (servers.length > 1) {
+    const start = Number.parseInt(stableHash(query).slice(0, 8), 16) % servers.length;
+    servers.push(...servers.splice(0, start));
+  }
+  const result: RankedToolMatch[] = [];
+  let index = 0;
+  while (result.length < matches.length) {
+    let added = false;
+    for (const server of servers) {
+      const match = buckets.get(server)?.[index];
+      if (match) { result.push(match); added = true; }
+    }
+    if (!added) break;
+    index += 1;
+  }
+  return result;
+}
+
+function selectSemanticCandidates(
+  state: McpExtensionState,
+  query: string,
+  server: string | undefined,
+  allowedServers: string[],
+  limit: number,
+): Candidate[] {
+  const eligible = eligibleMatches(state, server, new Set(allowedServers));
+  let selected = eligible;
+  if (eligible.length > limit) {
+    const eligiblePaths = new Set(eligible.map(match => `${match.server}\0${match.tool.name}`));
+    const lexical = rankToolMatches(state, query, server)
+      .filter(match => eligiblePaths.has(`${match.server}\0${match.tool.name}`));
+    const lexicalCount = Math.floor(limit / 2);
+    const first = lexical.slice(0, lexicalCount);
+    const lexicalPaths = new Set(lexical.map(match => `${match.server}\0${match.tool.name}`));
+    const broad = roundRobinNonLexical(query, eligible.filter(match => !lexicalPaths.has(`${match.server}\0${match.tool.name}`)));
+    selected = [...first, ...broad.slice(0, limit - first.length)];
+  }
+  return selected.map((match, index) => ({ id: `c${index}`, server: match.server,
+    description: truncateUtf8(match.tool.description ?? "", 512), tool: match.tool }));
+}
+
+export async function semanticSearch(
+  state: McpExtensionState,
+  query: string,
+  server?: string,
+  signal?: AbortSignal,
+  evaluator: SemanticSearchEvaluator = evaluateJev,
+  observedSources: readonly string[] = [],
+): Promise<SemanticSearchResult> {
+  let settings;
+  try {
+    settings = resolveSemanticJevSettings(state);
+  } catch {
+    return { ok: false, error: { code: "invalid_request", message: "Invalid TypeSafe semantic search settings." } };
+  }
+  if (!settings.semanticSearch) {
+    return { ok: false, error: { code: "disabled", message: "TypeSafe semantic search is disabled." } };
+  }
+  if (settings.allowedServers.length === 0) {
+    return { ok: false, error: { code: "data_policy_denied", message: "Semantic search is enabled, but settings.jev.allowedServers is empty. Run /mcp jev setup or allow specific MCP servers." } };
+  }
+  if (server && !settings.allowedServers.includes(server)) {
+    return { ok: false, error: { code: "data_policy_denied", message: `Server "${server}" is not allowed by settings.jev.allowedServers.` } };
+  }
+  if (!areJevSourcesAllowed(state, settings, observedSources)) {
+    return { ok: false, error: { code: "data_policy_denied", message: "Evaluation sources are not allowed by policy." } };
+  }
+  if (query.trim().length === 0) {
+    return { ok: false, error: { code: "empty_query", message: "Semantic search query cannot be empty." } };
+  }
+  const candidates = selectSemanticCandidates(state, query, server, settings.allowedServers, settings.semanticCandidateLimit);
+  if (candidates.length === 0) {
+    return { ok: false, error: { code: "no_eligible_tools", message: "Semantic search has no eligible cached tools from the allowed servers. Connect an allowed server or update settings.jev.allowedServers." } };
+  }
+  const input: JevEvaluateInput = {
+    state: {
+      query,
+      candidates: candidates.map(candidate => ({ id: candidate.id, path: candidate.tool.name,
+        name: candidate.tool.originalName, server: candidate.server, description: candidate.description })),
+    },
+    questions: {
+      match: {
+        type: "choice",
+        instructions: "Rank which tool best matches the query. Choose none when no tool is suitable.",
+        criteria: Object.fromEntries([
+          ...candidates.map(candidate => [candidate.id, { path: candidate.tool.name }]),
+          ["none", { noSuitableTool: true }],
+        ]),
+      },
+    },
+    sources: [...new Set(candidates.map(candidate => candidate.server))],
+  };
+  const envelope = await evaluator(state, input, { purpose: "semantic-search", ...(signal ? { signal } : {}), ...(observedSources.length > 0 ? { observedSources } : {}) });
+  if (!envelope.ok) {
+    if (envelope.error.code === "timeout" || envelope.error.code === "rate_limited" || envelope.error.code === "service_unavailable") {
+      return {
+        ok: true,
+        matches: rankToolMatches(state, query, server),
+        backend: { requested: "semantic", used: "lexical", degraded: true, reason: envelope.error.code },
+      };
+    }
+    return { ok: false, error: { code: envelope.error.code, message: envelope.error.message } };
+  }
+  const answer = envelope.data.answers.match;
+  if (!answer || answer.type !== "choice") {
+    return { ok: false, error: { code: "invalid_response", message: "TypeSafe returned an invalid semantic search response." } };
+  }
+  const ranked = candidates
+    .map(candidate => ({ candidate, probability: answer.probabilities[candidate.id] ?? 0 }))
+    .sort((a, b) => b.probability - a.probability || a.candidate.id.localeCompare(b.candidate.id));
+  const top = ranked[0];
+  const noneProbability = answer.probabilities.none ?? 0;
+  const abstained = answer.choice === "none" || !top || noneProbability >= top.probability || top.probability < settings.semanticMinProbability;
+  const matches = abstained ? [] : ranked.map(({ candidate, probability }) => ({ server: candidate.server, tool: candidate.tool, score: probability }));
+  return {
+    ok: true,
+    matches,
+    backend: {
+      requested: "semantic", used: "semantic", degraded: false, model: envelope.data.model,
+      usage: envelope.data.usage, abstained,
+    },
+  };
+}