@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

package/node_modules/pi-mcp-adapter/init.ts

@@ -20,7 +20,7 @@ import {
   serializeTools,
   type ServerCacheEntry,
 } from "./metadata-cache.ts";
-import { McpServerManager } from "./server-manager.ts";
+import { McpServerManager, isTransientHttpConnectError } from "./server-manager.ts";
 import { buildToolMetadata, totalToolCount } from "./tool-metadata.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";
 import { UiResourceHandler } from "./ui-resource-handler.ts";
@@ -37,8 +37,9 @@ import {
   type McpRuntimeOwner,
 } from "./runtime-owner.ts";
 import { publishMcpStatusSnapshot } from "./mcp-status.ts";
+import { FAILURE_BACKOFF_MS, getFailureAgeSeconds } from "./failure-backoff.ts";
+export { getFailureAgeSeconds, getFailureMessage, isServerInActiveFailureBackoff } from "./failure-backoff.ts";
 
-const FAILURE_BACKOFF_MS = 60 * 1000;
 const MAX_FAILURE_MESSAGE_CHARS = 8 * 1024;
 const failureExpiryTimers = new WeakMap<McpExtensionState, Map<string, ReturnType<typeof setTimeout>>>();
 
@@ -51,13 +52,19 @@ function getFailureExpiryTimers(state: McpExtensionState): Map<string, ReturnTyp
   return timers;
 }
 
-export function clearFailure(state: McpExtensionState, serverName: string): void {
+export function clearFailure(state: McpExtensionState, serverName: string, restoredReason?: string): boolean {
+  const wasActive = getFailureAgeSeconds(state, serverName) !== null;
   state.failureTracker.delete(serverName);
   state.failureMessages?.delete(serverName);
   const timers = failureExpiryTimers.get(state);
   const timer = timers?.get(serverName);
   if (timer) clearTimeout(timer);
   timers?.delete(serverName);
+  if (restoredReason && wasActive) {
+    notifyToolMetadataUpdated(state, serverName, restoredReason);
+    publishMcpStatusSnapshot(state);
+  }
+  return wasActive;
 }
 
 export function recordFailure(state: McpExtensionState, serverName: string, message: string): void {
@@ -73,12 +80,15 @@ export function recordFailure(state: McpExtensionState, serverName: string, mess
     if (state.failureTracker.get(serverName) === failedAt) {
       state.failureTracker.delete(serverName);
       state.failureMessages?.delete(serverName);
+      notifyToolMetadataUpdated(state, serverName, "failure-backoff-expired");
       publishMcpStatusSnapshot(state);
     }
     getFailureExpiryTimers(state).delete(serverName);
   }, FAILURE_BACKOFF_MS);
   timer.unref?.();
   getFailureExpiryTimers(state).set(serverName, timer);
+  notifyToolMetadataUpdated(state, serverName, "failure-backoff-started");
+  publishMcpStatusSnapshot(state);
 }
 
 export function isTuiMode(ctx: Pick<ExtensionContext, "hasUI" | "mode">): boolean {
@@ -293,16 +303,17 @@ export async function initializeMcp(
     try {
       const connection = await manager.connect(name, definition, runtimeSignal);
       if (connection.status === "needs-auth") {
-        return { name, definition, connection: null, error: `OAuth authentication required. Run /mcp-auth ${name}.` };
+        return { name, definition, connection: null, error: `OAuth authentication required. Run /mcp-auth ${name}.`, transient: false };
       }
-      return { name, definition, connection, error: null };
+      return { name, definition, connection, error: null, transient: false };
     } catch (error) {
       if (isAbortError(error, runtimeSignal)) {
         if (owner.signal.aborted) throw error;
-        return { name, definition, connection: null, error: null };
+        return { name, definition, connection: null, error: null, transient: false };
       }
+      const transient = isTransientHttpConnectError(error);
       const message = error instanceof Error ? error.message : String(error);
-      return { name, definition, connection: null, error: message };
+      return { name, definition, connection: null, error: message, transient };
     }
   });
 
