pi-provider-litellm 3.3.0 → 4.0.0

package/src/mcp-tools.ts

@@ -1,1536 +0,0 @@
-import { createHash, createHmac, randomBytes } from "node:crypto";
-import type { JsonValue, Static, TSchema } from "@earendil-works/pi-ai";
-import { Type } from "@earendil-works/pi-ai";
-import {
-  defineTool,
-  type ExtensionContext,
-  type ToolDefinition,
-  type ToolExposure,
-} from "@earendil-works/pi-coding-agent";
-import { normalizeBaseUrl } from "./discover.js";
-import type { LiteLLMMcpTool, LiteLLMRuntimeAuth, McpToolAnnotations } from "./types.js";
-
-const LIST_TIMEOUT_MS = 10_000;
-const CALL_TIMEOUT_MS = 30_000;
-const MAX_DISCOVERY_BODY_BYTES = 5 * 1024 * 1024;
-const MAX_DISCOVERY_ENTRIES = 10_000;
-const MAX_CALL_BODY_BYTES = 5 * 1024 * 1024;
-const MAX_REGISTERED_TOOLS = 512;
-const MAX_DESCRIPTION_BYTES = 4 * 1024;
-const MAX_SCHEMA_BYTES = 64 * 1024;
-const MAX_SCHEMA_DEPTH = 16;
-const MAX_RESULT_BYTES = 64 * 1024;
-// Pi 0.99 caps its own structured bash results at the same size.
-const MAX_STRUCTURED_RESULT_BYTES = 1024 * 1024;
-const MAX_TOOL_NAME_LENGTH = 64;
-const TOOL_NAME_HASH_LENGTH = 10;
-const MAX_LABEL_BYTES = 256;
-const MAX_DETAIL_BYTES = 256;
-const MAX_ERROR_WALK_DEPTH = 16;
-const MAX_DIAGNOSTIC_SAMPLES = 5;
-const MAX_DIAGNOSTIC_CAUSE_BYTES = 200;
-const INVALID_ENTRY_IDENTITY_BUFFER_BYTES = 64 * 1024;
-const TRUNCATION_MARKER = "\n[truncated by pi-provider-litellm]";
-const DESCRIPTION_TRUNCATION_MARKER = "… [truncated]";
-const SHORT_TRUNCATION_MARKER = "…";
-
-// `incidentScope` separates the suppression state of catalogs from different providers, so one
-// provider's clean pass cannot clear, and its differing report cannot re-trigger, another's incident.
-type DiagnosticSink = ((message: string) => void) & { readonly incidentScope?: string };
-
-interface RawLiteLLMMcpTool {
-  name?: unknown;
-  description?: unknown;
-  inputSchema?: unknown;
-  input_schema?: unknown;
-  annotations?: unknown;
-  server_id?: unknown;
-  server_name?: unknown;
-  mcp_info?: {
-    server_id?: unknown;
-    server_name?: unknown;
-    description?: unknown;
-  };
-}
-
-// The exposure values of a Pi `mcp.json` server entry, so `litellm.mcp.exposure` and
-// `litellm.mcp.toolExposure` mean what Pi's own MCP configuration means.
-export type McpExposure = "direct" | "codemode" | "codemode-deferred" | "deferred" | "hidden";
-const MCP_EXPOSURES: readonly McpExposure[] = ["direct", "codemode", "codemode-deferred", "deferred", "hidden"];
-
-export interface McpExposurePolicy {
-  // Exposure of every tool without a `toolExposure` match.
-  exposure: McpExposure;
-  // `[key, exposure]` in settings order. A key without `/` matches the tool name as the server offers
-  // it; a key with `/` matches `<server>/<tool>`. `*` matches any characters.
-  toolExposure: ReadonlyArray<readonly [string, McpExposure]>;
-}
-
-export const DEFAULT_MCP_EXPOSURE_POLICY: McpExposurePolicy = { exposure: "direct", toolExposure: [] };
-
-function isMcpExposure(value: unknown): value is McpExposure {
-  return typeof value === "string" && (MCP_EXPOSURES as readonly string[]).includes(value);
-}
-
-// Reads `exposure` and `toolExposure` from the `litellm.mcp` settings block. Unusable values fall back
-// to `direct`, today's behavior, and are reported in extension-owned text.
-export function parseMcpExposurePolicy(raw: unknown): { policy: McpExposurePolicy; warnings: string[] } {
-  const settings = asRecord(raw);
-  const warnings: string[] = [];
-  const expected = MCP_EXPOSURES.map((value) => JSON.stringify(value)).join(", ");
-  let exposure: McpExposure = "direct";
-  if (settings?.exposure !== undefined) {
-    if (isMcpExposure(settings.exposure)) exposure = settings.exposure;
-    else warnings.push(`litellm.mcp.exposure must be one of ${expected}; using "direct".`);
-  }
-  const toolExposure: Array<readonly [string, McpExposure]> = [];
-  if (settings?.toolExposure !== undefined) {
-    const overrides = asRecord(settings.toolExposure);
-    if (!overrides)
-      warnings.push("litellm.mcp.toolExposure must be an object mapping tool name patterns to exposures; ignoring it.");
-    else
-      for (const [key, value] of Object.entries(overrides)) {
-        if (isMcpExposure(value)) toolExposure.push([key, value]);
-        else warnings.push(`litellm.mcp.toolExposure[${JSON.stringify(key)}] must be one of ${expected}; ignoring it.`);
-      }
-  }
-  return { policy: { exposure, toolExposure }, warnings };
-}
-
-// Glob match where `*` matches any characters; segments must appear in order without overlapping.
-function wildcardMatches(pattern: string, subject: string): boolean {
-  const segments = pattern.split("*");
-  if (segments.length === 1) return pattern === subject;
-  const first = segments[0] ?? "";
-  const last = segments[segments.length - 1] ?? "";
-  if (!subject.startsWith(first) || !subject.endsWith(last)) return false;
-  const end = subject.length - last.length;
-  let position = first.length;
-  for (const segment of segments.slice(1, -1)) {
-    const index = subject.indexOf(segment, position);
-    if (index === -1 || index + segment.length > end) return false;
-    position = index + segment.length;
-  }
-  return position <= end;
-}
-
-// As in Pi's mcp.json: an exact key wins over patterns, and among patterns the first in settings
-// order wins. A `<server>/<tool>` exact key is more specific than a bare tool name.
-export function resolveMcpExposure(policy: McpExposurePolicy, serverName: string, toolName: string): McpExposure {
-  const qualified = `${serverName}/${toolName}`;
-  let qualifiedExact: McpExposure | undefined;
-  let bareExact: McpExposure | undefined;
-  let firstPattern: McpExposure | undefined;
-  for (const [key, exposure] of policy.toolExposure) {
-    const isQualified = key.includes("/");
-    const subject = isQualified ? qualified : toolName;
-    if (!key.includes("*")) {
-      if (key !== subject) continue;
-      if (isQualified) qualifiedExact ??= exposure;
-      else bareExact ??= exposure;
-    } else if (firstPattern === undefined && wildcardMatches(key, subject)) {
-      firstPattern = exposure;
-    }
-  }
-  return qualifiedExact ?? bareExact ?? firstPattern ?? policy.exposure;
-}
-
-// Pi's tool API has one `deferred`; the two deferred MCP exposures differ only in which discovery
-// tool (codemode or tool_search) is activated to reach them.
-export function toToolExposure(exposure: McpExposure): ToolExposure {
-  return exposure === "codemode-deferred" ? "deferred" : exposure;
-}
-
-interface PreparedTool {
-  tool: LiteLLMMcpTool;
-  name: string;
-  parameters: TSchema;
-  syntheticArgsEnvelope: boolean;
-  exposure: McpExposure;
-}
-
-interface InvalidMcpTool {
-  label: string;
-  identity: string;
-}
-
-export class McpAccessDeniedError extends Error {
-  constructor() {
-    super("MCP access denied");
-    this.name = "McpAccessDeniedError";
-  }
-}
-
-// Why a discovered MCP tool was not registered as the proxy described it.
-// `schema-envelope` is a degradation, not a loss: the tool still registers, with the
-// extension-owned envelope in place of a schema that could not be proven safe.
-export type McpDropReason = "invalid-tool" | "duplicate-identity" | "invalid-schema" | "name-collision";
-export type McpDegradeReason = "schema-envelope";
-export type McpIncidentReason = McpDropReason | McpDegradeReason;
-
-const DROP_REASON_TEXT: Readonly<Record<McpDropReason, string>> = {
-  "invalid-tool": "a missing name or server identity",
-  "duplicate-identity": "a repeated valid identity (the first valid occurrence of each is the one registered)",
-  "invalid-schema": "an invalid or oversized input schema",
-  "name-collision": "a colliding generated Pi name",
-};
-
-const DEGRADE_REASON_TEXT: Readonly<Record<McpDegradeReason, string>> = {
-  "schema-envelope": "a schema that could not be proven free of proxy-supplied regexes or references",
-};
-
-const INCIDENT_REASON_TEXT: Readonly<Record<McpIncidentReason, string>> = {
-  ...DROP_REASON_TEXT,
-  ...DEGRADE_REASON_TEXT,
-};
-
-export interface McpPreparationReport {
-  // Raw tool entries the proxy returned, before any normalization.
-  discovered: number;
-  // LiteLLM returned the usable subset from servers that answered while reporting another failed.
-  partialFailure: boolean;
-  // Tools that will be registered, whatever parameter shape they ended up with.
-  prepared: number;
-  // Of `prepared`, how many carry the extension-owned envelope rather than a proxy-supplied schema.
-  // Includes both the schemaless path and hazard degradations; `degraded` counts only the latter.
-  enveloped: number;
-  // Tools discarded because the registered-tool cap was reached.
-  overflow: number;
-  // Bounded generated names for the overflow membership, used to detect catalog changes.
-  overflowTools: string[];
-  dropped: Array<{ reason: McpDropReason; tools: string[] }>;
-  // Non-printed identities paired with `dropped`, used to detect membership changes safely.
-  dropMemberships: Array<{ reason: McpDropReason; identities: string[] }>;
-  degraded: Array<{ reason: McpDegradeReason; tools: string[] }>;
-  // Distinct exposures of the prepared tools, so the caller can activate codemode or tool_search.
-  exposures: McpExposure[];
-}
-
-// Bounded discovery result: `raw` is what the proxy returned, so losses can be reconciled.
-export interface McpDiscovery {
-  raw: number;
-  tools: LiteLLMMcpTool[];
-  partialFailure: boolean;
-  // Entries dropped by normalization, with safe display labels and non-displayed identities.
-  invalid: InvalidMcpTool[];
-}
-
-// Incident-aware suppression: an incident class is re-reported whenever its message changes
-// (different count or different tools), so a stable proxy stays quiet across refreshes while a
-// changed one is always surfaced. Keys come from a fixed set of classes, so this cannot grow
-// without bound.
-const lastEmittedIncident = new Map<string, string>();
-
-// Reports an incident unless its identity is unchanged since the last report of that class.
-// `identity` must capture everything an operator would want to hear about again — for tool
-// incidents that is the full sorted membership, not just the bounded sample that gets printed.
-function emitSafetyDiagnostic(
-  incident: string,
-  message: string,
-  identity: string = message,
-  onDiagnostic: DiagnosticSink = (line) => {
-    process.stderr.write(line);
-  },
-): void {
-  const scope = onDiagnostic.incidentScope;
-  const key = scope === undefined ? incident : `${scope}\0${incident}`;
-  if (lastEmittedIncident.get(key) === identity) return;
-  lastEmittedIncident.set(key, identity);
-  onDiagnostic(`LiteLLM MCP${scope === undefined ? "" : ` (${JSON.stringify(scope)})`}: ${message}\n`);
-}
-
-function clearIncident(incident: string, onDiagnostic?: DiagnosticSink): void {
-  const scope = onDiagnostic?.incidentScope;
-  lastEmittedIncident.delete(scope === undefined ? incident : `${scope}\0${incident}`);
-}
-
-function membershipIdentity(tools: readonly string[]): string {
-  return createHash("sha256")
-    .update([...tools].sort().join("\0"))
-    .digest("hex")
-    .slice(0, 16);
-}
-
-function plural(count: number, singular: string, pluralForm = `${singular}s`): string {
-  return `${count} ${count === 1 ? singular : pluralForm}`;
-}
-
-// Renders a bounded sample list. Names are already sanitized to `[a-z0-9_]`, so they are safe for stderr.
-function sampleList(names: readonly string[]): string {
-  const shown = names.slice(0, MAX_DIAGNOSTIC_SAMPLES);
-  const remainder = names.length - shown.length;
-  return remainder > 0 ? `${shown.join(", ")} (+${remainder} more)` : shown.join(", ");
-}
-
-// Reports a registration pass that Pi aborted.
-//
-// Pi's `registerTool` is a synchronous replace-by-name whose only throw comes from a staleness
-// check that is never reset, so a throw means the pass is over, not that one tool was rejected.
-// `cause` is Pi-authored and bounded; no proxy schema, description, or body reaches stderr.
-export function reportMcpRegistrationFatal(
-  registered: number,
-  attempted: number,
-  cause: unknown,
-  onDiagnostic?: DiagnosticSink,
-): void {
-  const causeText = truncateUtf8(
-    cause instanceof Error ? cause.message : String(cause),
-    MAX_DIAGNOSTIC_CAUSE_BYTES,
-    SHORT_TRUNCATION_MARKER,
-  );
-  emitSafetyDiagnostic(
-    "registration-fatal",
-    `registration stopped after ${registered} of ${plural(attempted, "MCP tool")}; ` +
-      `no further attempts will be made by this extension instance (${causeText}).`,
-    undefined,
-    onDiagnostic,
-  );
-}
-
-// A successful pass clears any fatal incident left by an earlier extension instance, so the same
-// failure is reported if it later recurs.
-export function reportMcpRegistrationSuccess(onDiagnostic?: DiagnosticSink): void {
-  clearIncident("registration-fatal", onDiagnostic);
-}
-
-// `registered` is the generated names of the tools that survived, so a failure that changes
-// which servers answered is reported again even when the count happens to stay the same.
-export function reportMcpPartialDiscovery(
-  partialFailure: boolean,
-  registered: readonly string[],
-  onDiagnostic?: DiagnosticSink,
-): void {
-  if (!partialFailure) {
-    clearIncident("discovery-partial-failure", onDiagnostic);
-    return;
-  }
-  emitSafetyDiagnostic(
-    "discovery-partial-failure",
-    `proxy reported a partial server failure; ${plural(registered.length, "tool")} registered.`,
-    `discovery-partial-failure:${membershipIdentity(registered)}`,
-    onDiagnostic,
-  );
-}
-
-// Reports a discovery that yielded no registrable tool, so the silence is explained. A pass that did
-// register something clears the incident, so a later recurrence is reported rather than suppressed as
-// an unchanged message.
-export function reportMcpCatalogOutcome(raw: number, registered: number, onDiagnostic?: DiagnosticSink): void {
-  if (registered > 0) {
-    clearIncident("empty-catalog", onDiagnostic);
-    return;
-  }
-  emitSafetyDiagnostic(
-    "empty-catalog",
-    `no MCP tools were registered from ${plural(raw, "raw entry", "raw entries")} returned by the proxy.`,
-    `empty-catalog:${raw}`,
-    onDiagnostic,
-  );
-}
-
-// Random per process, never logged and never persisted. The catalog identity it feeds is only ever
-// compared with other identities computed in the same process, so it does not need to be stable
-// across runs — and a random salt means even a leaked identity cannot be dictionary-attacked back to
-// the credential, which a bare digest of a short key would not prevent.
-const credentialIdentitySalt = randomBytes(32);
-
-// A non-reversible stand-in for the credential material behind an MCP catalog.
-//
-// Covers the headers as well as the key: `LITELLM_HEADERS` can carry its own authorization material,
-// so fingerprinting the key alone would leave secrets in the identity. Any change to either yields a
-// different fingerprint, which is what the catalog needs in order to notice a credential change.
-// Durable pause records supply a private agent-directory salt; ordinary catalog identities keep
-// using the per-process default above.
-export function credentialFingerprint(
-  apiKey: string,
-  headers?: Record<string, string>,
-  salt: Uint8Array = credentialIdentitySalt,
-): string {
-  const material = JSON.stringify([
-    apiKey,
-    Object.entries(headers ?? {}).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)),
-  ]);
-  return createHmac("sha256", salt).update(material).digest("hex").slice(0, 32);
-}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
-}
-
-function boundedSignal(timeoutMs: number, parent?: AbortSignal): AbortSignal {
-  const timeout = AbortSignal.timeout(timeoutMs);
-  return parent ? AbortSignal.any([parent, timeout]) : timeout;
-}
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
-function byteLength(value: string): number {
-  return Buffer.byteLength(value, "utf8");
-}
-
-function truncateUtf8(value: string, maxBytes: number, marker: string): string {
-  if (byteLength(value) <= maxBytes) return value;
-  const markerBytes = byteLength(marker);
-  const source = Buffer.from(value, "utf8");
-  let end = Math.max(0, maxBytes - markerBytes);
-  while (end > 0 && (source[end] & 0xc0) === 0x80) end -= 1;
-  return `${source.subarray(0, end).toString("utf8")}${marker}`;
-}
-
-async function readBoundedText(
-  response: Response,
-  limit: number,
-  surface: string,
-  onDiagnostic?: DiagnosticSink,
-): Promise<string> {
-  if (!response.body) {
-    clearIncident(`${surface}-body-cap`, onDiagnostic);
-    return "";
-  }
-  const reader = response.body.getReader();
-  const chunks: Uint8Array[] = [];
-  let size = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      size += value.byteLength;
-      if (size > limit) {
-        // Build the diagnostic and the error before cancelling: `cancel()` rejects with the stream's
-        // stored error if the body errored concurrently, which would otherwise discard both.
-        emitSafetyDiagnostic(
-          `${surface}-body-cap`,
-          `${surface} response exceeded its ${limit}-byte limit.`,
-          undefined,
-          onDiagnostic,
-        );
-        const capError = new Error(`${surface} response exceeds its ${limit}-byte limit`);
-        await reader.cancel().catch(() => undefined);
-        throw capError;
-      }
-      chunks.push(value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  // A response that stayed within the cap clears the incident, so a later breach on this surface
-  // is reported again instead of being suppressed as an unchanged message.
-  clearIncident(`${surface}-body-cap`, onDiagnostic);
-  return Buffer.concat(
-    chunks.map((chunk) => Buffer.from(chunk)),
-    size,
-  ).toString("utf8");
-}
-
-function parseJson(text: string, surface: string): unknown {
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    throw new Error(`${surface} returned invalid JSON`);
-  }
-}
-
-function skipJsonWhitespace(text: string, start: number): number {
-  let index = start;
-  while (index < text.length && /\s/.test(text[index] ?? "")) index += 1;
-  return index;
-}
-
-function jsonStringEnd(text: string, start: number): number | undefined {
-  if (text[start] !== '"') return undefined;
-  for (let index = start + 1; index < text.length; index += 1) {
-    if (text[index] === "\\") {
-      index += 1;
-      continue;
-    }
-    if (text[index] === '"') return index + 1;
-  }
-  return undefined;
-}
-
-// Advances over one JSON value without materializing it. Full syntax validation remains JSON.parse's
-// job; this scanner only needs enough structure to locate a top-level `tools` array before parsing.
-function jsonValueEnd(text: string, start: number): number {
-  const first = text[start];
-  if (first === '"') return jsonStringEnd(text, start) ?? text.length;
-  if (first !== "[" && first !== "{") {
-    let index = start;
-    while (index < text.length && !/[\s,}\]]/.test(text[index] ?? "")) index += 1;
-    return index;
-  }
-
-  let depth = 1;
-  for (let index = start + 1; index < text.length; index += 1) {
-    const character = text[index];
-    if (character === '"') {
-      index = (jsonStringEnd(text, index) ?? text.length) - 1;
-      continue;
-    }
-    if (character === "[" || character === "{") depth += 1;
-    else if (character === "]" || character === "}") {
-      depth -= 1;
-      if (depth === 0) return index + 1;
-    }
-  }
-  return text.length;
-}
-
-function assertJsonArrayEntryLimit(text: string, start: number): void {
-  let depth = 1;
-  let expectingEntry = true;
-  let entries = 0;
-  const recordEntry = (): void => {
-    entries += 1;
-    expectingEntry = false;
-    if (entries > MAX_DISCOVERY_ENTRIES) {
-      throw new Error(`MCP discovery exceeds its ${MAX_DISCOVERY_ENTRIES}-entry limit`);
-    }
-  };
-
-  for (let index = start + 1; index < text.length; index += 1) {
-    const character = text[index];
-    if (character === '"') {
-      if (depth === 1 && expectingEntry) recordEntry();
-      index = (jsonStringEnd(text, index) ?? text.length) - 1;
-      continue;
-    }
-    if (character === "[" || character === "{") {
-      if (depth === 1 && expectingEntry) recordEntry();
-      depth += 1;
-      continue;
-    }
-    if (character === "]" || character === "}") {
-      depth -= 1;
-      if (depth === 0) return;
-      continue;
-    }
-    if (depth !== 1) continue;
-    if (character === ",") {
-      expectingEntry = true;
-      continue;
-    }
-    if (/\s/.test(character ?? "") || !expectingEntry) continue;
-    recordEntry();
-  }
-}
-
-// Rejects an excessive catalog before JSON.parse can allocate an object for every raw entry. Both
-// documented response shapes are handled, including duplicate or escaped top-level `tools` keys.
-// The response byte cap bounds this lexical pass, and the entry cap makes the hostile-array path
-// stop after the first 10,001 primitive values rather than traversing the complete payload.
-function assertDiscoveryEntryLimit(text: string): void {
-  let index = skipJsonWhitespace(text, 0);
-  if (text[index] === "[") {
-    assertJsonArrayEntryLimit(text, index);
-    return;
-  }
-  if (text[index] !== "{") return;
-  index += 1;
-
-  while (index < text.length) {
-    index = skipJsonWhitespace(text, index);
-    if (text[index] === "}") return;
-    const keyStart = index;
-    const keyEnd = jsonStringEnd(text, keyStart);
-    if (keyEnd === undefined) return;
-    index = skipJsonWhitespace(text, keyEnd);
-    if (text[index] !== ":") return;
-    index = skipJsonWhitespace(text, index + 1);
-
-    let key: unknown;
-    try {
-      key = JSON.parse(text.slice(keyStart, keyEnd));
-    } catch {
-      return;
-    }
-    if (key === "tools" && text[index] === "[") assertJsonArrayEntryLimit(text, index);
-    index = skipJsonWhitespace(text, jsonValueEnd(text, index));
-    if (text[index] === ",") {
-      index += 1;
-      continue;
-    }
-    return;
-  }
-}
-
-function parseDiscoveryJson(text: string): unknown {
-  assertDiscoveryEntryLimit(text);
-  return parseJson(text, "MCP discovery");
-}
-
-const ANNOTATION_HINTS = ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"] as const;
-
-// Only the boolean hints, as Pi's own MCP client keeps them; other proxy-supplied annotation fields
-// (such as `title`) never reach Pi.
-function toolAnnotations(value: unknown): McpToolAnnotations | undefined {
-  const raw = asRecord(value);
-  if (!raw) return undefined;
-  const hints: McpToolAnnotations = {};
-  for (const hint of ANNOTATION_HINTS) {
-    const flag = raw[hint];
-    if (typeof flag === "boolean") hints[hint] = flag;
-  }
-  return Object.keys(hints).length > 0 ? hints : undefined;
-}
-
-function normalizeMcpTool(value: unknown): LiteLLMMcpTool | undefined {
-  const raw = asRecord(value) as RawLiteLLMMcpTool | undefined;
-  if (!raw) return undefined;
-  const name = stringValue(raw.name);
-  const serverName =
-    stringValue(raw.mcp_info?.server_name) ??
-    stringValue(raw.server_name) ??
-    stringValue(raw.mcp_info?.server_id) ??
-    stringValue(raw.server_id);
-  if (!name || !serverName) return undefined;
-  const hasInputSchema = Object.hasOwn(raw, "inputSchema");
-  const hasSnakeInputSchema = Object.hasOwn(raw, "input_schema");
-  const suppliedSchema = hasInputSchema ? raw.inputSchema : hasSnakeInputSchema ? raw.input_schema : undefined;
-  const inputSchema = asRecord(suppliedSchema);
-  const annotations = toolAnnotations(raw.annotations);
-  const serverDescription = stringValue(raw.mcp_info?.description);
-  return {
-    name,
-    server_name: serverName,
-    server_id: stringValue(raw.mcp_info?.server_id) ?? stringValue(raw.server_id) ?? serverName,
-    description: stringValue(raw.description) ?? name,
-    input_schema: inputSchema ?? {},
-    // Present but not an object: malformed, as distinct from absent.
-    ...(inputSchema === undefined && (hasInputSchema || hasSnakeInputSchema) ? { input_schema_malformed: true } : {}),
-    ...(annotations ? { annotations } : {}),
-    ...(serverDescription ? { server_description: serverDescription } : {}),
-  };
-}
-
-// Rejected entries have no registered name; positional labels keep stderr free of proxy text.
-function invalidToolLabel(index: number): string {
-  return `entry_${index}`;
-}
-
-// This structural encoding never retains or prints raw entry text. Length prefixes preserve
-// boundaries, while the discovery body cap bounds the amount of input hashed. Cursor frames keep
-// queued work proportional to nesting depth; each open object retains one key list rather than one
-// frame per field. The per-process salt keeps low-entropy malformed entries from being recoverable
-// by guessing.
-const invalidEntryIdentitySalt = randomBytes(32);
-const invalidEntryIdentityEncoder = new TextEncoder();
-const invalidEntryIdentityBuffer = new Uint8Array(INVALID_ENTRY_IDENTITY_BUFFER_BYTES);
-function invalidToolIdentity(value: unknown): string {
-  const digest = createHmac("sha256", invalidEntryIdentitySalt);
-  const active = new WeakSet<object>();
-
-  const writeText = (text: string): void => {
-    let remaining = text;
-    while (remaining.length > 0) {
-      const { read, written } = invalidEntryIdentityEncoder.encodeInto(remaining, invalidEntryIdentityBuffer);
-      if (written > 0) digest.update(invalidEntryIdentityBuffer.subarray(0, written));
-      if (read === 0) throw new Error("Failed to encode MCP entry identity");
-      remaining = remaining.slice(read);
-    }
-  };
-  const writeString = (text: string): void => {
-    writeText(`${byteLength(text)}:`);
-    writeText(text);
-  };
-  type IdentityPart =
-    | { kind: "value"; value: unknown }
-    | { kind: "array"; value: unknown[]; index: number }
-    | { kind: "object"; value: Record<string, unknown>; keys: string[]; index: number };
-  const pending: IdentityPart[] = [{ kind: "value", value }];
-  while (pending.length > 0) {
-    const part = pending.pop();
-    if (!part) break;
-    if (part.kind === "array") {
-      if (part.index >= part.value.length) {
-        writeText("]");
-        active.delete(part.value);
-      } else {
-        pending.push({ ...part, index: part.index + 1 });
-        pending.push({ kind: "value", value: part.value[part.index] });
-      }
-      continue;
-    }
-    if (part.kind === "object") {
-      if (part.index >= part.keys.length) {
-        writeText("}");
-        active.delete(part.value);
-      } else {
-        const key = part.keys[part.index] as string;
-        writeString(key);
-        pending.push({ ...part, index: part.index + 1 });
-        pending.push({ kind: "value", value: part.value[key] });
-      }
-      continue;
-    }
-
-    const entry = part.value;
-    if (entry === null) {
-      writeText("null;");
-    } else if (typeof entry === "string") {
-      writeText("string:");
-      writeString(entry);
-    } else if (typeof entry === "number") {
-      writeText(`number:${entry};`);
-    } else if (typeof entry === "boolean") {
-      writeText(entry ? "true;" : "false;");
-    } else if (typeof entry !== "object") {
-      writeText(`${typeof entry};`);
-    } else if (active.has(entry)) {
-      writeText("cycle;");
-    } else if (Array.isArray(entry)) {
-      active.add(entry);
-      writeText(`array:${entry.length}[`);
-      pending.push({ kind: "array", value: entry, index: 0 });
-    } else {
-      active.add(entry);
-      const value = entry as Record<string, unknown>;
-      const keys = Object.keys(value);
-      writeText(`object:${keys.length}{`);
-      pending.push({ kind: "object", value, keys, index: 0 });
-    }
-  }
-  return digest.digest("hex").slice(0, 32);
-}
-
-export async function discoverMcpTools(
-  baseUrl: string,
-  apiKey: string,
-  headers?: Record<string, string>,
-  onProgress?: (message: string) => void,
-  parentSignal?: AbortSignal,
-  allowInsecureHttp = false,
-  onDiagnostic?: DiagnosticSink,
-): Promise<McpDiscovery> {
-  parentSignal?.throwIfAborted();
-  onProgress?.("Discovering MCP tools from server...");
-  const signal = boundedSignal(LIST_TIMEOUT_MS, parentSignal);
-  try {
-    onProgress?.("Querying MCP tools/list endpoint...");
-    const response = await fetch(`${normalizeBaseUrl(baseUrl, allowInsecureHttp)}/mcp-rest/tools/list`, {
-      headers: {
-        ...headers,
-        Authorization: `Bearer ${apiKey}`,
-        "Content-Type": "application/json",
-      },
-      signal,
-    });
-    if (!response.ok) {
-      onProgress?.(`MCP tools discovery failed with status ${response.status}`);
-      if (response.status === 401 || response.status === 403) throw new McpAccessDeniedError();
-      throw new Error(`HTTP ${response.status}`);
-    }
-    const body = parseDiscoveryJson(
-      await readBoundedText(response, MAX_DISCOVERY_BODY_BYTES, "MCP discovery", onDiagnostic),
-    );
-    const bodyRecord = asRecord(body);
-    const errorTag = bodyRecord?.error;
-    // Older proxies catch their own access denial and wrap it in an HTTP 200 unexpected_error.
-    // Recognize only the fixed denial sentence; never display the proxy's message.
-    if (
-      errorTag === "access_denied" ||
-      (errorTag === "unexpected_error" &&
-        typeof bodyRecord?.message === "string" &&
-        bodyRecord.message.includes("The key is not allowed to access any MCP servers."))
-    )
-      throw new McpAccessDeniedError();
-    const partialFailure = errorTag === "partial_failure";
-    // LiteLLM reports total MCP discovery failure in an HTTP 200 envelope. Use only
-    // extension-owned text: neither its machine-readable tag nor its message is safe for stderr.
-    if (errorTag != null && !partialFailure) {
-      throw new Error(
-        errorTag === "unexpected_error"
-          ? "MCP discovery reported an unexpected proxy error"
-          : "MCP discovery reported an error",
-      );
-    }
-    // An unrecognized body shape is not the same as an empty catalog, and reporting it as "0 raw
-    // entries" would send an operator looking at the wrong thing. This check also applies to a
-    // partial-failure envelope, because LiteLLM's successful subset must still be an array.
-    const rawTools = Array.isArray(body) ? body : Array.isArray(bodyRecord?.tools) ? bodyRecord.tools : undefined;
-    if (rawTools === undefined) throw new Error("MCP discovery returned an unexpected body shape");
-    if (rawTools.length > MAX_DISCOVERY_ENTRIES) {
-      throw new Error(`MCP discovery exceeds its ${MAX_DISCOVERY_ENTRIES}-entry limit`);
-    }
-    onProgress?.(`Found ${rawTools.length} raw MCP tools, normalizing...`);
-    const tools: LiteLLMMcpTool[] = [];
-    const invalid: InvalidMcpTool[] = [];
-    // Every raw entry lands in exactly one bucket, so later counts reconcile back to `raw`.
-    rawTools.forEach((raw, index) => {
-      const tool = normalizeMcpTool(raw);
-      if (tool) tools.push(tool);
-      else invalid.push({ label: invalidToolLabel(index), identity: invalidToolIdentity(raw) });
-    });
-    onProgress?.(`Normalized ${tools.length} of ${rawTools.length} raw MCP tools`);
-    return { raw: rawTools.length, tools, invalid, partialFailure };
-  } catch (error) {
-    onProgress?.("MCP tools discovery encountered an error");
-    if (parentSignal?.aborted) throw parentSignal.reason;
-    throw error;
-  }
-}
-
-function mcpErrorMessage(value: unknown, depth = 0): string | undefined {
-  if (depth > MAX_ERROR_WALK_DEPTH) return undefined;
-  if (typeof value === "string") return value;
-  if (Array.isArray(value)) {
-    for (const entry of value) {
-      const message = mcpErrorMessage(entry, depth + 1);
-      if (message !== undefined) return message;
-    }
-    return undefined;
-  }
-  const record = asRecord(value);
-  if (!record) return undefined;
-  return (
-    stringValue(record.message) ??
-    (record.error !== value ? mcpErrorMessage(record.error, depth + 1) : undefined) ??
-    stringValue(record.text)
-  );
-}
-
-function serializeResult(value: unknown): string {
-  const serialized = JSON.stringify(value, null, 2) ?? "null";
-  return truncateUtf8(serialized, MAX_RESULT_BYTES, TRUNCATION_MARKER);
-}
-
-function mcpCallError(serverId: string, toolName: string, detail: string): Error {
-  return new Error(
-    truncateUtf8(`Error calling ${toolName} on ${serverId}: ${detail}`, MAX_RESULT_BYTES, TRUNCATION_MARKER),
-  );
-}
-
-export interface McpToolOutcome {
-  text: string;
-  structuredContent: Record<string, unknown>;
-  isError: boolean;
-}
-
-// Same shape as Pi's own MCP `createMcpResultSchema()`, which codemode detects to render
-// `CallToolResult`. Extension-owned: a proxy-supplied `outputSchema` is never forwarded.
-const MCP_RESULT_SCHEMA = {
-  type: "object",
-  properties: {
-    content: { type: "array", items: { type: "object" } },
-    isError: { type: "boolean" },
-    _meta: { type: "object" },
-  },
-  required: ["content"],
-} as unknown as TSchema;
-
-function structuredResult(result: unknown, text: string, isError: boolean): Record<string, unknown> {
-  const record = asRecord(result);
-  if (record && Array.isArray(record.content)) {
-    const { _meta: _ignored, ...rest } = record;
-    const structured = isError ? { ...rest, isError: true } : rest;
-    if (Buffer.byteLength(JSON.stringify(structured)) <= MAX_STRUCTURED_RESULT_BYTES) return structured;
-  }
-  return { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) };
-}
-
-export async function executeMcpTool(
-  baseUrl: string,
-  apiKey: string,
-  serverId: string,
-  toolName: string,
-  args: Record<string, unknown>,
-  headers?: Record<string, string>,
-  parentSignal?: AbortSignal,
-  allowInsecureHttp = false,
-  onDiagnostic?: DiagnosticSink,
-): Promise<McpToolOutcome> {
-  parentSignal?.throwIfAborted();
-  const signal = boundedSignal(CALL_TIMEOUT_MS, parentSignal);
-  let response: Response;
-  try {
-    response = await fetch(`${normalizeBaseUrl(baseUrl, allowInsecureHttp)}/mcp-rest/tools/call`, {
-      method: "POST",
-      headers: {
-        ...headers,
-        Authorization: `Bearer ${apiKey}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ server_id: serverId, name: toolName, arguments: args }),
-      signal,
-    });
-    if (!response.ok) throw mcpCallError(serverId, toolName, `HTTP ${response.status}`);
-    const body = parseJson(
-      await readBoundedText(response, MAX_CALL_BODY_BYTES, "MCP tool call", onDiagnostic),
-      "MCP tool call",
-    );
-    const bodyRecord = asRecord(body);
-    if (bodyRecord?.error != null) {
-      throw mcpCallError(serverId, toolName, mcpErrorMessage(bodyRecord.error) ?? "MCP error");
-    }
-    const result = bodyRecord && "result" in bodyRecord ? bodyRecord.result : body;
-    const resultRecord = asRecord(result);
-    if (resultRecord?.isError === true || bodyRecord?.isError === true) {
-      const message =
-        mcpErrorMessage(resultRecord?.content ?? bodyRecord?.content ?? result) ?? serializeResult(result);
-      const text = mcpCallError(serverId, toolName, message).message;
-      return { text, structuredContent: structuredResult(result, text, true), isError: true };
-    }
-    const text = serializeResult(result);
-    return { text, structuredContent: structuredResult(result, text, false), isError: false };
-  } catch (error) {
-    if (parentSignal?.aborted) throw parentSignal.reason;
-    throw error;
-  }
-}
-
-function sanitizeName(name: string): string {
-  const sanitized = name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "_")
-    .replace(/^_+|_+$/g, "");
-  return sanitized || "tool";
-}
-
-function toolIdentity(tool: LiteLLMMcpTool): string {
-  return JSON.stringify([tool.server_id ?? tool.server_name, tool.server_name, tool.name]);
-}
-
-// Derives a Pi tool name from the tool's identity alone.
-//
-// The hash is unconditional so the name is a pure function of `server_id`/`server_name`/`name`.
-// A conditional hash would make a survivor's name depend on which *other* tools happened to be in
-// the same catalog, so adding or removing a sibling would rename it — and because Pi cannot
-// unregister, the old name would linger and the model would see one tool twice.
-// An alias provider's catalog is namespaced by the provider name, in both the prefix and the hash,
-// so two providers exposing the same server never replace each other's tools.
-function buildPiToolName(tool: LiteLLMMcpTool, namespace?: string): string {
-  const identity = namespace === undefined ? toolIdentity(tool) : JSON.stringify([namespace, toolIdentity(tool)]);
-  const hash = createHash("sha256").update(identity).digest("hex").slice(0, TOOL_NAME_HASH_LENGTH);
-  const prefix = namespace === undefined ? "mcp" : `mcp_${sanitizeName(namespace)}`;
-  const base = `${prefix}_${sanitizeName(tool.server_name)}_${sanitizeName(tool.name)}`;
-  return `${base.slice(0, MAX_TOOL_NAME_LENGTH - hash.length - 1)}_${hash}`;
-}
-
-// A namespace groups one server's tools, so its name is a pure function of server identity too:
-// `My-Server` and `My_Server` sanitize alike, and long names truncate alike, so a hash keeps them apart.
-function buildNamespaceName(tool: LiteLLMMcpTool, namespace?: string): string {
-  const identity = JSON.stringify([namespace ?? null, tool.server_id ?? tool.server_name, tool.server_name]);
-  const hash = createHash("sha256").update(identity).digest("hex").slice(0, 6);
-  const prefix = namespace === undefined ? "mcp" : `mcp_${sanitizeName(namespace)}`;
-  const base = `${prefix}_${sanitizeName(tool.server_name)}`;
-  return `${base.slice(0, MAX_TOOL_NAME_LENGTH - hash.length - 1)}_${hash}`;
-}
-
-function schemaDepth(value: unknown, depth = 0): number {
-  if (!value || typeof value !== "object") return depth;
-  if (depth > MAX_SCHEMA_DEPTH) return depth;
-  const values = Array.isArray(value) ? value : Object.values(value as Record<string, unknown>);
-  return values.reduce((maximum, child) => Math.max(maximum, schemaDepth(child, depth + 1)), depth);
-}
-
-const DIRECT_SCHEMA_KEYWORDS = [
-  "additionalItems",
-  "additionalProperties",
-  "contains",
-  "contentSchema",
-  "else",
-  "if",
-  "not",
-  "propertyNames",
-  "then",
-  "unevaluatedItems",
-  "unevaluatedProperties",
-] as const;
-const SCHEMA_ARRAY_KEYWORDS = ["allOf", "anyOf", "oneOf", "prefixItems"] as const;
-const SCHEMA_MAP_KEYWORDS = ["$defs", "definitions", "dependentSchemas", "patternProperties", "properties"] as const;
-
-// TypeBox compiles a schema's `pattern` and the keys of `patternProperties` into a backtracking
-// RegExp and executes them with no time limit, so a proxy-supplied expression is an unbounded CPU
-// sink. A `$ref` resolves an arbitrary JSON pointer, which means a regex can be parked under any key
-// at all — including data-only positions such as `default` or `examples`. Enumerating "positions
-// where a subschema may appear" is therefore not a sound bound. We instead walk the entire supplied
-// document, every key and every value, and refuse to vouch for anything we could not fully inspect.
-const UNSAFE_REGEX_KEY = "pattern";
-const UNSAFE_REGEX_MAP_KEY = "patternProperties";
-const NONLOCAL_REF_KEYS = ["$dynamicRef", "$recursiveRef"] as const;
-// These keywords change TypeBox's reference base or introduce aliases. Rather than duplicate its
-// URI and dynamic-scope resolver, fail closed whenever an untrusted schema defines one.
-const REF_SCOPE_KEYS = new Set(["$id", "$anchor", "$dynamicAnchor", "$recursiveAnchor"]);
-const UNSAFE_POINTER_TOKENS = new Set(["__proto__", "constructor", "prototype"]);
-const MAX_SCAN_NODES = 20_000;
-const MAX_REF_HOPS = 32;
-const POINTER_MISSING = Symbol("pointer-missing");
-// Keywords whose immediate children are keyed by *name* rather than by keyword. Inside one of these
-// a key like `patternProperties` is the name of a tool argument, not a constraint, so the keyword
-// checks must not fire on it. This is the only context the scan needs; it does not restrict where
-// the scan looks, only how a key is interpreted.
-const NAME_KEYED_KEYWORDS = new Set([
-  "properties",
-  "patternProperties",
-  "$defs",
-  "definitions",
-  "dependentSchemas",
-  "dependentRequired",
-  "dependencies",
-]);
-
-// Why a supplied schema could not be proven safe to hand to the validator.
-export type SchemaHazard =
-  | "regex"
-  | "malformed-ref"
-  | "nonlocal-ref"
-  | "unresolvable-ref"
-  | "resolver-scope"
-  | "ref-cycle"
-  | "budget"
-  | "cycle";
-
-// Resolves a JSON pointer fragment against the supplied document. Returns POINTER_MISSING rather
-// than undefined so that a target whose value genuinely is `undefined` cannot be mistaken for a hit.
-function resolvePointer(root: unknown, fragment: string): unknown {
-  if (fragment === "") return root;
-  // A plain `#name` is an $anchor reference, which cannot be resolved without an anchor index.
-  if (!fragment.startsWith("/")) return POINTER_MISSING;
-  let current: unknown = root;
-  for (const rawToken of fragment.slice(1).split("/")) {
-    const token = rawToken.replaceAll("~1", "/").replaceAll("~0", "~");
-    // TypeBox's pointer lookup refuses these keys even when they are own properties.
-    if (UNSAFE_POINTER_TOKENS.has(token)) return POINTER_MISSING;
-    if (Array.isArray(current)) {
-      // TypeBox indexes arrays with the pointer token itself. Accept only the canonical decimal
-      // spellings that can name JSON array elements; Number("01") would incorrectly alias index 1.
-      if (!/^(0|[1-9]\d*)$/.test(token)) return POINTER_MISSING;
-      const index = Number(token);
-      if (!Number.isSafeInteger(index) || index >= current.length) return POINTER_MISSING;
-      current = current[index];
-      continue;
-    }
-    const record = asRecord(current);
-    if (!record || !Object.hasOwn(record, token)) return POINTER_MISSING;
-    current = record[token];
-  }
-  return current;
-}
-
-// Follows a local `#` reference chain and reports whether the validator could actually use it.
-//
-// Covering the whole document proves no regex hides behind a pointer, but it does not prove the
-// pointer names a subschema at all. TypeBox resolves the pointer and then treats whatever it finds
-// as a schema, so `#/description` makes it throw on a string, a mutual `$defs` pair makes it recurse
-// until the stack is gone, and a missing target silently resolves to `false` — a tool that can never
-// validate any argument. Object identity cannot see any of these, because each pointer hop is a
-// different object.
-function findLocalRefHazard(
-  root: Record<string, unknown>,
-  ref: string,
-  schemaPositionNodes: WeakSet<object>,
-): SchemaHazard | undefined {
-  const activePointers = new Set<string>();
-  const checkedPointers = new Set<string>();
-  // This is intentionally shared across the complete traversal from one root ref so a broad
-  // combinator graph cannot evade the same bound by branching.
-  let referenceCount = 0;
-
-  const visitRef = (pointer: string): SchemaHazard | undefined => {
-    if (activePointers.has(pointer)) return "ref-cycle";
-    if (checkedPointers.has(pointer)) return undefined;
-    referenceCount += 1;
-    if (referenceCount > MAX_REF_HOPS) return "budget";
-    // TypeBox percent-decodes URI fragments before resolving their JSON pointer. Keeping encoded
-    // refs would require exactly mirroring that decoding (including failures), so refuse them.
-    if (pointer.includes("%")) return "unresolvable-ref";
-    const target = resolvePointer(root, pointer.slice(1));
-    if (target === POINTER_MISSING) return "unresolvable-ref";
-    // A boolean is always a complete schema, independent of where it appears in the document.
-    if (typeof target === "boolean") return undefined;
-    const record = asRecord(target);
-    // Name-keyed containers are not schemas. Requiring an object target to have been visited where
-    // keys are interpreted as schema keywords prevents a ref from turning one into a schema behind
-    // the scan's back (for example, `#/dependencies`).
-    if (!record || !schemaPositionNodes.has(record) || !hasValidSchemaShape(record)) return "unresolvable-ref";
-
-    activePointers.add(pointer);
-    const hazard = visitSameInstanceSchemas(record);
-    activePointers.delete(pointer);
-    if (!hazard) checkedPointers.add(pointer);
-    return hazard;
-  };
-
-  // TypeBox evaluates these applicators against the same instance as their containing schema.
-  // Following only those edges catches unproductive reference cycles without rejecting ordinary
-  // recursive object/array schemas, whose property or item edge advances to a nested value.
-  const visitSameInstanceSchemas = (schema: Record<string, unknown>): SchemaHazard | undefined => {
-    if (typeof schema.$ref === "string") {
-      const hazard = schema.$ref.startsWith("#") ? visitRef(schema.$ref) : "nonlocal-ref";
-      if (hazard) return hazard;
-    }
-    for (const keyword of ["not", "if", "then", "else"] as const) {
-      const child = asRecord(schema[keyword]);
-      if (!child) continue;
-      const hazard = visitSameInstanceSchemas(child);
-      if (hazard) return hazard;
-    }
-    for (const keyword of ["allOf", "anyOf", "oneOf"] as const) {
-      const schemas = schema[keyword];
-      if (!Array.isArray(schemas)) continue;
-      for (const child of schemas) {
-        const record = asRecord(child);
-        if (!record) continue;
-        const hazard = visitSameInstanceSchemas(record);
-        if (hazard) return hazard;
-      }
-    }
-    for (const keyword of ["dependentSchemas", "dependencies"] as const) {
-      const map = asRecord(schema[keyword]);
-      if (!map) continue;
-      for (const child of Object.values(map)) {
-        const record = asRecord(child);
-        if (!record) continue;
-        const hazard = visitSameInstanceSchemas(record);
-        if (hazard) return hazard;
-      }
-    }
-    return undefined;
-  };
-
-  return visitRef(ref);
-}
-
-function schemaPositionNodes(root: Record<string, unknown>): WeakSet<object> {
-  const positions = new WeakSet<object>();
-  const seen = new WeakSet<object>();
-
-  const visitSchema = (value: unknown): void => {
-    if (typeof value === "boolean") return;
-    const schema = asRecord(value);
-    if (!schema || seen.has(schema)) return;
-    seen.add(schema);
-    positions.add(schema);
-
-    for (const keyword of DIRECT_SCHEMA_KEYWORDS) visitSchema(schema[keyword]);
-    for (const keyword of SCHEMA_MAP_KEYWORDS) {
-      const map = asRecord(schema[keyword]);
-      if (map) for (const child of Object.values(map)) visitSchema(child);
-    }
-    const dependencies = asRecord(schema.dependencies);
-    if (dependencies) {
-      for (const child of Object.values(dependencies)) {
-        // Draft-07 dependencies may also be arrays of property names; only schema-valued entries
-        // establish independently reachable schema positions.
-        if (typeof child === "boolean" || asRecord(child)) visitSchema(child);
-      }
-    }
-    for (const keyword of SCHEMA_ARRAY_KEYWORDS) {
-      const schemas = schema[keyword];
-      if (Array.isArray(schemas)) for (const child of schemas) visitSchema(child);
-    }
-    const items = schema.items;
-    if (Array.isArray(items)) for (const child of items) visitSchema(child);
-    else visitSchema(items);
-  };
-
-  visitSchema(root);
-  return positions;
-}
-
-// Walks the whole untrusted schema graph looking for anything the validator could turn into a
-// regex, plus references we cannot resolve within the document we were given.
-//
-// Bounded three ways so a hostile document cannot exhaust us while we inspect it: a depth cap, a
-// node budget, and identity-based cycle detection. Hitting any bound returns a hazard rather than
-// `undefined`, because an unfinished scan proves nothing.
-//
-// A local `#/...` ref is only accepted when the walk covers its target *and* the target resolves to
-// a usable subschema, with the reference chain proven acyclic. Any other ref form is a hazard.
-export function findSchemaHazard(root: Record<string, unknown>): SchemaHazard | undefined {
-  const seenKeywordObjects = new WeakSet<object>();
-  const seenNameMaps = new WeakSet<object>();
-  const active = new WeakSet<object>();
-  const localRefs: string[] = [];
-  let budget = MAX_SCAN_NODES;
-
-  const walk = (value: unknown, depth: number, keysAreNames: boolean): SchemaHazard | undefined => {
-    if (budget-- <= 0) return "budget";
-    if (depth > MAX_SCHEMA_DEPTH) return "budget";
-    if (value === null || typeof value !== "object") return undefined;
-    if (active.has(value)) return "cycle";
-    // Shared identities need inspection once per interpretation context: a `pattern` key is an
-    // argument name under `properties`, but the same object is hazardous if also used as a schema.
-    const seen = keysAreNames ? seenNameMaps : seenKeywordObjects;
-    if (seen.has(value)) return undefined;
-    seen.add(value);
-    active.add(value);
-
-    if (Array.isArray(value)) {
-      for (const child of value) {
-        const hazard = walk(child, depth + 1, false);
-        if (hazard) return hazard;
-      }
-      active.delete(value);
-      return undefined;
-    }
-
-    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
-      if (!keysAreNames) {
-        // `$id` changes the base against which fragment-only refs resolve, while the anchor
-        // keywords introduce aliases and dynamic scope. TypeBox applies those semantics while
-        // compiling, so the pointer-only safety resolver must not accept schemas that define them.
-        if (REF_SCOPE_KEYS.has(key)) return "resolver-scope";
-        // Any `pattern` or `patternProperties` at a keyword position, whatever its value type. This
-        // TypeBox only compiles a string-valued `pattern`, so a non-string one is not a CPU risk —
-        // but the expression text would still land in the schema Pi holds and forward to the
-        // provider, so refusing to vouch for it keeps the stated invariant literally true and does
-        // not depend on an upstream type guard staying as it is. A key that is an argument *name*
-        // is excluded by `keysAreNames` before reaching here.
-        if (key === UNSAFE_REGEX_KEY || key === UNSAFE_REGEX_MAP_KEY) return "regex";
-        // A pointer outside the supplied document cannot be inspected at all. A local one is only
-        // safe if it also resolves to something the validator can use as a schema.
-        if (key === "$ref") {
-          if (typeof child !== "string") return "malformed-ref";
-          if (!child.startsWith("#")) return "nonlocal-ref";
-          // TypeBox decodes percent escapes before pointer lookup. Reject encoded local refs rather
-          // than risk validating a different target from the one TypeBox will compile.
-          if (child.includes("%")) return "unresolvable-ref";
-          // Resolve after the complete walk so acceptance cannot depend on whether the referenced
-          // schema appeared before or after this `$ref` in object insertion order.
-          localRefs.push(child);
-        }
-        if ((NONLOCAL_REF_KEYS as readonly string[]).includes(key)) {
-          if (typeof child !== "string") return "malformed-ref";
-          return "nonlocal-ref";
-        }
-      }
-      const hazard = walk(child, depth + 1, !keysAreNames && NAME_KEYED_KEYWORDS.has(key));
-      if (hazard) return hazard;
-    }
-    active.delete(value);
-    return undefined;
-  };
-
-  const walkHazard = walk(root, 0, false);
-  if (walkHazard) return walkHazard;
-  const validPositions = schemaPositionNodes(root);
-  for (const ref of localRefs) {
-    const refHazard = findLocalRefHazard(root, ref, validPositions);
-    if (refHazard) return refHazard;
-  }
-  return undefined;
-}
-
-function isValidSchema(value: unknown): boolean {
-  if (typeof value === "boolean") return true;
-  const schema = asRecord(value);
-  return schema !== undefined && hasValidSchemaShape(schema);
-}
-
-function isValidSchemaMap(value: unknown): boolean {
-  const schemas = asRecord(value);
-  return schemas !== undefined && Object.values(schemas).every(isValidSchema);
-}
-
-function isValidSchemaArray(value: unknown): boolean {
-  return Array.isArray(value) && value.every(isValidSchema);
-}
-
-function isStringArray(value: unknown): boolean {
-  return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-
-function isValidDependencies(value: unknown): boolean {
-  const dependencies = asRecord(value);
-  return (
-    dependencies !== undefined &&
-    Object.values(dependencies).every((entry) => isValidSchema(entry) || isStringArray(entry))
-  );
-}
-
-function isValidDependentRequired(value: unknown): boolean {
-  const dependentRequired = asRecord(value);
-  return dependentRequired !== undefined && Object.values(dependentRequired).every(isStringArray);
-}
-
-// Shape validation is a separate concern from the hazard scan above: it exists to avoid handing the
-// validator a structurally broken document, and it deliberately only looks where a subschema may
-// legally appear so that data positions are not misread as constraints.
-function hasValidSchemaShape(record: Record<string, unknown>): boolean {
-  if ("required" in record && !isStringArray(record.required)) return false;
-  if ("dependentRequired" in record && !isValidDependentRequired(record.dependentRequired)) return false;
-  if ("dependencies" in record && !isValidDependencies(record.dependencies)) return false;
-  if (SCHEMA_MAP_KEYWORDS.some((keyword) => keyword in record && !isValidSchemaMap(record[keyword]))) return false;
-  if (SCHEMA_ARRAY_KEYWORDS.some((keyword) => keyword in record && !isValidSchemaArray(record[keyword]))) return false;
-  if (DIRECT_SCHEMA_KEYWORDS.some((keyword) => keyword in record && !isValidSchema(record[keyword]))) return false;
-  const items = record.items;
-  return !("items" in record) || isValidSchema(items) || isValidSchemaArray(items);
-}
-
-// The extension-owned parameter shape. Nothing in it originates from the proxy.
-function trustedEnvelope(): TSchema {
-  return Type.Object({
-    args: Type.Record(Type.String(), Type.Unknown(), { description: "Tool arguments as key-value pairs" }),
-  });
-}
-
-type BuiltParameters = {
-  parameters: TSchema;
-  syntheticArgsEnvelope: boolean;
-  // Set when the proxy supplied a usable schema that we replaced with the trusted envelope.
-  degraded?: McpDegradeReason;
-};
-
-function buildParameters(tool: LiteLLMMcpTool): BuiltParameters | McpDropReason {
-  // An `inputSchema` that was present but not a JSON object is a malformed tool, not a schemaless
-  // one, and must not be silently upgraded to the permissive envelope.
-  if (tool.input_schema_malformed) return "invalid-schema";
-  const inputSchema = tool.input_schema;
-  // Absent or empty schema: the proxy asked for no parameters, which the trusted envelope models
-  // exactly. This is the normal schemaless path, not a degradation.
-  if (Object.keys(inputSchema).length === 0) {
-    return { parameters: trustedEnvelope(), syntheticArgsEnvelope: true };
-  }
-  if (inputSchema.type !== "object") return "invalid-schema";
-  let serialized: string;
-  try {
-    serialized = JSON.stringify(inputSchema);
-  } catch {
-    return "invalid-schema";
-  }
-  if (byteLength(serialized) > MAX_SCHEMA_BYTES || schemaDepth(inputSchema) > MAX_SCHEMA_DEPTH) {
-    return "invalid-schema";
-  }
-  if (!hasValidSchemaShape(inputSchema)) return "invalid-schema";
-  // Structurally fine, but we will only forward it if the whole graph is provably free of
-  // proxy-supplied regexes and unresolvable references. Otherwise the tool still registers, with
-  // the trusted envelope standing in for its schema.
-  if (findSchemaHazard(inputSchema) !== undefined) {
-    return { parameters: trustedEnvelope(), syntheticArgsEnvelope: true, degraded: "schema-envelope" };
-  }
-  return { parameters: Type.Unsafe(inputSchema), syntheticArgsEnvelope: false };
-}
-
-export function prepareTools(
-  discovery: McpDiscovery,
-  namespace?: string,
-  exposurePolicy: McpExposurePolicy = DEFAULT_MCP_EXPOSURE_POLICY,
-): {
-  prepared: PreparedTool[];
-  report: McpPreparationReport;
-} {
-  const drops = new Map<McpDropReason, string[]>();
-  const dropMemberships = new Map<McpDropReason, string[]>();
-  const degrades = new Map<McpDegradeReason, string[]>();
-  const recordDrop = (reason: McpDropReason, label: string, identity = label): void => {
-    const labels = drops.get(reason);
-    if (labels) labels.push(label);
-    else drops.set(reason, [label]);
-    const identities = dropMemberships.get(reason);
-    if (identities) identities.push(identity);
-    else dropMemberships.set(reason, [identity]);
-  };
-
-  for (const invalid of discovery.invalid) {
-    recordDrop("invalid-tool", invalid.label, `${invalid.label}\0${invalid.identity}`);
-  }
-
-  const accepted: Array<Omit<PreparedTool, "name"> & { degraded?: McpDegradeReason }> = [];
-  const acceptedIdentities = new Set<string>();
-  for (const tool of discovery.tools) {
-    const built = buildParameters(tool);
-    if (typeof built === "string") {
-      recordDrop(built, buildPiToolName(tool, namespace));
-      continue;
-    }
-    const identity = toolIdentity(tool);
-    if (acceptedIdentities.has(identity)) {
-      recordDrop("duplicate-identity", buildPiToolName(tool, namespace));
-      continue;
-    }
-    acceptedIdentities.add(identity);
-    accepted.push({
-      tool,
-      parameters: built.parameters,
-      syntheticArgsEnvelope: built.syntheticArgsEnvelope,
-      exposure: resolveMcpExposure(exposurePolicy, tool.server_name, tool.name),
-      degraded: built.degraded,
-    });
-  }
-
-  const candidates = accepted.slice(0, MAX_REGISTERED_TOOLS);
-  const overflowTools = accepted.slice(MAX_REGISTERED_TOOLS).map(({ tool }) => buildPiToolName(tool, namespace));
-  const finalNames = new Set<string>();
-  const prepared: PreparedTool[] = [];
-  for (const candidate of candidates) {
-    // Membership-independent: the name depends only on this tool's identity.
-    const name = buildPiToolName(candidate.tool, namespace);
-    if (finalNames.has(name)) {
-      recordDrop("name-collision", name);
-      continue;
-    }
-    finalNames.add(name);
-    const { degraded, ...preparedCandidate } = candidate;
-    prepared.push({ ...preparedCandidate, name });
-    if (degraded) {
-      const labels = degrades.get(degraded);
-      if (labels) labels.push(name);
-      else degrades.set(degraded, [name]);
-    }
-  }
-
-  const report: McpPreparationReport = {
-    discovered: discovery.raw,
-    partialFailure: discovery.partialFailure,
-    prepared: prepared.length,
-    // Counting only hazard degradations would tell an operator that schemaless tools retain a
-    // proxy-specific argument contract; they have only the extension-owned args-envelope shape.
-    enveloped: prepared.filter((tool) => tool.syntheticArgsEnvelope).length,
-    overflow: overflowTools.length,
-    overflowTools,
-    dropped: [...drops.entries()].map(([reason, tools]) => ({ reason, tools })),
-    dropMemberships: [...dropMemberships.entries()].map(([reason, identities]) => ({ reason, identities })),
-    degraded: [...degrades.entries()].map(([reason, tools]) => ({ reason, tools })),
-    exposures: [...new Set(prepared.map((tool) => tool.exposure))].sort(),
-  };
-  return { prepared, report };
-}
-
-function emitPreparationDiagnostics(report: McpPreparationReport, onDiagnostic?: DiagnosticSink): void {
-  const seen = new Set<string>();
-  const emitClass = (reason: McpIncidentReason, message: string, tools: string[]): void => {
-    seen.add(reason);
-    // Identity covers the full membership, so a change beyond the printed sample still re-reports.
-    emitSafetyDiagnostic(reason, message, `${tools.length}:${membershipIdentity(tools)}`, onDiagnostic);
-  };
-  const dropMemberships = new Map(report.dropMemberships.map(({ reason, identities }) => [reason, identities]));
-  for (const { reason, tools } of report.dropped) {
-    const identities = dropMemberships.get(reason);
-    if (!identities) throw new Error(`Missing MCP diagnostic membership for ${reason}`);
-    emitClass(
-      reason,
-      `dropped ${plural(tools.length, "MCP tool")} with ${DROP_REASON_TEXT[reason]}: ${sampleList(tools)}.`,
-      identities,
-    );
-  }
-  for (const { reason, tools } of report.degraded) {
-    emitClass(
-      reason,
-      `kept ${plural(tools.length, "MCP tool")} but replaced ${tools.length === 1 ? "its" : "their"} schema with a ` +
-        `safe args envelope, because of ${DEGRADE_REASON_TEXT[reason]}: ${sampleList(tools)}.`,
-      tools,
-    );
-  }
-  if (report.overflow > 0) {
-    seen.add("tool-cap");
-    emitSafetyDiagnostic(
-      "tool-cap",
-      `ignoring ${plural(report.overflow, "MCP tool")} beyond the ${MAX_REGISTERED_TOOLS}-tool limit.`,
-      `${report.overflow}:${membershipIdentity(report.overflowTools)}`,
-      onDiagnostic,
-    );
-  }
-  // Clear classes that did not recur, so the same incident is reported again if it comes back
-  // after a clean refresh instead of being suppressed as an unchanged identity.
-  for (const reason of [...Object.keys(INCIDENT_REASON_TEXT), "tool-cap"]) {
-    if (!seen.has(reason)) clearIncident(reason, onDiagnostic);
-  }
-}
-
-export async function createMcpToolDefinitions(
-  getAuth: (ctx?: ExtensionContext) => Promise<LiteLLMRuntimeAuth>,
-  onProgress?: (message: string) => void,
-  signal?: AbortSignal,
-  onDiagnostic?: DiagnosticSink,
-  namespace?: string,
-  exposurePolicy: McpExposurePolicy = DEFAULT_MCP_EXPOSURE_POLICY,
-): Promise<{ definitions: ToolDefinition[]; report: McpPreparationReport }> {
-  const discoveryAuth = await getAuth();
-  const discovery = await discoverMcpTools(
-    discoveryAuth.baseUrl,
-    discoveryAuth.apiKey,
-    discoveryAuth.headers,
-    onProgress,
-    signal,
-    discoveryAuth.allowInsecureHttp,
-    onDiagnostic,
-  );
-  const { prepared, report } = prepareTools(discovery, namespace, exposurePolicy);
-  emitPreparationDiagnostics(report, onDiagnostic);
-  const lostTotal = report.dropped.reduce((total, entry) => total + entry.tools.length, 0) + report.overflow;
-  const lostDetail = [
-    ...report.dropped.map((entry) => `${entry.reason}=${entry.tools.length}`),
-    ...(report.overflow > 0 ? [`tool-cap=${report.overflow}`] : []),
-  ].join(", ");
-  // raw = prepared + lost, so an operator can always account for every entry the proxy returned.
-  onProgress?.(
-    `Prepared ${report.prepared} of ${report.discovered} raw MCP tools ` +
-      `(${report.enveloped} kept with a safe args envelope); lost ${lostTotal}` +
-      `${lostDetail ? ` (${lostDetail})` : ""}`,
-  );
-
-  const definitions = prepared.map(({ tool: mcpTool, name, parameters, syntheticArgsEnvelope, exposure }) => {
-    const description = truncateUtf8(
-      `${mcpTool.description} (via ${mcpTool.server_name} MCP server)`,
-      MAX_DESCRIPTION_BYTES,
-      DESCRIPTION_TRUNCATION_MARKER,
-    );
-    const promptSnippet = truncateUtf8(
-      `${mcpTool.description} via ${mcpTool.server_name} MCP server`,
-      MAX_DESCRIPTION_BYTES,
-      DESCRIPTION_TRUNCATION_MARKER,
-    );
-
-    // `label` and the `details` fields below are proxy-supplied, so they are bounded like every other
-    // untrusted string that reaches Pi's UI or the model.
-    const label = truncateUtf8(`${mcpTool.server_name}: ${mcpTool.name}`, MAX_LABEL_BYTES, SHORT_TRUNCATION_MARKER);
-    const boundedDetail = (value: string): string => truncateUtf8(value, MAX_DETAIL_BYTES, SHORT_TRUNCATION_MARKER);
-    // Pi 0.99 groups tools by namespace, as its own MCP client does per server. The prefix matches the
-    // generated tool names, so a group is recognisable in codemode listings; older Pi ignores it.
-    const toolNamespace = {
-      name: buildNamespaceName(mcpTool, namespace),
-      description: truncateUtf8(
-        mcpTool.server_description ?? `LiteLLM MCP server ${mcpTool.server_name}`,
-        MAX_LABEL_BYTES,
-        SHORT_TRUNCATION_MARKER,
-      ),
-    };
-
-    return defineTool({
-      name,
-      label,
-      description,
-      promptSnippet,
-      executionMode: "parallel",
-      exposure: toToolExposure(exposure),
-      namespace: toolNamespace,
-      ...(mcpTool.annotations ? { annotations: mcpTool.annotations } : {}),
-      parameters,
-      outputSchema: MCP_RESULT_SCHEMA,
-      async execute(_toolCallId, params: Static<typeof parameters>, toolSignal, _onUpdate, ctx) {
-        const auth = await getAuth(ctx);
-        const rawParams = params as Record<string, unknown>;
-        const args = syntheticArgsEnvelope ? asRecord(rawParams.args) : rawParams;
-        if (!args) throw new Error("Synthetic MCP tool arguments must contain an object-valued args property");
-        const { text, structuredContent, isError } = await executeMcpTool(
-          auth.baseUrl,
-          auth.apiKey,
-          mcpTool.server_id ?? mcpTool.server_name,
-          mcpTool.name,
-          args,
-          auth.headers,
-          toolSignal,
-          auth.allowInsecureHttp,
-          onDiagnostic,
-        );
-        // Pi before 0.99 ignores a returned `isError`; `ctx.executeTool` exists only from 0.99.
-        if (isError && typeof (ctx as { executeTool?: unknown }).executeTool !== "function") throw new Error(text);
-        return {
-          content: [{ type: "text", text }],
-          // The body came from JSON.parse, so it is a JsonValue; Pi's type cannot see that.
-          structuredContent: structuredContent as JsonValue,
-          ...(isError ? { isError: true } : {}),
-          details: {
-            server: boundedDetail(mcpTool.server_name),
-            serverId: boundedDetail(mcpTool.server_id ?? mcpTool.server_name),
-            tool: boundedDetail(mcpTool.name),
-          },
-        };
-      },
-    });
-  });
-
-  return { definitions, report };
-}