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

package/src/unstable/webmcp/useWebMcpProvider.ts

@@ -0,0 +1,185 @@
+"use client";
+
+import {
+  computed,
+  shallowRef,
+  toValue,
+  watch,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+} from "vue";
+import { useState } from "@ulearning/ai-tap";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import { useResources, useTapRoot, withKey } from "@ulearning/ai-tap";
+import { useAui } from "@ulearning/ai-store";
+import type { Tool } from "@ulearning/ai-stream";
+import { getDefaultWebMcpHost, type WebMcpHost } from "./webmcp-host";
+import { defaultWebMcpFilter, toWebMcpInputSchema } from "./convertTools";
+import { WebMcpRegistrationResource } from "./WebMcpRegistrationResource";
+import { shallowEqual } from "@ulearning/ai-store/internal";
+import {
+  useModelContextSnapshot,
+  type ModelContextSnapshotSource,
+} from "../useModelContextSnapshot";
+
+/** @deprecated Experimental since 2026-08-29. Not scheduled for removal; the API may change in any release. */
+export type Unstable_WebMcpProviderOptions = {
+  filter?: (name: string, tool: Tool<any, any>) => boolean;
+};
+
+/** @deprecated Experimental since 2026-08-29. Not scheduled for removal; the API may change in any release. */
+export type Unstable_WebMcpProviderResult = {
+  status: "unsupported" | "active";
+  registeredToolNames: readonly string[];
+};
+
+const EMPTY_NAMES: readonly string[] = Object.freeze([]);
+const EMPTY_TOOLS: Record<string, Tool<any, any>> = Object.freeze({});
+
+// The description is re-read on every sync so mutating it in place is
+// observed; the schema is converted only when the tool object itself changes.
+// Keyed on the tool so a schema or filter that throws warns once instead of
+// on every model-context notify.
+const warned = new WeakSet<Tool<any, any>>();
+
+const signatures = new WeakMap<
+  Tool<any, any>,
+  { description: string | undefined; signature: string }
+>();
+
+const signatureOf = (tool: Tool<any, any>) => {
+  const cached = signatures.get(tool);
+  if (cached && cached.description === tool.description)
+    return cached.signature;
+  const signature = `${tool.description ?? ""}\u0000${JSON.stringify(
+    toWebMcpInputSchema(tool),
+  )}`;
+  signatures.set(tool, { description: tool.description, signature });
+  return signature;
+};
+
+const NO_SUBSCRIPTION = () => {};
+
+// No `isEqual`: a caller republishing an unchanged tool set is how it asks for
+// a re-sync, which is what re-attempts a tool whose filter has stopped throwing
+// and what picks up a description edited in place on a stable tool object.
+const modelContextToolSource: ModelContextSnapshotSource<
+  Record<string, Tool<any, any>>
+> = {
+  empty: EMPTY_TOOLS,
+  read: (aui) => aui.modelContext.getModelContext().tools ?? EMPTY_TOOLS,
+  subscribe: (aui, onChange) =>
+    aui.modelContext.subscribe?.(onChange) ?? NO_SUBSCRIPTION,
+};
+
+const useStableNames = (names: readonly (string | null)[]) => {
+  const [cell] = useState(() => ({ names: EMPTY_NAMES }));
+  const next = names.filter((name): name is string => name !== null).sort();
+  const previous = cell.names;
+  if (shallowEqual(previous, next)) {
+    return previous;
+  }
+  cell.names = next;
+  return next;
+};
+
+const useWebMcpRegistry = ({
+  host,
+  filter,
+  tools,
+  getCurrentTool,
+}: {
+  host: WebMcpHost;
+  filter: (name: string, tool: Tool<any, any>) => boolean;
+  tools: Record<string, Tool<any, any>>;
+  getCurrentTool: (name: string) => Tool<any, any> | undefined;
+}) => {
+  const elements = [];
+  for (const [name, tool] of Object.entries(tools)) {
+    try {
+      if (!filter(name, tool)) continue;
+      const signature = signatureOf(tool);
+      elements.push(
+        withKey(
+          name,
+          WebMcpRegistrationResource({
+            host,
+            name,
+            signature,
+            tool,
+            getCurrentTool,
+          }),
+          [host, name, signature, tool, getCurrentTool],
+        ),
+      );
+    } catch (error) {
+      if (warned.has(tool)) continue;
+      warned.add(tool);
+      console.warn(
+        `[assistant-ui] Skipping WebMCP registration for tool "${name}": filter or schema conversion failed.`,
+        error,
+      );
+    }
+  }
+
+  return useStableNames(useResources(elements));
+};
+
+/**
+ * Publishes the frontend tools in the model context to a WebMCP-capable
+ * browser, so the user's own browser agent can call them.
+ *
+ * Returns `status: "unsupported"` when the page exposes no
+ * `document.modelContext` (or `navigator.modelContext`), and the sorted names
+ * of the tools currently registered with the host.
+ *
+ * @deprecated Experimental since 2026-08-29. Not scheduled for removal; the API may change in any release.
+ */
+export const unstable_useWebMcpProvider = (
+  options: MaybeRefOrGetter<Unstable_WebMcpProviderOptions> = {},
+): ComputedRef<Unstable_WebMcpProviderResult> => {
+  const aui = useAui();
+  const host = getDefaultWebMcpHost();
+  const tools = useModelContextSnapshot(
+    aui,
+    host.available,
+    modelContextToolSource,
+  );
+  let currentTools = tools.value;
+  // Snapshot changes arrive from the live, committed model-context source.
+  // Publish implementations synchronously so descendant mounted actions can
+  // call an existing descriptor before the registry's resource job runs.
+  watch(
+    tools,
+    (value) => {
+      currentTools = value;
+    },
+    { flush: "sync" },
+  );
+  const getCurrentTool = (name: string) => currentTools[name];
+  const root = useTapRoot(function WebMcpProviderRoot() {
+    return useWebMcpRegistry({
+      host,
+      filter: toValue(options).filter ?? defaultWebMcpFilter,
+      tools: tools.value,
+      getCurrentTool,
+    });
+  });
+  const registeredToolNames = shallowRef(EMPTY_NAMES);
+  useIsomorphicLayoutEffect(() => {
+    const sync = () => {
+      registeredToolNames.value = root.getValue();
+    };
+    const release = root.subscribe(sync);
+    sync();
+    return release;
+  }, [root]);
+  const published = shallowRef(false);
+  useIsomorphicLayoutEffect(() => {
+    published.value = host.available;
+  }, [host]);
+  return computed(() => ({
+    status: published.value ? "active" : "unsupported",
+    registeredToolNames: registeredToolNames.value,
+  }));
+};

