feat: add ui/update-model-context

specification/draft/apps.mdx

@@ -800,6 +800,46 @@ Guest UI behavior:
 * Guest UI SHOULD check `availableDisplayModes` in host context before requesting a mode change.
 * Guest UI MUST handle the response mode differing from the requested mode.
 
+`ui/update-model-context` - Update the model context
+
+```typescript
+// Request
+{
+  jsonrpc: "2.0",
+  id: 3,
+  method: "ui/update-model-context",
+  params: {
+    role: "user",
+    content: ContentBlock[]
+  }
+}
+
+// Success Response
+{
+  jsonrpc: "2.0",
+  id: 3,
+  result: {}  // Empty result on success
+}
+
+// Error Response (if denied or failed)
+{
+  jsonrpc: "2.0",
+  id: 3,
+  error: {
+    code: -32000,  // Implementation-defined error
+    message: "Context update denied" | "Invalid content format"
+  }
+}
+```
+
+Guest UI MAY send this request to update the Host's model context. This context will be used in future turns. Each request overwrites the previous context sent by the Guest UI.
+This event serves a different use case from `notifications/message` (logging) and `ui/message` (which also trigger follow-ups).
+
+Host behavior:
+- SHOULD store the context snapshot in the conversation context
+- SHOULD overwrite the previous model context with the new update
+- MAY display context updates to the user
+
 #### Notifications (Host → UI)
 
 `ui/notifications/tool-input` - Host MUST send this notification with the complete tool arguments after the Guest UI's initialize request completes.
@@ -1031,10 +1071,15 @@ sequenceDiagram
       H-->>UI: ui/notifications/tool-result
     else Message
       UI ->> H: ui/message
+      H -->> UI: ui/message response
       H -->> H: Process message and follow up
-    else Notify
+    else Context update
+      UI ->> H: ui/update-model-context
+      H ->> H: Store model context (overwrite existing)
+      H -->> UI: ui/update-model-context response
+    else Log
       UI ->> H: notifications/message
-      H ->> H: Process notification and store in context
+      H ->> H: Record log for debugging/telemetry
     else Resource read
       UI ->> H: resources/read
       H ->> S: resources/read

src/app-bridge.test.ts

@@ -439,6 +439,68 @@ describe("App <-> AppBridge integration", () => {
         logger: "TestApp",
       });
     });
