feat: add ui/update-model-context (#125)

---------

Co-authored-by: Olivier Chafik <ochafik@anthropic.com>

Author: idosal

specification/draft/apps.mdx

@@ -979,6 +979,49 @@ 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: {
+    content?: ContentBlock[],
+    structuredContent?: Record<string, unknown>
+  }
+}
+
+// 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 provide the context to the model in future turns
+- MAY overwrite the previous model context with the new update
+- MAY defer sending the context to the model until the next user message (including `ui/message`)
+- MAY dedupe identical `ui/update-model-context` calls
+- If multiple updates are received before the next user message, Host SHOULD only send the last update to the model
+- 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.
@@ -1222,10 +1265,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

@@ -442,6 +442,82 @@ describe("App <-> AppBridge integration", () => {
         logger: "TestApp",
       });
     });
+
+    it("app.updateModelContext 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.updateModelContext({
+        content: [{ type: "text", text: "User selected 3 items" }],
+      });
+
+      expect(receivedContexts).toHaveLength(1);
+      expect(receivedContexts[0]).toMatchObject({
+        content: [{ type: "text", text: "User selected 3 items" }],
+      });
+      expect(result).toEqual({});
+    });
+
+    it("app.updateModelContext 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.updateModelContext({
+        content: [
+          { type: "text", text: "Filter applied" },
+          { type: "text", text: "Category: electronics" },
+        ],
+      });
+
+      expect(receivedContexts).toHaveLength(1);
+      expect(receivedContexts[0]).toMatchObject({
+        content: [
+          { type: "text", text: "Filter applied" },
+          { type: "text", text: "Category: electronics" },
+        ],
+      });
+      expect(result).toEqual({});
+    });
+
+    it("app.updateModelContext works with structuredContent", async () => {
+      const receivedContexts: unknown[] = [];
+      bridge.onupdatemodelcontext = async (params) => {
+        receivedContexts.push(params);
+        return {};
+      };
+
+      await app.connect(appTransport);
+      const result = await app.updateModelContext({
+        structuredContent: { selectedItems: 3, total: 150.0, currency: "USD" },
+      });
+
+      expect(receivedContexts).toHaveLength(1);
+      expect(receivedContexts[0]).toMatchObject({
+        structuredContent: { selectedItems: 3, total: 150.0, currency: "USD" },
+      });
+      expect(result).toEqual({});
+    });
+
+    it("app.updateModelContext throws when handler throws", async () => {
+      bridge.onupdatemodelcontext = async () => {
+        throw new Error("Context update failed");
+      };
+
+      await app.connect(appTransport);
+      await expect(
+        app.updateModelContext({
+          content: [{ type: "text", text: "Test" }],
+        }),
+      ).rejects.toThrow("Context update failed");
+    });
   });
 
   describe("App -> Host requests", () => {

src/app-bridge.ts

@@ -5,6 +5,7 @@ import {
   CallToolRequestSchema,
   CallToolResult,
   CallToolResultSchema,
+  EmptyResult,
   Implementation,
   ListPromptsRequest,
   ListPromptsRequestSchema,
@@ -51,6 +52,8 @@ import {
   type McpUiToolResultNotification,
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
+  McpUiUpdateModelContextRequest,
+  McpUiUpdateModelContextRequestSchema,
   McpUiHostCapabilities,
   McpUiHostContext,
   McpUiHostContextChangedNotification,
@@ -66,7 +69,6 @@ import {
   McpUiOpenLinkRequestSchema,
   McpUiOpenLinkResult,
   McpUiResourceTeardownRequest,
-  McpUiResourceTeardownResult,
   McpUiResourceTeardownResultSchema,
   McpUiSandboxProxyReadyNotification,
   McpUiSandboxProxyReadyNotificationSchema,
@@ -633,6 +635,48 @@ 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.
+   *
+   * The host will typically defer sending the context to the model until the
+   * next user message (including `ui/message`), and will only send the last
+   * update received.
+   *
+   * @example
+   * ```typescript
+   * bridge.onupdatemodelcontext = async ({ content, structuredContent }, extra) => {
+   *   // Update the model context with the new snapshot
+   *   modelContext = {
+   *     type: "app_context",
+   *     content,
+   *     structuredContent,
+   *     timestamp: Date.now()
+   *   };
+   *   return {};
+   * };
+   * ```
+   *
+   * @see {@link McpUiUpdateModelContextRequest} for the request type
+   */
+  set onupdatemodelcontext(
+    callback: (
+      params: McpUiUpdateModelContextRequest["params"],
+      extra: RequestHandlerExtra,
+    ) => Promise<EmptyResult>,
+  ) {
+    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

@@ -9,6 +9,7 @@ import {
   CallToolRequestSchema,
   CallToolResult,
   CallToolResultSchema,
+  EmptyResultSchema,
   Implementation,
   ListToolsRequest,
   ListToolsRequestSchema,
@@ -20,6 +21,7 @@ import { PostMessageTransport } from "./message-transport";
 import {
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
+  McpUiUpdateModelContextRequest,
   McpUiHostCapabilities,
   McpUiHostContext,
   McpUiHostContextChangedNotification,
@@ -809,6 +811,52 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
     });
   }
 
+  /**
+   * Update the host's model context with app state.
+   *
+   * Unlike `sendLog`, which is for debugging/telemetry, context updates
+   * are intended to be available to the model in future reasoning,
+   * without requiring a follow-up action (like `sendMessage`).
+   *
+   * The host will typically defer sending the context to the model until the
+   * next user message (including `ui/message`), and will only send the last
+   * update received. Each call overwrites any previous context update.
+   *
+   * @param params - Context content and/or structured content
+   * @param options - Request options (timeout, etc.)
+   *
+   * @throws {Error} If the host rejects the context update (e.g., unsupported content type)
+   *
+   * @example Update model context with current app state
+   * ```typescript
+   * await app.updateModelContext({
+   *   content: [{ type: "text", text: "User selected 3 items totaling $150.00" }]
+   * });
+   * ```
+   *
+   * @example Update with structured content
+   * ```typescript
+   * await app.updateModelContext({
+   *   structuredContent: { selectedItems: 3, total: 150.00, currency: "USD" }
+   * });
+   * ```
+   *
+   * @returns Promise that resolves when the context update is acknowledged
+   */
+  updateModelContext(
+    params: McpUiUpdateModelContextRequest["params"],
+    options?: RequestOptions,
+  ) {
+    return this.request(
+      <McpUiUpdateModelContextRequest>{
+        method: "ui/update-model-context",
+        params,
+      },
+      EmptyResultSchema,
+      options,
+    );
+  }
+
   /**
    * Request the host to open an external URL in the default browser.
    *