@herbertgao/pi-extensions 2026.8.15 → 2026.9.0

package/node_modules/pi-mcp-adapter/proxy-modes.ts

@@ -19,6 +19,7 @@ import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session
 import { paginate, rankSuggestions, rankToolMatches, resolveSearchKeywords } from "./search-ranking.ts";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.ts";
 import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
+import { getInputRequiredNeedsUiDetails } from "./errors.ts";
 
 type ProxyToolResult = AgentToolResult<Record<string, unknown>>;
 type ClientCallToolResult = Awaited<ReturnType<Client["callTool"]>>;
@@ -339,7 +340,7 @@ export function executeUiMessages(state: McpExtensionState): ProxyToolResult {
 }
 
 export function executeStatus(state: McpExtensionState): ProxyToolResult {
-  const servers: Array<{ name: string; status: string; toolCount: number; failedAgo: number | null; disabled?: boolean }> = [];
+  const servers: Array<{ name: string; status: string; listenState: string; catalogStale?: boolean; toolCount: number; failedAgo: number | null; disabled?: boolean }> = [];
 
   for (const name of Object.keys(state.config.mcpServers)) {
     const definition = state.config.mcpServers[name];
@@ -360,7 +361,16 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
 
     const toolCount = status === "failed" ? 0 : metadata?.length ?? 0;
 
-    servers.push({ name, status, toolCount, failedAgo, ...(disabled ? { disabled: true } : {}) });
+    const listenState = connection?.status === "connected" ? connection.listenState : "disconnected";
+    servers.push({
+      name,
+      status,
+      listenState,
+      ...(connection?.status === "connected" && connection.listenCatalogStale ? { catalogStale: true } : {}),
+      toolCount,
+      failedAgo,
+      ...(disabled ? { disabled: true } : {}),
+    });
   }
 
   const disabledCount = servers.filter(s => s.disabled).length;
@@ -377,7 +387,18 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
       continue;
     }
     if (server.status === "connected") {
-      text += `✓ ${server.name} (${server.toolCount} tools)\n`;
+      const listen = server.listenState === "active"
+        ? server.catalogStale
+          ? ", listen active, catalog may be stale"
+          : ", listen active"
+        : server.listenState === "dropped"
+          ? ", catalog may be stale; will reconcile on next keep-alive or tool use"
+          : server.listenState === "re-establishing"
+            ? ", re-establishing listen"
+            : server.listenState === "legacy"
+              ? ", legacy notification path"
+              : ", not listening for catalog updates";
+      text += `✓ ${server.name} (${server.toolCount} tools${listen})\n`;
       continue;
     }
     if (server.status === "needs-auth") {
@@ -385,14 +406,19 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
       continue;
     }
     if (server.status === "cached") {
-      text += `○ ${server.name} (${server.toolCount} tools, cached)\n`;
+      text += `○ ${server.name} (${server.toolCount} tools, cached; not listening)\n`;
       continue;
     }
     if (server.status === "failed") {
       text += `✗ ${server.name} (failed ${server.failedAgo ?? 0}s ago)\n`;
       continue;
     }
-    text += `○ ${server.name} (not connected)\n`;
+    text += `○ ${server.name} (not listening; disconnected)\n`;
+  }
+
+  const directToolsFrozen = state.config.settings?.freezeDirectTools === true;
+  if (directToolsFrozen) {
+    text += "\nDirect tools frozen; active registrations may differ from current metadata.\n";
   }
 
   if (servers.length > 0) {
@@ -401,7 +427,7 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
 
   return {
     content: [{ type: "text" as const, text: text.trim() }],
-    details: { mode: "status", servers, totalTools, connectedCount, disabledCount },
+    details: { mode: "status", servers, totalTools, connectedCount, disabledCount, directToolsFrozen },
   };
 }
 
@@ -751,7 +777,17 @@ export function executeList(state: McpExtensionState, server: string): ProxyTool
     };
   }
 
