@ulearning/ai-sdk 0.0.0-stage → 1.0.0-next.0

package/src/mcp-apps/McpAppRenderer.tsx

@@ -0,0 +1,411 @@
+"use client";
+
+import { computed, defineComponent, h, shallowRef, type VNodeChild } from "vue";
+import { useEffect, useMemo, useState } from "@ulearning/ai-tap";
+import { useIsomorphicLayoutEffect } from "../utils/useIsomorphicLayoutEffect";
+import type {
+  McpAppMetadata,
+  TextMessagePart,
+  ToolCallMessagePart,
+} from "@ulearning/ai-core";
+import type {
+  ToolCallMessagePartComponent,
+  ToolCallMessagePartProps,
+} from "@ulearning/ai-core/vue";
+import { useAui } from "@ulearning/ai-store";
+import { createStore, type StoreApi } from "zustand/vanilla";
+
+import { useResource, resource, type ResourceElement } from "@ulearning/ai-tap";
+import { McpAppFrame } from "./app-frame";
+import type {
+  McpAppBridgeHandlers,
+  McpAppHostContext,
+  McpAppHostInfo,
+  McpAppResource,
+  McpAppSandboxConfig,
+  McpAppsHost,
+} from "./types";
+import { getMcpAppFromToolPart } from "./utils";
+import { isRecord } from "@ulearning/ai-core/internal";
+
+/**
+ * Options that apply to a single MCP app. `McpAppRenderer` takes them as
+ * thread-wide defaults, and its `forPart` resolver overrides them for one part.
+ */
+export type McpAppPartOptions = {
+  /** Sandbox + container styling. Passes through to SafeContentFrame. */
+  sandbox?: McpAppSandboxConfig;
+  /**
+   * Upper bound (in pixels) applied to the widget-driven auto-resize height.
+   * Defaults to 800.
+   */
+  maxHeight?: number;
+  /** Identifies the host to the widget in the `ui/initialize` response. */
+  hostInfo?: McpAppHostInfo;
+  /** Delivered to the widget on initialize and pushed via `notifications/host_context/changed` on change. */
+  hostContext?: McpAppHostContext;
+  /**
+   * Optional widget interaction and lifecycle handlers. Data-plane handlers
+   * (`callTool`, `readResource`, `listResources`) always use `host`.
+   *
+   * Which handlers a widget may call is captured when its frame mounts, so a
+   * `forPart` resolver returns the same handler keys for a part on every
+   * render even when the implementations change.
+   */
+  handlers?: Omit<
+    McpAppBridgeHandlers,
+    "callTool" | "readResource" | "listResources"
+  >;
+  /** Rendered when no MCP app is on the part, or while load is in flight / failed (unless overridden). */
+  fallback?: VNodeChild;
+  /** Rendered while the resource is loading. Defaults to `fallback`. */
+  loadingFallback?: VNodeChild;
+  /** Rendered when the resource load rejects. Defaults to `fallback`. */
+  errorFallback?: VNodeChild | ((error: Error) => VNodeChild);
+};
+
+export type McpAppRendererOptions = McpAppPartOptions & {
+  /**
+   * Provides the data-plane operations the widget can request
+   * (`loadResource`, `callTool`, `readResource`, `listResources`). Use
+   * `McpAppsRemoteHost({ url })` for the default HTTP-route convention.
+   */
+  host: ResourceElement<McpAppsHost>;
+  /**
+   * Resolves the options for one part. Each returned value replaces the
+   * thread-wide option of the same name, so a host can give every MCP app its
+   * own display mode and answer `requestDisplayMode` for the part that asked.
+   *
+   * `handlers` is the exception and merges per key. Its keys are capabilities
+   * negotiated with the widget rather than data, so replacing the whole bag to
+   * add one handler would withdraw the others from that part's widget with
+   * nothing to observe it by.
+   */
+  forPart?: (part: ToolCallMessagePart) => McpAppPartOptions;
+};
+
+type LoadedResourceState = {
+  host: McpAppsHost;
+  resourceUri: string;
+  serverId?: string;
+  resource?: McpAppResource;
+  error?: Error;
+};
+
+type RendererState = {
+  host: McpAppsHost;
+  options: McpAppRendererOptions;
+};
+
+type UseRendererStore = StoreApi<RendererState>;
+
+// Callers pass options as an object literal, so the resource hands this a fresh
+// identity on every run; comparing the values keeps an unchanged run from
+// re-rendering every mounted part. `host` is excluded because it is an element
+// rebuilt on every run, and the store carries the resolved host separately.
+const isSameOptions = (
+  a: McpAppRendererOptions,
+  b: McpAppRendererOptions,
+): boolean => {
+  const aKeys = Object.keys(a).filter((key) => key !== "host");
+  const bKeys = Object.keys(b).filter((key) => key !== "host");
+  if (aKeys.length !== bKeys.length) return false;
+  const aValues = a as Record<string, unknown>;
+  const bValues = b as Record<string, unknown>;
+  return aKeys.every(
+    (key) =>
+      Object.hasOwn(bValues, key) && Object.is(aValues[key], bValues[key]),
+  );
+};
+
+function getInput(part: {
+  status: { type: string };
+  argsText: string;
+  args: unknown;
+}): unknown {
+  if (
+    part.status.type === "running" &&
+    (part.argsText === "" || part.argsText === "{}")
+  ) {
+    return undefined;
+  }
+  return part.args;
+}
+
+const defaultOpenLink = ({ url }: { url: string }) => {
+  window.open(url, "_blank", "noopener,noreferrer");
+};
+
+function extractSendMessageTexts(params: unknown): string[] | undefined {
+  if (typeof params === "string") return [params];
+  if (!params || typeof params !== "object") return undefined;
+  const obj = params as Record<string, unknown>;
+  if (typeof obj["prompt"] === "string") return [obj["prompt"]];
+  if (typeof obj["text"] === "string") return [obj["text"]];
+  if (typeof obj["message"] === "string") return [obj["message"]];
+  const content = obj["content"];
+  if (Array.isArray(content)) {
+    return Object.keys(content)
+      .filter((key) => {
+        const index = Number(key);
+        return (
+          Number.isInteger(index) &&
+          index >= 0 &&
+          index < content.length &&
+          String(index) === key
+        );
+      })
+      .map((key) => content[Number(key)])
+      .filter(
+        (block): block is { type: "text"; text: string } =>
+          isRecord(block) &&
+          block["type"] === "text" &&
+          typeof block["text"] === "string",
+      )
+      .map((block) => block.text);
+  }
+  return undefined;
+}
+
+function extractSendMessageContent(
+  params: unknown,
+): { content: TextMessagePart[] } | { reason: string } {
+  const texts = extractSendMessageTexts(params);
+  if (!texts) return { reason: "unrecognised params shape" };
+  const content = texts
+    .filter((text) => text !== "")
+    .map((text): TextMessagePart => ({ type: "text", text }));
+  if (content.length === 0) {
+    return { reason: "no text content to append" };
+  }
+  return { content };
+}
+
+function resolvePartOptions(
+  options: McpAppRendererOptions,
+  part: ToolCallMessagePartProps,
+): McpAppRendererOptions {
+  const overrides = options.forPart?.(part);
+  if (!overrides) return options;
+  const handlers =
+    options.handlers && overrides.handlers
+      ? { ...options.handlers, ...overrides.handlers }
+      : (overrides.handlers ?? options.handlers);
+  return {
+    ...options,
+    ...overrides,
+    ...(handlers === undefined ? {} : { handlers }),
+  };
+}
+
+const InlineRenderer = defineComponent(
+  (props: {
+    part: ToolCallMessagePartProps;
+    useRendererStore: UseRendererStore;
+  }) => {
+    const aui = useAui();
+    const store = props.useRendererStore;
+    const snapshot = shallowRef(store.getState());
+    useIsomorphicLayoutEffect(() => {
+      let active = true;
+      const refresh = () => {
+        if (active) snapshot.value = store.getState();
+      };
+      const release = store.subscribe(refresh);
+      refresh();
+      return () => {
+        active = false;
+        release();
+      };
+    }, []);
+    const host = computed(() => snapshot.value.host);
+    const opts = computed(() =>
+      resolvePartOptions(snapshot.value.options, props.part),
+    );
+    const app = computed(() => getMcpAppFromToolPart(props.part));
+    // Cache only after the owning Vue branch commits. An abandoned Suspense
+    // branch must never replace the metadata used by the visible frame.
+    let cachedApp: McpAppMetadata | undefined;
+    useIsomorphicLayoutEffect(
+      () => {
+        if (app.value != null) cachedApp = app.value;
+      },
+      () => [app.value],
+    );
+    const appForRender = computed(() => app.value ?? cachedApp);
+    const loadedResource = shallowRef<LoadedResourceState>();
+    const resourceUri = computed(() => appForRender.value?.resourceUri);
+    const serverId = computed(() => appForRender.value?.serverId);
+    useIsomorphicLayoutEffect(
+      () => {
+        if (resourceUri.value == null) return;
+        let cancelled = false;
+        const targetHost = host.value;
+        const targetUri = resourceUri.value;
+        const targetServerId = serverId.value;
+        const loadResource = async () => {
+          // Tap publishes the committed host during its effect flush. Newly
+          // mounted parts wait for that publication before starting their load.
+          await Promise.resolve();
+          if (cancelled || store.getState().host !== targetHost) return;
+          try {
+            const resource = await targetHost.loadResource({
+              uri: targetUri,
+              ...(targetServerId ? { serverId: targetServerId } : {}),
+            });
+            if (!cancelled)
+              loadedResource.value = {
+                host: targetHost,
+                resourceUri: targetUri,
+                ...(targetServerId !== undefined
+                  ? { serverId: targetServerId }
+                  : {}),
+                resource,
+              };
+          } catch (error: unknown) {
+            if (!cancelled)
+              loadedResource.value = {
+                host: targetHost,
+                resourceUri: targetUri,
+                ...(targetServerId !== undefined
+                  ? { serverId: targetServerId }
+                  : {}),
+                error:
+                  error instanceof Error ? error : new Error(String(error)),
+              };
+          }
+        };
+        void loadResource();
+        return () => {
+          cancelled = true;
+        };
+      },
+      () => [host.value, resourceUri.value, serverId.value],
+    );
+
+    const bridgeHandlers = computed<McpAppBridgeHandlers>(() => {
+      const callerHandlers = opts.value.handlers;
+      const committedServerId = serverId.value;
+      return {
+        ...callerHandlers,
+        openLink: callerHandlers?.openLink ?? defaultOpenLink,
+        sendMessage:
+          callerHandlers?.sendMessage ??
+          ((params) => {
+            const result = extractSendMessageContent(params);
+            if ("reason" in result)
+              return { isError: true, ok: false, reason: result.reason };
+            const composer = aui.thread.composer();
+            composer.setText(
+              [
+                composer.getState().text,
+                result.content.map((part) => part.text).join("\n"),
+              ]
+                .filter((part) => part.trim())
+                .join(" "),
+            );
+            return { ok: true };
+          }),
+        callTool: (params) =>
+          store.getState().host.callTool({
+            ...params,
+            ...(committedServerId ? { serverId: committedServerId } : {}),
+          }),
+        readResource: (params) =>
+          store.getState().host.readResource({
+            ...params,
+            ...(committedServerId ? { serverId: committedServerId } : {}),
+          }),
+        listResources: (params) =>
+          committedServerId
+            ? store.getState().host.listResources({
+                ...(isRecord(params) ? params : {}),
+                serverId: committedServerId,
+              })
+            : store.getState().host.listResources(params),
+      };
+    });
+    return () => {
+      const options = opts.value;
+      const metadata = appForRender.value;
+      const loaded = loadedResource.value;
+      const current =
+        loaded?.host === host.value &&
+        loaded?.resourceUri === metadata?.resourceUri &&
+        loaded?.serverId === metadata?.serverId
+          ? loaded
+          : undefined;
+      const fallback = options.fallback ?? null;
+      if (metadata == null) return fallback;
+      if (current?.error != null) {
+        const errorFallback = options.errorFallback;
+        return errorFallback === undefined
+          ? fallback
+          : typeof errorFallback === "function"
+            ? errorFallback(current.error)
+            : errorFallback;
+      }
+      if (current?.resource == null) return options.loadingFallback ?? fallback;
+      return h(McpAppFrame, {
+        app: metadata,
+        resource: current.resource,
+        input: getInput(props.part),
+        output: props.part.result,
+        ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
+        handlers: bridgeHandlers.value,
+        ...(options.hostInfo === undefined
+          ? {}
+          : { hostInfo: options.hostInfo }),
+        ...(options.hostContext === undefined
+          ? {}
+          : { hostContext: options.hostContext }),
+        ...(options.maxHeight === undefined
+          ? {}
+          : { maxHeight: options.maxHeight }),
+      });
+    };
+  },
+  { name: "McpAppInlineRenderer", props: ["part", "useRendererStore"] },
+);
+
+/**
+ * Creates a tool-call renderer for MCP Apps embedded in assistant messages.
+ *
+ * Compose this into the `Tools` resource through its `mcpApp` option. When a
+ * tool-call part carries `mcp.app` metadata for a `ui://` resource, the
+ * renderer loads that resource from the configured host and displays it in a
+ * sandboxed frame.
+ */
+const useMcpAppRenderer = (
+  options: McpAppRendererOptions,
+): { readonly render: ToolCallMessagePartComponent } => {
+  const host = useResource(options.host);
+
+  // The rendered component identity has to stay stable, or every part remounts
+  // its frame; options reach the parts through the store instead of props.
+  const [useRendererStore] = useState(() =>
+    createStore<RendererState>(() => ({ host, options })),
+  );
+  useEffect(() => {
+    useRendererStore.setState((prev) =>
+      prev.host === host && isSameOptions(prev.options, options)
+        ? prev
+        : { host, options },
+    );
+  }, [host, options, useRendererStore]);
+
+  const render = useMemo((): ToolCallMessagePartComponent => {
+    function McpAppRenderer(props: ToolCallMessagePartProps) {
+      // Native functional components retain their attrs object across updates.
+      // Publish a fresh part snapshot so the stateful child's computed inputs
+      // observe field changes, including removal of the app metadata.
+      return h(InlineRenderer, { part: { ...props }, useRendererStore });
+    }
+    const Render = McpAppRenderer;
+    return Render;
+  }, [useRendererStore]);
+
+  return { render };
+};
+
+export const McpAppRenderer = resource(useMcpAppRenderer);

