pi-mcp-adapter 2.26.0 → 2.26.1

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.26.1] - 2026-08-18
+
+### Fixed
+- Scoped “Allow for session” tool approvals to the approved arguments, so one approval no longer applies to later calls with different inputs. Thanks to [@spaceshipmike](https://github.com/spaceshipmike) for #367.
+- Stopped MCP panel commands from hanging in RPC, JSON, and print modes when terminal-only UI is unavailable. Thanks to [@shixin-guo](https://github.com/shixin-guo) for PR #365.
+- Kept compact MCP result rows useful by showing a short input preview and skipping leading blank output in collapsed previews.
+- Recovered MCP gateway requests nested inside proxy `args` instead of showing status, and now rejects invalid nested gateway requests with guidance. Thanks to [@ibrmora](https://github.com/ibrmora) for #363.
+- Kept remote keep-alive tool catalogs fresh across server restarts, so long-lived Pi sessions can discover replacement tools without restarting. Thanks to [@dmorn](https://github.com/dmorn) for #369 and PR #370.
+
 ## [2.26.0] - 2026-08-14
 
 ### Added

package/README.md

@@ -293,8 +293,10 @@ You can also pass only the `code` query parameter with `args: { code: "..." }`.
 
 - **`lazy`** (default) — Don't connect at startup. Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
 - **`eager`** — Connect at startup but don't auto-reconnect if the connection drops. No idle timeout by default (set `idleTimeout` explicitly to enable).
-- **`keep-alive`** — Connect at startup. Auto-reconnect via health checks. No idle timeout. Use for servers you always need available.
-- **`lazy-keep-alive`** — Don't connect at startup. Connect on first tool call (like `lazy`). Once spawned, never idle-shut down and auto-reconnect via health checks if the process dies (like `keep-alive`). Use for servers that are expensive to start but should stay resident after their first use.
+- **`keep-alive`** — Connect at startup. Remote HTTP servers refresh their tool catalog during health checks, before user input, and before adapter-triggered turns, reconnecting when the server reports that the session expired. No idle timeout. Use for servers you always need available.
+- **`lazy-keep-alive`** — Don't connect at startup. Connect on first tool call (like `lazy`). Once spawned, never idle-shut down and use the same catalog refresh and reconnect checks as `keep-alive`. Use for servers that are expensive to start but should stay resident after their first use.
+
+For remote HTTP keep-alive servers, the authoritative `tools/list` refresh is also the fallback when `list_changed` notifications are unavailable or their stream is lost. Each `tools/list` or `ping` request is capped at 5 seconds, up to 10 servers are checked concurrently, and transient failures use bounded backoff. A successful refresh updates metadata without reconnecting; a response proving that the HTTP session expired triggers a full reconnect and reinstalls the notification handlers. Dynamic direct-tool registration follows the refreshed metadata unless `freezeDirectTools` is enabled.
 
 When any enabled server uses `eager` or `keep-alive`, initialization also starts when the extension loads. This supports hosts that embed Pi programmatically and never emit `session_start`; if a session does start later, the session-owned runtime supersedes the load-time runtime.
 
@@ -658,7 +660,7 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 
 `mcp({ connect: "server-name" })` refreshes an already connected server, so new tools, resources, prompts, and instructions can load without restarting Pi.
 
-MCP proxy and direct-tool results use compact self-rendered rows by default. Collapsed success output shows the call title and the first result line, with a `Ctrl+O to expand` hint when more text is hidden. The full result remains available when expanded and is still returned unchanged to the model. Set `settings.toolResultRendering` to `"boxed"` to restore the legacy boxed Pi row, or set `settings.collapsedResultLines` to `2` or `3` when you want more collapsed text.
+MCP proxy and direct-tool results use compact self-rendered rows by default. Collapsed success output shows the call title, a bounded one-line input preview when arguments exist, and the first result line, with a `Ctrl+O to expand` hint when more text is hidden. The full result remains available when expanded and is still returned unchanged to the model. Set `settings.toolResultRendering` to `"boxed"` to restore the legacy boxed Pi row, or set `settings.collapsedResultLines` to `2` or `3` when you want more collapsed text.
 
 Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are ranked by weighted matches across name, server, description, and any configured `searchKeywords`, then returned one page at a time (`limit` defaults to 12). Use `details.nextOffset` for the next page. Regex search is still available with `regex: true`, but regex results are paginated without ranking.
 
@@ -725,7 +727,7 @@ Advertised tool `outputSchema` values support JSON Schema draft-07 and 2020-12.
 - Idle servers disconnect after 10 minutes (configurable), reconnect automatically on next use
 - npx-based servers resolve to direct binary paths, skipping the ~143 MB npm parent process
 - MCP server validates arguments, not the adapter
-- Keep-alive servers get health checks and auto-reconnect
+- Remote keep-alive servers force-refresh their tool catalog during health checks, before user input, and before adapter-triggered turns, with bounded reconnect backoff
 - Specific tools can be promoted from the proxy to first-class Pi tools via `directTools` config, so the LLM sees them directly instead of having to search
 
 ## Limitations

package/commands.ts

@@ -28,6 +28,19 @@ function terminalHyperlink(label: string, url: string): string {
   return `\u001B]8;;${sanitizeTerminalText(url)}\u001B\\${sanitizeTerminalText(label)}\u001B]8;;\u001B\\`;
 }
 
+/**
+ * True when this run mode can display a `ctx.ui.custom()` overlay.
+ *
+ * `ctx.hasUI` only reports that *some* UI context is bound. In rpc/print mode
+ * that context is a headless stub whose `custom()` returns immediately without
+ * ever invoking the factory or the `done` callback, so a panel awaited through
+ * `new Promise(resolve => ctx.ui.custom(...))` never settles and the command
+ * hangs. Overlay panels therefore additionally require `ctx.mode === "tui"`.
+ */
+function canRenderPanel(ctx: ExtensionContext): boolean {
+  return ctx.hasUI && ctx.mode === "tui";
+}
+
 export async function showStatus(state: McpExtensionState, ctx: ExtensionContext): Promise<void> {
   if (!ctx.hasUI) return;
 
@@ -399,6 +412,10 @@ export async function openMcpSetup(
   options: { includeHostConfigs?: boolean } = {},
 ): Promise<PanelFlowResult> {
   if (!ctx.hasUI) return { configChanged: false };
+  if (!canRenderPanel(ctx)) {
+    ctx.ui.notify(`The interactive MCP setup panel is only available in the terminal UI (current mode: ${ctx.mode}). Edit .mcp.json directly, or run /mcp status to review servers.`, "info");
+    return { configChanged: false };
+  }
   if (state.programmaticConfig) {
     ctx.ui.notify("MCP setup is unavailable when config is supplied by createMcpAdapter().", "info");
     return { configChanged: false };
@@ -533,6 +550,11 @@ export async function openMcpPanel(
     }
     return { configChanged: false };
   }
+  if (!canRenderPanel(ctx)) {
+    // No overlay here, but the same information is available as text.
+    await showStatus(state, ctx);
+    return { configChanged: false };
+  }
   if (Object.keys(state.config.mcpServers).length === 0) {
     return openMcpSetup(state, pi, ctx, configOverridePath, "empty", { includeHostConfigs: false });
   }
@@ -587,6 +609,10 @@ export async function openMcpAuthPanel(
   configOverridePath?: string,
 ): Promise<PanelFlowResult> {
   if (!ctx.hasUI) return { configChanged: false };
+  if (!canRenderPanel(ctx)) {
+    ctx.ui.notify(`The interactive MCP auth panel is only available in the terminal UI (current mode: ${ctx.mode}). Use /mcp-auth <server> to authenticate a specific server.`, "info");
+    return { configChanged: false };
+  }
   if (state.programmaticConfig) {
     ctx.ui.notify("Use /mcp-auth <server> to authenticate a server from the in-memory SDK config.", "info");
     return { configChanged: false };

package/index.ts

@@ -417,6 +417,29 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     }
   });
 
+  pi.on("input", async () => {
+    const inputOwner = currentOwner;
+    if (!inputOwner?.isActive()) return;
+
+    if (!state && initPromise) {
+      try {
+        await awaitWithTimeout(initPromise, INIT_WAIT_TIMEOUT_MS);
+      } catch {
+        return;
+      }
+    }
+
+    const inputState = state;
+    if (!inputState || !inputOwner.isActive()) return;
+    try {
+      await inputState.lifecycle.ensureConverged(inputOwner.signal);
+    } catch (error) {
+      if (!isAbortError(error, inputOwner.signal)) {
+        logger.debug(`MCP: keep-alive convergence failed before input: ${formatTerminalError(error)}`);
+      }
+    }
+  });
+
   pi.on("session_shutdown", async () => {
     ++lifecycleGeneration;
     const currentState = state;
@@ -737,12 +760,12 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         action?: string;
       }, signal: AbortSignal | undefined, _onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined, _ctx: ExtensionContext) {
         const executeOwner = currentOwner;
-        let parsedArgs: Record<string, unknown> | undefined;
-        if (params.args !== undefined && params.args !== "") {
+        const parseArgs = (value: string | Record<string, unknown> | undefined): Record<string, unknown> | undefined => {
+          if (value === undefined || value === "") return undefined;
           let args: unknown;
-          if (typeof params.args === "string") {
+          if (typeof value === "string") {
             try {
-              args = JSON.parse(params.args);
+              args = JSON.parse(value);
             } catch (error) {
               if (error instanceof SyntaxError) {
                 throw new Error(`Invalid args JSON: ${error.message}`, { cause: error });
@@ -750,14 +773,35 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
               throw error;
             }
           } else {
-            args = params.args;
+            args = value;
           }
 
           if (typeof args !== "object" || args === null || Array.isArray(args)) {
             const gotType = Array.isArray(args) ? "array" : args === null ? "null" : typeof args;
             throw new Error(`Invalid args: expected a JSON object, got ${gotType}`);
           }
-          parsedArgs = args as Record<string, unknown>;
+          return args as Record<string, unknown>;
+        };
+        let parsedArgs = parseArgs(params.args);
+        let dispatchParams = params;
+        const hasGatewayMode = (value: typeof params): boolean =>
+          value.tool !== undefined
+          || value.connect !== undefined
+          || value.describe !== undefined
+          || value.instructions !== undefined
+          || value.search !== undefined
+          || value.server !== undefined
+          || value.action !== undefined;
+        if (!hasGatewayMode(params) && parsedArgs) {
+          const nestedParams = parsedArgs as typeof params;
+          if (hasGatewayMode(nestedParams)) {
+            dispatchParams = nestedParams;
+            parsedArgs = parseArgs(nestedParams.args);
+          } else {
+            throw new Error("Gateway params were nested inside `args`; pass them top-level (for example, mcp({ search: \"...\" }) or mcp({ tool: \"...\", args: {} })).");
+          }
+        } else if (!hasGatewayMode(params) && params.args !== undefined) {
+          throw new Error("Gateway params were nested inside `args`; pass them top-level (for example, mcp({ search: \"...\" }) or mcp({ tool: \"...\", args: {} })).");
         }
 
         if (!state && initPromise) {
@@ -788,22 +832,22 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         }
         executeOwner?.throwIfInactive();
 
-        if (params.action === "ui-messages") {
+        if (dispatchParams.action === "ui-messages") {
           return executeUiMessages(state);
         }
-        if (params.action === "auth-start") {
-          if (!params.server) {
+        if (dispatchParams.action === "auth-start") {
+          if (!dispatchParams.server) {
             return {
               content: [{ type: "text" as const, text: "auth-start requires `server`. Example: mcp({ action: \"auth-start\", server: \"linear-server\" })" }],
               details: { mode: "auth-start", error: "missing_server" },
             };
           }
           return signal
-            ? executeAuthStart(state, params.server, signal)
-            : executeAuthStart(state, params.server);
+            ? executeAuthStart(state, dispatchParams.server, signal)
+            : executeAuthStart(state, dispatchParams.server);
         }
-        if (params.action === "auth-complete") {
-          if (!params.server) {
+        if (dispatchParams.action === "auth-complete") {
+          if (!dispatchParams.server) {
             return {
               content: [{ type: "text" as const, text: "auth-complete requires `server`." }],
               details: { mode: "auth-complete", error: "missing_server" },
@@ -817,28 +861,28 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
             };
           }
           return signal
-            ? executeAuthComplete(state, params.server, input, signal)
-            : executeAuthComplete(state, params.server, input);
+            ? executeAuthComplete(state, dispatchParams.server, input, signal)
+            : executeAuthComplete(state, dispatchParams.server, input);
         }
-        if (params.tool) {
-          return executeCall(state, params.tool, parsedArgs, params.server, getPiTools, signal);
+        if (dispatchParams.tool) {
+          return executeCall(state, dispatchParams.tool, parsedArgs, dispatchParams.server, getPiTools, signal);
         }
-        if (params.connect) {
-          const result = await executeConnect(state, params.connect, signal);
+        if (dispatchParams.connect) {
+          const result = await executeConnect(state, dispatchParams.connect, signal);
           syncToolSurface(_ctx as ExtensionContext);
           return result;
         }
-        if (params.describe) {
-          return executeDescribe(state, params.describe);
+        if (dispatchParams.describe) {
+          return executeDescribe(state, dispatchParams.describe);
         }
-        if (params.instructions) {
-          return executeInstructions(state, params.instructions);
+        if (dispatchParams.instructions) {
+          return executeInstructions(state, dispatchParams.instructions);
         }
-        if (params.search !== undefined) {
-          return executeSearch(state, params.search, params.regex, params.server, params.includeSchemas, params.limit, params.offset);
+        if (dispatchParams.search !== undefined) {
+          return executeSearch(state, dispatchParams.search, dispatchParams.regex, dispatchParams.server, dispatchParams.includeSchemas, dispatchParams.limit, dispatchParams.offset);
         }
-        if (params.server) {
-          return executeList(state, params.server);
+        if (dispatchParams.server) {
+          return executeList(state, dispatchParams.server);
         }
         return executeStatus(state);
       },

package/init.ts

@@ -179,8 +179,20 @@ export async function initializeMcp(
     },
     ...(ui !== undefined ? { ui } : {}),
     sendMessage: (message, options) => {
-      if (!owner.isActive()) return;
-      pi.sendMessage(message as unknown as Parameters<typeof pi.sendMessage>[0], options);
+      const deliver = () => {
+        if (!owner.isActive()) return;
+        pi.sendMessage(message as unknown as Parameters<typeof pi.sendMessage>[0], options);
+      };
+      if (!options?.triggerTurn) {
+        deliver();
+        return;
+      }
+      void lifecycle.ensureConverged(owner.signal).then(deliver, error => {
+        if (!owner.isActive() || isAbortError(error, owner.signal)) return;
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.debug(`MCP: pre-turn keep-alive convergence failed: ${sanitizeTerminalText(detail)}`);
+        deliver();
+      });
     },
     ...(options.statusEvents !== undefined ? { statusEvents: options.statusEvents } : {}),
   };
@@ -419,6 +431,18 @@ export async function initializeMcp(
     updateStatusBar(state);
   });
 
+  lifecycle.setHealthRestoredCallback((serverName) => {
+    if (!owner.isActive()) return;
+    clearFailure(state, serverName);
+    updateStatusBar(state);
+  });
+
+  lifecycle.setAuthRequiredCallback((serverName) => {
+    if (!owner.isActive()) return;
+    clearFailure(state, serverName);
+    updateStatusBar(state);
+  });
+
   lifecycle.setIdleShutdownCallback((serverName) => {
     if (!owner.isActive()) return;
     const idleMinutes = getEffectiveIdleTimeoutMinutes(state, serverName);

package/lifecycle.ts

@@ -1,11 +1,26 @@
+import { SdkError, SdkErrorCode } from "@modelcontextprotocol/client";
 import { isServerDisabled, type ServerDefinition } from "./types.ts";
-import type { McpServerManager } from "./server-manager.ts";
+import type { McpServerManager, ServerConnection } from "./server-manager.ts";
 import { hasPendingAuth } from "./mcp-auth-flow.ts";
 import { logger } from "./logger.ts";
-import { formatTerminalError, sanitizeTerminalText } from "./utils.ts";
+import { formatTerminalError, parallelLimit, sanitizeTerminalText } from "./utils.ts";
+import { isTerminatedSession } from "./session-recovery.ts";
 
-export type ReconnectCallback = (serverName: string) => void;
+export type ReconnectCallback = (serverName: string) => void | Promise<void>;
 export type ReconnectFailureCallback = (serverName: string, error: unknown) => void;
+export type HealthRestoredCallback = (serverName: string) => void | Promise<void>;
+export type AuthRequiredCallback = (serverName: string) => void | Promise<void>;
+
+const KEEP_ALIVE_RETRY_BASE_MS = 30_000;
+const KEEP_ALIVE_RETRY_MAX_MS = 5 * 60_000;
+const KEEP_ALIVE_CHECK_CONCURRENCY = 10;
+
+interface RetryState {
+  attempts: number;
+  nextAttemptAt: number;
+  connection: ServerConnection | undefined;
+  status: ServerConnection["status"] | undefined;
+}
 
 export class McpLifecycleManager {
   private keepAliveServers = new Map<string, ServerDefinition>();
@@ -15,9 +30,14 @@ export class McpLifecycleManager {
   private healthCheckInterval: NodeJS.Timeout | undefined;
   private onReconnect: ReconnectCallback | undefined;
   private onReconnectFailure: ReconnectFailureCallback | undefined;
+  private onHealthRestored: HealthRestoredCallback | undefined;
+  private onAuthRequired: AuthRequiredCallback | undefined;
   private onIdleShutdown: ((serverName: string) => void) | undefined;
   private activeHealthCheck: Promise<void> | undefined;
+  private activeConvergence: Promise<void> | undefined;
   private shutdownPromise: Promise<void> | undefined;
+  private retryStates = new Map<string, RetryState>();
+  private pendingMetadataPublications = new Set<string>();
   private stopped = false;
   private removeHealthAbortListener: (() => void) | undefined;
 
@@ -34,6 +54,14 @@ export class McpLifecycleManager {
     this.onReconnectFailure = callback;
   }
 
+  setHealthRestoredCallback(callback: HealthRestoredCallback): void {
+    this.onHealthRestored = callback;
+  }
+
+  setAuthRequiredCallback(callback: AuthRequiredCallback): void {
+    this.onAuthRequired = callback;
+  }
+
   markKeepAlive(name: string, definition: ServerDefinition): void {
     if (isServerDisabled(definition)) return;
     this.keepAliveServers.set(name, definition);
@@ -82,29 +110,23 @@ export class McpLifecycleManager {
     this.healthCheckInterval.unref();
   }
 
-  private async checkConnections(signal?: AbortSignal): Promise<void> {
+  async ensureConverged(signal?: AbortSignal): Promise<void> {
     if (this.stopped || signal?.aborted) return;
-    for (const [name, definition] of this.keepAliveServers) {
-      if (isServerDisabled(definition)) continue;
-      const connection = this.manager.getConnection(name);
-      if (!connection || connection.status !== "connected") {
-        if (this.hasPendingAuthForServer(name)) {
-          logger.debug(`Skipping reconnect for ${name} while OAuth authorization is pending`);
-          continue;
-        }
-        try {
-          await this.manager.connect(name, definition, signal);
-          if (this.stopped || signal?.aborted) return;
-          logger.debug(`Reconnected to ${name}`);
-          this.onReconnect?.(name);
-        } catch (error) {
-          if (this.stopped || signal?.aborted) return;
-          this.onReconnectFailure?.(name, error);
-          const message = error instanceof Error ? error.message : String(error);
-          console.error(`MCP: Failed to reconnect to ${name}: ${sanitizeTerminalText(message)}`);
-        }
-      }
+    if (this.activeConvergence) return this.activeConvergence;
+
+    const check = this.checkKeepAliveConnections(signal);
+    this.activeConvergence = check;
+    try {
+      await check;
+    } finally {
+      if (this.activeConvergence === check) this.activeConvergence = undefined;
     }
+  }
+
+  private async checkConnections(signal?: AbortSignal): Promise<void> {
+    if (this.stopped || signal?.aborted) return;
+    await this.ensureConverged(signal);
+    if (this.stopped || signal?.aborted) return;
 
     for (const [name] of this.allServers) {
       if (this.keepAliveServers.has(name)) continue;
@@ -117,6 +139,205 @@ export class McpLifecycleManager {
     }
   }
 
+  private async checkKeepAliveConnections(signal?: AbortSignal): Promise<void> {
+    if (this.stopped || signal?.aborted) return;
+    await parallelLimit(
+      [...this.keepAliveServers],
+      KEEP_ALIVE_CHECK_CONCURRENCY,
+      ([name, definition]) => this.checkKeepAliveConnection(name, definition, signal),
+    );
+  }
+
+  private async checkKeepAliveConnection(
+    name: string,
+    definition: ServerDefinition,
+    signal?: AbortSignal,
+    retrySuperseded = true,
+  ): Promise<void> {
+    if (isServerDisabled(definition) || this.stopped || signal?.aborted) return;
+    const connection = this.manager.getConnection(name);
+    if (connection?.status === "needs-auth") {
+      this.pendingMetadataPublications.delete(name);
+      return;
+    }
+    if (!this.shouldAttemptConnection(name, connection)) return;
+    if (!connection || connection.status !== "connected") {
+      if (this.hasPendingAuthForServer(name)) {
+        logger.debug(`Skipping reconnect for ${name} while OAuth authorization is pending`);
+        return;
+      }
+      let freshConnection: ServerConnection;
+      try {
+        freshConnection = await this.manager.connect(name, definition, signal);
+      } catch (error) {
+        if (this.stopped || signal?.aborted) return;
+        this.reportConnectionFailure(name, error, "reconnect", this.manager.getConnection(name));
+        return;
+      }
+      if (this.stopped || signal?.aborted) return;
+      if (freshConnection.status === "needs-auth") {
+        await this.notifyAuthRequired(name);
+        return;
+      }
+      if (freshConnection.status !== "connected") {
+        this.reportConnectionFailure(
+          name,
+          new Error(`MCP server ${name} did not return a connected session`),
+          "reconnect",
+          freshConnection,
+        );
+        return;
+      }
+      logger.debug(`Reconnected to ${name}`);
+      await this.publishConnectedMetadata(name, freshConnection);
+      return;
+    }
+
+    if (this.pendingMetadataPublications.has(name)) {
+      await this.publishConnectedMetadata(name, connection);
+      return;
+    }
+    if (!definition.url) return;
+    const hadSessionId = (connection.transport as { sessionId?: string } | undefined)?.sessionId != null;
+    let refreshResult: Awaited<ReturnType<McpServerManager["refreshTools"]>>;
+    try {
+      refreshResult = await this.manager.refreshTools(name, connection, signal);
+    } catch (error) {
+      if (this.stopped || signal?.aborted) return;
+      const current = this.manager.getConnection(name);
+      if (current !== connection || connection.status !== "connected") {
+        await this.handleSupersededConnection(name, definition, connection, signal, retrySuperseded);
+        return;
+      }
+      if (!shouldReconnectAfterRefresh(error, hadSessionId)) {
+        this.reportConnectionFailure(name, error, "refresh", connection);
+        return;
+      }
+      if (this.hasPendingAuthForServer(name)) {
+        logger.debug(`Skipping reconnect for ${name} while OAuth authorization is pending`);
+        return;
+      }
+      let freshConnection: ServerConnection;
+      try {
+        freshConnection = await this.manager.reconnect(name, definition, connection, signal);
+      } catch (reconnectError) {
+        if (this.stopped || signal?.aborted) return;
+        this.reportConnectionFailure(name, reconnectError, "reconnect", this.manager.getConnection(name));
+        return;
+      }
+      if (this.stopped || signal?.aborted) return;
+      if (freshConnection.status === "needs-auth") {
+        await this.notifyAuthRequired(name);
+        return;
+      }
+      if (freshConnection.status !== "connected") {
+        this.reportConnectionFailure(
+          name,
+          new Error(`MCP server ${name} did not return a connected session`),
+          "reconnect",
+          freshConnection,
+        );
+        return;
+      }
+      logger.debug(`Reconnected stale MCP session for ${name}`);
+      await this.publishConnectedMetadata(name, freshConnection);
+      return;
+    }
+
+    if (refreshResult === "superseded") {
+      await this.handleSupersededConnection(name, definition, connection, signal, retrySuperseded);
+      return;
+    }
+    if (this.retryStates.delete(name)) {
+      await this.onHealthRestored?.(name);
+    }
+  }
+
+  private async handleSupersededConnection(
+    name: string,
+    definition: ServerDefinition,
+    staleConnection: ServerConnection,
+    signal: AbortSignal | undefined,
+    retrySuperseded: boolean,
+  ): Promise<void> {
+    const current = this.manager.getConnection(name);
+    if (current === staleConnection && current.status === "connected") {
+      if (this.retryStates.delete(name)) await this.onHealthRestored?.(name);
+      return;
+    }
+    if (current?.status === "connected") {
+      await this.publishConnectedMetadata(name, current);
+      return;
+    }
+    if (current?.status === "needs-auth") {
+      await this.notifyAuthRequired(name);
+      return;
+    }
+    if (retrySuperseded) {
+      await this.checkKeepAliveConnection(name, definition, signal, false);
+    }
+  }
+
+  private async publishConnectedMetadata(name: string, connection: ServerConnection): Promise<void> {
+    this.pendingMetadataPublications.add(name);
+    try {
+      await this.onReconnect?.(name);
+      this.pendingMetadataPublications.delete(name);
+      this.retryStates.delete(name);
+    } catch (error) {
+      if (this.stopped) return;
+      this.reportConnectionFailure(name, error, "publish", connection);
+    }
+  }
+
+  private async notifyAuthRequired(name: string): Promise<void> {
+    this.pendingMetadataPublications.delete(name);
+    this.retryStates.delete(name);
+    try {
+      await this.onAuthRequired?.(name);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.debug(`MCP: auth-required callback failed for ${name}: ${sanitizeTerminalText(message)}`);
+    }
+  }
+
+  private shouldAttemptConnection(name: string, connection: ServerConnection | undefined): boolean {
+    const retry = this.retryStates.get(name);
+    if (!retry) return true;
+    if (retry.connection !== connection || retry.status !== connection?.status) {
+      this.retryStates.delete(name);
+      return true;
+    }
+    return Date.now() >= retry.nextAttemptAt;
+  }
+
+  private reportConnectionFailure(
+    name: string,
+    error: unknown,
+    action: "refresh" | "reconnect" | "publish",
+    connection: ServerConnection | undefined,
+  ): void {
+    const attempts = (this.retryStates.get(name)?.attempts ?? 0) + 1;
+    const delay = Math.min(
+      KEEP_ALIVE_RETRY_BASE_MS * 2 ** Math.min(attempts - 1, 10),
+      KEEP_ALIVE_RETRY_MAX_MS,
+    );
+    this.retryStates.set(name, {
+      attempts,
+      nextAttemptAt: Date.now() + delay,
+      connection,
+      status: connection?.status,
+    });
+    this.onReconnectFailure?.(name, error);
+    const message = error instanceof Error ? error.message : String(error);
+    const target = action === "reconnect"
+      ? `reconnect to ${name}`
+      : action === "publish"
+        ? `publish metadata for ${name}`
+        : `refresh ${name}`;
+    console.error(`MCP: Failed to ${target}: ${sanitizeTerminalText(message)}`);
+  }
+
   private getIdleTimeout(name: string): number {
     const perServer = this.serverSettings.get(name)?.idleTimeout;
     if (perServer !== undefined) return perServer * 60 * 1000;
@@ -137,11 +358,23 @@ export class McpLifecycleManager {
     this.removeHealthAbortListener = undefined;
     await this.activeHealthCheck;
     this.activeHealthCheck = undefined;
+    await this.activeConvergence;
+    this.activeConvergence = undefined;
     this.onReconnect = undefined;
     this.onReconnectFailure = undefined;
+    this.onHealthRestored = undefined;
+    this.onAuthRequired = undefined;
     this.onIdleShutdown = undefined;
+    this.retryStates.clear();
+    this.pendingMetadataPublications.clear();
     if (typeof this.manager.closeAll === "function") {
       await this.manager.closeAll();
     }
   }
 }
+
+function shouldReconnectAfterRefresh(error: unknown, hadSessionId: boolean): boolean {
+  if (isTerminatedSession(error, hadSessionId)) return true;
+  return error instanceof SdkError
+    && (error.code === SdkErrorCode.NotConnected || error.code === SdkErrorCode.ConnectionClosed);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.26.0",
+  "version": "2.26.1",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",

package/server-manager.ts

@@ -1,4 +1,5 @@
 import { mkdirSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
 import {
   Client,
   SdkHttpError,
@@ -7,6 +8,7 @@ import {
   UnauthorizedError,
   type GetPromptResult,
   type ReadResourceResult,
+  type CacheableRequestOptions,
   type RequestOptions,
   type UrlElicitationRequiredError,
   type VersionNegotiationOptions,
@@ -123,6 +125,8 @@ export interface ServerConnection {
   transport: Transport;
   definition: ServerDefinition;
   tools: McpTool[];
+  /** Monotonic guard against older refresh responses replacing newer notifications. */
+  toolsRevision?: number;
   resources: McpResource[];
   prompts: McpPrompt[];
   /** True when prompts were advertised but prompts/list failed. */
@@ -139,6 +143,10 @@ export interface ServerConnection {
 type UiStreamListener = (serverName: string, notification: ServerStreamResultPatchNotification["params"]) => void;
 type MetadataListChangedListener = (serverName: string, reason: string) => void;
 
+export type ToolRefreshResult = "updated" | "unchanged" | "superseded";
+
+const KEEP_ALIVE_REFRESH_TIMEOUT_MS = 5_000;
+
 export class McpServerManager {
   private connections = new Map<string, ServerConnection>();
   private connectPromises = new Map<string, Promise<ServerConnection>>();
@@ -146,6 +154,10 @@ export class McpServerManager {
   private uiStreamListeners = new Map<string, UiStreamListener>();
   private samplingConfig: ServerSamplingConfig | undefined;
   private metadataListChangedListener: MetadataListChangedListener | undefined;
+  private pendingMetadataPublications = new Map<
+    string,
+    { connection: ServerConnection; reason: string }
+  >();
   private elicitationConfig: ServerElicitationConfig | undefined;
   private authStorageOptions: AuthStorageOptions = {};
   private oauthRuntime: McpOAuthRuntime | undefined;
@@ -170,6 +182,25 @@ export class McpServerManager {
     this.metadataListChangedListener = listener;
   }
 
+  publishMetadataChanged(
+    name: string,
+    expectedConnection: ServerConnection,
+    reason: string,
+  ): boolean {
+    const current = this.connections.get(name);
+    if (current !== expectedConnection || current.status !== "connected") return false;
+    try {
+      this.metadataListChangedListener?.(name, reason);
+      this.pendingMetadataPublications.delete(name);
+      return true;
+    } catch (error) {
+      this.pendingMetadataPublications.set(name, { connection: expectedConnection, reason });
+      const message = error instanceof Error ? error.message : String(error);
+      logger.debug(`MCP: metadata publication failed for ${name}; queued for retry: ${message}`);
+      return false;
+    }
+  }
+
   setElicitationConfig(config: ServerElicitationConfig | undefined): void {
     this.elicitationConfig = config;
   }
@@ -303,6 +334,88 @@ export class McpServerManager {
     return abortable(promise, ownedSignal);
   }
 
+  /**
+   * Fetch the authoritative tool catalog for a connection that still appears
+   * connected. The SDK response cache is explicitly bypassed so this request
+   * also proves the remote Streamable HTTP session is usable. Results are
+   * identity-guarded: a late response from a replaced connection is ignored.
+   */
+  async refreshTools(
+    name: string,
+    expectedConnection: ServerConnection,
+    signal?: AbortSignal,
+  ): Promise<ToolRefreshResult> {
+    if (this.stopped) throw new Error("MCP server manager is closed");
+    const ownedSignal = combineAbortSignals(this.runtimeSignal, signal);
+    throwIfAborted(ownedSignal);
+
+    const current = this.connections.get(name);
+    if (current !== expectedConnection || current.status !== "connected") {
+      return "superseded";
+    }
+
+    const requestOptions = this.buildRequestOptions(expectedConnection.definition, signal);
+    const timeout = Math.min(requestOptions?.timeout ?? KEEP_ALIVE_REFRESH_TIMEOUT_MS, KEEP_ALIVE_REFRESH_TIMEOUT_MS);
+    const healthOptions = {
+      ...requestOptions,
+      timeout,
+    };
+    if (!expectedConnection.client.getServerCapabilities?.()?.tools) {
+      await expectedConnection.client.ping(healthOptions);
+      throwIfAborted(ownedSignal);
+      if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") {
+        return "superseded";
+      }
+      this.retryPendingMetadataPublication(name, expectedConnection);
+      return "unchanged";
+    }
+
+    const toolsRevision = expectedConnection.toolsRevision ?? 0;
+    const refreshSignal = combineAbortSignals(healthOptions.signal, AbortSignal.timeout(timeout));
+    const tools = await this.fetchAllTools(expectedConnection.client, {
+      ...healthOptions,
+      ...(refreshSignal ? { signal: refreshSignal } : {}),
+      cacheMode: "refresh",
+    });
+    throwIfAborted(ownedSignal);
+
+    if (this.connections.get(name) !== expectedConnection || expectedConnection.status !== "connected") {
+      return "superseded";
+    }
+    if ((expectedConnection.toolsRevision ?? 0) !== toolsRevision) {
+      return "superseded";
+    }
+
+    if (isDeepStrictEqual(expectedConnection.tools, tools)) {
+      this.retryPendingMetadataPublication(name, expectedConnection);
+      return "unchanged";
+    }
+
+    const previousTools = expectedConnection.tools;
+    expectedConnection.tools = tools;
+    expectedConnection.toolsRevision = toolsRevision + 1;
+    try {
+      await this.metadataListChangedListener?.(name, "keep-alive-refresh");
+      this.pendingMetadataPublications.delete(name);
+    } catch (error) {
+      if (this.connections.get(name) === expectedConnection && expectedConnection.tools === tools) {
+        expectedConnection.tools = previousTools;
+        expectedConnection.toolsRevision = toolsRevision;
+      }
+      throw error;
+    }
+    return "updated";
+  }
+
+  private retryPendingMetadataPublication(name: string, connection: ServerConnection): void {
+    const pendingPublication = this.pendingMetadataPublications.get(name);
+    if (pendingPublication?.connection !== connection) return;
+    this.metadataListChangedListener?.(name, pendingPublication.reason);
+    if (this.pendingMetadataPublications.get(name) === pendingPublication) {
+      this.pendingMetadataPublications.delete(name);
+    }
+  }
+
   private async doReconnect(
     name: string,
     definition: ServerDefinition,
@@ -440,6 +553,7 @@ export class McpServerManager {
         transport,
         definition,
         tools: [],
+        toolsRevision: 0,
         resources: [],
         prompts: [],
         ...(instructions !== undefined ? { instructions } : {}),
@@ -641,7 +755,9 @@ export class McpServerManager {
     const connection = this.connections.get(serverName);
     if (!connection || connection.client !== client || connection.status !== "connected") return;
     connection.tools = tools;
+    connection.toolsRevision = (connection.toolsRevision ?? 0) + 1;
     this.metadataListChangedListener?.(serverName, "tools-list-changed");
+    this.pendingMetadataPublications.delete(serverName);
   }
 
   private handlePromptsListChanged(
@@ -660,6 +776,7 @@ export class McpServerManager {
     connection.prompts = prompts;
     connection.promptDiscoveryFailed = false;
     this.metadataListChangedListener?.(serverName, "prompts-list-changed");
+    this.pendingMetadataPublications.delete(serverName);
   }
 
   private handleResourcesListChanged(
@@ -677,6 +794,7 @@ export class McpServerManager {
     if (!connection || connection.client !== client || connection.status !== "connected") return;
     connection.resources = resources;
     this.metadataListChangedListener?.(serverName, "resources-list-changed");
+    this.pendingMetadataPublications.delete(serverName);
   }
 
   async handleUrlElicitationRequired(
@@ -851,7 +969,7 @@ export class McpServerManager {
     }
   }
 
-  private async fetchAllTools(client: Client, requestOptions?: RequestOptions): Promise<McpTool[]> {
+  private async fetchAllTools(client: Client, requestOptions?: CacheableRequestOptions): Promise<McpTool[]> {
     const allTools: McpTool[] = [];
     let cursor: string | undefined;
 
@@ -979,6 +1097,7 @@ export class McpServerManager {
   async close(name: string): Promise<void> {
     this.closeGenerations.set(name, (this.closeGenerations.get(name) ?? 0) + 1);
     this.connectAttempts.get(name)?.abort(new Error(`MCP connection ${name} was closed`));
+    this.pendingMetadataPublications.delete(name);
 
     const connection = this.connections.get(name);
     if (!connection) {
@@ -1042,6 +1161,7 @@ export class McpServerManager {
       .filter(error => this.containsCleanupFailure(error));
     this.uiStreamListeners.clear();
     this.acceptedUrlElicitations.clear();
+    this.pendingMetadataPublications.clear();
     this.samplingConfig = undefined;
     this.elicitationConfig = undefined;
     await this.traceWriter?.flush();

package/session-recovery.ts

@@ -146,6 +146,13 @@ export async function withSessionRecovery<T>(
       throw err;
     }
 
+    try {
+      deps.manager.publishMetadataChanged(serverName, freshConnection, "session-reconnect");
+    } catch (publicationError) {
+      const message = publicationError instanceof Error ? publicationError.message : String(publicationError);
+      logger.debug(`MCP metadata publication after reconnect failed for "${serverName}": ${message}`);
+    }
+    throwIfAborted(deps.signal);
     return fn(freshConnection);
   }
 }

package/tool-approval.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { abortable } from "./abort.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
 import type { McpExtensionState } from "./state.ts";
@@ -20,6 +20,18 @@ export type ToolCallApprovalResult =
   | { ok: true }
   | { ok: false; reason: "denied" | "approval_required_headless" };
 
+function stableStringify(value: unknown): string {
+  if (value === null || value === undefined || typeof value !== "object") {
+    const serialized = JSON.stringify(value);
+    return serialized === undefined ? "undefined" : serialized;
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(item => stableStringify(item)).join(",")}]`;
+  }
+  const object = value as Record<string, unknown>;
+  return `{${Object.keys(object).sort().map(key => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
+}
+
 export function isToolCallApprovalRequired(
   config: McpConfig,
   serverName: string,
@@ -136,7 +148,8 @@ export async function ensureToolCallApproved(
   origin: McpToolApprovalOrigin = toolMeta.resourceUri ? "resource" : "proxy",
   approvalMetadata?: ReadonlyMap<string, readonly ToolMetadata[]>,
 ): Promise<ToolCallApprovalResult> {
-  const cacheKey = `${serverName}\u0000${toolMeta.originalName}`;
+  const argsHash = createHash("sha256").update(stableStringify(args ?? {})).digest("hex");
+  const cacheKey = `${serverName}\u0000${toolMeta.originalName}\u0000${argsHash}`;
   const approvedToolCalls = state.approvedToolCalls ??= new Map<string, true>();
   if (approvedToolCalls.has(cacheKey)) {
     return { ok: true };

package/tool-result-renderer.ts

@@ -25,6 +25,7 @@ export interface McpProxyToolCallInput {
 
 interface McpToolRenderState {
   compactTitle?: string;
+  compactInputPreview?: string;
 }
 
 interface McpToolRenderContext {
@@ -52,6 +53,7 @@ export interface McpToolResultDisplay {
 }
 
 const DEFAULT_MAX_CALL_INPUT_CHARS = 1500;
+const DEFAULT_MAX_COMPACT_INPUT_CHARS = 240;
 const DEFAULT_BOXED_COLLAPSED_LINES = 3;
 const DEFAULT_COMPACT_COLLAPSED_LINES = 1;
 const DEFAULT_MAX_COLLAPSED_CHARS = 8000;
@@ -70,6 +72,7 @@ class CompactMcpToolResult implements Component {
 
   constructor(
     private readonly title: string,
+    private readonly inputPreview: string,
     private readonly display: McpToolResultDisplay,
     private readonly theme: RenderTheme,
   ) {}
@@ -83,7 +86,7 @@ class CompactMcpToolResult implements Component {
     });
     const lines = resultLines.length > 0 ? resultLines : [""];
     const bodies = lines.map((line, index) => {
-      const prefix = index === 0 && this.title ? `${this.theme.fg("toolTitle", this.title)} → ` : "";
+      const prefix = index === 0 ? this.renderPrefix(safeWidth) : "";
       return `${prefix}${this.theme.fg("toolOutput", line)}`;
     });
     const hiddenText = this.display.truncated || bodies.some((body) => visibleWidth(body) > safeWidth);
@@ -106,6 +109,22 @@ class CompactMcpToolResult implements Component {
   invalidate(): void {
     this.rendered = null;
   }
+
+  private renderPrefix(width: number): string {
+    if (!this.title) return "";
+    const arrow = " → ";
+    if (!this.inputPreview) return `${this.theme.fg("toolTitle", this.title)}${arrow}`;
+
+    const maxPrefixWidth = Math.max(12, Math.floor(width * 0.55));
+    const titleWidth = visibleWidth(this.title);
+    const inputWidth = Math.max(0, maxPrefixWidth - titleWidth - 1);
+    if (inputWidth <= 3) {
+      return `${this.theme.fg("toolTitle", truncateToWidth(this.title, maxPrefixWidth, "…"))}${arrow}`;
+    }
+
+    const input = truncateToWidth(this.inputPreview, inputWidth, "…");
+    return `${this.theme.fg("toolTitle", this.title)} ${this.theme.fg("muted", input)}${arrow}`;
+  }
 }
 
 class CollapsibleText implements Component {
@@ -239,6 +258,10 @@ function renderToolCallLines(lines: string[], theme?: RenderTheme) {
   return new Text([styledTitle, ...styledRest].join("\n"), 0, 0);
 }
 
+function formatCompactInputPreview(lines: string[], maxChars = DEFAULT_MAX_COMPACT_INPUT_CHARS): string {
+  return truncateText(lines.slice(1).join(" ").replace(/\s+/g, " ").trim(), maxChars);
+}
+
 export function resolveMcpToolRenderOptions(settings?: McpToolRenderSettings): McpToolRenderOptions {
   const resultRendering = settings?.toolResultRendering === "boxed" ? "boxed" : "compact";
   const collapsedLines = settings?.collapsedResultLines;
@@ -263,7 +286,10 @@ function renderToolCall(
   context: McpToolRenderContext | undefined,
   options: McpToolRenderOptions,
 ) {
-  if (context?.state) context.state.compactTitle = lines[0] ?? "mcp";
+  if (context?.state) {
+    context.state.compactTitle = lines[0] ?? "mcp";
+    context.state.compactInputPreview = formatCompactInputPreview(lines);
+  }
   if (shouldUseCompactFinalRender(options, context)) return new EmptyComponent();
   return renderToolCallLines(lines, theme);
 }
@@ -307,6 +333,19 @@ function collectCollapsedResultLines(
   let truncated = false;
 
   const appendLine = (line: string) => {
+    if (lines.length === 0) {
+      const previewWidth = Math.min(line.length, remainingChars);
+      if (line.slice(0, previewWidth).trim() === "") {
+        if (line.length >= remainingChars) {
+          truncated = true;
+          remainingChars = 0;
+          return false;
+        }
+        remainingChars -= line.length + 1;
+        return true;
+      }
+    }
+
     if (lines.length >= maxLines || remainingChars <= 0) {
       truncated = true;
       return false;
@@ -342,7 +381,7 @@ function collectCollapsedResultLines(
     if (truncated) break;
   }
 
-  if (lines.length === 0) lines.push("");
+  if (lines.length === 0) lines.push(truncated ? "(leading blank output omitted)" : "");
   if (truncated && lines.length >= maxLines) lines.push("…");
   return { lines, truncated };
 }
@@ -393,7 +432,8 @@ export function renderMcpToolResult(
   if (!expanded && renderOptions.resultRendering === "compact") {
     const display = formatMcpToolResultLines(result, false, renderOptions.collapsedResultLines);
     const title = context?.state?.compactTitle ?? formatMcpToolResultIdentity(result.details) ?? "";
-    return new CompactMcpToolResult(title, display, activeTheme);
+    const inputPreview = context?.state?.compactInputPreview ?? "";
+    return new CompactMcpToolResult(title, inputPreview, display, activeTheme);
   }
 
   const display = formatMcpToolResultLines(result, expanded, renderOptions.collapsedResultLines);