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

package/src/mcp-apps/csp.ts

@@ -0,0 +1,124 @@
+import type { McpAppResourceCSP } from "./types";
+
+const isAllowedOrigin = (value: string, allowWebSocket: boolean): boolean => {
+  const scheme = allowWebSocket ? /^(?:https?|wss?):\/\//i : /^https?:\/\//i;
+  if (!scheme.test(value) || /[\s;'"`,]/.test(value)) {
+    return false;
+  }
+
+  try {
+    const url = new URL(value.replace("://*.", "://wildcard."));
+    return (
+      url.username === "" &&
+      url.password === "" &&
+      url.pathname === "/" &&
+      url.search === "" &&
+      url.hash === ""
+    );
+  } catch {
+    return false;
+  }
+};
+
+const getAllowedOrigins = (
+  values: unknown,
+  allowWebSocket = false,
+): string[] =>
+  Array.isArray(values)
+    ? [
+        ...new Set(
+          values.filter(
+            (value): value is string =>
+              typeof value === "string" &&
+              isAllowedOrigin(value, allowWebSocket),
+          ),
+        ),
+      ]
+    : [];
+
+const directive = (name: string, values: readonly string[]) =>
+  `${name} ${values.join(" ")}`;
+
+export const buildMcpAppCsp = (csp?: McpAppResourceCSP): string => {
+  const connectDomains = getAllowedOrigins(csp?.connectDomains, true);
+  const resourceDomains = getAllowedOrigins(csp?.resourceDomains);
+  const frameDomains = getAllowedOrigins(csp?.frameDomains);
+  const baseUriDomains = getAllowedOrigins(csp?.baseUriDomains);
+
+  return [
+    "default-src 'none'",
+    directive("script-src", ["'self'", "'unsafe-inline'", ...resourceDomains]),
+    directive("style-src", ["'self'", "'unsafe-inline'", ...resourceDomains]),
+    directive(
+      "connect-src",
+      connectDomains.length > 0 ? ["'self'", ...connectDomains] : ["'none'"],
+    ),
+    directive("img-src", ["'self'", "data:", ...resourceDomains]),
+    directive("font-src", ["'self'", ...resourceDomains]),
+    directive("media-src", ["'self'", "data:", ...resourceDomains]),
+    directive("frame-src", frameDomains.length > 0 ? frameDomains : ["'none'"]),
+    directive(
+      "base-uri",
+      baseUriDomains.length > 0 ? baseUriDomains : ["'self'"],
+    ),
+    "object-src 'none'",
+    "form-action 'none'",
+  ].join("; ");
+};
+
+const findDoctypeEnd = (html: string): number => {
+  let offset = 0;
+
+  while (offset < html.length) {
+    const whitespace = html.slice(offset).match(/^[\t\n\f\r ]+/)?.[0];
+    if (whitespace) {
+      offset += whitespace.length;
+      continue;
+    }
+    if (html.startsWith("<!--", offset)) {
+      if (html.startsWith("<!-->", offset)) {
+        offset += 5;
+        continue;
+      }
+      if (html.startsWith("<!--->", offset)) {
+        offset += 6;
+        continue;
+      }
+      const commentEnd = html.indexOf("-->", offset + 4);
+      const bangCommentEnd = html.indexOf("--!>", offset + 4);
+      if (commentEnd === -1 && bangCommentEnd === -1) return 0;
+      offset =
+        bangCommentEnd !== -1 &&
+        (commentEnd === -1 || bangCommentEnd < commentEnd)
+          ? bangCommentEnd + 4
+          : commentEnd + 3;
+      continue;
+    }
+    if (html.slice(offset, offset + 9).toLowerCase() === "<!doctype") {
+      break;
+    }
+    if (html.startsWith("<?", offset) || html.startsWith("<!", offset)) {
+      const bogusCommentEnd = html.indexOf(">", offset + 2);
+      if (bogusCommentEnd === -1) return 0;
+      offset = bogusCommentEnd + 1;
+      continue;
+    }
+    break;
+  }
+
+  if (html.slice(offset, offset + 9).toLowerCase() !== "<!doctype") {
+    return offset;
+  }
+  const end = html.indexOf(">", offset + 9);
+  return end === -1 ? 0 : end + 1;
+};
+
+export const applyMcpAppCsp = (
+  html: string,
+  csp?: McpAppResourceCSP,
+): string => {
+  const normalizedHtml = html.charCodeAt(0) === 0xfeff ? html.slice(1) : html;
+  const meta = `<meta http-equiv="Content-Security-Policy" content="${buildMcpAppCsp(csp)}">`;
+  const insertionPoint = findDoctypeEnd(normalizedHtml);
+  return `${normalizedHtml.slice(0, insertionPoint)}${meta}${normalizedHtml.slice(insertionPoint)}`;
+};

package/src/mcp-apps/index.ts

@@ -0,0 +1,23 @@
+export {
+  McpAppRenderer,
+  type McpAppPartOptions,
+  type McpAppRendererOptions,
+} from "./McpAppRenderer";
+export { McpAppsRemoteHost } from "./McpAppsRemoteHost";
+export { getMcpAppFromToolPart } from "./utils";
+export type {
+  McpAppMetadata,
+  McpAppResource,
+  McpAppResourceMeta,
+  McpAppResourceCSP,
+  McpAppSandboxConfig,
+  McpAppHostInfo,
+  McpAppHostContext,
+  McpAppDisplayMode,
+  McpAppsHost,
+  McpAppsRemoteHostOptions,
+  McpAppToolCallParams,
+  McpAppInitializeParams,
+  McpAppBridgeHandlers,
+  ToolCallMessagePartMcpMetadata,
+} from "./types";

package/src/mcp-apps/types.ts

@@ -0,0 +1,176 @@
+import type {
+  McpAppMetadata,
+  ToolCallMessagePartMcpMetadata,
+} from "@ulearning/ai-core";
+import type { SandboxHostConfig } from "../sandbox-host/SandboxHost";
+
+export type { McpAppMetadata, ToolCallMessagePartMcpMetadata };
+
+export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app" as const;
+
+export const MCP_APP_PROTOCOL_VERSION = "0.1" as const;
+
+export type McpAppResourceCSP = {
+  connectDomains?: string[];
+  resourceDomains?: string[];
+  frameDomains?: string[];
+  baseUriDomains?: string[];
+  [k: string]: unknown;
+};
+
+export type McpAppResourceMeta = {
+  prefersBorder?: boolean;
+  csp?: McpAppResourceCSP;
+  permissions?: Record<string, unknown>;
+  [k: string]: unknown;
+};
+
+export type McpAppResource = {
+  uri: string;
+  mimeType: typeof MCP_APP_MIME_TYPE;
+  html: string;
+  meta?: McpAppResourceMeta;
+};
+
+export type McpAppDisplayMode = "inline" | "fullscreen" | "pip";
+
+export type McpAppHostContext = {
+  theme?: "light" | "dark";
+  displayMode?: McpAppDisplayMode;
+  availableDisplayModes?: McpAppDisplayMode[];
+  [k: string]: unknown;
+};
+
+export type McpAppHostInfo = {
+  name: string;
+  version: string;
+};
+
+/**
+ * What `McpAppRenderer` needs from its host — the data-plane operations
+ * the widget can request. Provided by a host resource like
+ * `McpAppsRemoteHost`.
+ */
+export type McpAppsHost = {
+  loadResource: (params: {
+    uri: string;
+    serverId?: string;
+  }) => Promise<McpAppResource>;
+  callTool: (
+    params: McpAppToolCallParams & { serverId?: string },
+  ) => Promise<unknown>;
+  readResource: (params: {
+    uri: string;
+    serverId?: string;
+  }) => Promise<unknown>;
+  listResources: (params?: unknown) => Promise<unknown>;
+};
+
+/**
+ * Options for `McpAppsRemoteHost`. The host POSTs `{ method, params }` to
+ * `url` and expects JSON responses. Params may carry `serverId` for host-side routing. Method names sent:
+ * - `mcp-apps/read-resource` (`{ uri, serverId? }`) → `McpAppResource`
+ * - `tools/call` (`{ name, arguments?, serverId? }`) → tool result
+ * - `resources/read` (`{ uri, serverId? }`) → resource read result
+ * - `resources/list` (`{ serverId?, ...params }?`) → list result
+ */
+export type McpAppsRemoteHostOptions = {
+  url: string;
+  fetch?: typeof fetch;
+  headers?:
+    | Record<string, string>
+    | (() => Record<string, string> | Promise<Record<string, string>>);
+};
+
+export type McpAppToolCallParams = {
+  name: string;
+  arguments?: Record<string, unknown>;
+};
+
+/**
+ * The params of the app's `ui/initialize` request, as `onInitialized`
+ * receives them. A field that fails validation is omitted, and
+ * `availableDisplayModes` keeps only the modes the bridge recognizes.
+ */
+export type McpAppInitializeParams = {
+  appInfo?: { name: string; version: string; [k: string]: unknown };
+  appCapabilities?: {
+    availableDisplayModes?: McpAppDisplayMode[];
+    [k: string]: unknown;
+  };
+  protocolVersion?: string;
+};
+
+export type McpAppBridgeHandlers = {
+  allowedTools?: readonly string[];
+  callTool?: (params: McpAppToolCallParams) => Promise<unknown> | unknown;
+  readResource?: (params: { uri: string }) => Promise<unknown> | unknown;
+  listResources?: (params?: unknown) => Promise<unknown> | unknown;
+  openLink?: (params: { url: string }) => Promise<unknown> | unknown;
+  sendMessage?: (params: unknown) => Promise<unknown> | unknown;
+  updateModelContext?: (params: unknown) => Promise<unknown> | unknown;
+  requestDisplayMode?: (params: {
+    mode: McpAppDisplayMode;
+  }) => Promise<{ mode: McpAppDisplayMode }> | { mode: McpAppDisplayMode };
+  onSizeChange?: (params: { width?: number; height?: number }) => void;
+  onInitialized?: (params: McpAppInitializeParams) => void;
+  onRequestTeardown?: (params: unknown) => void;
+  onLog?: (params: unknown) => void;
+  onError?: (error: Error) => void;
+};
+
+export type McpAppSandboxConfig = SandboxHostConfig;
+
+export type McpAppFrameProps = {
+  app: McpAppMetadata;
+  resource: McpAppResource;
+  input?: unknown;
+  output?: unknown;
+  sandbox?: McpAppSandboxConfig | undefined;
+  handlers?: McpAppBridgeHandlers | undefined;
+  hostInfo?: McpAppHostInfo | undefined;
+  hostContext?: McpAppHostContext | undefined;
+  /**
+   * Upper bound (in pixels) for the auto-resize height driven by the widget's
+   * `notifications/size_changed`. Defaults to 800.
+   */
+  maxHeight?: number | undefined;
+};
+
+export type McpAppJsonRpcRequest = {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: unknown;
+};
+
+export type McpAppJsonRpcNotification = {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+};
+
+export type McpAppJsonRpcError = {
+  code: number;
+  message: string;
+  data?: unknown;
+};
+
+export type McpAppJsonRpcResponse =
+  | {
+      jsonrpc: "2.0";
+      id: string | number;
+      result: unknown;
+      error?: never;
+    }
+  | {
+      jsonrpc: "2.0";
+      id: string | number;
+      result?: never;
+      error: McpAppJsonRpcError;
+    };
+
+export type McpAppJsonRpcMessage =
+  | McpAppJsonRpcRequest
+  | McpAppJsonRpcNotification
+  | McpAppJsonRpcResponse;

package/src/mcp-apps/utils.ts

@@ -0,0 +1,23 @@
+import {
+  isMcpAppUri,
+  type McpAppMetadata,
+  type ToolCallMessagePart,
+} from "@ulearning/ai-core";
+
+type ToolPartLike = Pick<ToolCallMessagePart, "mcp">;
+
+/**
+ * Returns MCP app metadata for a tool-call part that points at a `ui://`
+ * resource.
+ *
+ * Returns `undefined` when the part has no MCP app metadata or the metadata
+ * does not reference an assistant-ui MCP app resource.
+ */
+export function getMcpAppFromToolPart(
+  part: ToolPartLike,
+): McpAppMetadata | undefined {
+  const app = part.mcp?.app;
+  if (!app) return undefined;
+  if (!isMcpAppUri(app.resourceUri)) return undefined;
+  return app;
+}

package/src/model-context/frame/SPEC_AssistantFrame.md

@@ -0,0 +1,105 @@
+## Assistant Frames
+
+Assistant frames allow an iframe to provide model context (tools, instructions) to a parent window's assistant.
+
+### Scope
+
+Supported features are:
+
+- ModelContextProvider API
+- support for tools (defining tool name, description, parameters, execute)
+- support for instructions (system instructions)
+
+Out of scope for now:
+
+- model configuration (temperature, etc.)
+- ToolCallReader API (incremental reading support)
+
+### API design
+
+[SPEC_ModelContextRegistry](../registry/SPEC_ModelContextRegistry.md)
+
+### Inside the iframe (provides context)
+
+```typescript
+// Add model context providers
+const registry = new ModelContextRegistry();
+AssistantFrameProvider.addModelContextProvider(registry);
+
+// Add tools/instructions to registry
+registry.addTool({
+  toolName: "search",
+  description: "Search the web",
+  parameters: z.object({ query: z.string() }),
+  execute: async (args) => {
+    // Tool implementation runs in iframe
+    return { results: ["..."] };
+  },
+});
+```
+
+### In the parent window (consumes context)
+
+```typescript
+// The parent window hosts the assistant that needs the context
+const frameHost = new AssistantFrameHost(iframeWindow);
+
+// Register with assistant runtime
+const aui = useAui();
+aui.modelContext().register(frameHost);
+
+// The assistant now has access to tools from the iframe
+```
+
+### Communication Channel Design
+
+The communication between `AssistantFrameProvider` (iframe) and `AssistantFrameHost` (parent window) uses the `window.postMessage` API with a structured protocol. The iframe provides model context to the parent window's assistant.
+
+#### ModelContextProvider API
+
+AssistantFrameHost implements the ModelContextProvider API. It immediately subscribes to the iframe for updates. This is necessary because ModelContextProvider.getModelContext() is synchronous.
+
+#### Message Channel
+
+All messages are wrapped with a channel identifier to avoid conflicts with other postMessage usage:
+
+```typescript
+{
+  channel: "assistant-ui-frame",
+  message: FrameMessage
+}
+```
+
+#### Message Types
+
+1. **Context Discovery**
+   - `model-context-request`: Parent (Host) requests current context from iframe (Provider)
+   - `model-context-update`: Iframe pushes context changes to parent
+2. **Tool Execution**
+   - `tool-call`: Parent requests tool execution in iframe (where tools are defined)
+   - `tool-result`: Iframe returns execution result or error to parent
+   - `provider-disposed`: Iframe tells the parent it was disposed, so the parent rejects tool calls the iframe will not answer
+
+#### Serialization
+
+- **Tools**: Zod schemas are converted to JSON Schema format using `z.toJSONSchema()`
+- **Parameters**: Tool parameters are serialized as JSON
+- **System messages**: Passed as strings
+- **Unsupported features**: Model config, call settings, and priority are not transmitted
+
+#### Security Considerations
+
+1. **Origin Validation**: Both sides default to the current page's origin and can specify an exact `targetOrigin` for cross-origin frames; providers share a fail-closed origin policy
+2. **Window Reference**: Host (parent) only accepts messages from the specific iframe window it's connected to
+3. **Message Channel**: Using a unique channel identifier prevents cross-talk with other postMessage users
+
+#### Connection Lifecycle
+
+1. **Initialization**: Parent (Host) sends `model-context-request` to iframe on creation
+2. **Updates**: Iframe (Provider) notifies parent whenever any registered ModelContextProvider changes
+
+#### Error Handling
+
+- Tool execution errors are serialized and sent back as error messages
+- Connection failures (timeout, no response) are silently handled - the Host continues to work as an empty ModelContextProvider
+- If the iframe doesn't register any providers, the AssistantFrameHost acts as a no-op empty ModelContextProvider returning `{}` from `getModelContext()`

package/src/model-context/frame/useAssistantFrameHost.detach.test.tsx

@@ -0,0 +1,155 @@
+// @vitest-environment jsdom
+
+import { shallowRef } from "vue";
+import { renderHook } from "../../tests/vue";
+import { AssistantFrameHost, ModelContextRegistry } from "@ulearning/ai-core";
+import { expect, it, vi } from "vitest";
+import { useAssistantFrameHost } from "./useAssistantFrameHost";
+
+const attachFrame = () => {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  vi.spyOn(iframe.contentWindow!, "postMessage").mockImplementation(() => {});
+  return iframe;
+};
+
+const publishTool = (iframe: HTMLIFrameElement, name: string) => {
+  window.dispatchEvent(
+    new MessageEvent("message", {
+      source: iframe.contentWindow,
+      origin: window.location.origin,
+      data: {
+        channel: "assistant-ui-frame",
+        message: {
+          type: "model-context-update",
+          context: {
+            tools: {
+              [name]: { parameters: { type: "object", properties: {} } },
+            },
+          },
+        },
+      },
+    }),
+  );
+};
+
+it("withdraws a detached frame's tools and calls, then serves an attached frame", async () => {
+  const registry = new ModelContextRegistry();
+  const firstFrame = attachFrame();
+  const iframeRef = shallowRef(firstFrame);
+  const register = (host: Parameters<typeof registry.addProvider>[0]) =>
+    registry.addProvider(host).remove;
+  const { unmount } = renderHook(() =>
+    useAssistantFrameHost({ iframeRef, register }),
+  );
+
+  try {
+    publishTool(firstFrame, "search");
+    const search = registry.getModelContext().tools?.search;
+    expect(search).toBeDefined();
+    const pending = search!.execute!(
+      {},
+      {
+        toolCallId: "test-call",
+        abortSignal: new AbortController().signal,
+        human: async () => {
+          throw new Error("Unexpected human input");
+        },
+      },
+    );
+    const outcome = pending.then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+
+    firstFrame.remove();
+    await vi.waitFor(() => {
+      expect(registry.getModelContext().tools).toBeUndefined();
+    });
+    expect(await outcome).toMatchObject({
+      message: "AssistantFrameHost has been disposed",
+    });
+
+    const secondFrame = attachFrame();
+    iframeRef.value = secondFrame;
+    await vi.waitFor(() => {
+      publishTool(secondFrame, "replacement");
+      expect(registry.getModelContext().tools?.replacement).toBeDefined();
+    });
+    secondFrame.remove();
+  } finally {
+    unmount();
+    firstFrame.remove();
+  }
+});
+
+it("serves a replacement frame before reporting a disposal failure", () => {
+  const disposalError = new Error("tool cancellation failed");
+  const dispose = vi
+    .spyOn(AssistantFrameHost.prototype, "dispose")
+    .mockImplementationOnce(() => {
+      throw disposalError;
+    });
+  const mutationCallbacks: MutationCallback[] = [];
+  vi.stubGlobal(
+    "MutationObserver",
+    class {
+      constructor(callback: MutationCallback) {
+        mutationCallbacks.push(callback);
+      }
+      observe() {}
+      disconnect() {}
+    },
+  );
+
+  const registry = new ModelContextRegistry();
+  const firstFrame = attachFrame();
+  const secondFrame = attachFrame();
+  const iframeRef = shallowRef(firstFrame);
+  const register = (host: Parameters<typeof registry.addProvider>[0]) =>
+    registry.addProvider(host).remove;
+  const { unmount } = renderHook(() =>
+    useAssistantFrameHost({ iframeRef, register }),
+  );
+
+  try {
+    publishTool(firstFrame, "search");
+    expect(registry.getModelContext().tools?.search).toBeDefined();
+
+    iframeRef.value = secondFrame;
+    expect(() => mutationCallbacks[0]!([], {} as MutationObserver)).toThrow(
+      disposalError,
+    );
+
+    expect(registry.getModelContext().tools?.search).toBeUndefined();
+    publishTool(secondFrame, "replacement");
+    expect(registry.getModelContext().tools?.replacement).toBeDefined();
+  } finally {
+    unmount();
+    firstFrame.remove();
+    secondFrame.remove();
+    dispose.mockRestore();
+    vi.unstubAllGlobals();
+  }
+});
+
+it("disposes a host whose registration throws", () => {
+  const dispose = vi.spyOn(AssistantFrameHost.prototype, "dispose");
+  const iframe = attachFrame();
+  const register = vi.fn((): (() => void) => {
+    throw new Error("register failed");
+  });
+
+  try {
+    expect(() =>
+      renderHook(() =>
+        useAssistantFrameHost({ iframeRef: shallowRef(iframe), register }),
+      ),
+    ).toThrow("register failed");
+    expect(register).toHaveBeenCalledOnce();
+    expect(dispose).toHaveBeenCalledOnce();
+  } finally {
+    dispose.mockRestore();
+    iframe.remove();
+  }
+});