feat(app-bridge): warn when View sends requests before initialized

Host-side complement to the App-side guard: AppBridge now console.warns
when it receives any request (tools/call, ui/message, resources/read,
etc.) before the View has sent ui/notifications/initialized.

Unlike the App side this never throws — throwing here would cause the
very teardown→hidden-iframe symptom we're diagnosing. The warn surfaces
in the host's DevTools (where developers debugging "iframe stays hidden"
look first) and catches hand-rolled Views that don't use the SDK.

Implemented by overriding replaceRequestHandler to wrap every host-bound
handler in one place. ui/initialize and ping use setRequestHandler
directly and remain exempt; notifications are unaffected.

Refs anthropics/claude-ai-mcp#61, anthropics/claude-ai-mcp#149.

Author: ochafik

src/app-bridge.test.ts

@@ -840,6 +840,40 @@ describe("App <-> AppBridge integration", () => {
 
         errSpy.mockRestore();
       });
+
+      it("AppBridge warns on tools/call from a View that skipped the handshake", async () => {
+        const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+        bridge.oncalltool = async () => ({ content: [] });
+        await bridge.connect(bridgeTransport);
+
+        // Simulate a hand-rolled View (no SDK, no handshake) sending tools/call.
+        await appTransport.start();
+        appTransport.send({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "tools/call",
+          params: { name: "t", arguments: {} },
+        });
+        await flush();
+
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        expect(warnSpy.mock.calls[0][0]).toContain(
+          "received 'tools/call' before ui/notifications/initialized",
+        );
+        warnSpy.mockRestore();
+      });
+
+      it("AppBridge does not warn after initialized is received", async () => {
+        const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+        bridge.oncalltool = async () => ({ content: [] });
+        await bridge.connect(bridgeTransport);
+        await app.connect(appTransport);
+
+        await app.callServerTool({ name: "t", arguments: {} });
+
+        expect(warnSpy).not.toHaveBeenCalled();
+        warnSpy.mockRestore();
+      });
     });
 
     it("onlistresources setter registers handler for resources/list requests", async () => {

src/app-bridge.ts

@@ -39,6 +39,7 @@ import {
   ToolListChangedNotificationSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import {
+  Protocol,
   ProtocolOptions,
   RequestOptions,
 } from "@modelcontextprotocol/sdk/shared/protocol.js";
@@ -307,6 +308,37 @@ export class AppBridge extends ProtocolWithEvents<
   private _appCapabilities?: McpUiAppCapabilities;
   private _hostContext: McpUiHostContext = {};
   private _appInfo?: Implementation;
+  private _initializedReceived = false;
+
+  /**
+   * Wrap every handler registered via `replaceRequestHandler` with a check
+   * that the View has sent `ui/notifications/initialized`. Warns (never
+   * throws) so lenient hosts keep working while still surfacing the
+   * misordering that leaves strict hosts with a permanently hidden iframe.
+   * `ui/initialize` and `ping` use `setRequestHandler` directly and are
+   * intentionally exempt.
+   *
+   * @see {@link https://github.com/anthropics/claude-ai-mcp/issues/149 claude-ai-mcp#149}
+   */
+  private _baseReplaceRequestHandler = this.replaceRequestHandler;
+  protected override replaceRequestHandler: Protocol<
+    AppRequest,
+    AppNotification,
+    AppResult
+  >["setRequestHandler"] = (schema, handler) => {
+    this._baseReplaceRequestHandler(schema, (request, extra) => {
+      if (!this._initializedReceived) {
+        console.warn(
+          `[ext-apps] AppBridge received '${request.method}' before ` +
+            `ui/notifications/initialized. The View is calling host ` +
+            `methods before completing the handshake; it should await ` +
+            `app.connect() first. See ` +
+            `https://github.com/anthropics/claude-ai-mcp/issues/149`,
+        );
+      }
+      return handler(request, extra);
+    });
+  };
 
   protected readonly eventSchemas = {
     sizechange: McpUiSizeChangedNotificationSchema,
@@ -357,6 +389,10 @@ export class AppBridge extends ProtocolWithEvents<
   ) {
     super(options);
 
+    this.addEventListener("initialized", () => {
+      this._initializedReceived = true;
+    });
+
     this._hostContext = options?.hostContext || {};
 
     this.setRequestHandler(McpUiInitializeRequestSchema, (request) =>
@@ -1758,6 +1794,7 @@ export class AppBridge extends ProtocolWithEvents<
         "AppBridge is already connected. Call close() before connecting again.",
       );
     }
+    this._initializedReceived = false;
     if (this._client) {
       // When a client was passed to the constructor, automatically forward
       // MCP requests/notifications between the view and the server