package/src/unstable/webmcp/webmcp-host.test.ts

@@ -0,0 +1,142 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  getDefaultWebMcpHost,
+  type WebMcpModelContext,
+  type WebMcpToolDescriptor,
+} from "./webmcp-host";
+
+type Host = { modelContext?: WebMcpModelContext };
+
+const descriptor: WebMcpToolDescriptor = {
+  name: "get_weather",
+  description: "",
+  inputSchema: {},
+  execute: async () => ({ content: [] }),
+};
+
+const install = (
+  context: Partial<WebMcpModelContext>,
+  on: "document" | "navigator" = "document",
+) => {
+  const host = (on === "document" ? document : navigator) as Host;
+  host.modelContext = context as WebMcpModelContext;
+  return context;
+};
+
+afterEach(() => {
+  delete (document as Host).modelContext;
+  delete (navigator as Host).modelContext;
+});
+
+describe("getDefaultWebMcpHost", () => {
+  it("reports unavailable when the page exposes no model context", () => {
+    const host = getDefaultWebMcpHost();
+    expect(host.available).toBe(false);
+    expect(() => host.registerTool(descriptor)()).not.toThrow();
+  });
+
+  it("reports unavailable and warns when the platform property has no registerTool", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      install({} as Partial<WebMcpModelContext>);
+      const host = getDefaultWebMcpHost();
+      expect(host.available).toBe(false);
+      expect(() => host.registerTool(descriptor)()).not.toThrow();
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining("no callable registerTool"),
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("falls back to navigator.modelContext, preferring document when both exist", () => {
+    const fromNavigator = vi.fn();
+    install({ registerTool: fromNavigator }, "navigator");
+    expect(getDefaultWebMcpHost().available).toBe(true);
+    getDefaultWebMcpHost().registerTool(descriptor);
+    expect(fromNavigator).toHaveBeenCalledOnce();
+
+    const fromDocument = vi.fn();
+    install({ registerTool: fromDocument });
+    getDefaultWebMcpHost().registerTool(descriptor);
+    expect(fromDocument).toHaveBeenCalledOnce();
+    expect(fromNavigator).toHaveBeenCalledOnce();
+  });
+
+  it("registers with an abort signal and aborts it on dispose", () => {
+    const registerTool = vi.fn();
+    install({ registerTool });
+
+    const dispose = getDefaultWebMcpHost().registerTool(descriptor);
+    const options = registerTool.mock.calls[0]![1];
+    expect(registerTool).toHaveBeenCalledWith(descriptor, expect.anything());
+    expect(options.signal.aborted).toBe(false);
+
+    dispose();
+    expect(options.signal.aborted).toBe(true);
+    expect(() => dispose()).not.toThrow();
+  });
+
+  it("reports a rejected registration to the caller", async () => {
+    install({
+      registerTool: () => Promise.reject(new Error("already registered")),
+    });
+
+    const onError = vi.fn();
+    getDefaultWebMcpHost().registerTool(descriptor, onError);
+    await vi.waitFor(() => expect(onError).toHaveBeenCalledOnce());
+    expect(onError.mock.calls[0]![0]).toBeInstanceOf(Error);
+  });
+
+  it("aborts the signal even when the registration was rejected", async () => {
+    let options: { signal?: AbortSignal } | undefined;
+    install({
+      registerTool: (_def, registerOptions) => {
+        options = registerOptions;
+        return Promise.reject(new Error("already registered"));
+      },
+    });
+
+    const onError = vi.fn();
+    const dispose = getDefaultWebMcpHost().registerTool(descriptor, onError);
+    await vi.waitFor(() => expect(onError).toHaveBeenCalledOnce());
+
+    dispose();
+    expect(options?.signal?.aborted).toBe(true);
+  });
+
+  it("lets a synchronous registration failure propagate", () => {
+    install({
+      registerTool: () => {
+        throw new Error("already registered");
+      },
+    });
+
+    expect(() => getDefaultWebMcpHost().registerTool(descriptor)).toThrow(
+      "already registered",
+    );
+  });
+
+  it("survives a registration that returns a bare thenable", () => {
+    install({
+      registerTool: () =>
+        ({
+          then: (resolve: () => void) => resolve(),
+        }) as unknown as Promise<void>,
+    });
+
+    const dispose = getDefaultWebMcpHost().registerTool(descriptor);
+    expect(() => dispose()).not.toThrow();
+  });
+
+  it("survives a registration that returns nothing", () => {
+    const registerTool = vi.fn();
+    install({ registerTool });
+
+    const dispose = getDefaultWebMcpHost().registerTool(descriptor);
+    dispose();
+    expect(registerTool.mock.calls[0]![1].signal.aborted).toBe(true);
+  });
+});

package/src/unstable/webmcp/webmcp-host.ts

@@ -0,0 +1,83 @@
+export type WebMcpContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string };
+
+export type WebMcpCallToolResult = {
+  content: WebMcpContent[];
+  isError?: boolean;
+};
+
+export type WebMcpToolDescriptor = {
+  name: string;
+  description: string;
+  inputSchema: unknown;
+  execute: (
+    args: unknown,
+    context?: { signal?: AbortSignal },
+  ) => Promise<WebMcpCallToolResult>;
+};
+
+export type WebMcpModelContext = {
+  /**
+   * Aborting `options.signal` is what unregisters the tool. The explainer
+   * defines no other removal method, and a name-keyed one could not be used
+   * safely: a later registration may already hold the name.
+   */
+  registerTool(
+    tool: WebMcpToolDescriptor,
+    options?: { signal?: AbortSignal },
+  ): Promise<void> | void;
+};
+
+export type WebMcpHost = {
+  available: boolean;
+  registerTool(
+    def: WebMcpToolDescriptor,
+    onError?: (error: unknown) => void,
+  ): () => void;
+};
+
+type ModelContextHost = { modelContext?: WebMcpModelContext } | undefined;
+
+const isThenable = (value: unknown): value is Promise<unknown> =>
+  typeof (value as { then?: unknown } | null | undefined)?.then === "function";
+
+// The explainer puts modelContext on document; navigator is tolerated for
+// older drafts and extensions that still inject it there.
+const resolveModelContext = (): WebMcpModelContext | undefined => {
+  const context =
+    (globalThis.document as ModelContextHost)?.modelContext ??
+    (globalThis.navigator as ModelContextHost)?.modelContext;
+  if (!context) return undefined;
+  if (typeof context.registerTool === "function") return context;
+  console.warn(
+    "[assistant-ui] Ignoring a modelContext with no callable registerTool; WebMCP reports unsupported.",
+  );
+  return undefined;
+};
+
+const createHost = (context: WebMcpModelContext): WebMcpHost => ({
+  available: true,
+  registerTool: (def, onError) => {
+    const controller = new AbortController();
+    const handle = context.registerTool(def, { signal: controller.signal });
+    if (isThenable(handle)) {
+      handle.then(
+        () => {},
+        (error) => onError?.(error),
+      );
+    }
+    return () => controller.abort();
+  },
+});
+
+export const getDefaultWebMcpHost = (): WebMcpHost => {
+  const context = resolveModelContext();
+  if (!context) {
+    return {
+      available: false,
+      registerTool: () => () => {},
+    };
+  }
+  return createHost(context);
+};