feat: add ui/update-context

Author: idosal

specification/draft/apps.mdx

@@ -379,7 +379,7 @@ UI iframes can use the following subset of standard MCP protocol messages:
 
 **Notifications:**
 
-- `notifications/message` - Log messages to host
+- `notifications/message` - Log messages to host (for logging)
 
 **Lifecycle:**
 
@@ -533,6 +533,45 @@ Host SHOULD open the URL in the user's default browser or a new tab.
 
 Host SHOULD add the message to the conversation thread, preserving the specified role.
 
+`ui/update-context` - Update the agent's conversation context
+
+```typescript
+// Request
+{
+  jsonrpc: "2.0",
+  id: 3,
+  method: "ui/update-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 inform the agent about app state changes that should be stored in the conversation context for future reasoning. This event serves a different use case from `notifications/message` (logging) and `ui/message` (which also trigger followups).
+
+Host behavior:
+- SHOULD store the context update in the conversation context
+- MAY display context updates to the user
+- MAY filter or aggregate context updates
+
 #### 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.
@@ -765,9 +804,12 @@ sequenceDiagram
     else Message
       UI ->> H: ui/message
       H -->> H: Process message and follow up
-    else Notify
+    else Context update
+      UI ->> H: ui/update-context
+      H ->> H: Process context update and store in conversation context
+    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

@@ -212,6 +212,52 @@ describe("App <-> AppBridge integration", () => {
         logger: "TestApp",
       });
     });
+
+    it("app.sendContext triggers bridge.oncontext and returns result", async () => {
+      const receivedContexts: unknown[] = [];
+      bridge.oncontext = (params) => {
+        receivedContexts.push(params);
+      };
+
+      await app.connect(appTransport);
+      const result = await app.sendContext({
+        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.sendContext works with multiple content blocks", async () => {
+      const receivedContexts: unknown[] = [];
+      bridge.oncontext = (params) => {
+        receivedContexts.push(params);
+      };
+
+      await app.connect(appTransport);
+      const result = await app.sendContext({
+        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({});
+    });
   });
 
   describe("App -> Host requests", () => {

src/app-bridge.ts

@@ -39,6 +39,8 @@ import {
   type McpUiToolResultNotification,
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
+  McpUiUpdateContextRequest,
+  McpUiUpdateContextRequestSchema,
   McpUiHostCapabilities,
   McpUiHostContext,
   McpUiHostContextChangedNotification,
@@ -502,6 +504,43 @@ export class AppBridge extends Protocol<Request, Notification, Result> {
     );
   }
 
+  /**
+   * Register a handler for context updates from the Guest UI.
+   *
+   * The Guest UI sends `ui/update-context` requests to inform the agent
+   * about app state changes that should be stored in the conversation context for
+   * future reasoning. Unlike logging messages, context updates are intended to be
+   * available to the agent for decision making.
+   *
+   * @param callback - Handler that receives context update params
+   *   - params.role - Message role (currently only "user")
+   *   - params.content - Content blocks (text, image, etc.)
+   *
+   * @example
+   * ```typescript
+   * bridge.oncontext = ({ role, content }) => {
+   *   // Store context update for agent reasoning
+   *   conversationContext.push({
+   *     type: "app_context",
+   *     role,
+   *     content,
+   *     timestamp: Date.now()
+   *   });
+   * };
+   * ```
+   */
+  set oncontext(
+    callback: (params: McpUiUpdateContextRequest["params"]) => void,
+  ) {
+    this.setRequestHandler(
+      McpUiUpdateContextRequestSchema,
+      async (request) => {
+        callback(request.params);
+        return {};
+      },
+    );
+  }
+
   /**
    * Verify that the guest supports the capability required for the given request method.
    * @internal

src/app.ts

@@ -21,6 +21,8 @@ import {
 import {
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
+  McpUiUpdateContextRequest,
+  McpUiUpdateContextResultSchema,
   McpUiHostCapabilities,
   McpUiHostContextChangedNotification,
   McpUiHostContextChangedNotificationSchema,
@@ -673,6 +675,40 @@ export class App extends Protocol<Request, Notification, Result> {
     });
   }
 
+  /**
+   * Send context updates to the host for storage in the agent's conversation context.
+   *
+   * Unlike `sendLog` which is for debugging/telemetry, context updates are intended
+   * to inform the agent about app state changes that should be available for future
+   * reasoning without requiring a follow-up action (i.e., a prompt).
+   *
+   * @param params - Context role and content (same structure as ui/message)
+   * @param options - Request options (timeout, etc.)
+   *
+   * @example Notify agent of significant state change
+   * ```typescript
+   * await app.sendContext({
+   *   role: "user",
+   *   content: [{ type: "text", text: "User selected 3 items totaling $150.00" }]
+   * });
+   * ```
+   *
+   * @returns Promise that resolves when the context update is acknowledged
+   */
+  sendContext(
+    params: McpUiUpdateContextRequest["params"],
+    options?: RequestOptions
+  ) {
+    return this.request(
+      <McpUiUpdateContextRequest>{
+        method: "ui/update-context",
+        params,
+      },
+      McpUiUpdateContextResultSchema,
+      options
+    );
+  }
+
   /**
    * Request the host to open an external URL in the default browser.
    *