pi-mcp-adapter 3.2.0 → 4.0.0

package/metadata-cache.ts

@@ -23,6 +23,7 @@ import type {
 import { createToolSelectorCandidateIndex, formatPromptCommandName, formatToolName, getToolNameCandidates, isServerDisabled, isToolAllowed, resolveToolPrefix, resolveUniqueNameOwnership, type ToolPrefix, type ToolSelectorCandidateIndex } from "./types.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";
 import {
+  extractToolAnnotations,
   extractToolUiStreamMode,
   interpolateEnvRecord,
   interpolateEnvVars,
@@ -57,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);
 }
 
@@ -116,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,
@@ -130,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;
@@ -225,6 +276,7 @@ export function reconstructToolMetadata(
     }
 
     const name = formatToolName(tool.name, serverName, effectivePrefix);
+    const annotations = extractToolAnnotations(tool.annotations);
     metadata.push({
       name,
       originalName: tool.name,
@@ -234,6 +286,7 @@ export function reconstructToolMetadata(
       ...(tool.uiResourceUri !== undefined ? { uiResourceUri: tool.uiResourceUri } : {}),
       ...(tool.uiVisibility !== undefined ? { uiVisibility: tool.uiVisibility } : {}),
       ...(tool.uiStreamMode !== undefined ? { uiStreamMode: tool.uiStreamMode } : {}),
+      ...(annotations !== undefined ? { annotations } : {}),
     });
   }
 
@@ -289,6 +342,7 @@ export function serializeTools(tools: McpTool[]): CachedTool[] {
       const uiResourceUri = tryGetToolUiResourceUri(t);
       const uiVisibility = extractUiToolVisibility(t._meta);
       const uiStreamMode = extractToolUiStreamMode(t._meta);
+      const annotations = extractToolAnnotations(t.annotations);
       return {
         name: t.name,
         ...(t.description !== undefined ? { description: t.description } : {}),
@@ -297,6 +351,7 @@ export function serializeTools(tools: McpTool[]): CachedTool[] {
         ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
         ...(uiVisibility !== undefined ? { uiVisibility } : {}),
         ...(uiStreamMode !== undefined ? { uiStreamMode } : {}),
+        ...(annotations !== undefined ? { annotations } : {}),
       };
     });
 }

package/output-shape.ts

