@assistant-ui/react 0.15.17 → 0.15.18

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

@@ -0,0 +1,393 @@
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { ToolResponse, type Tool } from "assistant-stream";
+import {
+  defaultWebMcpFilter,
+  toMcpContent,
+  toWebMcpTool,
+} from "./convertTools";
+
+const jsonSchema = {
+  type: "object",
+  properties: { city: { type: "string" } },
+  required: ["city"],
+} as const;
+
+const frontendTool = (
+  overrides: Partial<Tool<any, any>> = {},
+): Tool<any, any> =>
+  ({
+    type: "frontend",
+    description: "Get the weather for a city.",
+    parameters: jsonSchema,
+    execute: async ({ city }: { city: string }) => `Sunny in ${city}`,
+    ...overrides,
+  }) as Tool<any, any>;
+
+const descriptorFor = (
+  overrides: Partial<Tool<any, any>> = {},
+  lifecycleSignal?: AbortSignal,
+) => toWebMcpTool("t", () => frontendTool(overrides), lifecycleSignal);
+
+const text = (value: string) => ({ type: "text", text: value });
+
+describe("defaultWebMcpFilter", () => {
+  it.for([
+    ["exposes an enabled frontend tool", {}, true],
+    ["hides a backend tool", { type: "backend" }, false],
+    ["hides a frontend tool with no execute", { execute: undefined }, false],
+    ["hides a disabled frontend tool", { disabled: true }, false],
+    ["exposes a tool authored without a type", { type: undefined }, true],
+    [
+      "hides a type-less tool with no execute",
+      { type: undefined, execute: undefined },
+      false,
+    ],
+  ] as const)("%s", ([, overrides, expected]) => {
+    expect(defaultWebMcpFilter("t", frontendTool(overrides as any))).toBe(
+      expected,
+    );
+  });
+});
+
+describe("toWebMcpTool descriptor", () => {
+  it("projects name, description, and the input schema", () => {
+    const descriptor = toWebMcpTool("get_weather", () => frontendTool());
+    expect(descriptor.name).toBe("get_weather");
+    expect(descriptor.description).toBe("Get the weather for a city.");
+    expect(descriptor.inputSchema).toEqual(jsonSchema);
+
+    expect(
+      descriptorFor({ parameters: z.object({ city: z.string() }) }).inputSchema,
+    ).toMatchObject(jsonSchema);
+
+    const bare = descriptorFor({
+      description: undefined,
+      parameters: undefined,
+    });
+    expect(bare.description).toBe("");
+    expect(bare.inputSchema).toEqual({ type: "object", properties: {} });
+  });
+
+  it("throws at construction for a schema that cannot convert", () => {
+    const badSchema = {
+      "~standard": { version: 1, validate: () => ({ issues: undefined }) },
+    };
+    expect(() => descriptorFor({ parameters: badSchema as any })).toThrow();
+  });
+});
+
+describe("toWebMcpTool execute", () => {
+  it("passes the arguments through, defaulting missing arguments to {}", async () => {
+    const execute = vi.fn(async () => "Sunny in Paris");
+    const descriptor = descriptorFor({ execute, parameters: undefined });
+
+    const result = await descriptor.execute({ city: "Paris" });
+    expect(execute).toHaveBeenCalledWith(
+      { city: "Paris" },
+      expect.objectContaining({ toolCallId: expect.any(String) }),
+    );
+    expect(result).toEqual({ content: [text("Sunny in Paris")] });
+
+    await descriptor.execute(undefined);
+    expect(execute).toHaveBeenLastCalledWith({}, expect.anything());
+  });
+
+  it.for([
+    ["serializes a non-string result", { ok: true }, '{"ok":true}'],
+    [
+      "falls back to String() for an unserializable result",
+      Symbol("opaque"),
+      "Symbol(opaque)",
+    ],
+  ] as const)("%s", async ([, value, expected]) => {
+    const result = await descriptorFor({
+      execute: async () => value,
+    }).execute({});
+    expect(result).toEqual({ content: [text(expected)] });
+  });
+
+  it("reports a thrown value as an error result", async () => {
+    const throwing = (value: unknown) =>
+      descriptorFor({
+        execute: async () => {
+          throw value;
+        },
+      });
+    await expect(throwing(new Error("boom")).execute({})).resolves.toEqual({
+      isError: true,
+      content: [text("boom")],
+    });
+    await expect(throwing("raw string boom").execute({})).resolves.toEqual({
+      isError: true,
+      content: [text("raw string boom")],
+    });
+    await expect(throwing({ code: 500 }).execute({})).resolves.toEqual({
+      isError: true,
+      content: [text("[object Object]")],
+    });
+
+    const circular: Record<string, unknown> = { a: 1 };
+    circular["self"] = circular;
+    const unserializable = await descriptorFor({
+      execute: async () => circular,
+    }).execute({});
+    expect(unserializable.isError).toBe(true);
+  });
+
+  it("reports an error when a published tool has no client-side execute", async () => {
+    await expect(
+      descriptorFor({ execute: undefined }).execute({}),
+    ).resolves.toEqual({
+      isError: true,
+      content: [text('Tool "t" has no client-side implementation.')],
+    });
+  });
+
+  it("projects values JSON cannot serialize but that have a string form", async () => {
+    await expect(
+      descriptorFor({ execute: async () => 9007199254740993n }).execute({}),
+    ).resolves.toEqual({ content: [text("9007199254740993")] });
+    await expect(
+      descriptorFor({ execute: async () => Symbol("ticket") }).execute({}),
+    ).resolves.toEqual({ content: [text("Symbol(ticket)")] });
+  });
+
+  it("rejects human input requests", async () => {
+    const result = await descriptorFor({
+      execute: async (_args: unknown, context: any) => await context.human(),
+    }).execute({});
+    expect(result).toEqual({
+      isError: true,
+      content: [text("human input not supported in WebMCP context")],
+    });
+  });
+});
+
+describe("toWebMcpTool schema validation", () => {
+  const zodTool = (overrides: Partial<Tool<any, any>> = {}) =>
+    descriptorFor({
+      parameters: z.object({ city: z.string() }),
+      ...overrides,
+    });
+
+  it("runs execute unchanged when the arguments validate", async () => {
+    const execute = vi.fn(async () => "ok");
+    const result = await zodTool({ execute }).execute({ city: "Paris" });
+    expect(execute).toHaveBeenCalledWith({ city: "Paris" }, expect.anything());
+    expect(result).toEqual({ content: [text("ok")] });
+  });
+
+  it("returns a validation error when the arguments do not validate", async () => {
+    const execute = vi.fn(async () => "ok");
+    const result = await zodTool({ execute }).execute({ city: 42 });
+    expect(execute).not.toHaveBeenCalled();
+    expect(result.isError).toBe(true);
+    expect(result.content[0]).toMatchObject({
+      text: expect.stringContaining("Function parameter validation failed."),
+    });
+  });
+
+  it("hands invalid arguments to experimental_onSchemaValidationError", async () => {
+    const execute = vi.fn(async () => "ok");
+    const result = await zodTool({
+      execute,
+      experimental_onSchemaValidationError: async () => "recovered",
+    }).execute({ city: 42 });
+    expect(execute).not.toHaveBeenCalled();
+    expect(result).toEqual({ content: [text("recovered")] });
+  });
+
+  it("awaits a validator that returns a non-Promise thenable", async () => {
+    const execute = vi.fn(async () => "ok");
+    const schema = z.object({ city: z.string() });
+    (schema as any)["~standard"] = {
+      ...schema["~standard"],
+      validate: () => ({
+        then: (resolve: (value: { issues: unknown[] }) => void) => {
+          resolve({ issues: [{ message: "cross-realm" }] });
+        },
+      }),
+    };
+
+    const result = await descriptorFor({ execute, parameters: schema }).execute(
+      { city: 42 },
+    );
+    expect(execute).not.toHaveBeenCalled();
+    expect(result.isError).toBe(true);
+    expect(result.content[0]).toMatchObject({
+      text: expect.stringContaining("cross-realm"),
+    });
+  });
+
+  it("awaits an async Standard Schema validation", async () => {
+    const execute = vi.fn(async () => "ok");
+    const schema = z.object({ city: z.string() });
+    const sync = schema["~standard"].validate;
+    (schema as any)["~standard"] = {
+      ...schema["~standard"],
+      validate: async (value: unknown) => sync(value),
+    };
+
+    const result = await descriptorFor({ execute, parameters: schema }).execute(
+      { city: 42 },
+    );
+    expect(execute).not.toHaveBeenCalled();
+    expect(result.isError).toBe(true);
+  });
+});
+
+describe("toWebMcpTool cancellation", () => {
+  it("refuses to run once its lifecycle signal is aborted", async () => {
+    const execute = vi.fn(async () => "never");
+    const controller = new AbortController();
+    controller.abort();
+    const result = await descriptorFor({ execute }, controller.signal).execute(
+      {},
+    );
+    expect(execute).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      isError: true,
+      content: [text('Tool "t" is no longer registered')],
+    });
+  });
+
+  it("refuses to run when the caller signal is already aborted", async () => {
+    const execute = vi.fn(async () => "never");
+    const controller = new AbortController();
+    controller.abort();
+    const result = await descriptorFor({ execute }).execute(
+      {},
+      { signal: controller.signal },
+    );
+    expect(execute).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      isError: true,
+      content: [text("Tool execution was cancelled.")],
+    });
+  });
+
+  it("merges the caller signal with the lifecycle signal", async () => {
+    const lifecycle = new AbortController();
+    const caller = new AbortController();
+    const descriptor = descriptorFor(
+      {
+        execute: async (_args: unknown, context: any) =>
+          new Promise((_resolve, reject) => {
+            context.abortSignal.addEventListener("abort", () =>
+              reject(new Error("aborted")),
+            );
+          }),
+      },
+      lifecycle.signal,
+    );
+
+    const pending = descriptor.execute({}, { signal: caller.signal });
+    lifecycle.abort();
+    await expect(pending).resolves.toEqual({
+      isError: true,
+      content: [text("aborted")],
+    });
+  });
+
+  it("returns an error result when the caller signal cannot be merged", async () => {
+    const execute = vi.fn(async () => "never");
+    const foreignSignal = {
+      aborted: false,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+    } as unknown as AbortSignal;
+
+    const result = await descriptorFor(
+      { execute },
+      new AbortController().signal,
+    ).execute({}, { signal: foreignSignal });
+    expect(result.isError).toBe(true);
+    expect(execute).not.toHaveBeenCalled();
+  });
+});
+
+describe("toMcpContent", () => {
+  const options = { tool: frontendTool(), toolCallId: "1", args: {} };
+
+  it.for([
+    ["text parts", [{ type: "text", text: "hello" }], [text("hello")]],
+    [
+      "image file parts",
+      [{ type: "file", data: "AAA", mediaType: "image/png" }],
+      [{ type: "image", data: "AAA", mimeType: "image/png" }],
+    ],
+    [
+      "image file parts with no data",
+      [{ type: "file", mediaType: "image/png" }],
+      [{ type: "image", data: "", mimeType: "image/png" }],
+    ],
+    [
+      "non-image file parts",
+      [{ type: "file", data: "raw", mediaType: "text/plain" }],
+      [text("raw")],
+    ],
+    [
+      "unknown parts",
+      [{ type: "reasoning", text: "why" }],
+      [text('{"type":"reasoning","text":"why"}')],
+    ],
+  ] as const)("maps %s", async ([, modelContent, expected]) => {
+    const response = await toMcpContent(
+      new ToolResponse({ result: "r", modelContent: modelContent as any }),
+      options,
+    );
+    expect(response).toEqual({ content: expected });
+  });
+
+  it("marks an error response, with or without an explicit modelContent", async () => {
+    await expect(
+      toMcpContent(
+        new ToolResponse({
+          result: "r",
+          isError: true,
+          modelContent: [{ type: "text", text: "failed" }],
+        }),
+        options,
+      ),
+    ).resolves.toEqual({ isError: true, content: [text("failed")] });
+
+    await expect(
+      toMcpContent(
+        new ToolResponse({ result: "went wrong", isError: true }),
+        options,
+      ),
+    ).resolves.toEqual({ isError: true, content: [text("went wrong")] });
+  });
+
+  it("projects a successful result through toModelOutput", async () => {
+    const toModelOutput = vi.fn(async () => [
+      { type: "text", text: "projected" },
+    ]);
+    const response = await toMcpContent("raw", {
+      ...options,
+      tool: frontendTool({ toModelOutput } as any),
+    });
+    expect(toModelOutput).toHaveBeenCalledWith({
+      toolCallId: "1",
+      input: {},
+      output: "raw",
+    });
+    expect(response).toEqual({ content: [text("projected")] });
+  });
+
+  it("falls back to the default projection when toModelOutput throws", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const response = await toMcpContent("raw", {
+      ...options,
+      tool: frontendTool({
+        toModelOutput: () => {
+          throw new Error("bad projection");
+        },
+      } as any),
+    });
+    expect(response).toEqual({ content: [text("raw")] });
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});

package/src/unstable/webmcp/convertTools.ts

@@ -0,0 +1,180 @@
+import {
+  ToolResponse,
+  toJSONSchema,
+  type Tool,
+  type ToolModelContentPart,
+} from "assistant-stream";
+import { generateId } from "@assistant-ui/core/internal";
+import type {
+  WebMcpCallToolResult,
+  WebMcpContent,
+  WebMcpToolDescriptor,
+} from "./webmcp-host";
+
+/**
+ * The predicate the WebMCP provider uses when no `filter` is passed: an enabled
+ * frontend tool with a client-side `execute`. A tool authored without a `type`
+ * is included, because `execute` is what distinguishes the deprecated
+ * type-less form from a backend or human tool. A `filter` replaces this, so
+ * pass it through to narrow the default set rather than widen it.
+ */
+export const defaultWebMcpFilter = (
+  _name: string,
+  tool: Tool<any, any>,
+): boolean =>
+  (tool.type === "frontend" || tool.type === undefined) &&
+  !!tool.execute &&
+  !tool.disabled;
+
+export const toWebMcpInputSchema = (tool: Tool<any, any>): unknown =>
+  tool.parameters
+    ? toJSONSchema(tool.parameters)
+    : { type: "object", properties: {} };
+
+const textContent = (text: string): WebMcpContent => ({ type: "text", text });
+
+const errorResult = (message: string): WebMcpCallToolResult => ({
+  isError: true,
+  content: [textContent(message)],
+});
+
+// bigint throws in JSON.stringify and symbol serializes to undefined, but both
+// have a faithful string form. A value that cannot be serialized at all still
+// throws through to the error result.
+const toText = (value: unknown): string => {
+  if (typeof value === "string") return value;
+  if (typeof value === "bigint" || typeof value === "symbol") {
+    return value.toString();
+  }
+  return JSON.stringify(value) ?? String(value);
+};
+
+const primitiveContent = (value: unknown): WebMcpContent[] => [
+  textContent(toText(value)),
+];
+
+const mapModelContentPart = (part: ToolModelContentPart): WebMcpContent => {
+  if (part.type === "text") {
+    return textContent(part.text ?? "");
+  }
+  if (part.type === "file") {
+    if (
+      typeof part.mediaType === "string" &&
+      part.mediaType.startsWith("image/")
+    ) {
+      return { type: "image", data: part.data ?? "", mimeType: part.mediaType };
+    }
+    return textContent(part.data ?? "");
+  }
+  return textContent(toText(part));
+};
+
+export const toMcpContent = async (
+  result: unknown,
+  options: {
+    tool: Tool<any, any>;
+    toolCallId: string;
+    args: Record<string, unknown>;
+  },
+): Promise<WebMcpCallToolResult> => {
+  const response = ToolResponse.toResponse(result);
+  if (response.modelContent) {
+    const content = response.modelContent.map(mapModelContentPart);
+    return response.isError ? { isError: true, content } : { content };
+  }
+  if (!response.isError && options.tool.toModelOutput) {
+    try {
+      const parts = await options.tool.toModelOutput({
+        toolCallId: options.toolCallId,
+        input: options.args,
+        output: response.result,
+      });
+      return { content: parts.map(mapModelContentPart) };
+    } catch (e) {
+      console.warn(
+        "[assistant-ui] toModelOutput threw; falling back to default projection.",
+        e,
+      );
+    }
+  }
+  const content = primitiveContent(response.result);
+  return response.isError ? { isError: true, content } : { content };
+};
+
+type StandardSchemaLike = {
+  "~standard": {
+    version: number;
+    validate: (
+      value: unknown,
+    ) =>
+      | { issues?: readonly unknown[] | undefined }
+      | Promise<{ issues?: readonly unknown[] | undefined }>;
+  };
+};
+
+const isStandardSchema = (schema: unknown): schema is StandardSchemaLike =>
+  typeof schema === "object" &&
+  schema !== null &&
+  "~standard" in schema &&
+  (schema as StandardSchemaLike)["~standard"].version === 1;
+
+export const toWebMcpTool = (
+  name: string,
+  getTool: () => Tool<any, any>,
+  lifecycleSignal?: AbortSignal,
+): WebMcpToolDescriptor => ({
+  name,
+  description: getTool().description ?? "",
+  inputSchema: toWebMcpInputSchema(getTool()),
+  execute: async (rawArgs, context) => {
+    if (lifecycleSignal?.aborted) {
+      return errorResult(`Tool "${name}" is no longer registered`);
+    }
+    const tool = getTool();
+    const args = (rawArgs ?? {}) as Record<string, unknown>;
+    const toolCallId = generateId();
+    try {
+      const callerSignal = context?.signal;
+      const abortSignal = !callerSignal
+        ? lifecycleSignal
+        : !lifecycleSignal
+          ? callerSignal
+          : AbortSignal.any([callerSignal, lifecycleSignal]);
+      let executeFn = tool.execute;
+      if (isStandardSchema(tool.parameters)) {
+        let validation = tool.parameters["~standard"].validate(args);
+        validation = await validation;
+        if (validation.issues) {
+          const issues = validation.issues;
+          executeFn =
+            tool.experimental_onSchemaValidationError ??
+            (() => {
+              throw new Error(
+                `Function parameter validation failed. ${JSON.stringify(issues)}`,
+              );
+            });
+        }
+      }
+
+      if (abortSignal?.aborted) {
+        return errorResult("Tool execution was cancelled.");
+      }
+
+      if (!executeFn) {
+        return errorResult(`Tool "${name}" has no client-side implementation.`);
+      }
+
+      const result = await executeFn(args, {
+        toolCallId,
+        abortSignal: abortSignal ?? new AbortController().signal,
+        human: () =>
+          Promise.reject(
+            new Error("human input not supported in WebMCP context"),
+          ),
+      });
+      return await toMcpContent(result, { tool, toolCallId, args });
+    } catch (e) {
+      return errorResult(e instanceof Error ? e.message : String(e));
+    }
+  },
+});