-  const cachedNote = connection?.status === "connected" ? "" : " (not connected, cached)";
+  // "not connected" alone reads as an outage while the tools listed below are
+  // real and the connection is simply lazy (tools served from cache).
+  // Distinguish auth from plain laziness so the caller knows which remedy applies.
+  let cachedNote = "";
+  if (connection?.status !== "connected") {
+    if (connection?.status === "needs-auth") {
+      cachedNote = ` (needs auth — run mcp({ action: "auth-start", server: "${server}" }))`;
+    } else {
+      cachedNote = ` (lazy: tools from cache, not connected yet — mcp({ connect: "${server}" }) to connect)`;
+    }
+  }
   let text = `${server} (${toolNames.length} tools${cachedNote}):\n\n`;
 
   const descMap = new Map<string, string>();
@@ -1300,7 +1336,13 @@ export async function executeCall(
           onNeedsAuth: recoverAuthConnection,
         },
         serverName,
-        (conn) => conn.client.readResource({ uri: toolMeta.resourceUri! }, requestOptions),
+        async (conn) => {
+          const refreshRead = await state.manager.prepareResourceUse?.(serverName, toolMeta.resourceUri!, conn);
+          return conn.client.readResource(
+            { uri: toolMeta.resourceUri! },
+            refreshRead ? { ...requestOptions, cacheMode: "refresh" } : requestOptions,
+          );
+        },
       );
       const content = transformMcpResourceContents(result.contents ?? [], state.owner?.signal);
       const guarded = await guardMcpOutput(content.length > 0 ? content : [{ type: "text" as const, text: "(empty resource)" }], outputGuardOptions);
@@ -1330,11 +1372,14 @@ export async function executeCall(
         onNeedsAuth: recoverAuthConnection,
       },
       serverName,
-      (conn) => abortable(conn.client.callTool({
-        name: toolMeta.originalName,
-        arguments: normalizedArgs,
-        _meta: uiSession?.requestMeta,
-      }, requestOptions), ownedSignal),
+      async (conn) => {
+        await state.manager.ensureListen?.(serverName, conn);
+        return abortable(conn.client.callTool({
+          name: toolMeta.originalName,
+          arguments: normalizedArgs,
+          _meta: uiSession?.requestMeta,
+        }, requestOptions), ownedSignal);
+      },
     );
 
     if (toolMeta.uiResourceUri) {
@@ -1408,6 +1453,14 @@ export async function executeCall(
         details: { mode: "call", error: "url_elicitation_required", ...callIdentity, action },
       };
     }
+    const inputRequired = getInputRequiredNeedsUiDetails(error, callIdentity);
+    if (inputRequired) {
+      uiSession?.sendToolCancelled(inputRequired.message);
+      return {
+        content: [{ type: "text" as const, text: inputRequired.message }],
+        details: { mode: "call", ...inputRequired },
+      };
+    }
     const message = error instanceof Error ? error.message : String(error);
     uiSession?.sendToolCancelled(message);
 

package/node_modules/pi-mcp-adapter/sandbox-proxy-template.ts

