pi-mcp-adapter 3.3.0 → 4.0.0

package/metadata-cache.ts

@@ -58,27 +58,32 @@ export function loadMetadataCache(): MetadataCache | null {
 }
 
 export function saveMetadataCache(cache: MetadataCache): void {
+  updateMetadataCacheFile(servers => ({ ...servers, ...cache.servers }));
+}
+
+/** Reads the cache file, applies one update, and writes the result; an update returning undefined skips the write. */
+function updateMetadataCacheFile(update: (servers: MetadataCache["servers"]) => MetadataCache["servers"] | undefined): void {
   const cachePath = getMetadataCachePath();
   const dir = dirname(cachePath);
   mkdirSync(dir, { recursive: true });
 
-  let merged: MetadataCache = { version: CACHE_VERSION, servers: {} };
+  let servers: MetadataCache["servers"] = {};
   try {
     if (existsSync(cachePath)) {
       const existing = JSON.parse(readFileSync(cachePath, "utf-8")) as MetadataCache;
       if (existing && existing.version === CACHE_VERSION && existing.servers) {
-        merged.servers = { ...existing.servers };
+        servers = { ...existing.servers };
       }
     }
   } catch {
     // Ignore parse errors and proceed with empty cache
   }
 
-  merged.version = CACHE_VERSION;
-  merged.servers = { ...merged.servers, ...cache.servers };
+  const next = update(servers);
+  if (!next) return;
 
   const tmpPath = `${cachePath}.${process.pid}.tmp`;
-  writeFileSync(tmpPath, JSON.stringify(merged), "utf-8");
+  writeFileSync(tmpPath, JSON.stringify({ version: CACHE_VERSION, servers: next }), "utf-8");
   renameSync(tmpPath, cachePath);
 }
 
@@ -117,6 +122,49 @@ export function computeServerHash(definition: ServerEntry, environment: NodeJS.P
   return createHash("sha256").update(normalized).digest("hex");
 }
 
