@assistant-ui/react 0.10.44 → 0.10.45

package/src/model-context/frame/AssistantFrameHost.ts

@@ -0,0 +1,218 @@
+import {
+  ModelContextProvider,
+  ModelContext,
+} from "../../model-context/ModelContextTypes";
+import { Unsubscribe } from "../../types/Unsubscribe";
+import { Tool } from "assistant-stream";
+import {
+  FrameMessage,
+  FRAME_MESSAGE_CHANNEL,
+  SerializedModelContext,
+  SerializedTool,
+} from "./AssistantFrameTypes";
+
+/**
+ * Deserializes tools from JSON Schema format back to Tool objects
+ */
+const deserializeTool = (serializedTool: SerializedTool): Tool<any, any> =>
+  ({
+    parameters: serializedTool.parameters,
+    ...(serializedTool.description && {
+      description: serializedTool.description,
+    }),
+    ...(serializedTool.disabled !== undefined && {
+      disabled: serializedTool.disabled,
+    }),
+    ...(serializedTool.type && { type: serializedTool.type }),
+  }) as Tool<any, any>;
+
+/**
+ * Deserializes a ModelContext from transmission format
+ */
+const deserializeModelContext = (
+  serialized: SerializedModelContext,
+): ModelContext => ({
+  ...(serialized.system !== undefined && { system: serialized.system }),
+  ...(serialized.tools && {
+    tools: Object.fromEntries(
+      Object.entries(serialized.tools).map(([name, tool]) => [
+        name,
+        deserializeTool(tool),
+      ]),
+    ),
+  }),
+});
+
+/**
+ * AssistantFrameHost - Runs in the parent window and acts as a ModelContextProvider
+ * that receives context from an iframe's AssistantFrameProvider.
+ *
+ * Usage example:
+ * ```typescript
+ * // In parent window
+ * const frameHost = new AssistantFrameHost(iframeWindow);
+ *
+ * // Register with assistant runtime
+ * const runtime = useAssistantRuntime();
+ * runtime.registerModelContextProvider(frameHost);
+ *
+ * // The assistant now has access to tools from the iframe
+ * ```
+ */
+export class AssistantFrameHost implements ModelContextProvider {
+  private _context: ModelContext = {};
+  private _subscribers = new Set<() => void>();
+  private _pendingRequests = new Map<
+    string,
+    {
+      resolve: (value: any) => void;
+      reject: (error: any) => void;
+    }
+  >();
+  private _requestCounter = 0;
+  private _iframeWindow: Window;
+  private _targetOrigin: string;
+
+  constructor(iframeWindow: Window, targetOrigin: string = "*") {
+    this._iframeWindow = iframeWindow;
+    this._targetOrigin = targetOrigin;
+
+    this.handleMessage = this.handleMessage.bind(this);
+    window.addEventListener("message", this.handleMessage);
+
+    // Request initial context
+    this.requestContext();
+  }
+
+  private handleMessage(event: MessageEvent) {
+    // Security: Validate origin and source
+    if (this._targetOrigin !== "*" && event.origin !== this._targetOrigin)
+      return;
+    if (event.source !== this._iframeWindow) return;
+    if (event.data?.channel !== FRAME_MESSAGE_CHANNEL) return;
+
+    const message = event.data.message as FrameMessage;
+
+    switch (message.type) {
+      case "model-context-update": {
+        this.updateContext(message.context);
+        break;
+      }
+
+      case "tool-result": {
+        const pending = this._pendingRequests.get(message.id);
+        if (pending) {
+          if (message.error) {
+            pending.reject(new Error(message.error));
+          } else {
+            pending.resolve(message.result);
+          }
+          this._pendingRequests.delete(message.id);
+        }
+        break;
+      }
+    }
+  }
+
+  private updateContext(serializedContext: SerializedModelContext) {
+    const context = deserializeModelContext(serializedContext);
+    this._context = {
+      ...context,
+      tools:
+        context.tools &&
+        Object.fromEntries(
+          Object.entries(context.tools).map(([name, tool]) => [
+            name,
+            {
+              ...tool,
+              execute: (args: any) => this.callTool(name, args),
+            } as Tool<any, any>,
+          ]),
+        ),
+    };
+    this.notifySubscribers();
+  }
+
+  private callTool(toolName: string, args: any): Promise<any> {
+    return this.sendRequest(
+      {
+        type: "tool-call",
+        id: `tool-${this._requestCounter++}`,
+        toolName,
+        args,
+      },
+      30000,
+      `Tool call "${toolName}" timed out`,
+    );
+  }
+
+  private sendRequest<T extends FrameMessage & { id: string }>(
+    message: T,
+    timeout = 30000,
+    timeoutMessage = "Request timed out",
+  ): Promise<any> {
+    return new Promise((resolve, reject) => {
+      this._pendingRequests.set(message.id, { resolve, reject });
+
+      this._iframeWindow.postMessage(
+        { channel: FRAME_MESSAGE_CHANNEL, message },
+        this._targetOrigin,
+      );
+
+      const timeoutId = setTimeout(() => {
+        const pending = this._pendingRequests.get(message.id);
+        if (pending) {
+          pending.reject(new Error(timeoutMessage));
+          this._pendingRequests.delete(message.id);
+        }
+      }, timeout);
+
+      // Store original resolve/reject with timeout cleanup
+      const originalResolve = this._pendingRequests.get(message.id)!.resolve;
+      const originalReject = this._pendingRequests.get(message.id)!.reject;
+
+      this._pendingRequests.set(message.id, {
+        resolve: (value: any) => {
+          clearTimeout(timeoutId);
+          originalResolve(value);
+        },
+        reject: (error: any) => {
+          clearTimeout(timeoutId);
+          originalReject(error);
+        },
+      });
+    });
+  }
+
+  private requestContext() {
+    // Request current context from iframe
+    this._iframeWindow.postMessage(
+      {
+        channel: FRAME_MESSAGE_CHANNEL,
+        message: {
+          type: "model-context-request",
+        } as FrameMessage,
+      },
+      this._targetOrigin,
+    );
+  }
+
+  private notifySubscribers() {
+    this._subscribers.forEach((callback) => callback());
+  }
+
+  getModelContext(): ModelContext {
+    return this._context;
+  }
+
+  subscribe(callback: () => void): Unsubscribe {
+    this._subscribers.add(callback);
+    return () => this._subscribers.delete(callback);
+  }
+
+  dispose() {
+    window.removeEventListener("message", this.handleMessage);
+    this._subscribers.clear();
+    this._pendingRequests.clear();
+  }
+}

