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

package/src/unstable/webmcp/WebMcpRegistrationResource.test.ts

@@ -0,0 +1,150 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { effectScope } from "vue";
+import {
+  createTapRoot,
+  flushTapSync,
+  useResource,
+  useState,
+} from "@ulearning/ai-tap";
+import type { Tool } from "@ulearning/ai-stream";
+import {
+  WebMcpRegistrationResource,
+  type WebMcpRegistrationProps,
+} from "./WebMcpRegistrationResource";
+import type { WebMcpHost, WebMcpToolDescriptor } from "./webmcp-host";
+
+const roots = new Set<{ unmount(): void }>();
+afterEach(() => {
+  for (const root of roots) root.unmount();
+  roots.clear();
+  vi.restoreAllMocks();
+});
+const frontend = (label: string): Tool => ({
+  type: "frontend",
+  parameters: { type: "object", properties: {} },
+  execute: vi.fn(async () => label),
+});
+const fixture = (register?: WebMcpHost["registerTool"]) => {
+  const descriptors: WebMcpToolDescriptor[] = [];
+  const errors: ((error: unknown) => void)[] = [];
+  const disposers: ReturnType<typeof vi.fn>[] = [];
+  const host: WebMcpHost = {
+    available: true,
+    registerTool: vi.fn(
+      register ??
+        ((descriptor, onError) => {
+          descriptors.push(descriptor);
+          if (onError) errors.push(onError);
+          const dispose = vi.fn();
+          disposers.push(dispose);
+          return dispose;
+        }),
+    ),
+  };
+  let current = frontend("A");
+  const initial: WebMcpRegistrationProps = {
+    host,
+    name: "search",
+    signature: "first",
+    tool: current,
+    getCurrentTool: () => current,
+  };
+  const scope = effectScope();
+  roots.add({ unmount: () => scope.stop() });
+  const root = scope.run(() =>
+    flushTapSync(() =>
+      createTapRoot(() => {
+        const [props, setProps] = useState(initial);
+        const name = useResource(WebMcpRegistrationResource(props));
+        return { name, setProps };
+      }),
+    ),
+  )!;
+  roots.add(root);
+  return {
+    host,
+    root,
+    descriptors,
+    errors,
+    disposers,
+    replaceTool(tool: Tool) {
+      current = tool;
+    },
+    update(patch: Partial<WebMcpRegistrationProps>) {
+      flushTapSync(() =>
+        root.getValue().setProps((props) => ({ ...props, ...patch })),
+      );
+    },
+  };
+};
+
+it("keeps a single registration and executes the latest implementation supplied by its owner", async () => {
+  const input = fixture();
+  expect(input.root.getValue().name).toBe("search");
+  expect(input.host.registerTool).toHaveBeenCalledOnce();
+  expect(await input.descriptors[0]!.execute({})).toEqual({
+    content: [{ type: "text", text: "A" }],
+  });
+  const replacement = frontend("B");
+  input.replaceTool(replacement);
+  input.update({ tool: replacement });
+  expect(input.host.registerTool).toHaveBeenCalledOnce();
+  expect(input.disposers[0]).not.toHaveBeenCalled();
+  expect(await input.descriptors[0]!.execute({})).toEqual({
+    content: [{ type: "text", text: "B" }],
+  });
+});
+
+it("disposes and invalidates the old descriptor on signature replacement and final unmount", async () => {
+  const input = fixture();
+  input.update({ signature: "changed" });
+  expect(input.host.registerTool).toHaveBeenCalledTimes(2);
+  expect(input.disposers[0]).toHaveBeenCalledOnce();
+  expect(input.disposers[1]).not.toHaveBeenCalled();
+  expect(await input.descriptors[0]!.execute({})).toEqual({
+    isError: true,
+    content: [{ type: "text", text: 'Tool "search" is no longer registered' }],
+  });
+  input.root.unmount();
+  expect(input.disposers[1]).toHaveBeenCalledOnce();
+  expect((await input.descriptors[1]!.execute({})).isError).toBe(true);
+});
+
+it("ignores late failures from replaced registrations and refuses a current name only once", () => {
+  const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  const input = fixture();
+  input.update({ signature: "replacement" });
+  flushTapSync(() => input.errors[0]!(new Error("late")));
+  expect(warn).not.toHaveBeenCalled();
+  expect(input.root.getValue().name).toBe("search");
+  const denied = Object.assign(new Error("denied"), {
+    name: "NotAllowedError",
+  });
+  flushTapSync(() => input.errors[1]!(denied));
+  expect(input.root.getValue().name).toBeNull();
+  expect(warn).toHaveBeenCalledOnce();
+  expect(warn).toHaveBeenCalledWith(
+    expect.stringContaining("tools permission is disabled"),
+    denied,
+  );
+  input.update({ signature: "no retry while name remains" });
+  expect(input.host.registerTool).toHaveBeenCalledTimes(2);
+  expect(input.disposers[1]).toHaveBeenCalledOnce();
+});
+
+it("contains synchronous host refusal and does not retry during unchanged resource lifetime", () => {
+  const denied = new Error("name collision");
+  const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  const input = fixture(() => {
+    throw denied;
+  });
+  expect(input.root.getValue().name).toBeNull();
+  expect(input.host.registerTool).toHaveBeenCalledOnce();
+  expect(warn).toHaveBeenCalledWith(
+    expect.stringContaining("registerTool failed"),
+    denied,
+  );
+  input.update({ signature: "new signature" });
+  expect(input.host.registerTool).toHaveBeenCalledOnce();
+  expect(warn).toHaveBeenCalledOnce();
+});

