canopy-ui 0.16.3 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-ui",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "license": "BSD-3-Clause",
   "type": "module",
   "repository": {

package/src/chat/ChatPanel.tsx

@@ -12,6 +12,7 @@ import { SendBox, type PendingAttachment } from "./SendBox";
 import { type DraftStorage } from "./drafts";
 import { agentHasFloor as computeAgentHasFloor, pendingLabel as computePendingLabel, turnNotice } from "./turnStatus";
 import { useStickyBottom } from "./useStickyBottom";
+import { AppHostContext, type AppHost } from "./mcpApps/context";
 
 export interface ChatPanelProps {
   state: SessionState;
@@ -54,6 +55,9 @@ export interface ChatPanelProps {
    *  a host with no draft sync (a contact) passes neither. */
   typingVisibility?: TypingVisibility;
   onTypingVisibilityChange?: (visibility: TypingVisibility) => void;
+  /** MCP Apps: how this page reaches canopy for the session's Views. Omit and
+   *  a tool result with a View renders as an ordinary tool row. */
+  appHost?: AppHost;
 }
 
 /**
@@ -85,6 +89,7 @@ export function ChatPanel({
   draftStorage,
   typingVisibility,
   onTypingVisibilityChange,
+  appHost,
 }: ChatPanelProps) {
   // `onDiscard` is part of the public surface (co-edit teardown) even though
   // the default composer doesn't render a discard button. Referenced to keep
@@ -197,6 +202,7 @@ export function ChatPanel({
   const typingUserIds = useMemo(() => peerDrafts.map((p) => p.author.id), [peerDrafts]);
 
   return (
+    <AppHostContext.Provider value={appHost ?? null}>
     <div className="flex h-full flex-col">
       <div className="flex items-center gap-3 border-b border-border bg-background px-3 py-1.5 text-xs">
         <ConnectionStatus connected={connected} />
@@ -275,5 +281,6 @@ export function ChatPanel({
         onTypingVisibilityChange={onTypingVisibilityChange}
       />
     </div>
+    </AppHostContext.Provider>
   );
 }

package/src/chat/MessageItem.tsx

@@ -5,6 +5,8 @@ import type { Message, MessageAuthor } from "./protocol";
 import { isMine } from "./identity";
 import { authorColor } from "./personColor";
 import { ToolCallPair } from "./ToolCallPair";
+import { AppView } from "./mcpApps/AppView";
+import { useAppHost } from "./mcpApps/context";
 
 /** How to render assistant/system markdown. Injected by the app so the kit
  *  stays free of `react-markdown`. Defaults to plain text in a <span>. */
@@ -90,6 +92,7 @@ export function MessageItem({
   currentUserId,
   currentContactId,
 }: Props) {
+  const appHost = useAppHost();
   const text = message.plaintext;
   const isStreaming = message.status === "streaming";
   const isPending = message.status === "pending";
@@ -103,6 +106,11 @@ export function MessageItem({
   if (message.role === "tool_use") {
     return <ToolCallPair use={message} result={null} forceOpen={forceToolOpen} />;
   }
+  if (message.role === "tool_result" && message.app && appHost) {
+    // A View row with no tool_use beside it — the embed widget, which receives
+    // the View but never the raw tool rows (`for_widget`).
+    return <AppView app={message.app} />;
+  }
   if (message.role === "tool_result") {
     // Synthesize a fake "use" message so the pair component can render
     // a uniform header. Defensive — should be rare.

package/src/chat/MessageList.tsx

@@ -6,6 +6,7 @@ import { Button } from "../ui/button";
 import type { RenderMarkdown } from "./MessageItem";
 import { MessageItem, ThinkingIndicator } from "./MessageItem";
 import { ToolCallPair } from "./ToolCallPair";
+import { AppView } from "./mcpApps/AppView";
 import { pairToolMessages } from "./pairToolMessages";
 import { groupToolRuns, runHasError, runIsActive, summariseRun } from "./groupToolRuns";
 
@@ -145,7 +146,7 @@ export function MessageList({
             );
           }
           if (row.kind === "tool_pair") {
-            return (
+            const pair = (
               <ToolCallPair
                 key={row.key}
                 use={row.use}
@@ -153,6 +154,15 @@ export function MessageList({
                 forceOpen={forceToolOpen}
               />
             );
+            // MCP Apps: the View first, the (collapsed) tool row below it.
+            return row.result?.app ? (
+              <div key={row.key}>
+                <AppView app={row.result.app} />
+                {pair}
+              </div>
+            ) : (
+              pair
+            );
           }
           return (
             <MessageItem

package/src/chat/agui.ts

@@ -27,7 +27,7 @@
  * standard.
  */
 
-import type { MessageAuthor, SessionMenu, WsEvent } from "./protocol";
+import type { MessageAppRef, MessageAuthor, SessionMenu, WsEvent } from "./protocol";
 
 /** Where canopy's own fields ride. Mirrors `agui.METADATA_KEY`. */
 export const METADATA_KEY = "canopy";
@@ -184,6 +184,8 @@ export function fromAgui(frame: AguiFrame): WsEvent[] {
             tool_message_id: str(frame.toolCallId),
             turn_index: num(m.turn_index),
             block: (m.block as Record<string, unknown> | undefined) ?? { content: frame.content },
+            // MCP Apps: the server says this result has a View.
+            ...(m.app ? { app: m.app as MessageAppRef } : {}),
           },
         },
       ];

package/src/chat/groupToolRuns.ts

@@ -40,7 +40,9 @@ export function groupToolRuns(
   };
 
   for (const row of rows) {
-    if (row.kind === "tool_pair") {
+    // A call with an MCP Apps View is something the person ACTS on, so it is
+    // never folded into a collapsed run.
+    if (row.kind === "tool_pair" && !row.result?.app) {
       run.push(row);
       continue;
     }

package/src/chat/index.ts

@@ -8,6 +8,7 @@
 export type {
   Message,
   MessageAuthor,
+  MessageAppRef,
   MessageRole,
   MessageStatus,
   Draft,
@@ -92,6 +93,19 @@ export {
   type PlacementBannerProps,
   type PlacementRunner,
 } from "./PlacementBanner";
+// MCP Apps (SEP-1865): render a Connected site's View for a tool result, and
+// the host side of its postMessage wire (spec 2026-10-08).
+export { AppView } from "./mcpApps/AppView";
+export {
+  AppHostContext,
+  useAppHost,
+  type AppHost,
+  type AppRef,
+  type AppReceipt,
+  type AppViewResource,
+} from "./mcpApps/context";
+export { AppBridge, PROTOCOL_VERSION as MCP_APPS_PROTOCOL_VERSION, type AppBridgeHandlers,
+         type AppBridgeOptions, type CallToolResult } from "./mcpApps/bridge";
 // The AG-UI projection's inverse. Exported so a consumer can translate a stream
 // it obtained some other way — and so the round-trip test can reach it.
 export { fromAgui, resetAguiState, CUSTOM_PREFIX, METADATA_KEY } from "./agui";

package/src/chat/mcpApps/AppView.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+/**
+ * A tool result with an MCP Apps View renders as a sandboxed, labelled frame —
+ * in a paired row (ChatPage) and as a standalone row (the embed widget, which
+ * never receives the tool_use) — and remounts cleanly from history.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+
+import { MessageList } from "../MessageList";
+import type { Message } from "../protocol";
+import { AppHostContext, type AppHost, type AppViewResource } from "./context";
+
+const APP = { tool_call_id: "toolu_1", site: "connect-labs", tool: "workflow_run_action",
+              resource_uri: "ui://labs/workflow-action-preview", path: "direct" };
+
+function msg(over: Partial<Message>): Message {
+  return { id: "m", turn_index: 1, role: "assistant", content: {}, plaintext: "", status: "complete",
+           error_detail: null, started_at: null, completed_at: null, created_at: "", ...over };
+}
+
+const use = msg({ id: "u", turn_index: 1, role: "tool_use",
+                  content: { id: "toolu_1", name: "mcp__connect_labs__workflow_run_action", input: {} } });
+const result = msg({ id: "r", turn_index: 2, role: "tool_result",
+                     content: { tool_use_id: "toolu_1", content: "preview" }, app: APP });
+
+function resource(over: Partial<AppViewResource> = {}): AppViewResource {
+  return { tool_call_id: "toolu_1", site: "connect-labs", tool: "workflow_run_action",
+           html: "<p>view</p>", csp: {}, sandbox_src: "/mcp-apps/sandbox/", prefers_border: true,
+           can_act: true, read_only_reason: "", sign_in_url: "", tool_input: {}, tool_result: null,
+           receipts: [], ...over };
+}
+
+function host(res: AppViewResource): AppHost {
+  return {
+    load: vi.fn(async () => res),
+    callTool: vi.fn(),
+    readResource: vi.fn(),
+    updateContext: vi.fn(),
+    sendMessage: vi.fn(),
+    resolveUrl: (p: string) => `/base${p}`,
+  } as unknown as AppHost;
+}
+
+afterEach(cleanup);
+
+describe("AppView", () => {
+  it("renders the View above its tool row, sandboxed with an opaque origin and labelled", async () => {
+    const h = host(resource());
+    render(
+      <AppHostContext.Provider value={h}>
+        <MessageList messages={[use, result]} />
+      </AppHostContext.Provider>,
+    );
+    await waitFor(() => expect(screen.getByTitle("Labs: workflow_run_action")).toBeTruthy());
+    const frame = screen.getByTitle("Labs: workflow_run_action") as HTMLIFrameElement;
+    expect(frame.getAttribute("sandbox")).toBe("allow-scripts");
+    expect(frame.getAttribute("src")).toBe("/base/mcp-apps/sandbox/");
+    expect(screen.getByText("from Labs")).toBeTruthy();
+    expect(h.load).toHaveBeenCalledWith("toolu_1");
+  });
+
+  it("a standalone View row (the widget) renders the View, not an orphan tool row", async () => {
+    render(
+      <AppHostContext.Provider value={host(resource())}>
+        <MessageList messages={[msg({ ...result, content: { tool_use_id: "toolu_1" } })]} />
+      </AppHostContext.Provider>,
+    );
+    await waitFor(() => expect(screen.getByTestId("app-view")).toBeTruthy());
+    expect(screen.queryByText("tool_result (orphan)")).toBeNull();
+  });
+
+  it("is read-only with a sign-in link for a viewer without a grant, and shows receipts", async () => {
+    render(
+      <AppHostContext.Provider value={host(resource({
+        can_act: false, read_only_reason: "I need you back on the page.",
+        sign_in_url: "https://labs.test",
+        receipts: [{ tool: "workflow_run_action", by: { name: "Jon" }, at: "2026-10-08T14:02:00Z",
+                     is_error: false }],
+      }))}>
+        <MessageList messages={[use, result]} />
+      </AppHostContext.Provider>,
+    );
+    await waitFor(() => expect(screen.getByTestId("app-view-readonly")).toBeTruthy());
+    expect(screen.getByText(/Sign in to Labs/).closest("a")?.getAttribute("href")).toBe("https://labs.test");
+    expect(screen.getByTestId("app-view-receipts").textContent).toContain("workflow_run_action by Jon");
+  });
+
+  it("without a host the row is the ordinary tool row (ace-web and older hosts)", () => {
+    render(<MessageList messages={[use, result]} />);
+    expect(screen.queryByTestId("app-view")).toBeNull();
+  });
+
+  it("remounts cleanly from history: a fresh load every mount", async () => {
+    const h = host(resource());
+    const tree = (
+      <AppHostContext.Provider value={h}>
+        <MessageList messages={[use, result]} />
+      </AppHostContext.Provider>
+    );
+    const first = render(tree);
+    await waitFor(() => expect(screen.getByTestId("app-view")).toBeTruthy());
+    first.unmount();
+    render(tree);
+    await waitFor(() => expect(screen.getByTestId("app-view")).toBeTruthy());
+    expect(h.load).toHaveBeenCalledTimes(2);
+  });
+});

package/src/chat/mcpApps/AppView.tsx

@@ -0,0 +1,182 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Check, ExternalLink, Loader2, X } from "lucide-react";
+
+import { AppBridge } from "./bridge";
+import { useAppHost, type AppReceipt, type AppRef, type AppViewResource } from "./context";
+
+const MIN_HEIGHT = 80;
+const MAX_HEIGHT = 900;
+
+function siteLabel(site: string): string {
+  return /labs/i.test(site) ? "Labs" : site;
+}
+
+function theme(): "light" | "dark" {
+  if (typeof document === "undefined") return "light";
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+function openLink(url: string): void {
+  window.open(url, "_blank", "noopener,noreferrer");
+}
+
+function receiptTime(at: string): string {
+  const d = new Date(at);
+  return Number.isNaN(d.getTime())
+    ? at
+    : d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+}
+
+/**
+ * One MCP Apps View, rendered sandboxed in the chat (spec 2026-10-08 §7-8).
+ *
+ * The frame is canopy's sandbox proxy, framed `sandbox="allow-scripts"` with NO
+ * `allow-same-origin` (owner decision 1): its origin is opaque, so the View it
+ * hosts can reach neither canopy's cookies, storage nor DOM. The View is drawn
+ * inside a labelled boundary ("from Labs") so nobody mistakes it for canopy's
+ * own UI. Mounting re-reads everything from the server, so a reload never
+ * replays anything the previous mount held.
+ */
+export function AppView({ app }: { app: AppRef }) {
+  const host = useAppHost();
+  const frame = useRef<HTMLIFrameElement | null>(null);
+  const [res, setRes] = useState<AppViewResource | null>(null);
+  const [error, setError] = useState<string>("");
+  const [height, setHeight] = useState<number>(160);
+  const [receipts, setReceipts] = useState<AppReceipt[]>([]);
+
+  useEffect(() => {
+    if (!host) return;
+    let live = true;
+    let attempt = 0;
+    const load = () => {
+      host.load(app.tool_call_id).then(
+        (r) => {
+          if (!live) return;
+          setRes(r);
+          setReceipts(r.receipts ?? []);
+        },
+        (err: unknown) => {
+          if (!live) return;
+          // A live frame can arrive before its row is stored; give it a moment.
+          if (attempt++ < 3) {
+            window.setTimeout(load, 800 * attempt);
+            return;
+          }
+          setError(err instanceof Error ? err.message : "This view could not be loaded.");
+        },
+      );
+    };
+    load();
+    return () => {
+      live = false;
+    };
+  }, [host, app.tool_call_id]);
+
+  const src = useMemo(() => {
+    if (!res) return "";
+    return host?.resolveUrl ? host.resolveUrl(res.sandbox_src) : res.sandbox_src;
+  }, [host, res]);
+
+  useEffect(() => {
+    if (!host || !res || !frame.current) return;
+    const refreshReceipts = () =>
+      host.load(app.tool_call_id).then((r) => setReceipts(r.receipts ?? []), () => undefined);
+    const bridge = new AppBridge({
+      getProxyWindow: () => frame.current?.contentWindow ?? null,
+      proxyOrigin: host.proxyOrigin,
+      html: res.html,
+      csp: res.csp,
+      canAct: res.can_act,
+      toolInput: res.tool_input ?? {},
+      toolResult: res.tool_result,
+      hostInfo: { name: "canopy", version: "1" },
+      hostContext: {
+        theme: theme(),
+        displayMode: "inline",
+        availableDisplayModes: ["inline"],
+        platform: "web",
+        containerDimensions: { maxHeight: MAX_HEIGHT, ...(host.maxWidth ? { maxWidth: host.maxWidth } : {}) },
+        locale: typeof navigator !== "undefined" ? navigator.language : "en",
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        toolInfo: { tool: { name: res.tool, inputSchema: { type: "object" } } },
+      },
+      handlers: {
+        callTool: async (name, args) => {
+          const out = await host.callTool(app.tool_call_id, name, args);
+          void refreshReceipts();
+          return out;
+        },
+        readResource: (uri) => host.readResource(app.tool_call_id, uri),
+        updateModelContext: (params) => host.updateContext(app.tool_call_id, params),
+        sendMessage: (text) => host.sendMessage(app.tool_call_id, text),
+        openLink,
+        onSize: ({ height: h }) => {
+          if (typeof h === "number" && h > 0) {
+            setHeight(Math.max(MIN_HEIGHT, Math.min(MAX_HEIGHT, Math.ceil(h))));
+          }
+        },
+      },
+    });
+    return () => bridge.close();
+  }, [host, res, app.tool_call_id]);
+
+  if (!host) return null;
+  const label = siteLabel(app.site);
+  const bordered = res?.prefers_border !== false;
+
+  return (
+    <section
+      data-testid="app-view"
+      aria-label={`View from ${label}`}
+      className={`my-2 overflow-hidden rounded-lg ${bordered ? "border border-border bg-card" : ""}`}
+    >
+      <header className="flex items-center gap-2 border-b border-border/60 px-3 py-1.5 text-xs text-muted-foreground">
+        <span className="rounded bg-muted px-1.5 py-0.5 font-medium text-foreground">from {label}</span>
+        <span className="truncate font-mono">{app.tool}</span>
+      </header>
+      {error ? (
+        <p className="px-3 py-2 text-sm text-muted-foreground">{error}</p>
+      ) : !res ? (
+        <p className="flex items-center gap-2 px-3 py-2 text-sm text-muted-foreground">
+          <Loader2 className="h-3.5 w-3.5 animate-spin" /> Loading the view…
+        </p>
+      ) : (
+        <>
+          {!res.can_act && (
+            <p data-testid="app-view-readonly" className="px-3 pt-2 text-xs text-muted-foreground">
+              {res.read_only_reason || "This view is read-only for you."}{" "}
+              {res.sign_in_url && (
+                <a href={res.sign_in_url} target="_blank" rel="noopener noreferrer"
+                   className="inline-flex items-center gap-1 font-medium text-primary underline">
+                  Sign in to {label} <ExternalLink className="h-3 w-3" />
+                </a>
+              )}
+            </p>
+          )}
+          <iframe
+            ref={frame}
+            title={`${label}: ${app.tool}`}
+            src={src}
+            // Opaque origin: never `allow-same-origin` (owner decision 1).
+            sandbox="allow-scripts"
+            referrerPolicy="no-referrer"
+            style={{ height, width: "100%", border: 0, display: "block" }}
+          />
+        </>
+      )}
+      {receipts.length > 0 && (
+        <ul data-testid="app-view-receipts" className="border-t border-border/60 px-3 py-1.5 text-xs text-muted-foreground">
+          {receipts.map((r, i) => (
+            <li key={`${r.at}-${i}`} className="flex items-center gap-1.5">
+              {r.is_error ? <X className="h-3 w-3 text-destructive" /> : <Check className="h-3 w-3 text-success" />}
+              <span>
+                {r.is_error ? "Failed" : "Done"}: {r.tool} by {r.by?.name || "someone"} at {receiptTime(r.at)}
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}

package/src/chat/mcpApps/bridge.test.ts

@@ -0,0 +1,170 @@
+// @vitest-environment jsdom
+/**
+ * The host end of an MCP Apps View's wire (spec 2026-10-08 test plan, frontend):
+ * the handshake order, who may speak, what is never forwarded, and what a viewer
+ * who may not act is told.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { AppBridge, type AppBridgeHandlers } from "./bridge";
+
+type Sent = Record<string, unknown>;
+
+function setup(opts: { canAct?: boolean; handlers?: Partial<AppBridgeHandlers> } = {}) {
+  const iframe = document.createElement("iframe");
+  document.body.appendChild(iframe);
+  const proxy = iframe.contentWindow as Window;
+  const sent: Sent[] = [];
+  vi.spyOn(proxy, "postMessage").mockImplementation(((msg: unknown) => {
+    sent.push(msg as Sent);
+  }) as Window["postMessage"]);
+  const handlers: AppBridgeHandlers = {
+    callTool: vi.fn(async () => ({ content: [{ type: "text", text: "ok" }], isError: false })),
+    readResource: vi.fn(async () => ({ contents: [] })),
+    updateModelContext: vi.fn(async () => undefined),
+    sendMessage: vi.fn(async () => undefined),
+    openLink: vi.fn(),
+    onSize: vi.fn(),
+    ...opts.handlers,
+  };
+  const bridge = new AppBridge({
+    getProxyWindow: () => proxy,
+    html: "<!doctype html><p>view</p>",
+    csp: { connectDomains: ["https://labs.test"] },
+    canAct: opts.canAct ?? true,
+    hostContext: { theme: "light", displayMode: "inline" },
+    toolInput: { run_id: 5 },
+    toolResult: { content: [{ type: "text", text: "preview" }] },
+    handlers,
+  });
+  const fromProxy = (data: unknown, { source = proxy as MessageEventSource | null, origin = "null" } = {}) =>
+    window.dispatchEvent(new MessageEvent("message", { data, source, origin }));
+  return { bridge, proxy, sent, handlers, fromProxy };
+}
+
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  vi.restoreAllMocks();
+});
+
+describe("AppBridge", () => {
+  it("runs the handshake in order and sends nothing to the View before initialized", async () => {
+    const { sent, fromProxy } = setup();
+    fromProxy({ jsonrpc: "2.0", method: "ui/notifications/sandbox-proxy-ready", params: {} });
+    expect(sent.map((m) => m.method)).toEqual(["ui/notifications/sandbox-resource-ready"]);
+    const ready = sent[0].params as Record<string, unknown>;
+    expect(ready.html).toContain("<p>view</p>");
+    expect(ready.sandbox).toBe("allow-scripts");
+    // A second proxy-ready does not re-send the resource.
+    fromProxy({ jsonrpc: "2.0", method: "ui/notifications/sandbox-proxy-ready", params: {} });
+    expect(sent).toHaveLength(1);
+
+    fromProxy({ jsonrpc: "2.0", id: 1, method: "ui/initialize", params: { appCapabilities: {} } });
+    await flush();
+    expect(sent).toHaveLength(2);
+    expect(sent[1].id).toBe(1);
+    expect((sent[1].result as Record<string, unknown>).protocolVersion).toBe("2026-01-26");
+    // Still nothing UNSOLICITED: the tool data waits for `initialized`.
+    expect(sent.some((m) => m.method === "ui/notifications/tool-input")).toBe(false);
+
+    fromProxy({ jsonrpc: "2.0", method: "ui/notifications/initialized", params: {} });
+    expect(sent.slice(2).map((m) => m.method)).toEqual([
+      "ui/notifications/tool-input",
+      "ui/notifications/tool-result",
+    ]);
+    expect(sent[2].params).toEqual({ arguments: { run_id: 5 } });
+  });
+
+  it("drops messages from any other source, a non-null origin, or that are not JSON-RPC", async () => {
+    const { sent, fromProxy } = setup();
+    const other = document.createElement("iframe");
+    document.body.appendChild(other);
+    const hello = { jsonrpc: "2.0", method: "ui/notifications/sandbox-proxy-ready", params: {} };
+    fromProxy(hello, { source: other.contentWindow });          // another frame, also "null"
+    fromProxy(hello, { origin: "https://evil.test" });           // right frame, wrong origin
+    fromProxy({ method: "ui/notifications/sandbox-proxy-ready" }); // not JSON-RPC 2.0
+    fromProxy("garbage");
+    await flush();
+    expect(sent).toEqual([]);
+  });
+
+  it("swallows sandbox-* notifications from the View instead of acting on them", async () => {
+    const { sent, fromProxy } = setup();
+    fromProxy({ jsonrpc: "2.0", method: "ui/notifications/sandbox-resource-ready",
+                params: { html: "<script>evil()</script>" } });
+    await flush();
+    expect(sent).toEqual([]);
+  });
+
+  it("proxies tools/call to canopy and answers with the result", async () => {
+    const { sent, handlers, fromProxy } = setup();
+    fromProxy({ jsonrpc: "2.0", id: 7, method: "tools/call",
+                params: { name: "workflow_action_preview_view", arguments: { run_id: 5 } } });
+    await flush();
+    expect(handlers.callTool).toHaveBeenCalledWith("workflow_action_preview_view", { run_id: 5 });
+    expect(sent[0]).toMatchObject({ id: 7, result: { isError: false } });
+  });
+
+  it("a viewer who may not act gets no serverTools and every act refused", async () => {
+    const { bridge, sent, handlers, fromProxy } = setup({ canAct: false });
+    expect(bridge.hostCapabilities()).not.toHaveProperty("serverTools");
+    fromProxy({ jsonrpc: "2.0", id: 1, method: "ui/initialize", params: {} });
+    await flush();
+    expect((sent[0].result as { hostCapabilities: object }).hostCapabilities)
+      .not.toHaveProperty("serverTools");
+    for (const [i, method] of ["tools/call", "resources/read", "ui/message",
+                               "ui/update-model-context"].entries()) {
+      fromProxy({ jsonrpc: "2.0", id: 10 + i, method,
+                  params: { name: "x", uri: "ui://x", content: { type: "text", text: "hi" } } });
+    }
+    await flush();
+    expect(handlers.callTool).not.toHaveBeenCalled();
+    expect(handlers.sendMessage).not.toHaveBeenCalled();
+    expect(sent.slice(1).every((m) => m.error)).toBe(true);
+  });
+
+  it("ui/open-link accepts https only", async () => {
+    const { sent, handlers, fromProxy } = setup();
+    fromProxy({ jsonrpc: "2.0", id: 1, method: "ui/open-link", params: { url: "javascript:alert(1)" } });
+    fromProxy({ jsonrpc: "2.0", id: 2, method: "ui/open-link", params: { url: "http://labs.test" } });
+    fromProxy({ jsonrpc: "2.0", id: 3, method: "ui/open-link", params: { url: "https://labs.test/run/5" } });
+    await flush();
+    expect(handlers.openLink).toHaveBeenCalledTimes(1);
+    expect(handlers.openLink).toHaveBeenCalledWith("https://labs.test/run/5");
+    expect(sent.filter((m) => m.error).map((m) => m.id)).toEqual([1, 2]);
+  });
+
+  it("answers display-mode, ping, size and unknown methods per the spec", async () => {
+    const { sent, handlers, fromProxy } = setup();
+    fromProxy({ jsonrpc: "2.0", id: 1, method: "ui/request-display-mode", params: { mode: "fullscreen" } });
+    fromProxy({ jsonrpc: "2.0", id: 2, method: "ping" });
+    fromProxy({ jsonrpc: "2.0", id: 3, method: "sampling/createMessage", params: {} });
+    fromProxy({ jsonrpc: "2.0", method: "ui/notifications/size-changed", params: { width: 300, height: 420 } });
+    await flush();
+    expect(sent[0]).toMatchObject({ id: 1, result: { mode: "inline" } });
+    expect(sent[1]).toMatchObject({ id: 2, result: {} });
+    expect(sent[2]).toMatchObject({ id: 3, error: { code: -32601 } });
+    expect(handlers.onSize).toHaveBeenCalledWith({ width: 300, height: 420 });
+  });
+
+  it("ui/message and update-model-context reach canopy", async () => {
+    const { handlers, fromProxy } = setup();
+    fromProxy({ jsonrpc: "2.0", id: 1, method: "ui/message",
+                params: { role: "user", content: { type: "text", text: "Sent" } } });
+    fromProxy({ jsonrpc: "2.0", id: 2, method: "ui/update-model-context",
+                params: { structuredContent: { outcome: "declined" } } });
+    await flush();
+    expect(handlers.sendMessage).toHaveBeenCalledWith("Sent");
+    expect(handlers.updateModelContext).toHaveBeenCalledWith({ structuredContent: { outcome: "declined" } });
+  });
+
+  it("stops listening when closed", async () => {
+    const { bridge, sent, fromProxy } = setup();
+    bridge.close();
+    fromProxy({ jsonrpc: "2.0", method: "ui/notifications/sandbox-proxy-ready", params: {} });
+    await flush();
+    expect(sent).toEqual([]);
+  });
+});

package/src/chat/mcpApps/bridge.ts

@@ -0,0 +1,288 @@
+/**
+ * The HOST side of an MCP Apps View (SEP-1865, `io.modelcontextprotocol/ui`,
+ * spec 2026-01-26 §Communication Protocol, §Sandbox proxy, §Lifecycle).
+ *
+ * canopy frames a sandbox proxy (`/mcp-apps/sandbox/`, opaque origin); the proxy
+ * frames the View and relays JSON-RPC both ways. This module is the host's end
+ * of that wire: it answers the View's requests (`ui/initialize`, `tools/call`,
+ * `resources/read`, `ui/open-link`, `ui/message`, `ui/update-model-context`,
+ * `ui/request-display-mode`, `ping`) through callbacks that go to canopy's REST
+ * routes, and sends the View its tool input and result.
+ *
+ * Why not `@modelcontextprotocol/ext-apps/app-bridge`: it peer-depends on
+ * `@modelcontextprotocol/{client,core,server}` v2 and zod 4, and this file ships
+ * inside `canopy-ui`, a published package whose consumers (ace-web) would all
+ * inherit those peers for one component. The wire is small and fully specified;
+ * this follows it method for method.
+ *
+ * **Who may talk.** The proxy's origin is OPAQUE (owner decision 1), so every
+ * message from it says `origin: "null"` — which is also what any other sandboxed
+ * frame on the page would say. The check is therefore the SOURCE: a message is
+ * accepted only when `event.source` is THIS proxy frame's `contentWindow`, and
+ * its origin is `"null"` (or the configured sandbox origin, if it ever moves to
+ * one). Anything else, or anything that is not JSON-RPC 2.0, is dropped.
+ *
+ * **Order.** Nothing is sent to the View before it says
+ * `ui/notifications/initialized` (§Sandbox proxy 6) — then `tool-input`, then
+ * `tool-result`, exactly once each.
+ */
+
+export const PROTOCOL_VERSION = "2026-01-26";
+
+export interface CallToolResult {
+  content: unknown[];
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+  [key: string]: unknown;
+}
+
+export interface AppBridgeHandlers {
+  callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+  readResource(uri: string): Promise<unknown>;
+  updateModelContext(params: Record<string, unknown>): Promise<void>;
+  sendMessage(text: string): Promise<void>;
+  openLink(url: string): void;
+  onSize?(size: { width?: number; height?: number }): void;
+  onLog?(params: unknown): void;
+}
+
+export interface AppBridgeOptions {
+  /** The proxy frame's window. Messages from anything else are ignored. */
+  getProxyWindow(): Window | null;
+  /** The origin the proxy's messages carry: "null" for the opaque default. */
+  proxyOrigin?: string;
+  /** The View's HTML and the sandbox it gets inside the proxy. */
+  html: string;
+  csp?: Record<string, string[]>;
+  /** Whether the viewer may act. False omits `serverTools` from the host's
+   *  capabilities — the standard's "cannot proxy tool calls" signal, so the
+   *  View renders its buttons disabled — and refuses the calls besides. */
+  canAct: boolean;
+  hostContext: Record<string, unknown>;
+  toolInput: Record<string, unknown>;
+  toolResult: CallToolResult | null;
+  handlers: AppBridgeHandlers;
+  hostInfo?: { name: string; version: string };
+  /** Defaults to `window`; tests pass their own. */
+  target?: Window;
+}
+
+type Rpc = {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method?: string;
+  params?: Record<string, unknown>;
+  result?: unknown;
+  error?: unknown;
+};
+
+function isRpc(d: unknown): d is Rpc {
+  return !!d && typeof d === "object" && (d as Rpc).jsonrpc === "2.0";
+}
+
+export class AppBridge {
+  private readonly opts: AppBridgeOptions;
+  private readonly target: Window;
+  private readonly listener: (ev: MessageEvent) => void;
+  private resourceSent = false;
+  private initialized = false;
+  private dataSent = false;
+  private nextId = 1;
+  private closed = false;
+
+  constructor(opts: AppBridgeOptions) {
+    this.opts = opts;
+    this.target = opts.target ?? window;
+    this.listener = (ev) => this.onMessage(ev);
+    this.target.addEventListener("message", this.listener);
+  }
+
+  /** The host capabilities the View sees in its `ui/initialize` result. */
+  hostCapabilities(): Record<string, unknown> {
+    const caps: Record<string, unknown> = {
+      openLinks: {},
+      logging: {},
+      sandbox: { csp: this.opts.csp ?? {}, permissions: {} },
+    };
+    if (this.opts.canAct) {
+      caps.serverTools = {};
+      caps.serverResources = {};
+    }
+    return caps;
+  }
+
+  /** §Lifecycle 4: tell the View before tearing it down. Best effort. */
+  close(reason = "unmounted"): void {
+    if (this.closed) return;
+    if (this.initialized) {
+      this.post({ jsonrpc: "2.0", id: `teardown-${this.nextId++}`, method: "ui/resource-teardown",
+                  params: { reason } });
+    }
+    this.closed = true;
+    this.target.removeEventListener("message", this.listener);
+  }
+
+  private post(msg: Rpc): void {
+    const win = this.opts.getProxyWindow();
+    // The proxy's origin is opaque, so "*" is the only targetOrigin that
+    // reaches it; WHICH window receives it is fixed by `win`, not by origin.
+    win?.postMessage(msg, "*");
+  }
+
+  private accepted(ev: MessageEvent): boolean {
+    const win = this.opts.getProxyWindow();
+    if (!win || ev.source !== win) return false;
+    return ev.origin === (this.opts.proxyOrigin ?? "null");
+  }
+
+  private onMessage(ev: MessageEvent): void {
+    if (this.closed || !this.accepted(ev) || !isRpc(ev.data)) return;
+    const msg = ev.data;
+    const method = typeof msg.method === "string" ? msg.method : null;
+    if (method === null) return; // a response to our teardown; nothing to do
+    if (method === "ui/notifications/sandbox-proxy-ready") {
+      if (this.resourceSent) return;
+      this.resourceSent = true;
+      this.post({
+        jsonrpc: "2.0",
+        method: "ui/notifications/sandbox-resource-ready",
+        params: { html: this.opts.html, csp: this.opts.csp ?? {}, sandbox: "allow-scripts",
+                  permissions: {} },
+      });
+      return;
+    }
+    if (method.startsWith("ui/notifications/sandbox-")) return;
+    if (msg.id === undefined || msg.id === null) {
+      this.onNotification(method, msg.params ?? {});
+      return;
+    }
+    void this.onRequest(msg.id, method, msg.params ?? {});
+  }
+
+  private onNotification(method: string, params: Record<string, unknown>): void {
+    if (method === "ui/notifications/initialized") {
+      if (this.initialized) return;
+      this.initialized = true;
+      this.sendToolData();
+      return;
+    }
+    if (method === "ui/notifications/size-changed") {
+      const width = typeof params.width === "number" ? params.width : undefined;
+      const height = typeof params.height === "number" ? params.height : undefined;
+      this.opts.handlers.onSize?.({ width, height });
+      return;
+    }
+    if (method === "notifications/message") {
+      this.opts.handlers.onLog?.(params);
+    }
+  }
+
+  private sendToolData(): void {
+    if (this.dataSent) return;
+    this.dataSent = true;
+    this.post({ jsonrpc: "2.0", method: "ui/notifications/tool-input",
+                params: { arguments: this.opts.toolInput } });
+    if (this.opts.toolResult) {
+      this.post({ jsonrpc: "2.0", method: "ui/notifications/tool-result",
+                  params: this.opts.toolResult as unknown as Record<string, unknown> });
+    }
+  }
+
+  private respond(id: string | number, result: unknown): void {
+    this.post({ jsonrpc: "2.0", id, result });
+  }
+
+  private fail(id: string | number, code: number, message: string): void {
+    this.post({ jsonrpc: "2.0", id, error: { code, message } });
+  }
+
+  private async onRequest(id: string | number, method: string,
+                          params: Record<string, unknown>): Promise<void> {
+    const h = this.opts.handlers;
+    try {
+      switch (method) {
+        case "ui/initialize":
+          this.respond(id, {
+            protocolVersion: PROTOCOL_VERSION,
+            hostCapabilities: this.hostCapabilities(),
+            hostInfo: this.opts.hostInfo ?? { name: "canopy", version: "1" },
+            hostContext: this.opts.hostContext,
+          });
+          return;
+        case "ping":
+          this.respond(id, {});
+          return;
+        case "ui/request-display-mode":
+          // Inline only (spec 2026-10-08 §7): the answer is the mode in force.
+          this.respond(id, { mode: "inline" });
+          return;
+        case "ui/open-link": {
+          const url = typeof params.url === "string" ? params.url : "";
+          if (!isHttps(url)) {
+            this.fail(id, -32000, "Invalid URL");
+            return;
+          }
+          h.openLink(url);
+          this.respond(id, {});
+          return;
+        }
+        case "tools/call": {
+          if (!this.opts.canAct) {
+            this.fail(id, -32000, "You can't act from this view");
+            return;
+          }
+          const name = typeof params.name === "string" ? params.name : "";
+          const args = (params.arguments && typeof params.arguments === "object")
+            ? params.arguments as Record<string, unknown> : {};
+          this.respond(id, await h.callTool(name, args));
+          return;
+        }
+        case "resources/read": {
+          if (!this.opts.canAct) {
+            this.fail(id, -32000, "You can't act from this view");
+            return;
+          }
+          const uri = typeof params.uri === "string" ? params.uri : "";
+          this.respond(id, await h.readResource(uri));
+          return;
+        }
+        case "ui/update-model-context":
+          if (!this.opts.canAct) {
+            this.fail(id, -32000, "Context update denied");
+            return;
+          }
+          await h.updateModelContext(params);
+          this.respond(id, {});
+          return;
+        case "ui/message": {
+          if (!this.opts.canAct) {
+            this.fail(id, -32000, "Message sending denied");
+            return;
+          }
+          const content = params.content as { type?: string; text?: unknown } | undefined;
+          const text = content && content.type === "text" && typeof content.text === "string"
+            ? content.text : "";
+          if (!text.trim()) {
+            this.fail(id, -32000, "Invalid message format");
+            return;
+          }
+          await h.sendMessage(text);
+          this.respond(id, {});
+          return;
+        }
+        default:
+          this.fail(id, -32601, `Method not found: ${method}`);
+      }
+    } catch (err) {
+      this.fail(id, -32000, err instanceof Error ? err.message : String(err));
+    }
+  }
+}
+
+export function isHttps(url: string): boolean {
+  try {
+    return new URL(url).protocol === "https:";
+  } catch {
+    return false;
+  }
+}

package/src/chat/mcpApps/context.ts

@@ -0,0 +1,64 @@
+import { createContext, useContext } from "react";
+
+import type { CallToolResult } from "./bridge";
+
+/** What the server put on a tool result row that has an MCP Apps View
+ *  (`MessageOut.app`; spec 2026-10-08 §3). Decided server-side — the client
+ *  never guesses which tools have Views. */
+export interface AppRef {
+  tool_call_id: string;
+  site: string;
+  tool: string;
+  resource_uri: string;
+  path?: string;
+}
+
+export interface AppReceipt {
+  tool: string;
+  by: { name: string };
+  at: string;
+  is_error: boolean;
+  result?: string;
+}
+
+/** `GET …/apps/{tool_call_id}/resource` — the View, read as the person looking. */
+export interface AppViewResource {
+  tool_call_id: string;
+  site: string;
+  tool: string;
+  html: string;
+  csp: Record<string, string[]>;
+  sandbox_src: string;
+  prefers_border: boolean | null;
+  can_act: boolean;
+  read_only_reason: string;
+  sign_in_url: string;
+  tool_input: Record<string, unknown>;
+  tool_result: CallToolResult | null;
+  receipts: AppReceipt[];
+}
+
+/** How a host page reaches canopy for one session's Views. ChatPage wires it
+ *  to `/api/canopy-sessions/{id}/apps/…`, the embed panel to the same or (for a
+ *  contact) `/api/contact/sessions/{id}/apps/…`. Absent, no View renders and a
+ *  tool result looks exactly as it always did (ace-web, older hosts). */
+export interface AppHost {
+  load(toolCallId: string): Promise<AppViewResource>;
+  callTool(toolCallId: string, name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+  readResource(toolCallId: string, uri: string): Promise<unknown>;
+  updateContext(toolCallId: string, params: Record<string, unknown>): Promise<void>;
+  sendMessage(toolCallId: string, text: string): Promise<void>;
+  /** Turns the server's `sandbox_src` into a frame URL (a path prefix, an origin). */
+  resolveUrl?(path: string): string;
+  /** The origin the proxy's messages carry; "null" (opaque) unless the sandbox
+   *  moved to a dedicated origin. */
+  proxyOrigin?: string;
+  /** Narrow panels (the embed) pass their width. */
+  maxWidth?: number;
+}
+
+export const AppHostContext = createContext<AppHost | null>(null);
+
+export function useAppHost(): AppHost | null {
+  return useContext(AppHostContext);
+}

package/src/chat/mcpApps/wiring.test.ts

@@ -0,0 +1,39 @@
+/**
+ * The server's `app` on a tool result survives every path into the kit: the
+ * AG-UI inverse, the reducer (new row and upsert) and the REST conversion.
+ */
+import { describe, expect, it } from "vitest";
+
+import { fromAgui } from "../agui";
+import type { SessionState } from "../protocol";
+import { restToKitMessage } from "../restMessage";
+import { sessionReducer } from "../sessionReducer";
+
+const APP = { tool_call_id: "toolu_1", site: "connect-labs", tool: "workflow_run_action",
+              resource_uri: "ui://labs/x", path: "direct" };
+
+describe("MCP Apps wiring", () => {
+  it("AG-UI TOOL_CALL_RESULT metadata.canopy.app becomes frame.data.app", () => {
+    const [frame] = fromAgui({ type: "TOOL_CALL_RESULT", toolCallId: "m1", messageId: "m1",
+                               content: "x", metadata: { canopy: { turn_index: 3, app: APP,
+                               block: { tool_use_id: "toolu_1" } } } } as never);
+    expect(frame).toMatchObject({ event: "chat.tool_result", data: { app: APP } });
+  });
+
+  it("the reducer keeps app on a new row and on an upsert", () => {
+    const empty = { messages: [] } as unknown as SessionState;
+    const frame = { event: "chat.tool_result" as const,
+                    data: { parent_message_id: null, tool_message_id: "m1", turn_index: 3,
+                            block: { tool_use_id: "toolu_1" }, app: APP } };
+    const once = sessionReducer(empty, frame);
+    expect(once.messages[0].app).toEqual(APP);
+    const twice = sessionReducer(once, { ...frame, data: { ...frame.data, tool_message_id: "m2" } });
+    expect(twice.messages).toHaveLength(1);
+    expect(twice.messages[0].app).toEqual(APP);
+  });
+
+  it("restToKitMessage carries app", () => {
+    expect(restToKitMessage({ turn_index: 1, role: "tool_result", content: {}, plaintext: "",
+                              created_at: "", app: APP }).app).toEqual(APP);
+  });
+});

package/src/chat/protocol.ts

@@ -49,6 +49,18 @@ export interface Message {
   /** Who typed this line — a canopy user or a contact. Absent/null on rows
    *  from before authorship was tracked, or on the agent's own messages. */
   author?: MessageAuthor | null;
+  /** MCP Apps: this tool result has a View (spec 2026-10-08 §3). Set by the
+   *  server on REST rows, the snapshot and the live frame — never guessed. */
+  app?: MessageAppRef | null;
+}
+
+/** `MessageOut.app` — mirrors `AppRef` in `mcpApps/AppView.tsx`. */
+export interface MessageAppRef {
+  tool_call_id: string;
+  site: string;
+  tool: string;
+  resource_uri: string;
+  path?: string;
 }
 
 /** How much of an in-progress message its author lets OTHERS see: the words
@@ -343,7 +355,7 @@ export type WsEvent =
   // Message carries, so a live tool row sorts into exactly the position it will
   // occupy after a reload. Optional: an older server omits it.
   | { event: "chat.tool_use"; data: { parent_message_id: string | null; tool_message_id: string; turn_index?: number; block: Record<string, unknown> } }
-  | { event: "chat.tool_result"; data: { parent_message_id: string | null; tool_message_id: string; turn_index?: number; block: Record<string, unknown> } }
+  | { event: "chat.tool_result"; data: { parent_message_id: string | null; tool_message_id: string; turn_index?: number; block: Record<string, unknown>; app?: MessageAppRef | null } }
   | { event: "chat.stream_complete"; data: { message_id: string; plaintext: string } }
   | { event: "chat.stream_error"; data: { message_id: string; detail: string } }
   | { event: "chat.stream_cancelled"; data: { message_id: string | null; partial_len: number } }

package/src/chat/restMessage.ts

@@ -27,6 +27,8 @@ export interface RestMessage {
   content: Record<string, unknown>;
   plaintext: string;
   created_at: string;
+  /** MCP Apps View on a tool result (`MessageOut.app`). */
+  app?: Message["app"];
 }
 
 /**
@@ -50,5 +52,6 @@ export function restToKitMessage(m: RestMessage): Message {
     started_at: null,
     completed_at: m.created_at,
     created_at: m.created_at,
+    ...(m.app ? { app: m.app } : {}),
   };
 }

package/src/chat/sessionReducer.ts

@@ -329,6 +329,9 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
                   turn_index: frame.data.turn_index ?? m.turn_index,
                   content: block,
                   plaintext,
+                  ...(role === "tool_result" && "app" in frame.data && frame.data.app
+                    ? { app: frame.data.app }
+                    : {}),
                 }
               : m,
           ),
@@ -345,6 +348,9 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
         role,
         content: block,
         plaintext,
+        ...(role === "tool_result" && "app" in frame.data && frame.data.app
+          ? { app: frame.data.app }
+          : {}),
         status: block.is_error === true ? "error" : "complete",
         error_detail: null,
         started_at: nowIso,