@herbertgao/pi-extensions 2026.9.17 → 2026.9.19

package/node_modules/pi-mcp-adapter/tool-metadata.ts

@@ -1,302 +0,0 @@
-import { getToolUiResourceUri } from "./ui-app-bridge-helpers.ts";
-import type { McpExtensionState } from "./state.ts";
-import type { ToolMetadata, McpTool, McpResource, ServerEntry, ToolPrefix } from "./types.ts";
-import { createToolSelectorCandidateIndex, formatToolName, getToolNameCandidates, isToolAllowed, resolveToolPrefix, resolveUniqueNameOwnership } from "./types.ts";
-import { resourceNameToToolName } from "./resource-tools.ts";
-import { extractToolUiStreamMode } from "./utils.ts";
-import { extractUiToolVisibility, isUiToolVisibleToModel } from "./ui-tool-visibility.ts";
-
-export function buildToolMetadata(
-  tools: McpTool[],
-  resources: McpResource[],
-  definition: ServerEntry,
-  serverName: string,
-  prefix: ToolPrefix,
-  configuredServers?: Record<string, ServerEntry>,
-  knownMetadata?: Map<string, ToolMetadata[]>,
-  includeMissingConfiguredCandidates = false,
-): { metadata: ToolMetadata[]; failedTools: string[] } {
-  const metadata: ToolMetadata[] = [];
-  const failedTools: string[] = [];
-  const effectivePrefix = resolveToolPrefix(definition, prefix);
-  const hasToolFilters =
-    (Array.isArray(definition.includeTools) && definition.includeTools.length > 0) ||
-    (Array.isArray(definition.excludeTools) && definition.excludeTools.length > 0);
-  const selectorCandidateIndex = hasToolFilters && configuredServers ? (() => {
-    const candidates = new Set<string>();
-    const additionalCandidatesByToolName = new Map<string, Set<string>>();
-    const evaluatedToolNames = new Set<string>();
-    const addCandidates = (
-      target: Set<string>,
-      originalName: string,
-      candidateServerName: string,
-      candidatePrefix: ToolPrefix,
-    ) => {
-      for (const candidate of getToolNameCandidates(originalName, candidateServerName, candidatePrefix, false)) target.add(candidate);
-    };
-
-    for (const tool of tools) {
-      if (!tool?.name) continue;
-      evaluatedToolNames.add(tool.name);
-      addCandidates(candidates, tool.name, serverName, effectivePrefix);
-    }
-    if (definition.exposeResources !== false) {
-      for (const resource of resources) {
-        const baseName = `read_${resourceNameToToolName(resource.name)}`;
-        evaluatedToolNames.add(baseName);
-        if (resource?.name && resource?.uri) addCandidates(candidates, baseName, serverName, effectivePrefix);
-      }
-    }
-    for (const [otherServerName, otherDefinition] of Object.entries(configuredServers)) {
-      if (otherServerName === serverName) continue;
-      const otherPrefix = resolveToolPrefix(otherDefinition, prefix);
-      const knownTools = knownMetadata?.get(otherServerName);
-      if (knownTools) {
-        for (const tool of knownTools) {
-          candidates.add(tool.name);
-          addCandidates(candidates, tool.originalName, otherServerName, otherPrefix);
-        }
-      } else if (!knownMetadata || includeMissingConfiguredCandidates) {
-        for (const toolName of evaluatedToolNames) {
-          let additionalCandidates = additionalCandidatesByToolName.get(toolName);
-          if (!additionalCandidates) {
-            additionalCandidates = new Set<string>();
-            additionalCandidatesByToolName.set(toolName, additionalCandidates);
-          }
-          addCandidates(additionalCandidates, toolName, otherServerName, otherPrefix);
-          if (includeMissingConfiguredCandidates) {
-            for (const candidate of getToolNameCandidates(toolName, otherServerName, otherPrefix, false)) {
-              additionalCandidates.add(candidate.replace(/-/g, "_"));
-            }
-          }
-        }
-      }
-    }
-    return createToolSelectorCandidateIndex(candidates, additionalCandidatesByToolName);
-  })() : undefined;
-
-  for (const tool of tools) {
-    if (!tool?.name) {
-      failedTools.push("(unnamed)");
-      continue;
-    }
-    if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex)) {
-      continue;
-    }
-
-    const name = formatToolName(tool.name, serverName, effectivePrefix);
-    const uiVisibility = extractUiToolVisibility(tool._meta);
-    if (!isUiToolVisibleToModel(uiVisibility)) {
-      continue;
-    }
-    let uiResourceUri: string | undefined;
-    try {
-      uiResourceUri = getToolUiResourceUri({ _meta: tool._meta });
-    } catch {
-      failedTools.push(tool.name);
-    }
-    const uiStreamMode = extractToolUiStreamMode(tool._meta);
-    metadata.push({
-      name,
-      originalName: tool.name,
-      description: tool.description ?? "",
-      ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
-      ...(tool.outputSchema !== undefined ? { outputSchema: tool.outputSchema } : {}),
-      ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
-      ...(uiVisibility !== undefined ? { uiVisibility } : {}),
-      ...(uiStreamMode !== undefined ? { uiStreamMode } : {}),
-    });
-  }
-
-  if (definition.exposeResources !== false) {
-    for (const resource of resources) {
-      const baseName = `read_${resourceNameToToolName(resource.name)}`;
-      if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools, selectorCandidateIndex)) {
-        continue;
-      }
-
-      const name = formatToolName(baseName, serverName, effectivePrefix);
-      metadata.push({
-        name,
-        originalName: baseName,
-        description: resource.description ?? `Read resource: ${resource.uri}`,
-        resourceUri: resource.uri,
-      });
-    }
-  }
-
-  const ownership = resolveUniqueNameOwnership(metadata, (tool) => tool.name);
-  for (const colliding of ownership.collisions.values()) {
-    failedTools.push(...colliding.map((tool) => tool.originalName));
-  }
-  return { metadata: ownership.unique, failedTools };
-}
-
-export function getToolNames(state: McpExtensionState, serverName: string): string[] {
-  return state.toolMetadata.get(serverName)?.map(m => m.name) ?? [];
-}
-
-export function totalToolCount(state: McpExtensionState): number {
-  let count = 0;
-  for (const metadata of state.toolMetadata.values()) {
-    count += metadata.length;
-  }
-  return count;
-}
-
-export function findToolByName(metadata: ToolMetadata[] | undefined, toolName: string): ToolMetadata | undefined {
-  if (!metadata) return undefined;
-  const exact = metadata.find(m => m.name === toolName);
-  if (exact) return exact;
-  const normalized = toolName.replace(/-/g, "_");
-  return metadata.find(m => m.name.replace(/-/g, "_") === normalized);
-}
-
-/** Whether the schema formatter has field descriptions worth showing beside a compact shape. */
-export function hasSchemaDescriptions(schema: unknown, includeRoot = false): boolean {
-  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return false;
-  const s = schema as Record<string, unknown>;
-  if (includeRoot && typeof s.description === "string" && s.description.length > 0) return true;
-  const hasNestedDescription = (child: unknown) => hasSchemaDescriptions(child, true);
-  if (s.properties && typeof s.properties === "object" && !Array.isArray(s.properties)
-    && Object.values(s.properties).some(hasNestedDescription)) return true;
-  return hasNestedDescription(s.items)
-    || (Array.isArray(s.anyOf) && s.anyOf.some(hasNestedDescription))
-    || (Array.isArray(s.oneOf) && s.oneOf.some(hasNestedDescription));
-}
-
-export function formatSchema(schema: unknown, indent = "  "): string {
-  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
-    return `${indent}(no schema)`;
-  }
-
-  const s = schema as Record<string, unknown>;
-
-  if (s.type === "object" && s.properties && typeof s.properties === "object" && !Array.isArray(s.properties)) {
-    const props = s.properties as Record<string, unknown>;
-    const required = Array.isArray(s.required) ? s.required.filter((name): name is string => typeof name === "string") : [];
-
-    if (Object.keys(props).length === 0) {
-      return `${indent}(no parameters)`;
-    }
-
-    const lines: string[] = [];
-    for (const [name, propSchema] of Object.entries(props)) {
-      lines.push(...formatProperty(name, propSchema, required.includes(name), indent));
-    }
-    return lines.join("\n");
-  }
-
-  const lines = formatNestedSchema(s, indent);
-  if (lines.length > 0) {
-    return lines.join("\n");
-  }
-
-  const typeStr = formatType(s);
-  if (typeStr) {
-    return `${indent}(${typeStr})`;
-  }
-
-  return `${indent}(complex schema)`;
-}
-
-function formatProperty(name: string, schema: unknown, required: boolean, indent: string): string[] {
-  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
-    return [`${indent}${name}${required ? " *required*" : ""}`];
-  }
-
-  const s = schema as Record<string, unknown>;
-  const parts = [`${indent}${name}`];
-  const typeStr = formatType(s);
-  if (typeStr) parts.push(`(${typeStr})`);
-  if (required) parts.push("*required*");
-  appendSchemaAnnotations(parts, s);
-
-  return [parts.join(" "), ...formatNestedSchema(s, `${indent}  `)];
-}
-
-function formatNestedSchema(schema: Record<string, unknown>, indent: string): string[] {
-  const lines: string[] = [];
-
-  if (Array.isArray(schema.anyOf)) {
-    lines.push(...formatVariants("anyOf", schema.anyOf, indent));
-  }
-  if (Array.isArray(schema.oneOf)) {
-    lines.push(...formatVariants("oneOf", schema.oneOf, indent));
-  }
-  if (schema.items !== undefined) {
-    lines.push(...formatProperty("items", schema.items, false, indent));
-  }
-  if (schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)) {
-    const required = Array.isArray(schema.required) ? schema.required.filter((name): name is string => typeof name === "string") : [];
-    for (const [name, propSchema] of Object.entries(schema.properties as Record<string, unknown>)) {
-      lines.push(...formatProperty(name, propSchema, required.includes(name), indent));
-    }
-  }
-
-  return lines;
-}
-
-function formatVariants(keyword: "anyOf" | "oneOf", variants: unknown[], indent: string): string[] {
-  const lines = [`${indent}${keyword}:`];
-
-  for (const variant of variants) {
-    if (!variant || typeof variant !== "object" || Array.isArray(variant)) {
-      lines.push(`${indent}  - ${JSON.stringify(variant)}`);
-      continue;
-    }
-
-    const s = variant as Record<string, unknown>;
-    const typeStr = formatType(s) || "schema";
-    const parts = [`${indent}  - ${typeStr}`];
-    appendSchemaAnnotations(parts, s);
-    lines.push(parts.join(" "));
-    lines.push(...formatNestedSchema(s, `${indent}    `));
-  }
-
-  return lines;
-}
-
-function formatType(schema: Record<string, unknown>): string {
-  if (Object.hasOwn(schema, "const")) {
-    return `const ${JSON.stringify(schema.const)}`;
-  }
-
-  if (Array.isArray(schema.enum)) {
-    return `enum: ${schema.enum.map(v => JSON.stringify(v)).join(", ")}`;
-  }
-
-  if (Array.isArray(schema.type)) {
-    return schema.type.map(type => String(type)).join(" | ");
-  }
-
-  if (schema.type) {
-    return String(schema.type);
-  }
-
-  if (schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)) {
-    return "object";
-  }
-
-  if (schema.items !== undefined) {
-    return "array";
-  }
-
-  return "";
-}
-
-function appendSchemaAnnotations(parts: string[], schema: Record<string, unknown>): void {
-  if (schema.description && typeof schema.description === "string") {
-    parts.push(`- ${schema.description}`);
-  }
-
-  for (const key of ["minLength", "maxLength", "minimum", "maximum", "minItems", "maxItems", "format", "pattern"] as const) {
-    if (schema[key] !== undefined) {
-      parts.push(`[${key}: ${JSON.stringify(schema[key])}]`);
-    }
-  }
-
-  if (schema.default !== undefined) {
-    parts.push(`[default: ${JSON.stringify(schema.default)}]`);
-  }
-}

