fix(studio): observe and retry WebMCP fallback

Author: miguel-heygen

packages/studio/src/webmcp/polyfill.test.ts

@@ -1,12 +1,15 @@
 // @vitest-environment jsdom
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { loadModelContextPolyfill, resetModelContextPolyfillForTest } from "./polyfill";
 import type { ModelContext } from "./types";
 
 // The real package defines `document.modelContext` as an import side effect.
 // A mock cannot do that, so tests stand the object up themselves to represent
 // the import having happened.
+const trackEvent = vi.hoisted(() => vi.fn());
 vi.mock("@mcp-b/global", () => ({}));
+vi.mock("../telemetry/client", () => ({ trackEvent }));
+
+let loadModelContextPolyfill: typeof import("./polyfill").loadModelContextPolyfill;
 
 function installModelContext(): ModelContext {
   const modelContext: ModelContext = { registerTool: vi.fn().mockResolvedValue(undefined) };
@@ -18,8 +21,10 @@ function installModelContext(): ModelContext {
   return modelContext;
 }
 
-beforeEach(() => {
-  resetModelContextPolyfillForTest();
+beforeEach(async () => {
+  vi.resetModules();
+  ({ loadModelContextPolyfill } = await import("./polyfill"));
+  trackEvent.mockReset();
 });
 
 afterEach(() => {
@@ -32,6 +37,7 @@ describe("loadModelContextPolyfill", () => {
     const modelContext = installModelContext();
 
     await expect(loadModelContextPolyfill()).resolves.toBe(modelContext);
+    expect(trackEvent).toHaveBeenCalledWith("webmcp.polyfill_loaded");
   });
 
   it("shares one load between callers that race", async () => {
@@ -57,16 +63,36 @@ describe("loadModelContextPolyfill", () => {
 
   it("returns null when the package loads but defines nothing", async () => {
     // Studio must still boot. A missing agent surface is not a broken editor.
-    await expect(loadModelContextPolyfill()).resolves.toBeNull();
+    const first = loadModelContextPolyfill();
+    await expect(first).resolves.toBeNull();
+
+    expect(trackEvent).toHaveBeenCalledWith("webmcp.polyfill_failed", {
+      error_name: "ModelContextMissingError",
+    });
+    const retry = loadModelContextPolyfill();
+    expect(retry).not.toBe(first);
+    await expect(retry).resolves.toBeNull();
   });
 
-  it("starts a fresh load after the test seam resets it", async () => {
-    installModelContext();
-    const first = loadModelContextPolyfill();
-    await first;
+  it("reports a polyfill failure and lets a later mount retry", async () => {
+    const failure = new TypeError("blocked by policy");
+    Object.defineProperty(document, "modelContext", {
+      configurable: true,
+      get: () => {
+        throw failure;
+      },
+    });
 
-    resetModelContextPolyfillForTest();
+    const first = loadModelContextPolyfill();
+    await expect(first).resolves.toBeNull();
+    expect(trackEvent).toHaveBeenCalledWith("webmcp.polyfill_failed", {
+      error_name: "TypeError",
+    });
 
-    expect(loadModelContextPolyfill()).not.toBe(first);
+    Reflect.deleteProperty(document, "modelContext");
+    const modelContext = installModelContext();
+    const retry = loadModelContextPolyfill();
+    expect(retry).not.toBe(first);
+    await expect(retry).resolves.toBe(modelContext);
   });
 });

packages/studio/src/webmcp/polyfill.ts

@@ -13,6 +13,7 @@
  */
 
 import { makeStudioDebugLogger } from "../utils/studioDebug";
+import { trackEvent } from "../telemetry/client";
 import { getModelContext, type ModelContext } from "./types";
 
 const log = makeStudioDebugLogger("webmcp");
@@ -30,21 +31,30 @@ async function importPolyfill(): Promise<ModelContext | null> {
     if (!modelContext) {
       // The package loaded but did not define what it promises to define.
       log("polyfill", { loaded: true, modelContext: false });
+      trackEvent("webmcp.polyfill_failed", { error_name: "ModelContextMissingError" });
+    } else {
+      trackEvent("webmcp.polyfill_loaded");
     }
     return modelContext;
   } catch (error) {
     // A missing agent surface must never break Studio's boot.
     log("polyfill", { failed: error instanceof Error ? error.message : String(error) });
+    trackEvent("webmcp.polyfill_failed", {
+      error_name: error instanceof Error ? error.name : "NonError",
+    });
     return null;
   }
 }
 
 export function loadModelContextPolyfill(): Promise<ModelContext | null> {
-  pending ??= importPolyfill();
-  return pending;
-}
+  if (pending) return pending;
 
-/** Test seam. Nothing in production resets this. */
-export function resetModelContextPolyfillForTest(): void {
-  pending = null;
+  const attempt = importPolyfill();
+  pending = attempt;
+  // A transient chunk/CSP failure must not disable WebMCP for the rest of the
+  // tab. Concurrent callers still share this attempt; a later mount may retry.
+  void attempt.then((modelContext) => {
+    if (modelContext === null && pending === attempt) pending = null;
+  });
+  return pending;
 }

packages/studio/src/webmcp/useStudioAgentTools.test.tsx

@@ -7,6 +7,9 @@ import { useStudioAgentTools, type StudioAgentToolsDeps } from "./useStudioAgent
 import type { ModelContext, ModelContextRegisterToolOptions, ModelContextTool } from "./types";
 import type { StudioLookSnapshot } from "./tools/lookTools";
 
+const trackEvent = vi.hoisted(() => vi.fn());
+vi.mock("../telemetry/client", () => ({ trackEvent }));
+
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
 let cleanup: (() => void) | null = null;
@@ -64,6 +67,7 @@ function mountTools(deps: StudioAgentToolsDeps) {
 
 beforeEach(() => {
   window.localStorage.clear();
+  trackEvent.mockReset();
 });
 
 afterEach(() => {
@@ -83,6 +87,7 @@ describe("useStudioAgentTools", () => {
     });
 
     expect(registered.map((tool) => tool.name)).toEqual(["studio_look"]);
+    expect(trackEvent).toHaveBeenCalledWith("webmcp.native_present");
   });
 
   it("does not re-register when the deps object changes identity", async () => {

packages/studio/src/webmcp/useStudioAgentTools.ts

@@ -1,6 +1,7 @@
 import { useEffect, useRef } from "react";
 import { readStudioUiPreferences } from "../utils/studioUiPreferences";
 import { makeStudioDebugLogger } from "../utils/studioDebug";
+import { trackEvent } from "../telemetry/client";
 import { loadModelContextPolyfill } from "./polyfill";
 import { registerStudioTools } from "./registrar";
 import { runToolBody, type ToolResult } from "./toolResult";
@@ -80,6 +81,7 @@ export function useStudioAgentTools(deps: StudioAgentToolsDeps): void {
 
     void (async () => {
       const native: ModelContext | null = getModelContext();
+      if (native) trackEvent("webmcp.native_present");
       // Native browsers never download the polyfill.
       const modelContext = native ?? (await loadModelContextPolyfill());
       if (!modelContext) {