package/src/model-context/frame/AssistantFrameProvider.ts

@@ -0,0 +1,225 @@
+import {
+  ModelContextProvider,
+  ModelContext,
+} from "../../model-context/ModelContextTypes";
+import { Unsubscribe } from "../../types/Unsubscribe";
+import { Tool } from "assistant-stream";
+import { z } from "zod";
+import {
+  FrameMessage,
+  FRAME_MESSAGE_CHANNEL,
+  SerializedModelContext,
+  SerializedTool,
+} from "./AssistantFrameTypes";
+
+/**
+ * Converts tools to JSON Schema format for serialization
+ */
+const serializeTool = (tool: Tool<any, any>): SerializedTool => ({
+  ...(tool.description && { description: tool.description }),
+  parameters:
+    tool.parameters instanceof z.ZodType
+      ? ((z as any).toJSONSchema?.(tool.parameters) ?? tool.parameters)
+      : tool.parameters,
+  ...(tool.disabled !== undefined && { disabled: tool.disabled }),
+  ...(tool.type && { type: tool.type }),
+});
+
+/**
+ * Serializes a ModelContext for transmission across iframe boundary
+ */
+const serializeModelContext = (
+  context: ModelContext,
+): SerializedModelContext => ({
+  ...(context.system !== undefined && { system: context.system }),
+  ...(context.tools && {
+    tools: Object.fromEntries(
+      Object.entries(context.tools).map(([name, tool]) => [
+        name,
+        serializeTool(tool),
+      ]),
+    ),
+  }),
+});
+
+/**
+ * AssistantFrameProvider - Runs inside an iframe and provides ModelContextProviders
+ * to the parent window's AssistantFrameHost.
+ *
+ * Usage example:
+ * ```typescript
+ * // Inside the iframe
+ * // Add model context providers
+ * const registry = new ModelContextRegistry();
+ * AssistantFrameProvider.addModelContextProvider(registry);
+ *
+ * // Add tools 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: ["..."] };
+ *   }
+ * });
+ * ```
+ */
+export class AssistantFrameProvider {
+  private static _instance: AssistantFrameProvider | null = null;
+
+  private _providers = new Set<ModelContextProvider>();
+  private _providerUnsubscribes = new Map<
+    ModelContextProvider,
+    Unsubscribe | undefined
+  >();
+  private _targetOrigin: string;
+
+  private constructor(targetOrigin: string = "*") {
+    this._targetOrigin = targetOrigin;
+    this.handleMessage = this.handleMessage.bind(this);
+    window.addEventListener("message", this.handleMessage);
+
+    // Send initial update on initialization
+    setTimeout(() => this.broadcastUpdate(), 0);
+  }
+
+  private static getInstance(targetOrigin?: string): AssistantFrameProvider {
+    if (!AssistantFrameProvider._instance) {
+      AssistantFrameProvider._instance = new AssistantFrameProvider(
+        targetOrigin,
+      );
+    }
+    return AssistantFrameProvider._instance;
+  }
+
+  private handleMessage(event: MessageEvent) {
+    // Security: Validate origin if specified
+    if (this._targetOrigin !== "*" && event.origin !== this._targetOrigin)
+      return;
+    if (event.data?.channel !== FRAME_MESSAGE_CHANNEL) return;
+
+    const message = event.data.message as FrameMessage;
+
+    switch (message.type) {
+      case "model-context-request":
+        // Respond with current context
+        this.sendMessage(event, {
+          type: "model-context-update",
+          context: serializeModelContext(this.getModelContext()),
+        });
+        break;
+
+      case "tool-call":
+        this.handleToolCall(message, event);
+        break;
+    }
+  }
+
+  private async handleToolCall(
+    message: Extract<FrameMessage, { type: "tool-call" }>,
+    event: MessageEvent,
+  ) {
+    const tool = this.getModelContext().tools?.[message.toolName];
+
+    let result: any;
+    let error: string | undefined;
+
+    if (!tool) {
+      error = `Tool "${message.toolName}" not found`;
+    } else {
+      try {
+        result = tool.execute
+          ? await tool.execute(message.args, {
+              toolCallId: message.id,
+              abortSignal: new AbortController().signal,
+            })
+          : undefined;
+      } catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+      }
+    }
+
+    this.sendMessage(event, {
+      type: "tool-result",
+      id: message.id,
+      ...(error ? { error } : { result }),
+    });
+  }
+
+  private sendMessage(event: MessageEvent, message: FrameMessage) {
+    event.source?.postMessage(
+      { channel: FRAME_MESSAGE_CHANNEL, message },
+      { targetOrigin: event.origin },
+    );
+  }
+
+  private getModelContext(): ModelContext {
+    const contexts = Array.from(this._providers).map((p) =>
+      p.getModelContext(),
+    );
+
+    return contexts.reduce(
+      (merged, context) => ({
+        system: context.system
+          ? merged.system
+            ? `${merged.system}\n\n${context.system}`
+            : context.system
+          : merged.system,
+        tools: { ...(merged.tools || {}), ...(context.tools || {}) },
+      }),
+      {} as ModelContext,
+    );
+  }
+
+  private broadcastUpdate() {
+    // Always broadcast to parent window
+    if (window.parent && window.parent !== window) {
+      const updateMessage: FrameMessage = {
+        type: "model-context-update",
+        context: serializeModelContext(this.getModelContext()),
+      };
+
+      window.parent.postMessage(
+        { channel: FRAME_MESSAGE_CHANNEL, message: updateMessage },
+        this._targetOrigin,
+      );
+    }
+  }
+
+  static addModelContextProvider(
+    provider: ModelContextProvider,
+    targetOrigin?: string,
+  ): Unsubscribe {
+    const instance = AssistantFrameProvider.getInstance(targetOrigin);
+    instance._providers.add(provider);
+
+    const unsubscribe = provider.subscribe?.(() => instance.broadcastUpdate());
+    if (unsubscribe) {
+      instance._providerUnsubscribes.set(provider, unsubscribe);
+    }
+
+    instance.broadcastUpdate();
+
+    return () => {
+      instance._providers.delete(provider);
+      instance._providerUnsubscribes.get(provider)?.();
+      instance._providerUnsubscribes.delete(provider);
+      instance.broadcastUpdate();
+    };
+  }
+
+  static dispose() {
+    if (AssistantFrameProvider._instance) {
+      const instance = AssistantFrameProvider._instance;
+      window.removeEventListener("message", instance.handleMessage);
+
+      // Unsubscribe from all providers
+      instance._providerUnsubscribes.forEach((unsubscribe) => unsubscribe?.());
+      instance._providerUnsubscribes.clear();
+      instance._providers.clear();
+
+      AssistantFrameProvider._instance = null;
+    }
+  }
+}

