@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-mcp-adapter/npx-resolver.ts

@@ -1,11 +1,11 @@
 // npx-resolver.ts - Resolve npx/npm exec binaries to avoid npm parent processes
-import { existsSync, readFileSync, realpathSync, readdirSync, statSync, writeFileSync, renameSync, mkdirSync, openSync, readSync, closeSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, readdirSync, statSync, writeFileSync, renameSync, mkdirSync, openSync, readSync, closeSync, unlinkSync } from "node:fs";
 import { join, dirname, extname, resolve, sep } from "node:path";
 import { getAgentPath } from "./agent-dir.ts";
 import { throwIfAborted } from "./abort.ts";
 import crossSpawn from "cross-spawn";
 
-const CACHE_VERSION = 1;
+const CACHE_VERSION = 2;
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 const EXACT_PACKAGE_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?(?:\+[0-9A-Za-z][0-9A-Za-z.-]*)?$/;
 
@@ -53,7 +53,7 @@ export async function resolveNpxBinary(
   if (!parsed) return null;
 
   const packageSpec = parsePackageSpec(parsed.packageSpec);
-  const cacheKey = JSON.stringify([command, ...args]);
+  const cacheKey = JSON.stringify([command, parsed.packageSpec, parsed.binName ?? ""]);
   const cache = loadCache();
   const cached = cache?.entries?.[cacheKey];
 
@@ -434,41 +434,96 @@ function getNpxCachePath(): string {
   return getAgentPath("mcp-npx-cache.json");
 }
 
-function loadCache(): NpxCache | null {
-  const cachePath = getNpxCachePath();
+function readNpxCachePayload(cachePath: string): unknown | null {
   if (!existsSync(cachePath)) return null;
   try {
-    const raw = JSON.parse(readFileSync(cachePath, "utf-8"));
-    if (!raw || typeof raw !== "object") return null;
-    if (raw.version !== CACHE_VERSION) return null;
-    if (!raw.entries || typeof raw.entries !== "object") return null;
-    return raw as NpxCache;
+    return JSON.parse(readFileSync(cachePath, "utf-8")) as unknown;
   } catch {
     return null;
   }
 }
 
-function saveCacheEntry(key: string, entry: NpxCacheEntry): void {
-  const cachePath = getNpxCachePath();
-  const dir = dirname(cachePath);
-  mkdirSync(dir, { recursive: true });
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function createCacheEntries(): Record<string, NpxCacheEntry> {
+  return Object.create(null) as Record<string, NpxCacheEntry>;
+}
+
+function toNpxCacheEntry(value: unknown): NpxCacheEntry | null {
+  const raw = asRecord(value);
+  if (!raw) return null;
+  if (typeof raw.resolvedBin !== "string") return null;
+  if (typeof raw.resolvedAt !== "number" || !Number.isFinite(raw.resolvedAt)) return null;
+  if (typeof raw.isJs !== "boolean") return null;
+  if (raw.packageVersion !== undefined && typeof raw.packageVersion !== "string") return null;
+  return {
+    resolvedBin: raw.resolvedBin,
+    resolvedAt: raw.resolvedAt,
+    ...(raw.packageVersion !== undefined ? { packageVersion: raw.packageVersion } : {}),
+    isJs: raw.isJs,
+  };
+}
+
+function toNpxCache(value: unknown): NpxCache | null {
+  const raw = asRecord(value);
+  if (!raw || raw.version !== CACHE_VERSION) return null;
+  const rawEntries = asRecord(raw.entries);
+  if (!rawEntries) return null;
+
+  const entries = createCacheEntries();
+  for (const [key, rawEntry] of Object.entries(rawEntries)) {
+    const entry = toNpxCacheEntry(rawEntry);
+    if (entry) entries[key] = entry;
+  }
+  return { version: CACHE_VERSION, entries };
+}
 
-  let merged: NpxCache = { version: CACHE_VERSION, entries: {} };
+function clearLegacyCache(): boolean {
+  const cachePath = getNpxCachePath();
+  const raw = asRecord(readNpxCachePayload(cachePath));
+  if (raw?.version !== 1) return false;
   try {
-    if (existsSync(cachePath)) {
-      const existing = JSON.parse(readFileSync(cachePath, "utf-8")) as NpxCache;
-      if (existing && existing.version === CACHE_VERSION && existing.entries) {
-        merged.entries = { ...existing.entries };
-      }
-    }
+    unlinkSync(cachePath);
   } catch {
-    // Ignore parse errors
+    try {
+      writeFileSync(cachePath, "", "utf-8");
+    } catch {
+      // Cache cleanup is best effort; resolution must still proceed.
+    }
   }
+  return true;
+}
 
-  merged.entries[key] = entry;
-  const tmpPath = `${cachePath}.${process.pid}.tmp`;
-  writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
-  renameSync(tmpPath, cachePath);
+clearLegacyCache();
+
+function loadCache(): NpxCache | null {
+  if (clearLegacyCache()) return null;
+
+  return toNpxCache(readNpxCachePayload(getNpxCachePath()));
+}
+
+function saveCacheEntry(key: string, entry: NpxCacheEntry): void {
+  try {
+    const cachePath = getNpxCachePath();
+    const dir = dirname(cachePath);
+    mkdirSync(dir, { recursive: true });
+
+    const existing = toNpxCache(readNpxCachePayload(cachePath));
+    const entries = createCacheEntries();
+    if (existing) Object.assign(entries, existing.entries);
+    const merged: NpxCache = { version: CACHE_VERSION, entries };
+
+    merged.entries[key] = entry;
+    const tmpPath = `${cachePath}.${process.pid}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
+    renameSync(tmpPath, cachePath);
+  } catch {
+    // Cache writes are best effort; resolution must still proceed.
+  }
 }
 
 function safeRealpath(path: string): string {

package/node_modules/pi-mcp-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.23.0",
+  "version": "2.26.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -34,8 +34,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:oauth": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --import tsx --test --test-concurrency=1 oauth-public-api.test.ts mcp-auth.test.ts mcp-auth-flow.test.ts mcp-callback-server.test.ts mcp-oauth-provider.test.ts",
-    "test:oauth-provider": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --import tsx --test mcp-oauth-provider.test.ts",
+    "test:oauth": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory PI_MCP_ADAPTER_DISABLE_AUTH_CACHE=1 node --import tsx --test --test-concurrency=1 oauth-public-api.test.ts mcp-auth.test.ts mcp-auth-flow.test.ts mcp-callback-server.test.ts mcp-oauth-provider.test.ts",
+    "test:oauth-provider": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory PI_MCP_ADAPTER_DISABLE_AUTH_CACHE=1 node --import tsx --test mcp-oauth-provider.test.ts",
     "test:conformance": "bash conformance/run.sh"
   },
   "repository": {
@@ -89,6 +89,7 @@
     "ui-app-bridge-helpers.ts",
     "config.ts",
     "server-manager.ts",
+    "request-headers-command.ts",
     "unix-socket-transport.ts",
     "json-schema-validator.ts",
     "session-recovery.ts",

package/node_modules/pi-mcp-adapter/proxy-modes.ts

@@ -16,7 +16,7 @@ import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime }
 import { formatAuthRequiredMessage, formatMcpStatus, resolveServerUrl, truncateAtWord } from "./utils.ts";
 import { authenticate, completeAuthFromInput, startAuth, supportsOAuth } from "./mcp-auth-flow.ts";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.ts";
-import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.ts";
+import { paginate, rankSuggestions, rankToolMatches, resolveSearchKeywords } from "./search-ranking.ts";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.ts";
 
 type ProxyToolResult = AgentToolResult<Record<string, unknown>>;
@@ -37,6 +37,36 @@ type AutoAuthResult =
   | { status: "success" }
   | { status: "failed"; message: string };
 
+function getToolMatches(metadata: ToolMetadata[] | undefined, toolName: string, exact: boolean): ToolMetadata[] {
+  if (!metadata) return [];
+  if (exact) return metadata.filter(tool => tool.name === toolName);
+  const normalizedName = toolName.replace(/-/g, "_");
+  return metadata.filter(tool => tool.name.replace(/-/g, "_") === normalizedName);
+}
+
+function getEnabledToolMatches(state: McpExtensionState, toolName: string, exact: boolean): { server: string; tool: ToolMetadata }[] {
+  const matches: { server: string; tool: ToolMetadata }[] = [];
+  for (const [server, metadata] of state.toolMetadata) {
+    if (isServerDisabled(state.config.mcpServers[server])) continue;
+    for (const tool of getToolMatches(metadata, toolName, exact)) matches.push({ server, tool });
+  }
+  return matches;
+}
+
+function getSingleToolMatch(metadata: ToolMetadata[] | undefined, toolName: string): ToolMetadata | "ambiguous" | undefined {
+  const exactMatches = getToolMatches(metadata, toolName, true);
+  const matches = exactMatches.length > 0 ? exactMatches : getToolMatches(metadata, toolName, false);
+  return matches.length > 1 ? "ambiguous" : matches[0];
+}
+
+function ambiguousToolResult(mode: "call" | "describe", toolName: string): ProxyToolResult {
+  const message = `Tool "${toolName}" matches multiple servers. Specify a server.`;
+  return {
+    content: [{ type: "text" as const, text: message }],
+    details: { mode, error: "ambiguous_tool", requestedTool: toolName, message },
+  };
+}
+
 function disabledResult(mode: string, serverName: string): ProxyToolResult {
   const message = `Server "${serverName}" is disabled. Run /mcp enable ${serverName} and /reload to enable it.`;
   return {
@@ -404,20 +434,28 @@ export async function executeAuthComplete(state: McpExtensionState, serverName:
 }
 
 export function executeDescribe(state: McpExtensionState, toolName: string): ProxyToolResult {
-  let serverName: string | undefined;
-  let toolMeta: ToolMetadata | undefined;
+  const exactMatches = getEnabledToolMatches(state, toolName, true);
+  if (exactMatches.length > 1) return ambiguousToolResult("describe", toolName);
+  if (exactMatches.length === 0 && getEnabledToolMatches(state, toolName, false).length > 1) {
+    return ambiguousToolResult("describe", toolName);
+  }
+
+  let serverName = exactMatches[0]?.server;
+  let toolMeta = exactMatches[0]?.tool;
   let disabledMatch: string | undefined;
 
-  for (const [server, metadata] of state.toolMetadata.entries()) {
-    const found = findToolByName(metadata, toolName);
-    if (!found) continue;
-    if (isServerDisabled(state.config.mcpServers[server])) {
-      disabledMatch ??= server;
-      continue;
+  if (!toolMeta) {
+    for (const [server, metadata] of state.toolMetadata.entries()) {
+      const found = findToolByName(metadata, toolName);
+      if (!found) continue;
+      if (isServerDisabled(state.config.mcpServers[server])) {
+        disabledMatch ??= server;
+        continue;
+      }
+      serverName = server;
+      toolMeta = found;
+      break;
     }
-    serverName = server;
-    toolMeta = found;
-    break;
   }
 
   if (!serverName || !toolMeta) {
@@ -430,7 +468,7 @@ export function executeDescribe(state: McpExtensionState, toolName: string): Pro
     };
   }
 
-  const approvalMarker = isToolCallApprovalRequired(state.config, serverName, toolMeta)
+  const approvalMarker = isToolCallApprovalRequired(state.config, serverName, toolMeta, state.toolMetadata)
     ? " (requires approval)"
     : "";
   let text = `${toolMeta.name}${approvalMarker}\n`;
@@ -503,11 +541,15 @@ export function executeSearch(
     }
 
     matches = [];
+    const globalPrefix = state.config.settings?.toolPrefix ?? "server";
     for (const [serverName, metadata] of state.toolMetadata.entries()) {
-      if (isServerDisabled(state.config.mcpServers[serverName])) continue;
+      const definition = state.config.mcpServers[serverName];
+      if (isServerDisabled(definition)) continue;
       if (server && serverName !== server) continue;
       for (const tool of metadata) {
-        if (pattern.test(tool.name) || pattern.test(tool.description)) matches.push({ server: serverName, tool, score: 0 });
+        const matched = pattern.test(tool.name) || pattern.test(tool.description)
+          || resolveSearchKeywords(definition, tool.originalName, serverName, globalPrefix).some(keyword => pattern.test(keyword));
+        if (matched) matches.push({ server: serverName, tool, score: 0 });
       }
     }
   } else if (query.trim().length === 0) {
@@ -553,7 +595,7 @@ export function executeSearch(
 
   let text = `Found ${page.total} tool${page.total === 1 ? "" : "s"} matching "${query}":\n\n`;
   for (const match of page.items) {
-    const approvalMarker = isToolCallApprovalRequired(state.config, match.server, match.tool)
+    const approvalMarker = isToolCallApprovalRequired(state.config, match.server, match.tool, state.toolMetadata)
       ? " (requires approval)"
       : "";
     if (showSchemas) {
@@ -733,7 +775,7 @@ export async function executeConnect(state: McpExtensionState, serverName: strin
       }
     }
     const prefix = state.config.settings?.toolPrefix ?? "server";
-    const { metadata } = buildToolMetadata(connection.tools, connection.resources, definition, serverName, prefix);
+    const { metadata } = buildToolMetadata(connection.tools, connection.resources, definition, serverName, prefix, state.config.mcpServers, state.toolMetadata);
     state.toolMetadata.set(serverName, metadata);
     if (!connection.promptDiscoveryFailed) {
       state.promptMetadata?.set(serverName, reconstructPromptMetadata(serverName, connection.prompts ?? [], prefix, definition));
@@ -801,14 +843,22 @@ export async function executeCall(
     };
   }
   if (serverName) {
-    toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
+    const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
+    if (match === "ambiguous") return ambiguousToolResult("call", toolName);
+    toolMeta = match;
     if (isServerDisabled(state.config.mcpServers[serverName])) {
       return disabledCallResult(serverName, toolMeta);
     }
   } else {
+    const exactMatches = getEnabledToolMatches(state, toolName, true);
+    if (exactMatches.length > 1) return ambiguousToolResult("call", toolName);
+    if (exactMatches.length === 0 && getEnabledToolMatches(state, toolName, false).length > 1) {
+      return ambiguousToolResult("call", toolName);
+    }
+
     let disabledMatch: { serverName: string; toolMeta: ToolMetadata } | undefined;
     for (const [server, metadata] of state.toolMetadata.entries()) {
-      const found = findToolByName(metadata, toolName);
+      const found = metadata.find(tool => tool.name === toolName);
       if (!found) continue;
       if (isServerDisabled(state.config.mcpServers[server])) {
         disabledMatch ??= { serverName: server, toolMeta: found };
@@ -818,13 +868,28 @@ export async function executeCall(
       toolMeta = found;
       break;
     }
+    if (!toolMeta && !disabledMatch) {
+      for (const [server, metadata] of state.toolMetadata.entries()) {
+        const found = findToolByName(metadata, toolName);
+        if (!found) continue;
+        if (isServerDisabled(state.config.mcpServers[server])) {
+          disabledMatch ??= { serverName: server, toolMeta: found };
+          continue;
+        }
+        serverName = server;
+        toolMeta = found;
+        break;
+      }
+    }
     if (!toolMeta && disabledMatch) return disabledCallResult(disabledMatch.serverName, disabledMatch.toolMeta);
   }
 
   if (serverName && !toolMeta) {
     const connected = await lazyConnect(state, serverName, ownedSignal);
     if (connected) {
-      toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
+      const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
+      if (match === "ambiguous") return ambiguousToolResult("call", toolName);
+      toolMeta = match;
     } else {
       const needsAuthConnection = state.manager.getConnection(serverName);
       if (needsAuthConnection?.status === "needs-auth") {
@@ -842,7 +907,9 @@ export async function executeCall(
             clearFailure(state, serverName);
             const connectedAfterAuth = await lazyConnect(state, serverName, ownedSignal);
             if (connectedAfterAuth) {
-              toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
+              const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
+              if (match === "ambiguous") return ambiguousToolResult("call", toolName);
+              toolMeta = match;
               if (!toolMeta) {
                 const suggestions = rankSuggestions(state, toolName, 5);
                 const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
@@ -879,6 +946,8 @@ export async function executeCall(
   let prefixMatchedServer: string | undefined;
 
   if (!serverName && !toolMeta && prefixMode !== "none") {
+    const lazyExactMatches: { serverName: string; toolMeta: ToolMetadata }[] = [];
+    const lazyFallbackMatches: { serverName: string; toolMeta: ToolMetadata }[] = [];
     const candidates = Object.keys(state.config.mcpServers)
       .filter(name => !isServerDisabled(state.config.mcpServers[name]))
       .map(name => ({ name, prefix: getServerPrefix(name, prefixMode) }))
@@ -909,11 +978,22 @@ export async function executeCall(
 
       if (!connected) continue;
       if (!prefixMatchedServer) prefixMatchedServer = configuredServer;
-      toolMeta = findToolByName(state.toolMetadata.get(configuredServer), toolName);
-      if (toolMeta) {
-        serverName = configuredServer;
-        break;
+      const metadata = state.toolMetadata.get(configuredServer);
+      const exactMatches = getToolMatches(metadata, toolName, true);
+      if (exactMatches.length > 1) return ambiguousToolResult("call", toolName);
+      if (exactMatches.length === 1) {
+        lazyExactMatches.push({ serverName: configuredServer, toolMeta: exactMatches[0]! });
+        continue;
       }
+      const fallbackMatches = getToolMatches(metadata, toolName, false);
+      if (fallbackMatches.length > 1) return ambiguousToolResult("call", toolName);
+      if (fallbackMatches.length === 1) lazyFallbackMatches.push({ serverName: configuredServer, toolMeta: fallbackMatches[0]! });
+    }
+    const lazyMatches = lazyExactMatches.length > 0 ? lazyExactMatches : lazyFallbackMatches;
+    if (lazyMatches.length > 1) return ambiguousToolResult("call", toolName);
+    if (lazyMatches.length === 1) {
+      serverName = lazyMatches[0]!.serverName;
+      toolMeta = lazyMatches[0]!.toolMeta;
     }
   }
 
@@ -1026,7 +1106,9 @@ export async function executeCall(
       notifyToolMetadataUpdated(state, serverName, "proxy-call-reconnect");
       markKeepAliveAfterConnect(state, serverName);
       updateStatusBar(state);
-      toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
+      const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
+      if (match === "ambiguous") return ambiguousToolResult("call", toolName);
+      toolMeta = match;
       if (!toolMeta) {
         const available = getToolNames(state, serverName);
         const hint = available.length > 0