+/**
+ * Identifies the tool definition an output shape was learned against. A shape is only used or saved while
+ * the tool's description and input schema still match, since a change there can mean a different result.
+ */
+export function outputShapeKey(tool: Pick<CachedTool, "description" | "inputSchema">): string {
+  return stableStringify({ description: tool.description ?? "", inputSchema: tool.inputSchema ?? null });
+}
+
+/**
+ * Saves one tool's observed output shape into its server's cache entry, if the entry matches the running config
+ * and tool. The entry comes from the same read the write replaces, so newer metadata from other Pi processes is kept.
+ */
+export function saveObservedOutput(
+  serverName: string,
+  definition: ServerEntry,
+  toolName: string,
+  toolKey: string,
+  output: NonNullable<ServerCacheEntry["outputShapes"]>[string],
+): void {
+  const configHash = computeServerHash(definition);
+  updateMetadataCacheFile(servers => {
+    const entry = servers[serverName];
+    const cachedTool = entry?.tools?.find(tool => tool.name === toolName);
+    if (!entry || !cachedTool || entry.configHash !== configHash || outputShapeKey(cachedTool) !== toolKey) return undefined;
+    return { ...servers, [serverName]: { ...entry, outputShapes: { ...entry.outputShapes, [toolName]: output } } };
+  });
+}
+
+/** Output shapes to carry into a rewritten cache entry: same config, not private, and only tools whose definition kept its shape key. */
+export function keepOutputShapes(
+  previous: ServerCacheEntry | undefined,
+  configHash: string,
+  tools: CachedTool[],
+): ServerCacheEntry["outputShapes"] {
+  if (!previous?.outputShapes || previous.configHash !== configHash || previous.cacheScope === "private") return undefined;
+  const kept = Object.entries(previous.outputShapes).filter(([toolName]) => {
+    const before = previous.tools?.find(tool => tool.name === toolName);
+    const after = tools.find(tool => tool.name === toolName);
+    return before !== undefined && after !== undefined && outputShapeKey(before) === outputShapeKey(after);
+  });
+  return kept.length > 0 ? Object.fromEntries(kept) : undefined;
+}
+
 export function isServerCacheValid(
   entry: ServerCacheEntry,
   definition: ServerEntry,
@@ -131,6 +179,8 @@ export function isServerCacheValid(
   }
   if (!entry || entry.configHash !== configHash) return false;
   if (!entry.cachedAt || typeof entry.cachedAt !== "number") return false;
+  // The persistent cache is not partitioned by authorization context.
+  if (entry.cacheScope === "private") return false;
   const declaredTtlMs = entry.ttlMs;
   if (typeof declaredTtlMs === "number" && Number.isSafeInteger(declaredTtlMs) && declaredTtlMs >= 0) {
     if (declaredTtlMs === 0) return false;

package/output-shape.ts

@@ -1,11 +1,14 @@
+import { logger } from "./logger.ts";
+import { outputShapeKey, saveObservedOutput } from "./metadata-cache.ts";
 import type { McpExtensionState } from "./state.ts";
 import { formatPropertyName } from "./ts-shape.ts";
-import type { ToolMetadata } from "./types.ts";
+import type { ServerCacheEntry, ServerDefinition, ToolMetadata } from "./types.ts";
 
 /**
- * Session-only output shapes for tools that declare no outputSchema.
+ * Output shapes for tools that declare no outputSchema.
  * Field names and broad JSON types only, never values; every dimension is
  * bounded because inference runs on arbitrary upstream payloads after each call.
+ * Script sessions also save them in the metadata cache for later sessions.
  */
 export interface OutputShape {
   type?: "null" | "boolean" | "number" | "string" | "object" | "array";
@@ -19,7 +22,13 @@ export interface OutputShape {
 export interface ObservedOutput {
   source: "structuredContent" | "jsonText";
   shape: OutputShape;
-  calls: number;
+  /** outputShapeKey of the tool definition the shape was learned against; other definitions do not see it. */
+  toolKey: string;
+  /**
+   * True once any observation merged into the shape was made under a private tool listing, which is tied to one
+   * authorization context. Such a shape is used in this session only and never saved.
+   */
+  private: boolean;
 }
 
 const MAX_DEPTH = 6;
@@ -33,61 +42,191 @@ const MAX_NODES_PER_CALL = 1000;
 // Sizes count UTF-16 code units (string length), not bytes.
 const MAX_SHAPE_CHARS = 4 * 1024;
 const MAX_JSON_TEXT_CHARS = 256 * 1024;
+// Object shapes at least this long that appear more than once are written once as a named type.
+const MIN_ALIAS_CHARS = 80;
+const SHAPE_TYPES = new Set(["null", "boolean", "number", "string", "object", "array"]);
 
-export function recordObservedOutput(
+/**
+ * Looks the tool up when the call starts, so its result is recorded against the definition it was
+ * requested under even if a tools/list_changed refresh replaces that definition mid-call.
+ */
+export function observedOutputRecorder(state: McpExtensionState, serverName: string, toolName: string): (result: Record<string, unknown>) => void {
+  const tool = findTool(state, serverName, toolName);
+  const listingIsPrivate = () => state.manager.getConnection(serverName)?.toolListHints?.cacheScope === "private";
+  const privateAtStart = listingIsPrivate();
+  return result => recordObservedOutput(state, serverName, tool, privateAtStart || listingIsPrivate(), result);
+}
+
+function recordObservedOutput(
   state: McpExtensionState,
   serverName: string,
-  toolName: string,
+  tool: ToolMetadata | undefined,
+  observedPrivately: boolean,
   result: Record<string, unknown>,
 ): void {
-  if (findTool(state, serverName, toolName)?.outputSchema !== undefined) return;
+  if (!tool || tool.outputSchema !== undefined) return;
+  const toolName = tool.originalName;
   const observed = readResultValue(result);
   if (!observed) return;
   const definition = state.config.mcpServers[serverName];
   if (!definition) return;
   const shape = inferShape(observed.value, 0, { nodes: MAX_NODES_PER_CALL });
-  const observedOutputs = state.observedOutputs ??= new WeakMap();
-  let byTool = observedOutputs.get(definition);
-  if (!byTool) observedOutputs.set(definition, byTool = new Map());
+  const byTool = observedOutputsFor(state, definition);
+  const toolKey = outputShapeKey(tool);
   const previous = byTool.get(toolName);
-  byTool.set(toolName, previous?.source === observed.source
-    ? { source: observed.source, shape: fitShape(mergeShapes(previous.shape, shape)), calls: previous.calls + 1 }
-    : { source: observed.source, shape: fitShape(shape), calls: 1 });
+  const mergeable = previous?.source === observed.source && previous.toolKey === toolKey;
+  const next: ObservedOutput = {
+    source: observed.source,
+    shape: fitShape(mergeable ? mergeShapes(previous.shape, shape) : shape),
+    toolKey,
+    private: observedPrivately || (mergeable && previous.private),
+  };
+  byTool.set(toolName, next);
+  // Skip unchanged shapes to avoid repeated cache writes; sessions without mcpScript never write.
+  if (state.scriptTool === true && !next.private && JSON.stringify(next) !== JSON.stringify(previous)) {
+    try {
+      saveObservedOutput(serverName, definition, toolName, toolKey, { source: next.source, shape: next.shape });
+    } catch (error) {
+      // The shape stays in memory for this session; only later sessions miss it.
+      logger.debug(`MCP: failed to save output shape for ${serverName}/${toolName}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+
+/** Adds shapes from a cache entry, tagged with the entry's own tool definitions, unless this session already has one for that definition. */
+export function seedObservedOutputs(state: McpExtensionState, serverName: string, entry: Pick<ServerCacheEntry, "tools" | "outputShapes">): void {
+  const definition = state.config.mcpServers[serverName];
+  const saved = entry.outputShapes;
+  if (!definition || typeof saved !== "object" || saved === null) return;
+  const byTool = observedOutputsFor(state, definition);
+  for (const [toolName, value] of Object.entries(saved)) {
+    const cachedTool = Array.isArray(entry.tools) ? entry.tools.find(tool => tool?.name === toolName) : undefined;
+    if (!cachedTool || typeof value !== "object" || value === null) continue;
+    const toolKey = outputShapeKey(cachedTool);
+    if (byTool.get(toolName)?.toolKey === toolKey) continue;
+    const { source, shape } = value as { source?: unknown; shape?: unknown };
+    if (source !== "structuredContent" && source !== "jsonText") continue;
+    const parsed = readSavedShape(shape, 0);
+    if (parsed && !isUnknown(parsed)) byTool.set(toolName, { source, shape: fitShape(parsed), toolKey, private: false });
+  }
 }
 
 export function getObservedOutput(
   state: McpExtensionState,
   serverName: string,
-  tool: Pick<ToolMetadata, "originalName" | "outputSchema">,
+  tool: Pick<ToolMetadata, "originalName" | "outputSchema" | "description" | "inputSchema">,
 ): ObservedOutput | undefined {
   if (tool.outputSchema !== undefined) return undefined;
   const definition = state.config.mcpServers[serverName];
   const observed = definition && state.observedOutputs?.get(definition)?.get(tool.originalName);
-  return observed && !isUnknown(observed.shape) ? observed : undefined;
+  return observed && observed.toolKey === outputShapeKey(tool) && !isUnknown(observed.shape) ? observed : undefined;
 }
 
 export function renderOutputShape(shape: OutputShape): string {
-  if (shape.anyOf) return shape.anyOf.map(renderOutputShape).join(" | ");
+  // First pass: each object's full text, counted, so APIs that repeat a wide object (a user under
+  // user, assignee, and assignees) show its fields once instead of three times.
+  const plain = new Map<OutputShape, string>();
+  const uses = new Map<string, { count: number; field: string }>();
+  const once = renderShape(shape, "item", (node, field, text) => {
+    plain.set(node, text);
+    const use = uses.get(text);
+    if (use) use.count++;
+    else uses.set(text, { count: 1, field });
+    return text;
+  });
+  const names = new Map<string, string>();
+  const taken = new Set(["Record"]);
+  for (const [text, use] of uses) {
+    if (use.count < 2 || text.length < MIN_ALIAS_CHARS) continue;
+    const words = use.field.split(/[^A-Za-z0-9]+/).filter(Boolean).map(part => part[0]!.toUpperCase() + part.slice(1)).join("");
+    const base = /^[A-Za-z]/.test(words) ? words : `T${words}`;
+    let name = base;
+    for (let suffix = 2; taken.has(name); suffix++) name = `${base}${suffix}`;
+    taken.add(name);
+    names.set(text, name);
+  }
+  if (names.size === 0) return once;
+  const definitions = new Map<string, string>();
+  const main = renderShape(shape, "item", (node, _field, text) => {
+    const name = names.get(plain.get(node)!);
+    if (!name) return text;
+    if (!definitions.has(name)) definitions.set(name, text);
+    return name;
+  });
+  return [...[...definitions].map(([name, body]) => `type ${name} = ${body};`), main].join("\n");
+}
+
+function renderShape(
+  shape: OutputShape,
+  field: string,
+  onObject: (node: OutputShape, field: string, text: string) => string,
+): string {
+  if (shape.anyOf) return shape.anyOf.map(variant => renderShape(variant, field, onObject)).join(" | ");
   switch (shape.type) {
     case undefined:
       return "unknown";
     case "object": {
-      if (shape.additionalProperties) return `Record<string, ${renderOutputShape(shape.additionalProperties)}>`;
+      if (shape.additionalProperties) return `Record<string, ${renderShape(shape.additionalProperties, field, onObject)}>`;
       const required = new Set(shape.required);
       const properties = Object.entries(shape.properties ?? {})
-        .map(([name, property]) => `${formatPropertyName(name)}${required.has(name) ? "" : "?"}: ${renderOutputShape(property)};`);
-      return properties.length === 0 ? "{}" : `{ ${properties.join(" ")} }`;
+        .map(([name, property]) => `${formatPropertyName(name)}${required.has(name) ? "" : "?"}: ${renderShape(property, name, onObject)};`);
+      return onObject(shape, field, properties.length === 0 ? "{}" : `{ ${properties.join(" ")} }`);
     }
     case "array": {
       if (!shape.items) return "unknown[]";
-      const item = renderOutputShape(shape.items);
-      return item.includes(" | ") ? `(${item})[]` : `${item}[]`;
+      const item = renderShape(shape.items, field, onObject);
+      return shape.items.anyOf ? `(${item})[]` : `${item}[]`;
     }
     default:
       return shape.type;
   }
 }
 
+function observedOutputsFor(state: McpExtensionState, definition: ServerDefinition): Map<string, ObservedOutput> {
+  const observedOutputs = state.observedOutputs ??= new WeakMap();
+  let byTool = observedOutputs.get(definition);
+  if (!byTool) observedOutputs.set(definition, byTool = new Map());
+  return byTool;
+}
+
+/** Rebuilds a shape read from the cache file, or returns undefined when any part is not something inferShape writes. */
+function readSavedShape(value: unknown, depth: number): OutputShape | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || depth > MAX_DEPTH) return undefined;
+  const raw = value as Record<string, unknown>;
+  if (raw.anyOf !== undefined) {
+    // Inference writes flat unions only; rejecting nested ones first keeps recursion bounded by MAX_DEPTH.
+    if (!Array.isArray(raw.anyOf) || raw.anyOf.length < 2 || raw.anyOf.length > MAX_UNION
+      || raw.anyOf.some(variant => typeof variant !== "object" || variant === null || "anyOf" in variant)) return undefined;
+    const variants = raw.anyOf.map(variant => readSavedShape(variant, depth));
+    return variants.every(variant => variant?.type !== undefined) ? { anyOf: variants as OutputShape[] } : undefined;
+  }
+  if (raw.type === undefined) return {};
+  if (typeof raw.type !== "string" || !SHAPE_TYPES.has(raw.type)) return undefined;
+  const shape: OutputShape = { type: raw.type as NonNullable<OutputShape["type"]> };
+  for (const key of ["items", "additionalProperties"] as const) {
+    if (raw[key] === undefined) continue;
+    const child = readSavedShape(raw[key], depth + 1);
+    if (!child) return undefined;
+    shape[key] = child;
+  }
+  if (raw.properties !== undefined) {
+    if (typeof raw.properties !== "object" || raw.properties === null || Array.isArray(raw.properties)) return undefined;
+    const entries = Object.entries(raw.properties);
+    if (entries.length > MAX_OBJECT_KEYS) return undefined;
+    const properties: Record<string, OutputShape> = {};
+    for (const [key, child] of entries) {
+      const property = key !== "__proto__" && FIELD_NAME.test(key) ? readSavedShape(child, depth + 1) : undefined;
+      if (!property) return undefined;
+      properties[key] = property;
+    }
+    shape.properties = properties;
+    shape.required = Array.isArray(raw.required)
+      ? raw.required.filter((key): key is string => typeof key === "string" && Object.hasOwn(properties, key))
+      : [];
+  }
+  return shape;
+}
+
 function findTool(state: McpExtensionState, serverName: string, toolName: string): ToolMetadata | undefined {
   return state.toolMetadata.get(serverName)?.find(tool => tool.originalName === toolName && !tool.resourceUri);
 }
@@ -181,11 +320,11 @@ function mergeSameType(left: OutputShape, right: OutputShape): OutputShape {
   return { type: "object", properties, required: (left.required ?? []).filter(key => rightRequired.has(key)) };
 }
 
-/** Drops nesting from the deepest level up until the stored shape fits the size bound. */
+/** Drops nesting from the deepest level up until the rendered shape, which is what describe shows, fits the size bound. */
 function fitShape(shape: OutputShape): OutputShape {
   for (let depth = MAX_DEPTH; depth > 0; depth--) {
     const pruned = pruneShape(shape, depth);
-    if (JSON.stringify(pruned).length <= MAX_SHAPE_CHARS) return pruned;
+    if (renderOutputShape(pruned).length <= MAX_SHAPE_CHARS) return pruned;
   }
   return {};
 }

package/package-mcp-loader.ts

@@ -103,11 +103,14 @@ function resolvePackageRoot(source: string, scope: "user" | "project", cwd: stri
     ? source.slice(4).trim()
     : /^(?:(?:https?|ssh):\/\/|git@[^:]+:)/.test(source) ? source : null;
   if (gitSource) {
-    const value = gitSource
-      .replace(/^ssh:\/\/git@/, "")
-      .replace(/^git@([^:]+):/, "$1/")
-      .replace(/^[a-z]+:\/\//i, "");
-    const path = value.replace(/@[^/]+$/, "").replace(/\.git$/, "");
+    // Pi installs URL sources under the bare hostname, without user or port.
+    const isUrl = /^[a-z]+:\/\//i.test(gitSource);
+    if (isUrl && !URL.canParse(gitSource)) return null;
+    const url = isUrl ? new URL(gitSource) : null;
+    const value = url ? url.hostname + url.pathname : gitSource.replace(/^git@([^:]+):/, "$1/");
+    // Like Pi, a non-empty ref starts at the first "@" after the host, so refs such as "@feature/x" keep their slash.
+    const refStart = value.indexOf("@", value.indexOf("/"));
+    const path = (refStart < 0 || refStart === value.length - 1 ? value : value.slice(0, refStart)).replace(/\.git$/, "");
     return path && !path.startsWith("/") ? resolveContainedPath(join(baseDir, "git"), path) : null;
   }
   return isAbsolute(source) ? resolve(source) : resolve(baseDir, source);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -196,7 +196,7 @@
     "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1 || ^0.85.0 || ^0.86.0 || ^0.87.0",
+    "@earendil-works/pi-ai": "^0.84.1 || ^0.85.0 || ^0.86.0 || ^0.87.0 || ^0.99.0",
     "@earendil-works/pi-tui": "*",
     "typebox": "*",
     "zod": "^3.25.0 || ^4.0.0"
@@ -213,9 +213,9 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.87.0",
-    "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0",
+    "@earendil-works/pi-ai": "0.99.1",
+    "@earendil-works/pi-coding-agent": "0.99.1",
+    "@earendil-works/pi-tui": "0.99.1",
     "@modelcontextprotocol/conformance": "0.1.16",
     "@types/bun": "^1.0.0",
     "@types/cross-spawn": "6.0.6",