package/src/unstable/webmcp/WebMcpRegistrationResource.ts

@@ -0,0 +1,92 @@
+import { resource, useEffect, useRef, useState } from "@ulearning/ai-tap";
+import type { Tool } from "@ulearning/ai-stream";
+import { toWebMcpTool } from "./convertTools";
+import type { WebMcpHost } from "./webmcp-host";
+
+export type WebMcpRegistrationProps = {
+  host: WebMcpHost;
+  name: string;
+  /** Re-registers when it changes; an execute-only edit reads through instead. */
+  signature: string;
+  tool: Tool<any, any>;
+  getCurrentTool: (name: string) => Tool<any, any> | undefined;
+};
+
+// The explainer specifies NotAllowedError for a page whose tools permission is
+// off, which a cross-origin iframe without allow="tools" reaches routinely. It
+// documents no rejection for a name already taken, so that stays a hedge.
+const notPermitted = (error: unknown) =>
+  (error as { name?: unknown } | null | undefined)?.name === "NotAllowedError";
+
+const notPermittedMessage = (name: string) =>
+  `[assistant-ui] WebMCP registration for tool "${name}" was not permitted; the page's tools permission is disabled.`;
+
+const useWebMcpRegistration = ({
+  host,
+  name,
+  signature,
+  tool,
+  getCurrentTool,
+}: WebMcpRegistrationProps): string | null => {
+  // A refused name is remembered for as long as the tool stays in the model
+  // context, so a permanent collision warns once rather than on every sync.
+  const [refused, setRefused] = useState(false);
+  const fallbackToolRef = useRef(tool);
+
+  useEffect(() => {
+    if (refused) return undefined;
+
+    const lifecycle = new AbortController();
+    let live = true;
+    let dispose: (() => void) | undefined;
+
+    const refuse = (message: string, error: unknown) => {
+      if (!live) return;
+      live = false;
+      setRefused(true);
+      console.warn(message, error);
+    };
+
+    try {
+      dispose = host.registerTool(
+        toWebMcpTool(
+          name,
+          () => getCurrentTool(name) ?? fallbackToolRef.current,
+          lifecycle.signal,
+        ),
+        (error) =>
+          refuse(
+            notPermitted(error)
+              ? notPermittedMessage(name)
+              : `[assistant-ui] WebMCP registration for tool "${name}" failed (name may already be registered).`,
+            error,
+          ),
+      );
+    } catch (error) {
+      refuse(
+        notPermitted(error)
+          ? notPermittedMessage(name)
+          : `[assistant-ui] Skipping WebMCP registration for tool "${name}": registerTool failed (name may already be registered).`,
+        error,
+      );
+      return undefined;
+    }
+
+    return () => {
+      live = false;
+      lifecycle.abort();
+      try {
+        dispose();
+      } catch (error) {
+        console.warn(
+          `[assistant-ui] Unregistering WebMCP tool "${name}" failed.`,
+          error,
+        );
+      }
+    };
+  }, [getCurrentTool, host, name, signature, refused]);
+
+  return refused ? null : name;
+};
+
+export const WebMcpRegistrationResource = resource(useWebMcpRegistration);

package/src/unstable/webmcp/__tests__/webmcp.fake.tsx

