@herbertgao/pi-extensions 2026.9.10 → 2026.9.12

package/node_modules/pi-mcp-adapter/bearer-command-resolver.ts

@@ -0,0 +1,193 @@
+import { spawn } from "node:child_process";
+
+const DEFAULT_TTL_MS = 5 * 60_000;
+const ENV_TTL_MS = "PI_MCP_ADAPTER_BEARER_COMMAND_TTL_MS";
+const COMMAND_TIMEOUT_MS = 10_000;
+const COMMAND_MAX_OUTPUT_BYTES = 1024 * 1024;
+const USE_PROCESS_GROUP = process.platform !== "win32";
+
+function resolveDefaultTtlMs(): number {
+  const parsed = Number(process.env[ENV_TTL_MS] || DEFAULT_TTL_MS);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : DEFAULT_TTL_MS;
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+function runCommand(command: string, context: string, signal: AbortSignal): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let output = Buffer.alloc(0);
+    let settled = false;
+    let terminating = false;
+    const child = spawn(command.slice(1), {
+      shell: true,
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+      detached: USE_PROCESS_GROUP,
+    });
+
+    const kill = async (): Promise<void> => {
+      if (child.pid === undefined) return;
+      if (!USE_PROCESS_GROUP) {
+        await new Promise<void>((resolveKill, rejectKill) => {
+          const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+            stdio: "ignore",
+            windowsHide: true,
+          });
+          killer.on("error", () => rejectKill(new Error("Failed to stop bearer token command")));
+          killer.on("close", code => {
+            if (code === 0 || code === 128) resolveKill();
+            else rejectKill(new Error(`Failed to stop bearer token command: taskkill exited with code ${code ?? "unknown"}`));
+          });
+        });
+        return;
+      }
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+      }
+    };
+    const finish = (error: unknown, token?: string) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      if (error !== undefined) reject(error);
+      else resolve(token!);
+    };
+    const terminate = async (error: unknown) => {
+      if (settled || terminating) return;
+      terminating = true;
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      try {
+        await kill();
+        finish(error);
+      } catch (cleanupError) {
+        finish(cleanupError);
+      }
+    };
+    const onAbort = () => {
+      void terminate(abortReason(signal));
+    };
+    const timer = setTimeout(() => {
+      void terminate(new Error(`Failed to resolve ${context}: command timed out after ${COMMAND_TIMEOUT_MS}ms`));
+    }, COMMAND_TIMEOUT_MS);
+
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    child.on("error", () => {
+      if (!terminating) finish(new Error(`Failed to resolve ${context}: command failed to start`));
+    });
+    child.stdout.on("data", (chunk: Buffer | string) => {
+      if (settled || terminating) return;
+      output = Buffer.concat([output, Buffer.from(chunk)]);
+      if (output.byteLength > COMMAND_MAX_OUTPUT_BYTES) {
+        void terminate(new Error(`Failed to resolve ${context}: command output exceeded 1 MiB`));
+      }
+    });
+    child.on("close", code => {
+      if (settled || terminating) return;
+      if (code !== 0) {
+        finish(new Error(`Failed to resolve ${context}: command exited with code ${code ?? "unknown"}`));
+        return;
+      }
+      const token = output.toString("utf8").trim();
+      if (!token) {
+        finish(new Error(`Failed to resolve ${context}: command returned empty output`));
+        return;
+      }
+      finish(undefined, token);
+    });
+  });
+}
+
+type Inflight = {
+  controller: AbortController;
+  promise: Promise<string>;
+  waiters: number;
+};
+
+/** Resolve and periodically refresh one command-backed bearer token. */
+export class BearerCommandResolver {
+  readonly #command: string;
+  readonly #context: string;
+  readonly #ttlMs: number;
+  #cached: { token: string; expiresAt: number } | undefined;
+  #failure: { error: unknown; retryAt: number } | undefined;
+  #inflight: Inflight | undefined;
+
+  constructor(command: string, context: string, ttlMs: number = resolveDefaultTtlMs()) {
+    this.#command = command;
+    this.#context = context;
+    this.#ttlMs = ttlMs;
+  }
+
+  resolve(signal?: AbortSignal): Promise<string> {
+    if (signal?.aborted) return Promise.reject(abortReason(signal));
+    const now = Date.now();
+    if (this.#cached !== undefined && now < this.#cached.expiresAt) {
+      return Promise.resolve(this.#cached.token);
+    }
+    if (this.#failure !== undefined && now < this.#failure.retryAt) {
+      return this.#cached !== undefined
+        ? Promise.resolve(this.#cached.token)
+        : Promise.reject(this.#failure.error);
+    }
+
+    let inflight = this.#inflight;
+    if (inflight === undefined) {
+      const controller = new AbortController();
+      let current: Inflight;
+      const promise = runCommand(this.#command, this.#context, controller.signal)
+        .then(token => {
+          this.#cached = { token, expiresAt: Date.now() + this.#ttlMs };
+          this.#failure = undefined;
+          return token;
+        })
+        .catch(error => {
+          // Request cancellation is not a helper outage. Do not let one
+          // cancelled request suppress refresh attempts for the next caller.
+          if (!controller.signal.aborted) {
+            this.#failure = { error, retryAt: Date.now() + this.#ttlMs };
+          }
+          if (this.#cached !== undefined) return this.#cached.token;
+          throw error;
+        })
+        .finally(() => {
+          if (this.#inflight === current) this.#inflight = undefined;
+        });
+      current = { controller, promise, waiters: 0 };
+      this.#inflight = current;
+      inflight = current;
+    }
+    return this.#wait(inflight, signal);
+  }
+
+  #wait(inflight: Inflight, signal?: AbortSignal): Promise<string> {
+    inflight.waiters++;
+    let onAbort: (() => void) | undefined;
+    const result = signal === undefined
+      ? inflight.promise
+      : Promise.race([
+          inflight.promise,
+          new Promise<string>((_resolve, reject) => {
+            onAbort = () => reject(abortReason(signal));
+            signal.addEventListener("abort", onAbort, { once: true });
+          }),
+        ]);
+    return result.finally(() => {
+      if (onAbort) signal!.removeEventListener("abort", onAbort);
+      inflight.waiters--;
+      if (this.#inflight === inflight && inflight.waiters === 0) {
+        this.#inflight = undefined;
+        inflight.controller.abort(signal?.reason);
+      }
+    });
+  }
+}

package/node_modules/pi-mcp-adapter/cli.js

@@ -78,6 +78,11 @@ function printHelp(log = console.log) {
   log("  pi-mcp-adapter token set <server>     Store a token read from stdin (masked prompt or pipe; never argv)");
   log("  pi-mcp-adapter token status <server>  Report whether a stored token matches the configured URL");
   log("  pi-mcp-adapter token remove <server>  Remove the stored token");
+  log("");
+  log("TypeSafe API key storage:");
+  log("  pi-mcp-adapter key set typesafe     Store a key read from stdin (masked prompt or pipe; never argv)");
+  log("  pi-mcp-adapter key status typesafe  Report the effective credential source without revealing it");
+  log("  pi-mcp-adapter key remove typesafe  Remove the stored key");
 }
 
 function readJsonFile(filePath) {
@@ -214,8 +219,8 @@ async function importTokenModules(error) {
   }
 }
 
-function readTokenFromStdin(stdin) {
-  if (stdin.isTTY) return readTokenMasked(stdin);
+function readSecretFromStdin(stdin, prompt = "Enter bearer token (input hidden): ") {
+  if (stdin.isTTY) return readSecretMasked(stdin, prompt);
   return new Promise((resolve, reject) => {
     let data = "";
     stdin.setEncoding("utf8");
@@ -228,9 +233,9 @@ function readTokenFromStdin(stdin) {
 }
 
 // Raw-mode masked prompt: the token never echoes to the terminal.
-function readTokenMasked(stdin) {
+function readSecretMasked(stdin, prompt) {
   return new Promise((resolve, reject) => {
-    process.stderr.write("Enter bearer token (input hidden): ");
+    process.stderr.write(prompt);
     stdin.setRawMode(true);
     stdin.resume();
     stdin.setEncoding("utf8");
@@ -306,7 +311,7 @@ async function runToken(argv, log, error, stdin) {
   }
 
   if (action === "set") {
-    const token = await readTokenFromStdin(stdin);
+    const token = await readSecretFromStdin(stdin);
     if (!token) {
       error("No token provided on stdin.");
       return 1;
@@ -352,6 +357,48 @@ async function runToken(argv, log, error, stdin) {
   return 0;
 }
 
+async function runKey(argv, log, error, stdin) {
+  const [action, provider, ...extra] = argv;
+  if (!["set", "status", "remove"].includes(action) || provider !== "typesafe") {
+    error("Usage: pi-mcp-adapter key <set|status|remove> typesafe");
+    error("`key set` reads the API key from stdin only. Never pass the key as an argument.");
+    return 1;
+  }
+  if (extra.length > 0) {
+    error("Unexpected extra arguments. The API key must not be passed on the command line; pipe it on stdin or use the interactive prompt.");
+    return 1;
+  }
+  let store;
+  try { store = await import("./dist/jev-key-store.js"); }
+  catch (err) {
+    error("Unable to load TypeSafe key command module.");
+    error(`Import failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+
+  if (action === "set") {
+    const apiKey = await readSecretFromStdin(stdin, "Enter TypeSafe API key (input hidden): ");
+    if (!apiKey) { error("No API key provided on stdin."); return 1; }
+    try { store.saveJevApiKey(apiKey); }
+    catch (err) { error(err instanceof Error ? err.message : "TypeSafe API key could not be stored."); return 1; }
+    log("TypeSafe API key stored in the OS secure credential store.");
+    if (Object.hasOwn(process.env, "TYPESAFE_API_KEY")) log("Note: TYPESAFE_API_KEY is present and overrides the stored key.");
+    return 0;
+  }
+  if (action === "status") {
+    const status = store.resolveJevCredential();
+    if (status.status === "present") { log(`source=${status.source}`); return 0; }
+    if (status.status === "unavailable") { error(`unavailable: ${status.message}`); return 1; }
+    log("missing");
+    return 1;
+  }
+  try { store.removeJevApiKey(); }
+  catch (err) { error(err instanceof Error ? err.message : "TypeSafe API key could not be removed."); return 1; }
+  log("TypeSafe API key removed from the OS secure credential store.");
+  if (Object.hasOwn(process.env, "TYPESAFE_API_KEY")) log("TYPESAFE_API_KEY is still present and overrides the stored key.");
+  return 0;
+}
+
 export async function main(argv = process.argv.slice(2), log = console.log, error = console.error, stdin = process.stdin) {
   const [command, ...rest] = argv;
 
@@ -364,6 +411,10 @@ export async function main(argv = process.argv.slice(2), log = console.log, erro
     return runToken(rest, log, error, stdin);
   }
 
+  if (command === "key") {
+    return runKey(rest, log, error, stdin);
+  }
+
   if (command === "install") {
     error("The custom downloader has been retired.");
     error("Use `pi install npm:pi-mcp-adapter` instead, then optionally run `pi-mcp-adapter init`.");

package/node_modules/pi-mcp-adapter/commands.ts

@@ -1,3 +1,4 @@
+import { existsSync, readFileSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { OverlayHandle } from "@earendil-works/pi-tui";
 import type { McpExtensionState } from "./state.ts";
@@ -14,8 +15,10 @@ import {
   previewSharedServerEntry,
   previewStarterSharedConfig,
   writeDirectToolsConfig,
+  writeJevSemanticSearchConfig,
   writeProjectServerDisabledOverride,
   writeSharedServerEntry,
+  writeSharedConfigText,
   writeStarterSharedConfig,
 } from "./config.ts";
 import { markKeepAliveAfterConnect, notifyToolMetadataUpdated, updateMetadataCache, updateStatusBar, getFailureAgeSeconds, getFailureMessage, clearFailure, recordFailure } from "./init.ts";
@@ -26,8 +29,9 @@ import { supportsOAuth, authenticate, removeAuth, type McpOAuthRuntime } from ".
 import { getAuthStorageOptions, inspectAuthForUrl } from "./mcp-auth.ts";
 import { inspectBearerTokenForUrl, removeBearerToken } from "./mcp-bearer-store.ts";
 import { loadOnboardingState, markSetupCompleted as persistSetupCompleted, markSharedConfigHintShown } from "./onboarding-state.ts";
-import { openPath, resolveServerUrl, sanitizeTerminalText } from "./utils.ts";
+import { formatTerminalError, openPath, resolveServerUrl, sanitizeTerminalText } from "./utils.ts";
 import { isAbortError } from "./runtime-owner.ts";
+import { resolveJevCredential } from "./jev-key-store.ts";
 
 function terminalHyperlink(label: string, url: string): string {
   return `\u001B]8;;${sanitizeTerminalText(url)}\u001B\\${sanitizeTerminalText(label)}\u001B]8;;\u001B\\`;
@@ -46,6 +50,93 @@ function canRenderPanel(ctx: ExtensionContext): boolean {
   return ctx.hasUI && ctx.mode === "tui";
 }
 
+export async function editSharedConfig(ctx: ExtensionContext, target: SharedConfigTarget): Promise<boolean> {
+  if (!ctx.hasUI) return false;
+  const path = getSharedConfigPath(target, ctx.cwd);
+  const before = existsSync(path) ? readFileSync(path, "utf8") : '{\n  "mcpServers": {}\n}\n';
+  const after = await ctx.ui.editor(`Edit ${path} (Ctrl+G opens $EDITOR)`, before);
+  if (after === undefined || after === before) return false;
+  try {
+    writeSharedConfigText(path, after);
+  } catch (error) {
+    ctx.ui.notify(`MCP: not saved: ${formatTerminalError(error)}`, "error");
+    return false;
+  }
+  return true;
+}
+
+export async function setupJevSemanticSearch(
+  state: McpExtensionState,
+  ctx: ExtensionContext,
+  configOverridePath?: string,
+): Promise<boolean> {
+  if (!ctx.hasUI) return false;
+  const credential = resolveJevCredential();
+  if (credential.status !== "present") {
+    const detail = credential.status === "unavailable" ? ` ${credential.message}` : "";
+    ctx.ui.notify(
+      `Jev needs a TypeSafe API key.${detail}\nRun \`pi-mcp-adapter key set typesafe\` in a terminal, then run \`/mcp jev setup\` again.`,
+      "error",
+    );
+    return false;
+  }
+
+  const servers = Object.keys(state.config.mcpServers)
+    .filter((name) => !isServerDisabled(state.config.mcpServers[name]))
+    .sort((a, b) => a.localeCompare(b));
+  if (servers.length === 0) {
+    ctx.ui.notify("Enable or add an MCP server before setting up Jev semantic search.", "error");
+    return false;
+  }
+  const configuredJev = state.config.settings?.jev;
+  const payloadDisclosure = configuredJev && configuredJev.scriptEvaluation
+    ? " Allowed servers can also be sources for script evaluations, which may send state and MCP results."
+    : " Semantic search does not send tool results.";
+
+  const choice = await ctx.ui.select("Configure Jev semantic search", [
+    `Use all ${servers.length} enabled servers (default)`,
+    "Restrict to selected servers",
+    "Cancel",
+  ]);
+  if (!choice || choice === "Cancel") return false;
+
+  let allowedServers: string[];
+  if (choice.startsWith("Use all ")) {
+    const confirmed = await ctx.ui.confirm(
+      "Share MCP tool metadata with Jev?",
+      `Semantic searches send the query text, server names, tool paths, tool names, and descriptions from ${servers.length} servers to TypeSafe.${payloadDisclosure}`,
+    );
+    if (!confirmed) return false;
+    allowedServers = servers;
+  } else {
+    allowedServers = [];
+    for (const server of servers) {
+      if (await ctx.ui.confirm(
+        `Allow ${server}?`,
+        `Semantic searches send the query text, server name, tool paths, tool names, and descriptions to TypeSafe.${payloadDisclosure}`,
+      )) allowedServers.push(server);
+    }
+    if (allowedServers.length === 0) {
+      ctx.ui.notify("Jev setup cancelled because no servers were allowed.", "info");
+      return false;
+    }
+  }
+
+  try {
+    const result = writeJevSemanticSearchConfig(configOverridePath, ctx.cwd, allowedServers, state.config.settings?.jev);
+    ctx.ui.notify(
+      result.changed
+        ? `Jev semantic search configured for ${allowedServers.length} server${allowedServers.length === 1 ? "" : "s"}. Reloading Pi…`
+        : "Jev semantic search is already configured for those servers.",
+      "info",
+    );
+    return result.changed;
+  } catch (error) {
+    ctx.ui.notify(`Jev setup failed: ${formatTerminalError(error)}`, "error");
+    return false;
+  }
+}
+
 export async function showStatus(state: McpExtensionState, ctx: ExtensionContext): Promise<void> {
   if (!ctx.hasUI) return;
 
@@ -194,11 +285,11 @@ export async function reconnectServer(
   }
 
   try {
-    await state.manager.close(name);
     state.owner?.throwIfInactive();
-    const connection = signal
-      ? await state.manager.connect(name, definition, signal)
-      : await state.manager.connect(name, definition);
+    const current = state.manager.getConnection(name);
+    const connection = current
+      ? await state.manager.reconnect(name, definition, current, signal)
+      : await state.manager.connect(name, definition, signal);
     state.owner?.throwIfInactive();
     if (connection.status === "needs-auth") {
       if (ui) {

package/node_modules/pi-mcp-adapter/config.ts

@@ -1,5 +1,5 @@
 // config.ts - Config loading with import support
-import { existsSync, readFileSync, realpathSync, statSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse as parseToml } from "smol-toml";
@@ -9,6 +9,7 @@ import { getAgentPluginSummaries, loadAgentPluginConfigs, type AgentPluginSummar
 import { cloneBuiltInAgentPluginEntry, isBuiltInAgentPlugin, mergeBuiltInAgentPluginEntries } from "./agent-plugin-provenance.ts";
 import { loadClaudePluginBundles } from "./claude-plugin-loader.ts";
 import { loadPackageMcpConfigs } from "./package-mcp-loader.ts";
+import { validateJevSettings } from "./jev-client.ts";
 import { formatServerNamespace, isServerDisabled, type ClaudePluginConfig, type HostConfigDiscovery, type McpConfig, type ServerEntry, type McpSettings, type ImportKind, type ServerProvenance } from "./types.ts";
 import { parseJsonWithComments, toStringRecord } from "./utils.ts";
 
@@ -846,11 +847,21 @@ function validateConfig(raw: unknown): McpConfig {
   return {
     mcpServers: toServerEntries(raw.mcpServers ?? raw["mcp-servers"]),
     ...(Array.isArray(raw.imports) ? { imports: raw.imports as ImportKind[] } : {}),
-    ...(raw.settings !== undefined ? { settings: raw.settings as McpSettings } : {}),
+    ...(raw.settings !== undefined ? { settings: parseSettings(raw.settings) } : {}),
     ...(raw.claudePlugins !== undefined ? { claudePlugins: parseClaudePlugins(raw.claudePlugins) } : {}),
   };
 }
 
+function parseSettings(value: unknown): McpSettings {
+  if (!isRecord(value)) throw new Error("settings must be an object");
+  const settings = { ...value } as McpSettings;
+  if (value.jev !== undefined) {
+    validateJevSettings(value.jev);
+    settings.jev = value.jev as NonNullable<McpSettings["jev"]>;
+  }
+  return settings;
+}
+
 function parseClaudePlugins(value: unknown): ClaudePluginConfig[] {
   if (!Array.isArray(value)) {
     console.warn("Invalid claudePlugins config: expected an array");
@@ -1139,11 +1150,67 @@ function readRawConfigObject(filePath: string): Record<string, unknown> {
   }
 }
 
+function writeConfigText(writePath: string, text: string): void {
+  let mode: number | undefined;
+  try {
+    writePath = realpathSync(writePath);
+    mode = statSync(writePath).mode & 0o777;
+  } catch {}
+  mkdirSync(dirname(writePath), { recursive: true });
+  const tmpPath = `${writePath}.${process.pid}.tmp`;
+  rmSync(tmpPath, { force: true });
+  try {
+    writeFileSync(tmpPath, text, mode === undefined ? "utf-8" : { encoding: "utf-8", mode });
+    if (mode !== undefined) chmodSync(tmpPath, mode);
+    renameSync(tmpPath, writePath);
+  } catch (error) {
+    try { rmSync(tmpPath, { force: true }); } catch {}
+    throw error;
+  }
+}
+
 function writeRawConfigObject(filePath: string, raw: Record<string, unknown>): void {
-  mkdirSync(dirname(filePath), { recursive: true });
-  const tmpPath = `${filePath}.${process.pid}.tmp`;
-  writeFileSync(tmpPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
-  renameSync(tmpPath, filePath);
+  writeConfigText(filePath, `${JSON.stringify(raw, null, 2)}\n`);
+}
+
+export function writeSharedConfigText(filePath: string, text: string): void {
+  if (!isRecord(parseJsonWithComments(text))) throw new Error("top-level value must be an object");
+  writeConfigText(filePath, text);
+}
+
+export function writeJevSemanticSearchConfig(
+  overridePath: string | undefined,
+  cwd: string,
+  allowedServers: string[],
+  effectiveJev?: unknown,
+): { path: string; changed: boolean } {
+  const filePath = overridePath ? getPiGlobalConfigPath(overridePath) : getProjectPiConfigPath(cwd);
+  let raw: Record<string, unknown> = {};
+  if (existsSync(filePath)) {
+    try {
+      const parsed = parseJsonWithComments(readFileSync(filePath, "utf8"));
+      if (!isRecord(parsed)) throw new Error("top-level value must be an object");
+      raw = parsed;
+    } catch (error) {
+      throw new Error(`Failed to update Jev settings at ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+  }
+  if (raw.settings !== undefined && !isRecord(raw.settings)) {
+    throw new Error(`Failed to update Jev settings at ${filePath}: settings must be an object`);
+  }
+  const settings = raw.settings as Record<string, unknown> | undefined;
+  const currentJev = settings?.jev;
+  if (currentJev !== undefined && currentJev !== false && !isRecord(currentJev)) {
+    throw new Error(`Failed to update Jev settings at ${filePath}: settings.jev must be an object or false`);
+  }
+  const jev = isRecord(effectiveJev) ? effectiveJev : isRecord(currentJev) ? currentJev : {};
+  const nextServers = [...new Set(allowedServers)].sort((a, b) => a.localeCompare(b));
+  const nextJev = { ...jev, semanticSearch: true, allowedServers: nextServers };
+  validateJevSettings(nextJev);
+  if (isRecord(currentJev) && JSON.stringify(currentJev) === JSON.stringify(nextJev)) return { path: filePath, changed: false };
+  raw.settings = { ...settings, jev: nextJev };
+  writeRawConfigObject(filePath, raw);
+  return { path: filePath, changed: true };
 }
 
 function getServersObject(raw: Record<string, unknown>): Record<string, ServerEntry> {

package/node_modules/pi-mcp-adapter/direct-tool-surface.ts

@@ -1,6 +1,6 @@
 import { Check, Errors } from "typebox/value";
 import type { DirectToolSpec, McpConfig, ToolPrefix } from "./types.ts";
-import { createToolSelectorCandidateIndex, formatToolName, getToolNameCandidates, isServerDisabled, isToolAllowed, resolveToolPrefix } from "./types.ts";
+import { createToolSelectorCandidateIndex, formatToolName, getToolNameCandidates, isServerDisabled, isToolAllowed, resolveToolPrefix, resolveUniqueNameOwnership } from "./types.ts";
 import type { MetadataCache } from "./metadata-cache.ts";
 import { isServerCacheValid, parseDirectToolSelectors } from "./metadata-cache.ts";
 export { getMissingConfiguredDirectToolServers } from "./metadata-cache.ts";
@@ -10,6 +10,13 @@ import { resourceNameToToolName } from "./resource-tools.ts";
 const BUILTIN_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
 export const DIRECT_TOOLS_ADVISORY_THRESHOLD = 75;
 
+export function getLargeDirectToolsAdvisory(config: McpConfig, specs: readonly DirectToolSpec[]): string | undefined {
+  if (config.settings?.warnOnLargeDirectTools === false) return undefined;
+  const eagerCount = specs.filter((spec) => !spec.lazy).length;
+  if (eagerCount < DIRECT_TOOLS_ADVISORY_THRESHOLD) return undefined;
+  return `MCP: ${eagerCount} direct tools resolved. Each direct tool adds prompt context; README guidance recommends targeted sets of 5-20 tools and using the proxy or an explicit string[] when 75+ direct tools would be registered. Set settings.warnOnLargeDirectTools to false to hide this advisory.`;
+}
+
 /**
  * Recover one model-emitted JSON layer for schema-declared object and array
  * properties, then validate the complete input against the same schema.
@@ -28,14 +35,14 @@ export function prepareDirectToolArguments(inputSchema: unknown, args: unknown):
     for (const [name, propertySchema] of Object.entries(properties)) {
       if (!Object.hasOwn(input, name) || typeof input[name] !== "string"
         || !propertySchema || typeof propertySchema !== "object" || Array.isArray(propertySchema)) continue;
-      const expectedType = (propertySchema as Record<string, unknown>).type;
-      if (expectedType !== "object" && expectedType !== "array") continue;
+      // A valid string may be intentional (for example, string | object).
+      // Only recover JSON when the advertised property rejects the raw value.
+      if (Check(propertySchema as never, input[name])) continue;
       try {
         const parsed: unknown = JSON.parse(input[name] as string);
-        const matches = expectedType === "array"
-          ? Array.isArray(parsed)
-          : parsed !== null && typeof parsed === "object" && !Array.isArray(parsed);
-        if (matches) {
+        const isContainer = Array.isArray(parsed)
+          || (parsed !== null && typeof parsed === "object");
+        if (isContainer && Check(propertySchema as never, parsed)) {
           prepared ??= { ...input };
           prepared[name] = parsed;
         }
@@ -73,8 +80,6 @@ export function resolveDirectTools(
   const specs: DirectToolSpec[] = [];
   if (!cache) return specs;
 
-  const seenNames = new Set<string>();
-
   const envSelection = envOverride ? parseDirectToolSelectors(envOverride) : null;
   const globalDirect = config.settings?.directTools;
 
@@ -139,11 +144,6 @@ export function resolveDirectTools(
         console.warn(`MCP: skipping direct tool "${prefixedName}" (collides with builtin)`);
         continue;
       }
-      if (seenNames.has(prefixedName)) {
-        console.warn(`MCP: skipping duplicate direct tool "${prefixedName}" from "${serverName}"`);
-        continue;
-      }
-      seenNames.add(prefixedName);
       specs.push({
         ...(lazy ? { lazy: true } : {}),
         serverName,
@@ -166,11 +166,6 @@ export function resolveDirectTools(
           console.warn(`MCP: skipping direct resource tool "${prefixedName}" (collides with builtin)`);
           continue;
         }
-        if (seenNames.has(prefixedName)) {
-          console.warn(`MCP: skipping duplicate direct resource tool "${prefixedName}" from "${serverName}"`);
-          continue;
-        }
-        seenNames.add(prefixedName);
         specs.push({
           ...(lazy ? { lazy: true } : {}),
           serverName,
@@ -183,17 +178,16 @@ export function resolveDirectTools(
     }
   }
 
-  for (const spec of specs) reservedNames?.add(spec.prefixedName);
+  const ownership = resolveUniqueNameOwnership(specs, (spec) => spec.prefixedName);
+  for (const [name, colliding] of ownership.collisions) {
+    console.warn(`MCP: skipping colliding direct name "${name}" from ${colliding.map((spec) => `"${spec.serverName}"`).join(", ")}`);
+  }
+  const uniqueSpecs = ownership.unique;
+  for (const spec of uniqueSpecs) reservedNames?.add(spec.prefixedName);
 
   const emittedSpecs = unavailableServers.size === 0
-    ? specs
-    : specs.filter((spec) => !unavailableServers.has(spec.serverName));
-
-  // Lazy specs cost nothing at turn start, so they do not count toward the advisory.
-  const eagerCount = emittedSpecs.filter((spec) => !spec.lazy).length;
-  if (config.settings?.warnOnLargeDirectTools !== false && eagerCount >= DIRECT_TOOLS_ADVISORY_THRESHOLD) {
-    console.warn(`MCP: ${eagerCount} direct tools resolved. Each direct tool adds prompt context; README guidance recommends targeted sets of 5-20 tools and using the proxy or an explicit string[] when 75+ direct tools would be registered. Set settings.warnOnLargeDirectTools to false to hide this advisory.`);
-  }
+    ? uniqueSpecs
+    : uniqueSpecs.filter((spec) => !unavailableServers.has(spec.serverName));
 
   return emittedSpecs;
 }