Add ui/close-resource request for UI to initiate termination

Author: fredericbarthelet

src/app-bridge.ts

@@ -70,6 +70,8 @@ import {
   McpUiOpenLinkResult,
   McpUiResourceTeardownRequest,
   McpUiResourceTeardownResultSchema,
+  McpUiCloseResourceRequest,
+  McpUiCloseResourceRequestSchema,
   McpUiSandboxProxyReadyNotification,
   McpUiSandboxProxyReadyNotificationSchema,
   McpUiSizeChangedNotificationSchema,
@@ -586,6 +588,40 @@ export class AppBridge extends Protocol<
     );
   }
 
+  /**
+   * Register a handler for app-initiated close notifications from the Guest UI.
+   *
+   * The Guest UI sends `ui/close-resource` when it wants to close itself.
+   * This is the app-initiated counterpart to the host-initiated `ui/resource-teardown`.
+   * Since the app initiates this, it has already performed any necessary cleanup
+   * before sending the message.
+   *
+   * This is a fire-and-forget event - the host should immediately unmount
+   * the app iframe upon receiving this request. No response are expected since the
+   * host will immediately unmount the app upon receiving this request.
+   *
+   * @param callback - Handler that receives close params
+   *   - params - Empty object (reserved for future use)
+   *
+   * @example
+   * ```typescript
+   * bridge.oncloseresource = (params) => {
+   *   console.log("App requested close");
+   *   // Unmount the iframe
+   *   iframe.remove();
+   * };
+   * ```
+   *
+   * @see {@link McpUiCloseResourceRequest} for the notification type
+   */
+  set oncloseresource(
+    callback: (params: McpUiCloseResourceRequest["params"]) => void,
+  ) {
+    this.setNotificationHandler(McpUiCloseResourceRequestSchema, (request) =>
+      callback(request.params),
+    );
+  }
+
   /**
    * Register a handler for display mode change requests from the Guest UI.
    *

src/app.ts

@@ -36,6 +36,7 @@ import {
   McpUiResourceTeardownRequest,
   McpUiResourceTeardownRequestSchema,
   McpUiResourceTeardownResult,
+  McpUiCloseResourceRequest,
   McpUiSizeChangedNotification,
   McpUiToolCancelledNotification,
   McpUiToolCancelledNotificationSchema,
@@ -906,6 +907,43 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
   /** @deprecated Use {@link openLink} instead */
   sendOpenLink: App["openLink"] = this.openLink;
 
+  /**
+   * Signal the host to close this app.
+   *
+   * Apps call this method to initiate their own termination. The host will
+   * close/unmount the app iframe upon receiving this notification. Since the app
+   * is initiating the close, it should perform any necessary cleanup (save state,
+   * close connections, etc.) before calling this method.
+   *
+   * This is a fire-and-forget request - no response is expected since the
+   * host will immediately unmount the app upon receiving this payload.
+   *
+   * Unlike host-initiated teardown (`ui/resource-teardown`), the app has already
+   * done its cleanup when it calls this method, so no teardown request is
+   * sent back to the app.
+   *
+   * @param params - Empty params object (reserved for future use)
+   * @returns Promise that resolves when the message is sent
+   *
+   * @example App-initiated close after user action
+   * ```typescript
+   * // User clicks "Done" button in the app
+   * async function handleDoneClick() {
+   *   await saveState();
+   *   await app.closeResource();
+   *   // App will be unmounted by host
+   * }
+   * ```
+   *
+   * @see {@link McpUiCloseResourceRequest} for notification structure
+   */
+  closeResource(params: McpUiCloseResourceRequest["params"] = {}) {
+    return this.notification(<McpUiCloseResourceRequest>{
+      method: "ui/close-resource",
+      params,
+    });
+  }
+
   /**
    * Request a change to the display mode.
    *

src/generated/schema.json

@@ -441,6 +441,19 @@ export interface McpUiSupportedContentBlockModalities {
   structuredContent?: {};
 }
 
+/**
+ * @description Request for app-initiated termination (Guest UI -> Host).
+ * Apps send this to signal the host to close/unmount them.
+ * Since the app initiates this, it has already performed any necessary cleanup.
+ * This is fire-and-forget - no response is expected since the host will
+ * immediately unmount the app upon receiving this notification.
+ * @see {@link app.App.closeResource} for the app method that sends this
+ */
+export interface McpUiCloseResourceRequest {
+  method: "ui/close-resource";
+  params: {};
+}
+
 /**
  * @description Capabilities supported by the host application.
  * @see {@link McpUiInitializeResult} for the initialization result that includes these capabilities

src/generated/schema.test.ts

@@ -49,6 +49,7 @@ export {
   type McpUiHostContextChangedNotification,
   type McpUiResourceTeardownRequest,
   type McpUiResourceTeardownResult,
+  type McpUiCloseResourceRequest,
   type McpUiHostCapabilities,
   type McpUiAppCapabilities,
   type McpUiInitializeRequest,
@@ -80,6 +81,7 @@ import type {
   McpUiInitializedNotification,
   McpUiSizeChangedNotification,
   McpUiSandboxProxyReadyNotification,
+  McpUiCloseResourceRequest,
   McpUiInitializeResult,
   McpUiOpenLinkResult,
   McpUiMessageResult,
@@ -110,6 +112,7 @@ export {
   McpUiHostContextChangedNotificationSchema,
   McpUiResourceTeardownRequestSchema,
   McpUiResourceTeardownResultSchema,
+  McpUiCloseResourceRequestSchema,
   McpUiHostCapabilitiesSchema,
   McpUiAppCapabilitiesSchema,
   McpUiInitializeRequestSchema,
@@ -180,7 +183,7 @@ export type AppRequest =
  * - Sandbox resource ready
  *
  * App to host:
- * - Initialized, size-changed, sandbox-proxy-ready
+ * - Initialized, size-changed, sandbox-proxy-ready, close-resource
  * - Logging messages
  */
 export type AppNotification =
@@ -198,6 +201,7 @@ export type AppNotification =
   | McpUiInitializedNotification
   | McpUiSizeChangedNotification
   | McpUiSandboxProxyReadyNotification
+  | McpUiCloseResourceRequest
   | LoggingMessageNotification;
 
 /**