@@ -0,0 +1,177 @@
+import { defineComponent, h, type ComputedRef, type VNode } from "vue";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import { render } from "../../../tests/vue";
+import { expect, vi } from "vitest";
+import { AuiConfig, AuiProvider, useAui } from "@ulearning/ai-store";
+import { ModelContext } from "@ulearning/ai-core/store";
+import type { ModelContextProvider } from "@ulearning/ai-core";
+import type { Tool } from "@ulearning/ai-stream";
+import type {
+  WebMcpHost,
+  WebMcpModelContext,
+  WebMcpToolDescriptor,
+} from "../webmcp-host";
+import {
+  unstable_useWebMcpProvider,
+  type Unstable_WebMcpProviderOptions,
+  type Unstable_WebMcpProviderResult,
+} from "../useWebMcpProvider";
+
+export type FakeWebMcpHost = WebMcpHost & {
+  registry: Map<string, WebMcpToolDescriptor>;
+  registerCalls: string[];
+  unregisterCalls: string[];
+};
+
+export const createFakeWebMcpHost = (): FakeWebMcpHost => {
+  const registry = new Map<string, WebMcpToolDescriptor>();
+  const registerCalls: string[] = [];
+  const unregisterCalls: string[] = [];
+
+  return {
+    available: true,
+    registry,
+    registerCalls,
+    unregisterCalls,
+    registerTool: (def) => {
+      if (registry.has(def.name)) {
+        throw new Error(`Tool "${def.name}" is already registered`);
+      }
+      registry.set(def.name, def);
+      registerCalls.push(def.name);
+      let disposed = false;
+      return () => {
+        if (disposed) return;
+        disposed = true;
+        if (registry.get(def.name) === def) registry.delete(def.name);
+        unregisterCalls.push(def.name);
+      };
+    },
+  };
+};
+
+// Mirrors the spec's registerTool: the tool enters the map synchronously while
+// the promise resolves on a later task, aborting removes it and rejects, and a
+// name already in the map is refused.
+export const createAsyncModelContext = (): Map<
+  string,
+  WebMcpToolDescriptor
+> => {
+  const registry = new Map<string, WebMcpToolDescriptor>();
+  const context: WebMcpModelContext = {
+    registerTool: (tool, options) => {
+      if (registry.has(tool.name)) {
+        return Promise.reject(
+          new DOMException(
+            `Tool "${tool.name}" is already registered`,
+            "InvalidStateError",
+          ),
+        );
+      }
+      registry.set(tool.name, tool);
+      return new Promise<void>((resolve, reject) => {
+        options?.signal?.addEventListener("abort", () => {
+          registry.delete(tool.name);
+          reject(options.signal?.reason);
+        });
+        setTimeout(() => resolve(), 0);
+      });
+    },
+  };
+  (document as { modelContext?: WebMcpModelContext }).modelContext = context;
+  return registry;
+};
+
+export const frontendTool = (
+  overrides: Partial<Tool<any, any>> = {},
+): Tool<any, any> =>
+  ({
+    type: "frontend",
+    description: "search things",
+    parameters: { type: "object", properties: {} },
+    execute: async () => "found",
+    ...overrides,
+  }) as Tool<any, any>;
+
+export type FakeProvider = ModelContextProvider & {
+  setTools: (next: Record<string, Tool<any, any>>) => void;
+};
+
+export const createProvider = (
+  initialTools: Record<string, Tool<any, any>>,
+): FakeProvider => {
+  let tools = initialTools;
+  const listeners = new Set<() => void>();
+  return {
+    getModelContext: () => ({ tools }),
+    subscribe: (callback: () => void) => {
+      listeners.add(callback);
+      return () => {
+        listeners.delete(callback);
+      };
+    },
+    setTools: (next) => {
+      tools = next;
+      listeners.forEach((callback) => callback());
+    },
+  } as FakeProvider;
+};
+
+let latest: ComputedRef<Unstable_WebMcpProviderResult>;
+
+export const providerResult = (): Unstable_WebMcpProviderResult => latest.value;
+
+const Probe = defineComponent(
+  (props: { options: Unstable_WebMcpProviderOptions }) => {
+    latest = unstable_useWebMcpProvider(() => props.options);
+    return () => null;
+  },
+  { props: ["options"] },
+);
+const Registrar = defineComponent(
+  (props: { provider: ModelContextProvider }) => {
+    const aui = useAui();
+    useIsomorphicLayoutEffect(
+      () => aui.modelContext.register(props.provider),
+      () => [aui, props.provider],
+    );
+    return () => null;
+  },
+  { props: ["provider"] },
+);
+const Harness = defineComponent(
+  (props: {
+    provider: ModelContextProvider;
+    options: Unstable_WebMcpProviderOptions;
+  }) =>
+    () =>
+      h(
+        AuiProvider,
+        { config: AuiConfig({ modelContext: ModelContext() }) },
+        {
+          default: () => [
+            h(Registrar, { provider: props.provider }),
+            h(Probe, { options: props.options }),
+          ],
+        },
+      ),
+  { props: ["provider", "options"] },
+);
+export const mountProvider = (
+  provider: ModelContextProvider,
+  options: Unstable_WebMcpProviderOptions = {},
+  wrap: (children: VNode) => VNode = (children) => children,
+) => {
+  const view = render(wrap(h(Harness, { provider, options })));
+  return {
+    view,
+    rerender: (next: Unstable_WebMcpProviderOptions) =>
+      view.rerender(wrap(h(Harness, { provider, options: next }))),
+  };
+};
+
+export const waitForNames = (names: string[]) =>
+  vi.waitFor(() => expect(providerResult().registeredToolNames).toEqual(names));
+
+export const silenceWarnings = () =>
+  vi.spyOn(console, "warn").mockImplementation(() => {});