@@ -0,0 +1,217 @@
+/**
+ * The proxy is served from a different loopback origin than the trusted host.
+ * `allow-same-origin` is safe here because this document never contains the
+ * host's session capability; provider HTML is loaded into the nested frame.
+ */
+export const SANDBOX_PROXY_SANDBOX =
+  "allow-scripts allow-forms allow-modals allow-popups allow-downloads allow-same-origin";
+export const SANDBOX_INNER_SANDBOX = SANDBOX_PROXY_SANDBOX;
+export const SANDBOX_PROXY_PATH = "/sandbox";
+
+export interface SandboxProxyTemplateInput {
+  parentOrigin: string;
+}
+
+/**
+ * Build the static document used by the trusted, second-origin sandbox proxy.
+ * The only per-session value is the exact origin of the parent host.
+ */
+export function buildSandboxProxyHtml(input: SandboxProxyTemplateInput): string {
+  const parentOrigin = safeInlineJSON(input.parentOrigin);
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>MCP App Sandbox</title>
+  <style>
+    html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; background: transparent; }
+    iframe { display: block; width: 100%; height: 100%; border: 0; }
+  </style>
+</head>
+<body>
+  <iframe id="mcp-app" title="MCP App" sandbox="${SANDBOX_INNER_SANDBOX}" referrerpolicy="no-referrer"></iframe>
+  <script>
+    const EXPECTED_PARENT_ORIGIN = ${parentOrigin};
+    const SANDBOX_PROXY_READY_METHOD = "ui/notifications/sandbox-proxy-ready";
+    const SANDBOX_RESOURCE_READY_METHOD = "ui/notifications/sandbox-resource-ready";
+    const INNER_SANDBOX = ${safeInlineJSON(SANDBOX_INNER_SANDBOX)};
+    const MAX_PENDING_MESSAGES = 64;
+    const innerFrame = document.getElementById("mcp-app");
+    const pendingToInner = [];
+    let innerReady = false;
+
+    const isObject = (value) => value !== null && typeof value === "object";
+    const isMessageFromParent = (event) =>
+      event.source === window.parent && event.origin === EXPECTED_PARENT_ORIGIN;
+    const isMessageFromInner = (event) =>
+      event.source === innerFrame.contentWindow && event.origin === window.location.origin;
+
+    const postToParent = (data) => {
+      window.parent.postMessage(data, EXPECTED_PARENT_ORIGIN);
+    };
+
+    const postToInner = (data) => {
+      if (!innerReady || !innerFrame.contentWindow) {
+        if (pendingToInner.length < MAX_PENDING_MESSAGES) pendingToInner.push(data);
+        return;
+      }
+      innerFrame.contentWindow.postMessage(data, window.location.origin);
+    };
+
+    const flushPendingMessages = () => {
+      if (!innerFrame.contentWindow) return;
+      innerReady = true;
+      for (const data of pendingToInner.splice(0)) {
+        innerFrame.contentWindow.postMessage(data, window.location.origin);
+      }
+    };
+
+    const sanitizeDomains = (domains) => {
+      if (!Array.isArray(domains)) return [];
+      return [...new Set(domains.filter((domain) =>
+        typeof domain === "string" &&
+        domain.length > 0 &&
+        /^[\\x21-\\x7E]+$/.test(domain) &&
+        !/[;'\"]/.test(domain),
+      ))];
+    };
+
+    const toDirective = (name, trustedSources, domains) =>
+      name + " " + [...new Set([...trustedSources, ...domains])].join(" ");
+
+    const buildResourceCsp = (csp) => {
+      const resourceDomains = sanitizeDomains(csp?.resourceDomains);
+      const connectDomains = sanitizeDomains(csp?.connectDomains);
+      const frameDomains = sanitizeDomains(csp?.frameDomains);
+      const baseUriDomains = sanitizeDomains(csp?.baseUriDomains);
+      return [
+        "default-src 'none'",
+        "sandbox " + INNER_SANDBOX,
+        toDirective("script-src", ["'self'", "'unsafe-inline'"], resourceDomains),
+        toDirective("style-src", ["'self'", "'unsafe-inline'"], resourceDomains),
+        toDirective("font-src", ["'self'"], resourceDomains),
+        toDirective("img-src", ["'self'", "data:"], resourceDomains),
+        toDirective("media-src", ["'self'", "data:"], resourceDomains),
+        connectDomains.length > 0 ? "connect-src " + connectDomains.join(" ") : "connect-src 'none'",
+        frameDomains.length > 0 ? "frame-src " + frameDomains.join(" ") : "frame-src 'none'",
+        "worker-src 'none'",
+        "object-src 'none'",
+        baseUriDomains.length > 0 ? "base-uri " + baseUriDomains.join(" ") : "base-uri 'self'",
+      ].join("; ");
+    };
+
+    const escapeAttribute = (value) => value
+      .replace(/&/g, "&amp;")
+      .replace(/\"/g, "&quot;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;");
+
+    const injectCsp = (html, csp) => {
+      const meta = '<meta http-equiv="Content-Security-Policy" content="' + escapeAttribute(csp) + '">';
+      const head = html.match(/<head(?:\\s[^>]*)?>/i);
+      if (head && head.index !== undefined) {
+        const end = head.index + head[0].length;
+        return html.slice(0, end) + meta + html.slice(end);
+      }
+      return meta + html;
+    };
+
+    const safeSandbox = (requested) => {
+      const requestedTokens = typeof requested === "string" ? requested.split(/\\s+/) : [];
+      const allowedTokens = new Set(INNER_SANDBOX.split(" "));
+      const tokens = requestedTokens.filter((token) => allowedTokens.has(token));
+      // Provider HTML needs both script execution and a real proxy-origin
+      // storage context. Never accept popup escape or top-navigation tokens.
+      return [...new Set([
+        "allow-scripts",
+        "allow-same-origin",
+        ...tokens,
+      ])].filter((token) => allowedTokens.has(token)).join(" ");
+    };
+
+    const buildAllowAttribute = (permissions) => {
+      if (!isObject(permissions) || Array.isArray(permissions)) return "";
+      const allowed = [];
+      if (permissions.camera) allowed.push("camera");
+      if (permissions.microphone) allowed.push("microphone");
+      if (permissions.geolocation) allowed.push("geolocation");
+      if (permissions.clipboardWrite) allowed.push("clipboard-write");
+      return allowed.join("; ");
+    };
+
+    const loadResource = (params) => {
+      if (!isObject(params) || typeof params.html !== "string" || !innerFrame.contentDocument) return;
+      innerFrame.setAttribute("sandbox", safeSandbox(params.sandbox));
+      const allow = buildAllowAttribute(params.permissions);
+      if (allow) innerFrame.setAttribute("allow", allow);
+      else innerFrame.removeAttribute("allow");
+      innerReady = false;
+      const document = innerFrame.contentDocument;
+      document.open();
+      document.write(injectCsp(params.html, buildResourceCsp(params.csp)));
+      document.close();
+      flushPendingMessages();
+    };
+
+    window.addEventListener("message", (event) => {
+      if (isMessageFromParent(event)) {
+        const data = event.data;
+        if (!isObject(data)) return;
+        if (data.method === SANDBOX_RESOURCE_READY_METHOD) {
+          loadResource(data.params);
+          return;
+        }
+        if (data.method === SANDBOX_PROXY_READY_METHOD) return;
+        if (typeof data.method === "string" && data.method.startsWith("ui/notifications/sandbox-")) return;
+        postToInner(data);
+        return;
+      }
+
+      if (!isMessageFromInner(event)) return;
+      const data = event.data;
+      if (!isObject(data)) return;
+      if (typeof data.method === "string" && data.method.startsWith("ui/notifications/sandbox-")) return;
+      postToParent(data);
+    });
+
+    postToParent({
+      jsonrpc: "2.0",
+      method: SANDBOX_PROXY_READY_METHOD,
+      params: {},
+    });
+  </script>
+</body>
+</html>`;
+}
+
+/**
+ * CSP for the proxy document itself. It contains only the inline relay script
+ * and a nested about:blank frame; provider policy is applied separately after
+ * the host sends the resource-ready notification.
+ */
+export function buildSandboxProxyCsp(): string {
+  return [
+    "default-src 'none'",
+    "script-src 'unsafe-inline'",
+    "style-src 'unsafe-inline'",
+    "frame-src 'self'",
+    "connect-src 'none'",
+    "worker-src 'none'",
+    "object-src 'none'",
+    "base-uri 'none'",
+    `sandbox ${SANDBOX_PROXY_SANDBOX}`,
+  ].join("; ");
+}
+
+function safeInlineJSON(value: unknown): string {
+  const json = JSON.stringify(value);
+  if (json === undefined) return "undefined";
+  return json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}