+
+    it("app.sendUpdateModelContext triggers bridge.onupdatemodelcontext and returns result", async () => {
+      const receivedContexts: unknown[] = [];
+      bridge.onupdatemodelcontext = async (params) => {
+        receivedContexts.push(params);
+        return {};
+      };
+
+      await app.connect(appTransport);
+      const result = await app.sendUpdateModelContext({
+        role: "user",
+        content: [{ type: "text", text: "User selected 3 items" }],
+      });
+
+      expect(receivedContexts).toHaveLength(1);
+      expect(receivedContexts[0]).toMatchObject({
+        role: "user",
+        content: [{ type: "text", text: "User selected 3 items" }],
+      });
+      expect(result).toEqual({});
+    });
+
+    it("app.sendUpdateModelContext works with multiple content blocks", async () => {
+      const receivedContexts: unknown[] = [];
+      bridge.onupdatemodelcontext = async (params) => {
+        receivedContexts.push(params);
+        return {};
+      };
+
+      await app.connect(appTransport);
+      const result = await app.sendUpdateModelContext({
+        role: "user",
+        content: [
+          { type: "text", text: "Filter applied" },
+          { type: "text", text: "Category: electronics" },
+        ],
+      });
+
+      expect(receivedContexts).toHaveLength(1);
+      expect(receivedContexts[0]).toMatchObject({
+        role: "user",
+        content: [
+          { type: "text", text: "Filter applied" },
+          { type: "text", text: "Category: electronics" },
+        ],
+      });
+      expect(result).toEqual({});
+    });
+
+    it("app.sendUpdateModelContext returns error result when handler indicates error", async () => {
+      bridge.onupdatemodelcontext = async () => {
+        return { isError: true };
+      };
+
+      await app.connect(appTransport);
+      const result = await app.sendUpdateModelContext({
+        role: "user",
+        content: [{ type: "text", text: "Test" }],
+      });
+
+      expect(result.isError).toBe(true);
+    });
   });
 
   describe("App -> Host requests", () => {

src/app-bridge.ts

@@ -51,6 +51,9 @@ import {
   type McpUiToolResultNotification,
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
+  McpUiUpdateModelContextRequest,
+  McpUiUpdateModelContextRequestSchema,
+  McpUiUpdateModelContextResult,
   McpUiHostCapabilities,
   McpUiHostContext,
   McpUiHostContextChangedNotification,
@@ -66,7 +69,6 @@ import {
   McpUiOpenLinkRequestSchema,
   McpUiOpenLinkResult,
   McpUiResourceTeardownRequest,
-  McpUiResourceTeardownResult,
   McpUiResourceTeardownResultSchema,
   McpUiSandboxProxyReadyNotification,
   McpUiSandboxProxyReadyNotificationSchema,
@@ -633,6 +635,50 @@ export class AppBridge extends Protocol<
     );
   }
 
+  /**
+   * Register a handler for model context updates from the Guest UI.
+   *
+   * The Guest UI sends `ui/update-model-context` requests to update the Host's
+   * model context. Each request overwrites the previous context stored by the Guest UI.
+   * Unlike logging messages, context updates are intended to be available to
+   * the model in future turns. Unlike messages, context updates do not trigger follow-ups
+   *
+   * @example
+   * ```typescript
+   * bridge.onupdatemodelcontext = async ({ role, content }, extra) => {
+   *   try {
+   *     // Update the model context with the new snapshot
+   *     modelContext = {
+   *       type: "app_context",
+   *       role,
+   *       content,
+   *       timestamp: Date.now()
+   *     };
+   *     return {};
+   *   } catch (err) {
+   *     // Handle error and signal failure to the app
+   *     return { isError: true };
+   *   }
+   * };
+   * ```
+   *
+   * @see {@link McpUiUpdateModelContextRequest} for the request type
+   * @see {@link McpUiUpdateModelContextResult} for the result type
+   */
+  set onupdatemodelcontext(
+    callback: (
+      params: McpUiUpdateModelContextRequest["params"],
+      extra: RequestHandlerExtra,
+    ) => Promise<McpUiUpdateModelContextResult>,
+  ) {
+    this.setRequestHandler(
+      McpUiUpdateModelContextRequestSchema,
+      async (request, extra) => {
+        return callback(request.params, extra);
+      },
+    );
+  }
+
   /**
    * Register a handler for tool call requests from the Guest UI.
    *

src/app.ts

@@ -20,6 +20,8 @@ import { PostMessageTransport } from "./message-transport";
 import {
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
+  McpUiUpdateModelContextRequest,
+  McpUiUpdateModelContextResultSchema,
   McpUiHostCapabilities,
   McpUiHostContext,
   McpUiHostContextChangedNotification,
@@ -809,6 +811,40 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
     });
   }
 
+  /**
+   * Send context updates to the host to be included in the agent's context.
+   *
+   * Unlike `sendLog`, which is for debugging/telemetry, context updates
+   * are inteded to be available to the model in future reasoning,
+   * without requiring a follow-up action (like `sendMessage`).
+   *
+   * @param params - Context role and content (same structure as ui/message)
+   * @param options - Request options (timeout, etc.)
+   *
+   * @example Update model context with current app state
+   * ```typescript
+   * await app.sendUpdateModelContext({
+   *   role: "user",
+   *   content: [{ type: "text", text: "User selected 3 items totaling $150.00" }]
+   * });
+   * ```
+   *
+   * @returns Promise that resolves when the context update is acknowledged
+   */
+  sendUpdateModelContext(
+    params: McpUiUpdateModelContextRequest["params"],
+    options?: RequestOptions,
+  ) {
+    return this.request(
+      <McpUiUpdateModelContextRequest>{
+        method: "ui/update-model-context",
+        params,
+      },
+      McpUiUpdateModelContextResultSchema,
+      options,
+    );
+  }
+
   /**
    * Request the host to open an external URL in the default browser.
    *