@@ -0,0 +1,348 @@
+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 { ServerCacheEntry, ServerDefinition, ToolMetadata } from "./types.ts";
+
+/**
+ * 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";
+  properties?: Record<string, OutputShape>;
+  required?: string[];
+  items?: OutputShape;
+  additionalProperties?: OutputShape;
+  anyOf?: OutputShape[];
+}
+
+export interface ObservedOutput {
+  source: "structuredContent" | "jsonText";
+  shape: OutputShape;
+  /** 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;
+const MAX_ARRAY_SAMPLE = 5;
+// Objects wider than this, or with any key that does not look like a field name, are treated as maps
+// keyed by data (ids, emails, dates), so their keys are not kept.
+const MAX_OBJECT_KEYS = 40;
+const FIELD_NAME = /^[A-Za-z_$][A-Za-z0-9_$]{0,39}$/;
+const MAX_UNION = 4;
+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"]);
+
+/**
+ * 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,
+  tool: ToolMetadata | undefined,
+  observedPrivately: boolean,
+  result: Record<string, unknown>,
+): void {
+  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 byTool = observedOutputsFor(state, definition);
+  const toolKey = outputShapeKey(tool);
+  const previous = byTool.get(toolName);
+  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" | "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 && observed.toolKey === outputShapeKey(tool) && !isUnknown(observed.shape) ? observed : undefined;
+}
+
+export function renderOutputShape(shape: OutputShape): string {
+  // 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, ${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) ? "" : "?"}: ${renderShape(property, name, onObject)};`);
+      return onObject(shape, field, properties.length === 0 ? "{}" : `{ ${properties.join(" ")} }`);
+    }
+    case "array": {
+      if (!shape.items) return "unknown[]";
+      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);
+}
+
+function readResultValue(result: Record<string, unknown>): { source: ObservedOutput["source"]; value: unknown } | undefined {
+  const structured = result.structuredContent;
+  if (typeof structured === "object" && structured !== null) return { source: "structuredContent", value: structured };
+  const content = result.content;
+  if (!Array.isArray(content) || content.length !== 1) return undefined;
+  const block = content[0] as { type?: unknown; text?: unknown };
+  if (block.type !== "text" || typeof block.text !== "string" || block.text.length > MAX_JSON_TEXT_CHARS) return undefined;
+  const text = block.text.trim();
+  if (!text.startsWith("{") && !text.startsWith("[")) return undefined;
+  try {
+    return { source: "jsonText", value: JSON.parse(text) };
+  } catch {
+    return undefined;
+  }
+}
+
+function inferShape(value: unknown, depth: number, budget: { nodes: number }): OutputShape {
+  if (--budget.nodes < 0) return {};
+  if (value === null) return { type: "null" };
+  if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") return { type: typeof value as "boolean" | "number" | "string" };
+  if (typeof value !== "object" || depth >= MAX_DEPTH) return {};
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_ARRAY_SAMPLE).map(item => inferShape(item, depth + 1, budget));
+    return items.length === 0 ? { type: "array" } : { type: "array", items: items.reduce(mergeShapes) };
+  }
+  const record = value as Record<string, unknown>;
+  const keys: string[] = [];
+  let isMap = false;
+  // Stops at the first key that makes this a map, so a huge object costs O(MAX_OBJECT_KEYS) here.
+  for (const key in record) {
+    if (!Object.hasOwn(record, key)) continue;
+    keys.push(key);
+    // An own "__proto__" key would set the prototype of the shape's properties object instead of adding a field.
+    if (keys.length > MAX_OBJECT_KEYS || !FIELD_NAME.test(key) || /\d{4}/.test(key) || key === "__proto__") {
+      isMap = true;
+      break;
+    }
+  }
+  if (isMap) {
+    const values = keys.slice(0, MAX_ARRAY_SAMPLE).map(key => inferShape(record[key], depth + 1, budget));
+    return { type: "object", additionalProperties: values.reduce(mergeShapes) };
+  }
+  const properties: Record<string, OutputShape> = {};
+  for (const key of keys) properties[key] = inferShape(record[key], depth + 1, budget);
+  return { type: "object", properties, required: keys };
+}
+
+function isUnknown(shape: OutputShape): boolean {
+  return shape.type === undefined && shape.anyOf === undefined;
+}
+
+function mergeShapes(left: OutputShape, right: OutputShape): OutputShape {
+  if (isUnknown(left) || isUnknown(right)) return {};
+  const variants = [...(left.anyOf ?? [left])];
+  for (const variant of right.anyOf ?? [right]) {
+    const index = variants.findIndex(existing => existing.type === variant.type);
+    if (index === -1) variants.push(variant);
+    else variants[index] = mergeSameType(variants[index]!, variant);
+  }
+  if (variants.length > MAX_UNION) return {};
+  return variants.length === 1 ? variants[0]! : { anyOf: variants };
+}
+
+function mergeSameType(left: OutputShape, right: OutputShape): OutputShape {
+  if (left.type === "array") {
+    const items = left.items && right.items ? mergeShapes(left.items, right.items) : left.items ?? right.items;
+    return items ? { type: "array", items } : { type: "array" };
+  }
+  if (left.type !== "object") return left;
+  const keys = new Set([...Object.keys(left.properties ?? {}), ...Object.keys(right.properties ?? {})]);
+  if (left.additionalProperties || right.additionalProperties || keys.size > MAX_OBJECT_KEYS) {
+    const values = [
+      left.additionalProperties,
+      right.additionalProperties,
+      ...Object.values(left.properties ?? {}),
+      ...Object.values(right.properties ?? {}),
+    ].filter((shape): shape is OutputShape => shape !== undefined);
+    return { type: "object", additionalProperties: values.reduce(mergeShapes) };
+  }
+  const properties: Record<string, OutputShape> = {};
+  for (const key of keys) {
+    const leftProperty = left.properties?.[key];
+    const rightProperty = right.properties?.[key];
+    properties[key] = leftProperty && rightProperty ? mergeShapes(leftProperty, rightProperty) : (leftProperty ?? rightProperty)!;
+  }
+  const rightRequired = new Set(right.required);
+  return { type: "object", properties, required: (left.required ?? []).filter(key => rightRequired.has(key)) };
+}
+
+/** 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 (renderOutputShape(pruned).length <= MAX_SHAPE_CHARS) return pruned;
+  }
+  return {};
+}
+
+function pruneShape(shape: OutputShape, depth: number): OutputShape {
+  if (shape.anyOf) {
+    const variants = shape.anyOf.map(variant => pruneShape(variant, depth));
+    return variants.some(isUnknown) ? {} : { anyOf: variants };
+  }
+  if (shape.type !== "object" && shape.type !== "array") return shape;
+  if (depth === 0) return {};
+  const prune = (child: OutputShape) => pruneShape(child, depth - 1);
+  return {
+    ...shape,
+    ...(shape.properties
+      ? { properties: Object.fromEntries(Object.entries(shape.properties).map(([key, child]) => [key, prune(child)])) }
+      : {}),
+    ...(shape.items ? { items: prune(shape.items) } : {}),
+    ...(shape.additionalProperties ? { additionalProperties: prune(shape.additionalProperties) } : {}),
+  };
+}

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.2.0",
+  "version": "4.0.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -89,6 +89,7 @@
     "runtime-owner.ts",
     "tool-metadata.ts",
     "ts-shape.ts",
+    "output-shape.ts",
     "search-ranking.ts",
     "tool-approval.ts",
     "tool-parameters.ts",
@@ -180,7 +181,6 @@
   "dependencies": {
     "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/core": "2.0.0",
-    "@modelcontextprotocol/ext-apps": "^1.2.2",
     "@modelcontextprotocol/ext-tasks": "^0.1.0",
     "@napi-rs/keyring": "^2.1.0",
     "@typesafe-ai/sdk": "0.6.0",
@@ -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",

package/prompts.ts

@@ -122,6 +122,64 @@ function stripQuotes(value: string): string {
   return value;
 }
 
+function findCurrentPromptTokenStart(input: string): number {
+  let quote: '"' | "'" | null = null;
+  let escaped = false;
+  let start = 0;
+
+  for (let i = 0; i < input.length; i++) {
+    const char = input.charAt(i);
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) start = i + 1;
+  }
+
+  return start;
+}
+
+export function completePromptArgs(
+  metadata: PromptMetadata,
+  input: string,
+): Array<{ value: string; label: string; description?: string }> | null {
+  const tokenStart = findCurrentPromptTokenStart(input);
+  const current = input.slice(tokenStart);
+  if (current.includes("=") || current.startsWith('"') || current.startsWith("'")) return null;
+
+  const committed = input.slice(0, tokenStart);
+  const parsed = parsePromptArgs(committed);
+  const used = new Set(Object.keys(parsed.named));
+  let positionalIndex = 0;
+
+  for (const arg of metadata.arguments) {
+    if (Object.hasOwn(parsed.named, arg.name)) continue;
+    const positional = parsed.positional[positionalIndex++];
+    if (positional !== undefined && positional !== "") used.add(arg.name);
+  }
+
+  const matches = metadata.arguments.filter(arg => !used.has(arg.name) && arg.name.startsWith(current));
+  if (matches.length === 0) return null;
+
+  return matches.map(arg => ({
+    value: committed + arg.name + "=",
+    label: arg.name + "=",
+    ...(arg.description ? { description: arg.description } : {}),
+  }));
+}
+
 export interface ResolvedPromptArgs {
   ok: boolean;
   /** Present when `ok === true`. */
@@ -249,6 +307,16 @@ export function createPromptCommand(
 
   return {
     description,
+    getArgumentCompletions: (prefix: string) => {
+      const state = getState();
+      if (!state) return completePromptArgs(metadata, prefix);
+      const definition = state.config.mcpServers[metadata.serverName];
+      if (!definition || isServerDisabled(definition)) return null;
+
+      const liveMetadata = findLivePromptMetadata(state, metadata.serverName, metadata.originalName);
+      if (state.promptMetadataLive?.has(metadata.serverName) && !liveMetadata) return null;
+      return completePromptArgs(liveMetadata ?? metadata, prefix);
+    },
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       let state = getState();
       if (!state && runtime.ensureState) {