package/src/model-context/frame/AssistantFrameTypes.ts

@@ -0,0 +1,40 @@
+export type SerializedTool = {
+  description?: string;
+  parameters: any; // JSON Schema
+  disabled?: boolean;
+  type?: string;
+};
+
+export type SerializedModelContext = {
+  system?: string;
+  tools?: Record<string, SerializedTool>;
+};
+
+export type FrameMessageType =
+  | "model-context-request"
+  | "model-context-update"
+  | "tool-call"
+  | "tool-result";
+
+export type FrameMessage =
+  | {
+      type: "model-context-request";
+    }
+  | {
+      type: "model-context-update";
+      context: SerializedModelContext;
+    }
+  | {
+      type: "tool-call";
+      id: string;
+      toolName: string;
+      args: unknown;
+    }
+  | {
+      type: "tool-result";
+      id: string;
+      result?: unknown;
+      error?: string;
+    };
+
+export const FRAME_MESSAGE_CHANNEL = "assistant-ui-frame";

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

@@ -0,0 +1,104 @@
+## 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 (temprature, 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 runtime = useAssistantRuntime();
+runtime.registerModelContextProvider(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 necssary 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
+
+#### 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 can specify `targetOrigin` to restrict message sources
+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/index.ts

@@ -0,0 +1,4 @@
+export * from "./AssistantFrameHost";
+export * from "./AssistantFrameProvider";
+export * from "./AssistantFrameTypes";
+export * from "./useAssistantFrameHost";

package/src/model-context/frame/useAssistantFrameHost.ts

@@ -0,0 +1,48 @@
+"use client";
+
+import { useEffect, RefObject } from "react";
+import { AssistantFrameHost } from "./AssistantFrameHost";
+import { Unsubscribe } from "../../types";
+
+type UseAssistantFrameHostOptions = {
+  iframeRef: Readonly<RefObject<HTMLIFrameElement | null | undefined>>;
+  targetOrigin?: string;
+  register: (frameHost: AssistantFrameHost) => Unsubscribe;
+};
+
+/**
+ * React hook that manages the lifecycle of an AssistantFrameHost and its binding to the current AssistantRuntime.
+ *
+ * Usage example:
+ * ```typescript
+ * function MyComponent() {
+ *   const iframeRef = useRef<HTMLIFrameElement>(null);
+ *
+ *   useAssistantFrameHost({
+ *     iframeRef,
+ *     targetOrigin: "https://trusted-domain.com", // optional
+ *   });
+ *
+ *   return <iframe ref={iframeRef} src="..." />;
+ * }
+ * ```
+ */
+export const useAssistantFrameHost = ({
+  iframeRef,
+  targetOrigin = "*",
+  register,
+}: UseAssistantFrameHostOptions): void => {
+  useEffect(() => {
+    const iframeWindow = iframeRef.current?.contentWindow;
+    if (!iframeWindow) return;
+
+    const frameHost = new AssistantFrameHost(iframeWindow, targetOrigin);
+
+    const unsubscribe = register(frameHost);
+
+    return () => {
+      frameHost.dispose();
+      unsubscribe();
+    };
+  }, [iframeRef, targetOrigin, register]);
+};

package/src/model-context/index.ts

@@ -33,3 +33,6 @@ export { tool } from "./tool";
  */
 export { makeAssistantVisible as makeAssistantReadable } from "./makeAssistantVisible";
 export { makeAssistantVisible } from "./makeAssistantVisible";
+
+export * from "./registry";
+export * from "./frame";