@herbertgao/pi-extensions 2026.8.15 → 2026.9.1

package/node_modules/pi-mcp-adapter/mcp-setup-panel.ts

@@ -2,7 +2,7 @@ import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tu
 import { createPanelKeys, type PanelKeybindings, type PanelKeys } from "./panel-keys.ts";
 import type { ImportKind } from "./types.ts";
 import { getConfigDirName } from "./agent-dir.ts";
-import { KNOWN_SERVER_PRESETS, type ConfigWritePreview, type KnownServerPreset, type McpDiscoverySummary } from "./config.ts";
+import { KNOWN_SERVER_PRESETS, type ConfigWritePreview, type KnownServerPreset, type McpDiscoverySummary, type SharedConfigTarget } from "./config.ts";
 import type { McpOnboardingState } from "./onboarding-state.ts";
 
 interface SetupTheme {
@@ -54,13 +54,13 @@ function wrapText(text: string, width: number): string[] {
 
 export interface SetupPanelCallbacks {
   previewImports: (imports: ImportKind[]) => ConfigWritePreview;
-  previewStarterProject: () => ConfigWritePreview;
-  previewRepoPrompt: () => ConfigWritePreview | null;
-  previewKnownServer: (preset: KnownServerPreset) => ConfigWritePreview;
+  previewStarterConfig: (target: SharedConfigTarget) => ConfigWritePreview;
+  previewRepoPrompt: (target: SharedConfigTarget) => ConfigWritePreview | null;
+  previewKnownServer: (preset: KnownServerPreset, target: SharedConfigTarget) => ConfigWritePreview;
   adoptImports: (imports: ImportKind[]) => Promise<{ added: ImportKind[]; path: string }>;
-  scaffoldProjectConfig: () => Promise<{ path: string }>;
-  addRepoPrompt: () => Promise<{ path: string; serverName: string }>;
-  addKnownServer: (preset: KnownServerPreset) => Promise<{ path: string; serverName: string }>;
+  scaffoldConfig: (target: SharedConfigTarget) => Promise<{ path: string }>;
+  addRepoPrompt: (target: SharedConfigTarget) => Promise<{ path: string; serverName: string }>;
+  addKnownServer: (preset: KnownServerPreset, target: SharedConfigTarget) => Promise<{ path: string; serverName: string }>;
   openPath: (path: string) => Promise<void>;
   markSetupCompleted: () => void;
 }
@@ -75,13 +75,14 @@ type Screen = "empty" | "setup" | "imports" | "paths";
 
 type ActionId =
   | "run-setup"
+  | "select-shared-target"
   | "adopt-imports"
   | "view-example"
   | "show-precedence"
   | "open-paths"
   | "add-repoprompt"
   | "add-known-server"
-  | "scaffold-project"
+  | "scaffold-shared-config"
   | "close";
 
 interface Action {
@@ -89,6 +90,7 @@ interface Action {
   label: string;
   description: string;
   preset?: KnownServerPreset;
+  target?: SharedConfigTarget;
 }
 
 export class McpSetupPanel {
@@ -96,6 +98,7 @@ export class McpSetupPanel {
   private actionCursor = 0;
   private importCursor = 0;
   private pathCursor = 0;
+  private sharedConfigTarget: SharedConfigTarget = "project";
   private selectedImports = new Set<ImportKind>();
   private busy = false;
   private notice: { text: string; tone: "success" | "warning" | "muted" } | null = null;
@@ -144,9 +147,13 @@ export class McpSetupPanel {
     if (this.discovery.imports.length > 0) {
       actions.push({ id: "adopt-imports", label: "Adopt detected compatibility imports", description: `Choose which host-specific MCP configs Pi should import into its own override file. ${this.discovery.imports.length} source${this.discovery.imports.length === 1 ? "" : "s"} found.` });
     }
-    actions.push({ id: "view-example", label: "View example `.mcp.json`", description: "Preview a working shared MCP config you can paste or adapt." });
-    if (!this.discovery.sources.some((source) => source.id === "shared-project" && source.exists)) {
-      actions.push({ id: "scaffold-project", label: "Scaffold project `.mcp.json`", description: "Write a minimal project config using the standard shared MCP file path, then reload Pi." });
+    actions.push(
+      { id: "select-shared-target", label: `${this.sharedConfigTarget === "project" ? "●" : "○"} Add to this project (.mcp.json)`, description: "Write new shared MCP servers to the project/team config.", target: "project" },
+      { id: "select-shared-target", label: `${this.sharedConfigTarget === "global" ? "●" : "○"} Add globally (~/.config/mcp/mcp.json)`, description: "Write new shared MCP servers to your all-projects config.", target: "global" },
+    );
+    actions.push({ id: "view-example", label: "View example shared config", description: "Preview a working shared MCP config you can paste or adapt." });
+    if (!this.selectedSharedConfigExists()) {
+      actions.push({ id: "scaffold-shared-config", label: `Scaffold ${this.sharedTargetLabel()}`, description: "Write a minimal config at the selected normal MCP setup path, then reload Pi." });
     }
     actions.push({ id: "show-precedence", label: "Explain config precedence", description: "Show the read order and where Pi writes compatibility settings." });
     if (this.getDetectedPaths().length > 0) {
@@ -156,7 +163,7 @@ export class McpSetupPanel {
       actions.push({ id: "add-known-server", label: preset.name, description: preset.summary, preset });
     }
     if (!this.discovery.repoPrompt.configured && this.discovery.repoPrompt.executablePath && this.discovery.repoPrompt.targetPath && this.discovery.repoPrompt.entry && this.discovery.repoPrompt.serverName) {
-      actions.push({ id: "add-repoprompt", label: "Add RepoPrompt to shared MCP config", description: "Write a standard MCP entry for RepoPrompt to the recommended shared target, then reload MCP in-session." });
+      actions.push({ id: "add-repoprompt", label: "Add RepoPrompt to selected shared config", description: "Write a standard MCP entry for RepoPrompt to the selected normal setup path, then reload MCP in-session." });
     }
     actions.push({ id: "close", label: "Close", description: "Exit the onboarding flow." });
     return actions;
@@ -170,6 +177,15 @@ export class McpSetupPanel {
     return [...new Set(paths)];
   }
 
+  private sharedTargetLabel(): string {
+    return this.sharedConfigTarget === "project" ? "project .mcp.json" : "global ~/.config/mcp/mcp.json";
+  }
+
+  private selectedSharedConfigExists(): boolean {
+    const sourceId = this.sharedConfigTarget === "project" ? "shared-project" : "shared-global";
+    return this.discovery.sources.some((source) => source.id === sourceId && source.exists);
+  }
+
   private getSelectedAction(): Action | undefined {
     const actions = this.getActions();
     return actions[this.actionCursor];
@@ -293,9 +309,15 @@ export class McpSetupPanel {
       this.tui.requestRender();
       return;
     }
-    if (action.id === "scaffold-project") {
+    if (action.id === "select-shared-target" && action.target) {
+      this.sharedConfigTarget = action.target;
+      this.notice = { text: `New shared servers will be written to ${this.sharedTargetLabel()}.`, tone: "muted" };
+      this.tui.requestRender();
+      return;
+    }
+    if (action.id === "scaffold-shared-config") {
       await this.runBusy(async () => {
-        const result = await this.callbacks.scaffoldProjectConfig();
+        const result = await this.callbacks.scaffoldConfig(this.sharedConfigTarget);
         this.callbacks.markSetupCompleted();
         this.notice = { text: `Wrote starter config to ${result.path}. Pi will reload after this panel closes.`, tone: "success" };
       });
@@ -303,7 +325,7 @@ export class McpSetupPanel {
     }
     if (action.id === "add-repoprompt") {
       await this.runBusy(async () => {
-        const result = await this.callbacks.addRepoPrompt();
+        const result = await this.callbacks.addRepoPrompt(this.sharedConfigTarget);
         this.callbacks.markSetupCompleted();
         this.notice = { text: `Added ${result.serverName} to ${result.path}. Pi will reload after this panel closes.`, tone: "success" };
       });
@@ -312,7 +334,7 @@ export class McpSetupPanel {
     if (action.id === "add-known-server" && action.preset) {
       const preset = action.preset;
       await this.runBusy(async () => {
-        const result = await this.callbacks.addKnownServer(preset);
+        const result = await this.callbacks.addKnownServer(preset, this.sharedConfigTarget);
         this.callbacks.markSetupCompleted();
         this.notice = { text: `Added ${result.serverName} to ${result.path}. Pi will reload after this panel closes.`, tone: "success" };
       });
@@ -416,8 +438,11 @@ export class McpSetupPanel {
     for (let index = start; index < end; index++) {
       const action = actions[index];
       if (!action) continue;
+      if (action.id === "select-shared-target" && (index === start || actions[index - 1]?.id !== "select-shared-target")) {
+        lines.push(this.padLine(fg(this.t.title, "Choose where new shared servers go"), innerW));
+      }
       if (action.id === "add-known-server" && (index === start || actions[index - 1]?.id !== "add-known-server")) {
-        lines.push(this.padLine(fg(this.t.title, "Add a known server"), innerW));
+        lines.push(this.padLine(fg(this.t.title, `Add a known server to ${this.sharedTargetLabel()}`), innerW));
       }
       const selected = index === this.actionCursor;
       const cursor = selected ? fg(this.t.selected, "›") : " ";
@@ -495,12 +520,12 @@ export class McpSetupPanel {
       ? ` ${this.discovery.conflicts.length} same-name conflict${this.discovery.conflicts.length === 1 ? "" : "s"} reported.`
       : "";
     if (!this.discovery.hasAnyConfig) {
-      return `Create a shared .mcp.json, adopt host imports, or quick-add RepoPrompt from this screen.${hostNote}${conflictNote}`;
+      return `Add shared servers to .mcp.json for this project/team or ~/.config/mcp/mcp.json for all projects. Adopt host imports or quick-add RepoPrompt from this screen.${hostNote}${conflictNote}`;
     }
     if (this.discovery.totalServerCount === 0 && this.discovery.imports.length > 0) {
       return `Detected ${this.discovery.imports.length} compatibility import source${this.discovery.imports.length === 1 ? "" : "s"}. Adopt them into Pi or inspect the underlying files.${hostNote}${conflictNote}`;
     }
-    return `Shared MCP files are preferred. Pi-owned files are only for compatibility imports and adapter-specific overrides.${hostNote}${conflictNote}`;
+    return `Use .mcp.json for project/team servers or ~/.config/mcp/mcp.json for all projects. Pi-owned files are for compatibility imports and adapter-specific overrides, not another normal setup path.${hostNote}${conflictNote}`;
   }
 
   private visibleActionRange(total: number): { start: number; end: number } {
@@ -534,6 +559,12 @@ export class McpSetupPanel {
           ],
           previewW,
         );
+      case "select-shared-target":
+        return this.formatPreview([
+          action.target === "project" ? "Project target: .mcp.json" : "Global target: ~/.config/mcp/mcp.json",
+          "Known server presets and starter configs will be written to the selected normal MCP setup path.",
+          "Pi-owned mcp.json files remain compatibility and adapter-only override state.",
+        ], previewW);
       case "view-example":
         return this.formatPreview([
           "Example shared `.mcp.json`:",
@@ -546,10 +577,17 @@ export class McpSetupPanel {
           "  }",
           "}",
           "",
-          "Use Scaffold project `.mcp.json` when you want a safe empty shell instead of a live example server.",
+          "Use Scaffold selected config when you want a safe empty shell instead of a live example server.",
         ], previewW);
       case "show-precedence":
         return this.formatPreview([
+          "Recommended shared config:",
+          "  project/team: .mcp.json",
+          "  all projects: ~/.config/mcp/mcp.json",
+          "",
+          "Advanced compatibility and Pi-owned layers:",
+          "  host imports, .agents files, package MCP manifests, and Pi overrides",
+          "",
           "Read order (later entries win):",
           "0. detected host configs (opt-in lowest-precedence fallback)",
           "1. ~/.config/mcp/mcp.json",
@@ -570,7 +608,7 @@ export class McpSetupPanel {
           : ["No config paths were detected."], previewW);
       case "add-repoprompt": {
         const repoPrompt = this.discovery.repoPrompt;
-        const preview = this.callbacks.previewRepoPrompt();
+        const preview = this.callbacks.previewRepoPrompt(this.sharedConfigTarget);
         if (!preview) {
           return this.formatPreview(["RepoPrompt is not available to add from this setup screen."], previewW);
         }
@@ -579,7 +617,7 @@ export class McpSetupPanel {
           preview,
           [
             `Executable: ${repoPrompt.executablePath ?? "not found"}`,
-            `Target: ${repoPrompt.targetPath ?? "n/a"}`,
+            `Target: ${this.sharedTargetLabel()}`,
             `Server name: ${repoPrompt.serverName ?? "repoprompt"}`,
           ],
           previewW,
@@ -590,17 +628,17 @@ export class McpSetupPanel {
         if (!preset) return this.formatPreview(["Known server preset is unavailable."], previewW);
         return this.formatWritePreview(
           `${preset.name} write preview`,
-          this.callbacks.previewKnownServer(preset),
-          [preset.summary],
+          this.callbacks.previewKnownServer(preset, this.sharedConfigTarget),
+          [preset.summary, `Target: ${this.sharedTargetLabel()}`],
           previewW,
         );
       }
-      case "scaffold-project":
+      case "scaffold-shared-config":
         return this.formatWritePreview(
-          "Starter project `.mcp.json` write preview",
-          this.callbacks.previewStarterProject(),
+          `${this.sharedTargetLabel()} starter write preview`,
+          this.callbacks.previewStarterConfig(this.sharedConfigTarget),
           [
-            "This writes a minimal `.mcp.json` in the current project using the shared MCP layout.",
+            "This writes a minimal config at the selected normal MCP setup path.",
             "It intentionally avoids adding a fake placeholder server that would fail on first reload.",
           ],
           previewW,

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

@@ -48,7 +48,9 @@ export function createMcpStatusSnapshot(state: McpExtensionState): McpStatusSnap
     servers.push({
       name,
       status,
+      listenState: connection?.status === "connected" ? connection.listenState : "disconnected",
       toolCount,
+      ...(connection?.status === "connected" && connection.listenCatalogStale ? { catalogStale: true } : {}),
       ...(resourceCount !== undefined ? { resourceCount } : {}),
       ...(status === "failed" && failedAgoSeconds !== null ? { failedAgoSeconds } : {}),
       disabled,

package/node_modules/pi-mcp-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.31.0",
+  "version": "2.32.1",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -125,6 +125,7 @@
     "mcp-status.ts",
     "metadata-cache.ts",
     "host-html-template.ts",
+    "sandbox-proxy-template.ts",
     "ui-resource-handler.ts",
     "consent-manager.ts",
     "ui-server.ts",

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");
+}