package/src/mcp-apps/McpAppsRemoteHost.concurrent.test.tsx

@@ -0,0 +1,226 @@
+// @vitest-environment jsdom
+
+import { cleanup, render } from "../tests/vue";
+import { waitFor } from "@testing-library/dom";
+import { flushTapSync, useResource } from "@ulearning/ai-tap";
+import { defineComponent, h, nextTick, shallowRef, Suspense } from "vue";
+import { useIsomorphicLayoutEffect } from "../utils/useIsomorphicLayoutEffect";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { McpAppsHost } from "./types";
+import { McpAppsRemoteHost } from "./McpAppsRemoteHost";
+
+afterEach(cleanup);
+
+describe("McpAppsRemoteHost concurrent rendering", () => {
+  it("keeps committed authorization options during an interrupted render", async () => {
+    const pending = new Promise<never>(() => {});
+    const fetch = vi.fn(async () => Response.json({ content: [] }));
+    let committedHost: McpAppsHost | undefined;
+
+    const Blocker = defineComponent({
+      async setup() {
+        await pending;
+        return () => null;
+      },
+    });
+    const Probe = defineComponent(
+      (props: { authorization: string; suspend: boolean; label: string }) => {
+        const host = useResource(() =>
+          McpAppsRemoteHost({
+            url: "/api/mcp-apps",
+            fetch,
+            headers: { authorization: props.authorization },
+          }),
+        );
+        useIsomorphicLayoutEffect(
+          () => {
+            committedHost = host.value;
+          },
+          () => [host.value],
+        );
+        return () => [props.label, props.suspend ? h(Blocker) : null];
+      },
+      { props: ["authorization", "suspend", "label"] },
+    );
+    const scene = (suspend: boolean) =>
+      h(Suspense, null, {
+        default: () =>
+          h(Probe, {
+            key: suspend ? "pending" : "committed",
+            suspend,
+            authorization: suspend
+              ? "Bearer workspace-b"
+              : "Bearer workspace-a",
+            label: suspend ? "workspace-b" : "workspace-a",
+          }),
+        fallback: () => null,
+      });
+    const view = render(scene(false));
+    await view.rerender(scene(true));
+
+    expect(view.container.textContent).toBe("workspace-a");
+    await committedHost?.callTool({ name: "search" });
+
+    expect(fetch).toHaveBeenCalledWith("/api/mcp-apps", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: "Bearer workspace-a",
+      },
+      body: JSON.stringify({
+        method: "tools/call",
+        params: { name: "search" },
+      }),
+    });
+
+    view.unmount();
+  });
+
+  it("keeps the URL and authorization from one committed options snapshot", async () => {
+    const fetch = vi.fn(async () => Response.json({ content: [] }));
+    let currentHost: McpAppsHost | undefined;
+
+    const Probe = defineComponent(
+      (props: { url: string; authorization: string }) => {
+        const host = useResource(() =>
+          McpAppsRemoteHost({
+            url: props.url,
+            fetch,
+            headers: { authorization: props.authorization },
+          }),
+        );
+        useIsomorphicLayoutEffect(
+          () => {
+            currentHost = host.value;
+            void host.value.callTool({ name: "layout-request" });
+          },
+          () => [host.value],
+        );
+        return () => null;
+      },
+      { props: ["url", "authorization"] },
+    );
+    const view = render(
+      h(Probe, {
+        url: "/workspace-a/mcp",
+        authorization: "Bearer workspace-a",
+      }),
+    );
+    fetch.mockClear();
+    await view.rerender(
+      h(Probe, {
+        url: "/workspace-b/mcp",
+        authorization: "Bearer workspace-b",
+      }),
+    );
+    flushTapSync(() => {});
+    await nextTick();
+    await waitFor(() => expect(fetch).toHaveBeenCalledTimes(1));
+
+    expect(fetch).toHaveBeenNthCalledWith(1, "/workspace-b/mcp", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: "Bearer workspace-b",
+      },
+      body: JSON.stringify({
+        method: "tools/call",
+        params: { name: "layout-request" },
+      }),
+    });
+
+    await currentHost?.callTool({ name: "committed-request" });
+
+    expect(fetch).toHaveBeenNthCalledWith(2, "/workspace-b/mcp", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: "Bearer workspace-b",
+      },
+      body: JSON.stringify({
+        method: "tools/call",
+        params: { name: "committed-request" },
+      }),
+    });
+
+    view.unmount();
+  });
+
+  it("refreshes pending options when a URL switch render retries", async () => {
+    const authorization = shallowRef("Bearer workspace-b-old");
+    let resume: (() => void) | undefined;
+    const pending = new Promise<void>((resolve) => {
+      resume = () => {
+        resolve();
+      };
+    });
+    const fetch = vi.fn(async () => Response.json({ content: [] }));
+
+    const Blocker = defineComponent({
+      async setup() {
+        await pending;
+        return () => null;
+      },
+    });
+    const Probe = defineComponent(
+      (props: { url: string }) => {
+        const host = useResource(() =>
+          McpAppsRemoteHost({
+            url: props.url,
+            fetch,
+            headers: {
+              authorization:
+                props.url === "/workspace-a/mcp"
+                  ? "Bearer workspace-a"
+                  : authorization.value,
+            },
+          }),
+        );
+        useIsomorphicLayoutEffect(
+          () => {
+            void host.value.callTool({ name: "layout-request" });
+          },
+          () => [host.value],
+        );
+        return () => [
+          h("span", props.url),
+          props.url === "/workspace-b/mcp" ? h(Blocker) : null,
+        ];
+      },
+      { props: ["url"] },
+    );
+    const scene = (url: string) =>
+      h(Suspense, null, {
+        default: () => h(Probe, { key: url, url }),
+        fallback: () => null,
+      });
+    const view = render(scene("/workspace-a/mcp"));
+    try {
+      fetch.mockClear();
+      await view.rerender(scene("/workspace-b/mcp"));
+      expect(view.container.textContent).toBe("/workspace-a/mcp");
+
+      authorization.value = "Bearer workspace-b-new";
+      await nextTick();
+      resume?.();
+      await nextTick();
+      await waitFor(() =>
+        expect(view.container.textContent).toBe("/workspace-b/mcp"),
+      );
+
+      expect(fetch).toHaveBeenCalledWith("/workspace-b/mcp", {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: "Bearer workspace-b-new",
+        },
+        body: JSON.stringify({
+          method: "tools/call",
+          params: { name: "layout-request" },
+        }),
+      });
+    } finally {
+      view.unmount();
+    }
+  });
+});