package/node_modules/pi-mcp-adapter/tool-registrar.ts

@@ -1,255 +0,0 @@
-// tool-registrar.ts - MCP content transformation
-// NOTE: Tools are NOT registered with Pi - only the unified `mcp` proxy tool is registered.
-// This keeps the LLM context small (1 tool instead of 100s).
-
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { McpContent, ContentBlock } from "./types.ts";
-
-const MAX_BINARY_RESOURCE_BYTES = 10 * 1024 * 1024;
-const MAX_SESSION_RESOURCE_BYTES = 100 * 1024 * 1024;
-const MAX_SESSION_RESOURCE_FILES = 10_000; // Bounds metadata from empty or tiny resources.
-const CLEANUP_RETRY_DELAY_MS = 30_000;
-const MAX_CLEANUP_RETRY_ATTEMPTS = 3;
-type MaterializedResourceSession = {
-  directory: string | undefined;
-  bytes: number;
-  files: number;
-  sequence: number;
-};
-
-function createMaterializedResourceSession(): MaterializedResourceSession {
-  return {
-    directory: undefined,
-    bytes: 0,
-    files: 0,
-    sequence: 0,
-  };
-}
-
-const defaultMaterializedResourceSession = createMaterializedResourceSession();
-const scopedMaterializedResourceSessions = new WeakMap<object, MaterializedResourceSession>();
-const pendingCleanupDirectories = new Set<string>();
-const cleanupRetryAttempts = new Map<string, number>();
-let pendingCleanupRetry: ReturnType<typeof setTimeout> | undefined;
-
-function isAbortedScope(scope: object | undefined): boolean {
-  return !!scope && "aborted" in scope && (scope as { aborted?: unknown }).aborted === true;
-}
-
-function getMaterializedResourceSession(scope?: object): MaterializedResourceSession | undefined {
-  if (isAbortedScope(scope)) return undefined;
-  if (!scope) return defaultMaterializedResourceSession;
-  let session = scopedMaterializedResourceSessions.get(scope);
-  if (!session) {
-    session = createMaterializedResourceSession();
-    scopedMaterializedResourceSessions.set(scope, session);
-  }
-  return session;
-}
-
-type BinaryResource = { uri?: string | undefined; text?: string | undefined; mimeType?: string | undefined; blob: string };
-type McpResourceContent = {
-  uri: string;
-  text?: string | undefined;
-  blob?: string | undefined;
-  mimeType?: string | undefined;
-  [key: string]: unknown;
-};
-
-function hasRetryableCleanupDirectory(): boolean {
-  for (const directory of pendingCleanupDirectories) {
-    if ((cleanupRetryAttempts.get(directory) ?? 0) < MAX_CLEANUP_RETRY_ATTEMPTS) return true;
-  }
-  return false;
-}
-
-function schedulePendingCleanupRetry(): void {
-  if (pendingCleanupRetry || !hasRetryableCleanupDirectory()) return;
-  for (const directory of pendingCleanupDirectories) {
-    const attempts = cleanupRetryAttempts.get(directory) ?? 0;
-    if (attempts < MAX_CLEANUP_RETRY_ATTEMPTS) cleanupRetryAttempts.set(directory, attempts + 1);
-  }
-  pendingCleanupRetry = setTimeout(() => {
-    pendingCleanupRetry = undefined;
-    try {
-      drainPendingCleanupDirectories();
-    } catch {
-      // drainPendingCleanupDirectories already retained the paths and rescheduled another retry.
-    }
-  }, CLEANUP_RETRY_DELAY_MS);
-}
-
-function drainPendingCleanupDirectories(): void {
-  const failures: unknown[] = [];
-  for (const directory of Array.from(pendingCleanupDirectories)) {
-    try {
-      rmSync(directory, { recursive: true, force: true });
-      pendingCleanupDirectories.delete(directory);
-      cleanupRetryAttempts.delete(directory);
-    } catch (error) {
-      failures.push(error);
-    }
-  }
-  if (pendingCleanupDirectories.size === 0 && pendingCleanupRetry) {
-    clearTimeout(pendingCleanupRetry);
-    pendingCleanupRetry = undefined;
-  }
-  if (failures.length > 0) {
-    schedulePendingCleanupRetry();
-    throw new AggregateError(failures, "Failed to clean materialized MCP resources");
-  }
-}
-
-export function cleanupMaterializedBinaryResources(scope?: object): void {
-  const session = scope ? scopedMaterializedResourceSessions.get(scope) : defaultMaterializedResourceSession;
-  if (session?.directory) pendingCleanupDirectories.add(session.directory);
-  if (session) {
-    session.directory = undefined;
-    session.bytes = 0;
-    session.files = 0;
-    session.sequence = 0;
-    if (scope) scopedMaterializedResourceSessions.delete(scope);
-  }
-
-  drainPendingCleanupDirectories();
-}
-
-function replaceBlob(resource: BinaryResource, text: string): string {
-  delete (resource as Partial<BinaryResource>).blob;
-  resource.text = text;
-  return text;
-}
-
-function omitBinaryResource(resource: BinaryResource, reason: string): string {
-  return replaceBlob(resource, [
-    `[Resource: ${resource.uri ?? "(no URI)"}]`,
-    `Binary content omitted: ${reason}`,
-    `MIME type: ${resource.mimeType ?? "application/octet-stream"}`,
-  ].join("\n"));
-}
-
-function materializeBinaryResource(resource: BinaryResource, scope?: object): string {
-  const session = getMaterializedResourceSession(scope);
-  if (!session) return omitBinaryResource(resource, "runtime stopped");
-  const decodedBytes = Buffer.byteLength(resource.blob, "base64");
-  if (decodedBytes > MAX_BINARY_RESOURCE_BYTES) {
-    return omitBinaryResource(resource, "decoded size exceeds 10 MiB");
-  }
-  if (
-    session.bytes + decodedBytes > MAX_SESSION_RESOURCE_BYTES ||
-    session.files >= MAX_SESSION_RESOURCE_FILES
-  ) {
-    return omitBinaryResource(resource, "session resource limit reached");
-  }
-
-  try {
-    session.directory ??= mkdtempSync(join(tmpdir(), "pi-mcp-resource-"));
-  } catch {
-    return omitBinaryResource(resource, "could not be saved");
-  }
-
-  const filePath = join(session.directory, `resource-${++session.sequence}.bin`);
-  session.bytes += decodedBytes;
-  session.files += 1;
-  try {
-    writeFileSync(filePath, Buffer.from(resource.blob, "base64"), { flag: "wx", mode: 0o600 });
-  } catch {
-    try {
-      rmSync(filePath, { force: true });
-      session.bytes -= decodedBytes;
-      session.files -= 1;
-    } catch {
-      // Keep the reservation when a partial file cannot be removed.
-    }
-    return omitBinaryResource(resource, "could not be saved");
-  }
-
-  return replaceBlob(resource, [
-    `[Resource: ${resource.uri ?? "(no URI)"}]`,
-    `Binary content saved to ${filePath}`,
-    `MIME type: ${resource.mimeType ?? "application/octet-stream"}`,
-  ].join("\n"));
-}
-
-/**
- * Transform MCP content types to Pi content blocks.
- */
-export function transformMcpResourceContents(contents: McpResourceContent[], scope?: object): ContentBlock[] {
-  return contents.map(resource => {
-    if (typeof resource.text === "string") return { type: "text" as const, text: resource.text };
-    if (typeof resource.blob === "string") return { type: "text" as const, text: materializeBinaryResource(resource as BinaryResource, scope) };
-    return { type: "text" as const, text: JSON.stringify(resource) };
-  });
-}
-
-export function transformMcpContent(content: McpContent[], scope?: object): ContentBlock[] {
-  return content.map(c => {
-    if (c.type === "text") {
-      return { type: "text" as const, text: c.text ?? "" };
-    }
-    if (c.type === "image") {
-      return {
-        type: "image" as const,
-        data: c.data ?? "",
-        mimeType: c.mimeType ?? "image/png",
-      };
-    }
-    if (c.type === "resource") {
-      const resourceUri = c.resource?.uri ?? "(no URI)";
-      if (c.resource && "blob" in c.resource && typeof c.resource.blob === "string") {
-        const binaryResource = c.resource as typeof c.resource & { mimeType?: string; blob: string };
-        return {
-          type: "text" as const,
-          text: materializeBinaryResource(binaryResource, scope),
-        };
-      }
-      const resourceContent = c.resource?.text ?? (c.resource ? JSON.stringify(c.resource) : "(no content)");
-      return {
-        type: "text" as const,
-        text: `[Resource: ${resourceUri}]\n${resourceContent}`,
-      };
-    }
-    if (c.type === "resource_link") {
-      const linkName = c.name ?? c.uri ?? "unknown";
-      const linkUri = c.uri ?? "(no URI)";
-      return {
-        type: "text" as const,
-        text: `[Resource Link: ${linkName}]\nURI: ${linkUri}`,
-      };
-    }
-    if (c.type === "audio") {
-      return {
-        type: "text" as const,
-        text: `[Audio content: ${c.mimeType ?? "audio/*"}]`,
-      };
-    }
-    return { type: "text" as const, text: JSON.stringify(c) };
-  });
-}
-
-/**
- * Resolve a tool result's content blocks, appending structuredContent when it
- * coexists with ordinary content and falling back to it when content is empty.
- */
-export function resolveMcpResultContent(result: Record<string, unknown>, scope?: object): ContentBlock[] {
-  const blocks = transformMcpContent((Array.isArray(result.content) ? result.content : []) as McpContent[], scope);
-  if (result.structuredContent !== undefined && result.structuredContent !== null) {
-    const structured = stringifyStructuredContent(result.structuredContent);
-    if (blocks.length > 0) {
-      return [...blocks, { type: "text" as const, text: `structuredContent:\n${structured}` }];
-    }
-    return [{ type: "text" as const, text: structured }];
-  }
-
-  return blocks;
-}
-
-function stringifyStructuredContent(value: unknown): string {
-  try {
-    return JSON.stringify(value, null, 2) ?? String(value);
-  } catch {
-    return String(value);
-  }
-}