refactor: improve ui/update-model-context API

- Rename sendUpdateModelContext → updateModelContext (avoid double verbs)
- Remove role field from params (always user, adds no value)
- Add structuredContent support for machine-readable context data
- Use EmptyResult instead of {isError?: boolean} for result type
- Errors now signaled via JSON-RPC error responses
- Update capability to specify supported content types:
  text, image, audio, resource, resourceLink, structuredContent
- Add spec guidance for deferred delivery semantics:
  - Host MAY defer until next user message
  - Host MAY dedupe identical updates
  - Only last update before user message is sent to model

Author: ochafik

specification/draft/apps.mdx

@@ -809,8 +809,8 @@ Guest UI behavior:
   id: 3,
   method: "ui/update-model-context",
   params: {
-    role: "user",
-    content: ContentBlock[]
+    content?: ContentBlock[],
+    structuredContent?: Record<string, unknown>
   }
 }
 
@@ -836,8 +836,11 @@ Guest UI MAY send this request to update the Host's model context. This context
 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 provide the context to the model in future turns
 - SHOULD 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)

src/app-bridge.test.ts

@@ -440,37 +440,34 @@ describe("App <-> AppBridge integration", () => {
       });
     });
 
-    it("app.sendUpdateModelContext triggers bridge.onupdatemodelcontext and returns result", async () => {
+    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.sendUpdateModelContext({
-        role: "user",
+      const result = await app.updateModelContext({
         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 () => {
+    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.sendUpdateModelContext({
-        role: "user",
+      const result = await app.updateModelContext({
         content: [
           { type: "text", text: "Filter applied" },
           { type: "text", text: "Category: electronics" },
@@ -479,7 +476,6 @@ describe("App <-> AppBridge integration", () => {
 
       expect(receivedContexts).toHaveLength(1);
       expect(receivedContexts[0]).toMatchObject({
-        role: "user",
         content: [
           { type: "text", text: "Filter applied" },
           { type: "text", text: "Category: electronics" },
@@ -488,18 +484,36 @@ describe("App <-> AppBridge integration", () => {
       expect(result).toEqual({});
     });
 
-    it("app.sendUpdateModelContext returns error result when handler indicates error", async () => {
-      bridge.onupdatemodelcontext = async () => {
-        return { isError: true };
+    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.sendUpdateModelContext({
-        role: "user",
-        content: [{ type: "text", text: "Test" }],
+      const result = await app.updateModelContext({
+        structuredContent: { selectedItems: 3, total: 150.0, currency: "USD" },
       });
 
-      expect(result.isError).toBe(true);
+      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");
     });
   });
 

src/app-bridge.ts

@@ -5,6 +5,7 @@ import {
   CallToolRequestSchema,
   CallToolResult,
   CallToolResultSchema,
+  EmptyResult,
   Implementation,
   ListPromptsRequest,
   ListPromptsRequestSchema,
@@ -53,7 +54,6 @@ import {
   McpUiAppCapabilities,
   McpUiUpdateModelContextRequest,
   McpUiUpdateModelContextRequestSchema,
-  McpUiUpdateModelContextResult,
   McpUiHostCapabilities,
   McpUiHostContext,
   McpUiHostContextChangedNotification,
@@ -641,35 +641,33 @@ export class AppBridge extends Protocol<
    * 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 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 ({ 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 };
-   *   }
+   * 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
-   * @see {@link McpUiUpdateModelContextResult} for the result type
    */
   set onupdatemodelcontext(
     callback: (
       params: McpUiUpdateModelContextRequest["params"],
       extra: RequestHandlerExtra,
-    ) => Promise<McpUiUpdateModelContextResult>,
+    ) => Promise<EmptyResult>,
   ) {
     this.setRequestHandler(
       McpUiUpdateModelContextRequestSchema,

src/app.ts

@@ -9,6 +9,7 @@ import {
   CallToolRequestSchema,
   CallToolResult,
   CallToolResultSchema,
+  EmptyResultSchema,
   Implementation,
   ListToolsRequest,
   ListToolsRequestSchema,
@@ -21,7 +22,6 @@ import {
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
   McpUiUpdateModelContextRequest,
-  McpUiUpdateModelContextResultSchema,
   McpUiHostCapabilities,
   McpUiHostContext,
   McpUiHostContextChangedNotification,
@@ -812,26 +812,38 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
   }
 
   /**
-   * Send context updates to the host to be included in the agent's context.
+   * Update the host's model context with app state.
    *
    * Unlike `sendLog`, which is for debugging/telemetry, context updates
-   * are inteded to be available to the model in future reasoning,
+   * are intended 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)
+   * 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.sendUpdateModelContext({
-   *   role: "user",
+   * 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
    */
-  sendUpdateModelContext(
+  updateModelContext(
     params: McpUiUpdateModelContextRequest["params"],
     options?: RequestOptions,
   ) {
@@ -840,7 +852,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
         method: "ui/update-model-context",
         params,
       },
-      McpUiUpdateModelContextResultSchema,
+      EmptyResultSchema,
       options,
     );
   }