@@ -332,11 +343,18 @@ export async function initializeMcp(
     startupKnownMetadata.set(name, metadata);
   }
 
-  for (const { name, definition, connection, error } of results) {
+  for (const { name, definition, connection, error, transient } of results) {
     owner.throwIfInactive();
     if (error || !connection) {
       if (initialSignal?.aborted) continue;
       if (error) recordFailure(state, name, error);
+      if (transient) {
+        const notice = `MCP: ${name} temporarily unavailable (HTTP 503); retry later`;
+        logger.debug(`MCP: startup connect hit transient upstream outage for ${name}; will retry`);
+        if (ui) ui.notify(notice, "warning");
+        else console.error(notice);
+        continue;
+      }
       const displayError = sanitizeTerminalText(error ?? "Unknown connection failure");
       if (ui) {
         ui.notify(`MCP: Failed to connect to ${name}: ${displayError}`, "error");
@@ -399,9 +417,9 @@ export async function initializeMcp(
             }
             updateServerMetadata(state, name);
             updateMetadataCache(state, name);
-            notifyToolMetadataUpdated(state, name, "direct-tools-bootstrap");
+            const restored = clearFailure(state, name, "direct-tools-bootstrap");
+            if (!restored) notifyToolMetadataUpdated(state, name, "direct-tools-bootstrap");
             markKeepAliveAfterConnect(state, name);
-            clearFailure(state, name);
             return { name, ok: true };
           } catch (error) {
             if (isAbortError(error, runtimeSignal)) {
@@ -427,8 +445,8 @@ export async function initializeMcp(
     if (!owner.isActive()) return;
     updateServerMetadata(state, serverName);
     updateMetadataCache(state, serverName);
-    notifyToolMetadataUpdated(state, serverName, "lifecycle-reconnect");
-    clearFailure(state, serverName);
+    const restored = clearFailure(state, serverName, "lifecycle-reconnect");
+    if (!restored) notifyToolMetadataUpdated(state, serverName, "lifecycle-reconnect");
     updateStatusBar(state);
   });
 
@@ -441,13 +459,13 @@ export async function initializeMcp(
 
   lifecycle.setHealthRestoredCallback((serverName) => {
     if (!owner.isActive()) return;
-    clearFailure(state, serverName);
+    clearFailure(state, serverName, "health-restored");
     updateStatusBar(state);
   });
 
   lifecycle.setAuthRequiredCallback((serverName) => {
     if (!owner.isActive()) return;
-    clearFailure(state, serverName);
+    clearFailure(state, serverName, "auth-required");
     updateStatusBar(state);
   });
 
@@ -544,6 +562,8 @@ export function updateMetadataCache(
     resources,
     ...(prompts !== undefined ? { prompts } : {}),
     ...(connection.instructions !== undefined ? { instructions: connection.instructions } : {}),
+    ...(connection.toolListHints?.ttlMs !== undefined ? { ttlMs: connection.toolListHints.ttlMs } : {}),
+    ...(connection.toolListHints?.cacheScope !== undefined ? { cacheScope: connection.toolListHints.cacheScope } : {}),
     cachedAt: Date.now(),
   };
 
@@ -606,20 +626,11 @@ export function updateStatusBar(state: McpExtensionState): void {
     ui.setStatus("mcp", undefined);
     return;
   }
-  ui.setStatus("mcp", ui.theme ? ui.theme.fg("accent", formattedStatus) : formattedStatus);
-}
-
-export function getFailureAgeSeconds(state: McpExtensionState, serverName: string): number | null {
-  const failedAt = state.failureTracker.get(serverName);
-  if (!failedAt) return null;
-  const ageMs = Date.now() - failedAt;
-  if (ageMs > FAILURE_BACKOFF_MS) return null;
-  return Math.round(ageMs / 1000);
-}
-
-export function getFailureMessage(state: McpExtensionState, serverName: string): string | null {
-  if (getFailureAgeSeconds(state, serverName) === null) return null;
-  return state.failureMessages?.get(serverName) ?? null;
+  const theme = ui.theme;
+  const styledStatus = typeof theme?.fg === "function"
+    ? theme.fg("accent", formattedStatus)
+    : formattedStatus;
+  ui.setStatus("mcp", styledStatus);
 }
 
 export async function lazyConnect(state: McpExtensionState, serverName: string, signal?: AbortSignal): Promise<boolean> {
@@ -650,10 +661,10 @@ export async function lazyConnect(state: McpExtensionState, serverName: string,
     if (newConnection.status === "needs-auth") {
       return false;
     }
-    clearFailure(state, serverName);
     updateServerMetadata(state, serverName);
     updateMetadataCache(state, serverName);
-    notifyToolMetadataUpdated(state, serverName, "lazy-connect");
+    const restored = clearFailure(state, serverName, "lazy-connect");
+    if (!restored) notifyToolMetadataUpdated(state, serverName, "lazy-connect");
     markKeepAliveAfterConnect(state, serverName);
     updateStatusBar(state);
     return true;

package/node_modules/pi-mcp-adapter/lifecycle.ts

@@ -1,6 +1,6 @@
 import { SdkError, SdkErrorCode } from "@modelcontextprotocol/client";
 import { isServerDisabled, type ServerDefinition } from "./types.ts";
-import type { McpServerManager, ServerConnection } from "./server-manager.ts";
+import { isTransientHttpConnectError, type McpServerManager, type ServerConnection } from "./server-manager.ts";
 import { hasPendingAuth } from "./mcp-auth-flow.ts";
 import { logger } from "./logger.ts";
 import { formatTerminalError, parallelLimit, sanitizeTerminalText } from "./utils.ts";
@@ -20,6 +20,7 @@ interface RetryState {
   nextAttemptAt: number;
   connection: ServerConnection | undefined;
   status: ServerConnection["status"] | undefined;
+  warningReported: boolean;
 }
 
 export class McpLifecycleManager {
@@ -347,6 +348,12 @@ export class McpLifecycleManager {
     return Date.now() >= retry.nextAttemptAt;
   }
 
+  private connectionFailureTarget(action: "refresh" | "reconnect" | "publish", name: string): string {
+    if (action === "reconnect") return `reconnect to ${name}`;
+    if (action === "publish") return `publish metadata for ${name}`;
+    return `refresh ${name}`;
+  }
+
   private reportConnectionFailure(
     name: string,
     definition: ServerDefinition,
@@ -356,13 +363,12 @@ export class McpLifecycleManager {
   ): void {
     if (!this.recordRetry(name, definition, connection)) return;
     this.onReconnectFailure?.(name, error);
+    if (isTransientHttpConnectError(error)) return;
+    const retry = this.retryStates.get(name);
+    if (retry?.warningReported) return;
+    if (retry) retry.warningReported = true;
     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)}`);
+    console.error(`MCP: Failed to ${this.connectionFailureTarget(action, name)}: ${sanitizeTerminalText(message)}`);
   }
 
   private deferRefreshTimeout(
@@ -382,7 +388,8 @@ export class McpLifecycleManager {
     // Do not recreate retry/failure state from a stale convergence pass after
     // disposal or a same-name replacement registration.
     if (this.keepAliveServers.get(name) !== definition) return false;
-    const attempts = (this.retryStates.get(name)?.attempts ?? 0) + 1;
+    const previous = this.retryStates.get(name);
+    const attempts = (previous?.attempts ?? 0) + 1;
     const delay = Math.min(
       KEEP_ALIVE_RETRY_BASE_MS * 2 ** Math.min(attempts - 1, 10),
       KEEP_ALIVE_RETRY_MAX_MS,
@@ -392,6 +399,7 @@ export class McpLifecycleManager {
       nextAttemptAt: Date.now() + delay,
       connection,
       status: connection?.status,
+      warningReported: previous?.warningReported ?? false,
     });
     return true;
   }

package/node_modules/pi-mcp-adapter/mcp-code.ts

@@ -5,6 +5,7 @@ import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from
 import { executeCall } from "./proxy-modes.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
 import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.ts";
+import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
 import type { McpExtensionState } from "./state.ts";
 import { findToolByName, formatSchema } from "./tool-metadata.ts";
 import { renderTsShape } from "./ts-shape.ts";
@@ -202,6 +203,7 @@ export async function runMcpScript(
     let error: unknown;
     try {
       for (const [server, metadata] of state.toolMetadata) {
+        if (isServerInActiveFailureBackoff(state, server)) continue;
         const tool = findToolByName(metadata, path);
         if (!tool) continue;
         const inputTypeScript = tool.inputSchema

package/node_modules/pi-mcp-adapter/mcp-oauth-provider.ts

@@ -8,6 +8,7 @@
 import {
   UnauthorizedError,
   type AddClientAuthentication,
+  type OAuthClientInformationContext,
   type OAuthClientProvider,
   type OAuthDiscoveryState,
 } from "@modelcontextprotocol/client"
@@ -21,9 +22,8 @@ import {
   updateTokens,
   updateClientInfo,
   clearAllCredentials,
-  clearClientInfo,
   clearCodeVerifier,
-  clearTokens,
+  invalidateAuthEntryCache,
   type AuthEntry,
   type AuthStorageOptions,
   type StoredTokens,
@@ -71,6 +71,18 @@ function issuersMatch(first: string, second: string): boolean {
     || (second.endsWith("/") && second.slice(0, -1) === first)
 }
 
+function toOAuthTokens(tokens: StoredTokens): IssuerBoundTokens {
+  const result: IssuerBoundTokens = {
+    access_token: tokens.accessToken,
+    token_type: "Bearer",
+  }
+  if (tokens.refreshToken !== undefined) result.refresh_token = tokens.refreshToken
+  if (tokens.expiresAt !== undefined) result.expires_in = Math.max(0, Math.floor(tokens.expiresAt - Date.now() / 1000))
+  if (tokens.scope !== undefined) result.scope = tokens.scope
+  if (tokens.issuer !== undefined) result.issuer = tokens.issuer
+  return result
+}
+
 // Callback server configuration
 const DEFAULT_OAUTH_CALLBACK_PORT = 19876
 const DEFAULT_OAUTH_CALLBACK_PATH = "/callback"
@@ -161,6 +173,11 @@ export class McpOAuthProvider implements OAuthClientProvider {
   private flowDiscoveryState: OAuthDiscoveryState | undefined
   private flowIssuerMismatch = false
   private flowState: string | undefined
+  private invalidatedAccessToken: string | undefined
+  private invalidatedClientId: string | undefined
+  private lastObservedClientId: string | undefined
+  private lastSavedAccessToken: string | undefined
+  private pendingAuthAccessToken: string | undefined
 
   constructor(
     private serverName: string,
@@ -188,6 +205,11 @@ export class McpOAuthProvider implements OAuthClientProvider {
 
   deactivate(): void {
     this.active = false
+    this.invalidatedAccessToken = undefined
+    this.invalidatedClientId = undefined
+    this.lastObservedClientId = undefined
+    this.lastSavedAccessToken = undefined
+    this.pendingAuthAccessToken = undefined
   }
 
   private assertStoredIssuerBindings(entry: AuthEntry | undefined, issuer: string | undefined): void {
@@ -264,6 +286,9 @@ export class McpOAuthProvider implements OAuthClientProvider {
    * Returns undefined if no client info exists or if the server URL has changed.
    */
   async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
+    if (this.invalidatedClientId !== undefined) {
+      invalidateAuthEntryCache(this.serverName)
+    }
     const issuer = this.discoveredIssuer
     const stored = await getAuthForUrl(this.serverName, this.serverUrl, this.storageOptions)
     this.assertStoredIssuerBindings(stored, issuer)
@@ -298,7 +323,9 @@ export class McpOAuthProvider implements OAuthClientProvider {
     // Keep client registration associated with this in-flight flow even if
     // another runtime writes the shared persistent entry for the same name.
     const clientInfo = this.flowClientInfo ?? stored?.clientInfo
+    if (clientInfo?.clientId === this.invalidatedClientId) return undefined
     if (clientInfo) {
+      this.invalidatedClientId = undefined
       // A stored SEP-2352 issuer stub for a config-pre-registered client
       // (identified by the explicit marker, or by the legacy stub shape of
       // {clientId, issuer} with no registration metadata) is only meaningful
@@ -329,6 +356,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
       }
       // Return all registration metadata and the local issuer extension.
       // This keeps the SDK OAuth view and the stored issuer binding consistent.
+      this.lastObservedClientId = clientInfo.clientId
       return {
         client_id: clientInfo.clientId,
         client_secret: clientInfo.clientSecret,
@@ -380,6 +408,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
       ...(issuer !== undefined ? { issuer } : {}),
     }
     this.flowClientInfo = clientInfo
+    this.invalidatedClientId = undefined
+    this.lastObservedClientId = clientInfo.clientId
     updateClientInfo(this.serverName, clientInfo, this.serverUrl, this.storageOptions)
   }
 
@@ -387,27 +417,28 @@ export class McpOAuthProvider implements OAuthClientProvider {
    * Get stored OAuth tokens.
    * Returns undefined if no tokens exist or if the server URL has changed.
    */
-  async tokens(): Promise<OAuthTokens | undefined> {
+  async tokens(ctx?: OAuthClientInformationContext): Promise<OAuthTokens | undefined> {
+    // Once this provider rejects a token, bypass its process-local cache until
+    // another process replaces that token in shared secure storage.
+    if (this.invalidatedAccessToken !== undefined) {
+      invalidateAuthEntryCache(this.serverName)
+    }
+
     // Use getAuthForUrl to validate tokens are for the current server URL.
     const entry = await getAuthForUrl(this.serverName, this.serverUrl, this.storageOptions)
-    if (!entry?.tokens) return undefined
+    if (!entry?.tokens || entry.tokens.accessToken === this.invalidatedAccessToken) return undefined
+    this.invalidatedAccessToken = undefined
     const issuer = this.discoveredIssuer
     this.assertStoredIssuerBindings(entry, issuer)
     if (issuer && entry.tokens.issuer === undefined) {
       entry.tokens.issuer = issuer
       updateTokens(this.serverName, entry.tokens, this.serverUrl, this.storageOptions)
     }
+    if (ctx !== undefined) {
+      this.pendingAuthAccessToken = entry.tokens.accessToken
+    }
 
-    return {
-      access_token: entry.tokens.accessToken,
-      token_type: "Bearer",
-      refresh_token: entry.tokens.refreshToken,
-      expires_in: entry.tokens.expiresAt
-        ? Math.max(0, Math.floor(entry.tokens.expiresAt - Date.now() / 1000))
-        : undefined,
-      scope: entry.tokens.scope,
-      ...(entry.tokens.issuer !== undefined ? { issuer: entry.tokens.issuer } : {}),
-    } as IssuerBoundTokens
+    return toOAuthTokens(entry.tokens)
   }
 
   /**
@@ -427,6 +458,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
     }
     this.throwIfInactive()
     updateTokens(this.serverName, storedTokens, this.serverUrl, this.storageOptions)
+    this.invalidatedAccessToken = undefined
+    this.lastSavedAccessToken = storedTokens.accessToken
     // Discovery must survive the browser redirect so the callback can verify
     // the authorization server that minted the code. Once token issuance
     // succeeds, clear it so a later 401 re-reads PRM and can observe an
@@ -533,14 +566,31 @@ export class McpOAuthProvider implements OAuthClientProvider {
         this.flowDiscoveryState = undefined
         this.flowIssuerMismatch = false
         this.flowState = undefined
+        this.invalidatedAccessToken = undefined
+        this.invalidatedClientId = undefined
+        this.lastObservedClientId = undefined
+        this.lastSavedAccessToken = undefined
+        this.pendingAuthAccessToken = undefined
         clearAllCredentials(this.serverName, this.storageOptions)
         break
       case "client":
+        // Dynamic client registrations share the same credential-store entry as
+        // tokens. Keep SDK invalidation local so a stale process cannot rewrite
+        // that entry over credentials another process just authorized.
+        this.invalidatedClientId = this.lastObservedClientId
+        this.lastObservedClientId = undefined
         this.flowClientInfo = undefined
-        clearClientInfo(this.serverName, this.storageOptions)
+        invalidateAuthEntryCache(this.serverName)
         break
       case "tokens":
-        clearTokens(this.serverName, this.storageOptions)
+        // Invalidation is provider-local. Persistently deleting a shared token
+        // here lets a process refreshing stale cached credentials erase a token
+        // that another process just authorized. A later tokens() call bypasses
+        // the local cache and adopts a replacement token when one exists.
+        this.invalidatedAccessToken = this.pendingAuthAccessToken ?? this.lastSavedAccessToken
+        this.lastSavedAccessToken = undefined
+        this.pendingAuthAccessToken = undefined
+        invalidateAuthEntryCache(this.serverName)
         break
       case "verifier":
         clearCodeVerifier(this.serverName, this.storageOptions)

package/node_modules/pi-mcp-adapter/mcp-output-guard.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
-import { mkdtemp, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { ContentBlock, McpSettings } from "./types.ts";
 
 export const DEFAULT_MCP_OUTPUT_MAX_BYTES = 50 * 1024;
@@ -10,7 +10,9 @@ export const DEFAULT_MCP_DETAILS_MAX_BYTES = 16 * 1024;
 
 const CONTENT_SUMMARY_LIMIT = 20;
 const KEY_PREVIEW_LIMIT = 20;
-const KEY_MAX_CHARS = 120;
+const KEY_MAX_BYTES = 120;
+const STRUCTURED_CONTENT_PRESERVE_MAX_BYTES = 4 * 1024;
+const STRUCTURED_CONTENT_FIELD_PRESERVE_MAX_BYTES = 512;
 
 type Recordish = Record<string, unknown>;
 
@@ -269,7 +271,33 @@ async function boundMcpResult(result: unknown, detailsMaxBytes: number): Promise
   const raw = safeStringify(result);
   const rawBytes = byteLength(raw);
   if (rawBytes <= detailsMaxBytes) return result;
-  return summarizeMcpResult(result, raw, rawBytes);
+  const marker = { omitted: true } as const;
+  if (byteLength(safeStringify(marker)) > detailsMaxBytes) return undefined;
+
+  const summary = await summarizeMcpResult(result, raw, rawBytes);
+  if (byteLength(safeStringify(summary)) <= detailsMaxBytes) return summary;
+  return compactMcpResultOmission(summary, marker, detailsMaxBytes);
+}
+
+async function compactMcpResultOmission(
+  summary: McpResultSummary,
+  marker: Readonly<{ omitted: true }>,
+  maxBytes: number,
+): Promise<unknown> {
+  if (summary.fullResultPath) {
+    const withPathAndSize = {
+      ...marker,
+      rawResultBytes: summary.rawResultBytes,
+      fullResultPath: summary.fullResultPath,
+    };
+    if (byteLength(safeStringify(withPathAndSize)) <= maxBytes) return withPathAndSize;
+    const withPath = { ...marker, fullResultPath: summary.fullResultPath };
+    if (byteLength(safeStringify(withPath)) <= maxBytes) return withPath;
+    await discardArtifact(summary.fullResultPath);
+  }
+
+  const withSize = { ...marker, rawResultBytes: summary.rawResultBytes };
+  return byteLength(safeStringify(withSize)) <= maxBytes ? withSize : marker;
 }
 
 async function summarizeMcpResult(result: unknown, raw: string, rawBytes: number): Promise<McpResultSummary> {
@@ -289,7 +317,7 @@ async function summarizeMcpResult(result: unknown, raw: string, rawBytes: number
   };
 
   if (record && "structuredContent" in record) {
-    summary.structuredContent = summarizeValue(record.structuredContent);
+    summary.structuredContent = summarizeStructuredContent(record.structuredContent);
   }
   if (record && "_meta" in record) {
     summary.meta = summarizeValue(record._meta);
@@ -336,11 +364,41 @@ function summarizeValue(value: unknown): Record<string, unknown> {
     type: Array.isArray(value) ? "array" : "object",
     estimatedBytes: estimateValueBytes(value),
     keyCount: keys.length,
-    keysPreview: keys.slice(0, KEY_PREVIEW_LIMIT).map(truncateKey),
+    keysPreview: uniqueBoundedKeys(keys.slice(0, KEY_PREVIEW_LIMIT)),
     omitted: true,
   };
 }
 
+function summarizeStructuredContent(value: unknown): Record<string, unknown> {
+  const record = asRecord(value);
+  if (!record || Array.isArray(value)) return summarizeValue(value);
+  const keys = Object.keys(record);
+  const entries = Object.entries(record).slice(0, KEY_PREVIEW_LIMIT);
+  const previewKeys = uniqueBoundedKeys(entries.map(([key]) => key));
+  const fields: Record<string, unknown> = {};
+  let preservedBytes = byteLength("{}");
+  for (const [key, field] of entries) {
+    const fieldBytes = byteLength(safeStringify(field));
+    const candidate = fieldBytes <= STRUCTURED_CONTENT_FIELD_PRESERVE_MAX_BYTES
+      ? field
+      : summarizeValue(field);
+    const entryBytes = serializedObjectEntryBytes(key, candidate, Object.keys(fields).length > 0);
+    if (preservedBytes + entryBytes > STRUCTURED_CONTENT_PRESERVE_MAX_BYTES) continue;
+    fields[key] = candidate;
+    preservedBytes += entryBytes;
+  }
+  return {
+    preservedFields: fields,
+    summary: {
+      type: "object",
+      estimatedBytes: estimateValueBytes(value),
+      keyCount: keys.length,
+      keysPreview: previewKeys,
+      omitted: true,
+    },
+  };
+}
+
 function estimateValueBytes(value: unknown, depth = 0): number {
   if (value === null || value === undefined) return 0;
   if (typeof value === "string") return byteLength(value);
@@ -352,7 +410,29 @@ function estimateValueBytes(value: unknown, depth = 0): number {
 }
 
 function truncateKey(key: string): string {
-  return key.length <= KEY_MAX_CHARS ? key : `${key.slice(0, KEY_MAX_CHARS - 1)}…`;
+  if (byteLength(key) <= KEY_MAX_BYTES) return key;
+  const suffix = "…";
+  return `${truncateStringToBytes(key, KEY_MAX_BYTES - byteLength(suffix))}${suffix}`;
+}
+
+function uniqueBoundedKeys(keys: string[]): string[] {
+  const used = new Set<string>();
+  return keys.map((key) => {
+    let candidate = truncateKey(key);
+    let ordinal = 2;
+    while (used.has(candidate)) {
+      const suffix = `~${ordinal}`;
+      candidate = `${truncateStringToBytes(key, KEY_MAX_BYTES - byteLength(suffix))}${suffix}`;
+      ordinal += 1;
+    }
+    used.add(candidate);
+    return candidate;
+  });
+}
+
+function serializedObjectEntryBytes(key: string, value: unknown, hasPrevious: boolean): number {
+  const serialized = safeStringify({ [key]: value });
+  return Math.max(0, byteLength(serialized) - byteLength("{}")) + (hasPrevious ? 1 : 0);
 }
 
 async function saveArtifact(kind: string, text: string): Promise<{ path?: string; error?: string }> {
@@ -366,6 +446,14 @@ async function saveArtifact(kind: string, text: string): Promise<{ path?: string
   }
 }
 
+async function discardArtifact(path: string): Promise<void> {
+  try {
+    await rm(dirname(path), { recursive: true, force: true });
+  } catch {
+    // Cleanup cannot increase the returned details payload.
+  }
+}
+
 function asRecord(value: unknown): Recordish | undefined {
   return typeof value === "object" && value !== null ? value as Recordish : undefined;
 }

package/node_modules/pi-mcp-adapter/mcp-probe.ts

@@ -5,6 +5,7 @@ const JSON_ACCEPT = "application/json, text/event-stream";
 const SSE_ACCEPT = "text/event-stream";
 const MODERN_FALLBACK_STATUSES = new Set([400, 401, 404, 405, 406, 415]);
 const POST_ENDPOINT_MISMATCH_STATUSES = new Set([404, 405, 406, 415]);
+const AMBIGUOUS_STATUSES = new Set([202, 401, 503]);
 
 export interface McpProbeResult {
   isMcp: boolean;
@@ -163,25 +164,38 @@ async function probe(url: string | URL, strategy: ProbeStrategy): Promise<ProbeR
 }
 
 function notMcp(response: Response): McpProbeResult {
+  const responseDescription = `endpoint returned ${responseKind(response)} (${response.status})`;
   return {
     isMcp: false,
-    classification: `endpoint returned ${responseKind(response)} (${response.status}) — this URL does not appear to speak MCP`,
+    classification: response.status === 503
+      ? `${responseDescription} — server is temporarily unavailable; MCP endpoint shape could not be determined`
+      : response.status === 202
+        ? `${responseDescription} — MCP endpoint shape could not be determined`
+      : response.status === 401
+        ? `${responseDescription} — authentication may be required; MCP endpoint shape could not be determined`
+        : `${responseDescription} — this URL does not appear to speak MCP`,
   };
 }
 
+function ambiguousNotMcp(response: Response): McpProbeResult | undefined {
+  return AMBIGUOUS_STATUSES.has(response.status) ? notMcp(response) : undefined;
+}
+
 /** Makes one unauthenticated metadata-only request to identify an HTTP endpoint's protocol shape. */
 export async function probeMcpEndpoint(url: string | URL): Promise<McpProbeResult> {
   const { response: modernResponse, outcome: modernOutcome } = await probe(url, MODERN_STRATEGY);
   if (modernOutcome.kind === "mcp") return modernOutcome.result;
+  let ambiguousResult = ambiguousNotMcp(modernResponse);
 
   if (modernOutcome.kind !== "unsupported-modern" && !MODERN_FALLBACK_STATUSES.has(modernResponse.status)) {
-    return notMcp(modernResponse);
+    return ambiguousResult ?? notMcp(modernResponse);
   }
 
   const { response: postResponse, outcome: postOutcome } = await probe(url, LEGACY_POST_STRATEGY);
   if (postOutcome.kind === "mcp") return postOutcome.result;
-  if (!POST_ENDPOINT_MISMATCH_STATUSES.has(postResponse.status)) return notMcp(postResponse);
+  ambiguousResult ??= ambiguousNotMcp(postResponse);
+  if (!POST_ENDPOINT_MISMATCH_STATUSES.has(postResponse.status)) return ambiguousNotMcp(postResponse) ?? ambiguousResult ?? notMcp(postResponse);
 
   const { response: getResponse, outcome: getOutcome } = await probe(url, LEGACY_SSE_STRATEGY);
-  return getOutcome.kind === "mcp" ? getOutcome.result : notMcp(getResponse);
+  return getOutcome.kind === "mcp" ? getOutcome.result : ambiguousNotMcp(getResponse) ?? ambiguousResult ?? notMcp(getResponse);
 }