@assistant-ui/core 0.2.21 → 0.2.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/core",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "Framework-agnostic core runtime for assistant-ui",
   "keywords": [
     "assistant",
@@ -59,7 +59,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.26",
+    "assistant-stream": "^0.3.28",
     "nanoid": "^6.0.0"
   },
   "optionalDevDependencies": {
@@ -91,15 +91,15 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.17",
     "jsdom": "^29.1.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "vitest": "^4.1.10",
     "zustand": "^5.0.14",
-    "@assistant-ui/store": "0.2.20",
-    "@assistant-ui/tap": "0.9.4",
-    "@assistant-ui/vite": "0.0.9",
-    "@assistant-ui/x-buildutils": "0.0.18",
-    "assistant-cloud": "0.1.35"
+    "@assistant-ui/store": "0.2.22",
+    "@assistant-ui/tap": "0.9.6",
+    "@assistant-ui/vite": "0.0.11",
+    "@assistant-ui/x-buildutils": "0.0.20",
+    "assistant-cloud": "0.1.37"
   },
   "publishConfig": {
     "access": "public",
@@ -117,6 +117,7 @@
   "scripts": {
     "build": "aui-build",
     "test": "vitest run",
+    "test:react-compiler": "vitest run --config vitest.react-compiler.config.ts",
     "test:watch": "vitest"
   }
 }

package/src/adapters/speech.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { WebSpeechSynthesisAdapter } from "./speech";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("WebSpeechSynthesisAdapter", () => {
+  it("isolates a late subscriber that throws after the utterance ended", async () => {
+    const listeners = new Map<string, EventListener>();
+    class MockSpeechSynthesisUtterance {
+      addEventListener(type: string, listener: EventListener) {
+        listeners.set(type, listener);
+      }
+    }
+    vi.stubGlobal("SpeechSynthesisUtterance", MockSpeechSynthesisUtterance);
+    vi.stubGlobal("window", {
+      speechSynthesis: {
+        speak: vi.fn(),
+        cancel: vi.fn(),
+      },
+    });
+    const listenerError = new Error("late listener failed");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    const result = new WebSpeechSynthesisAdapter().speak("Hello");
+    listeners.get("end")!(new Event("end"));
+
+    const lateListener = vi.fn();
+    result.subscribe(() => {
+      throw listenerError;
+    });
+    result.subscribe(lateListener);
+    await Promise.resolve();
+
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Speech synthesis listener threw an error",
+      listenerError,
+    );
+    expect(lateListener).toHaveBeenCalledOnce();
+  });
+
+  it("continues notifying listeners when one throws", () => {
+    const listeners = new Map<string, EventListener>();
+    class MockSpeechSynthesisUtterance {
+      addEventListener(type: string, listener: EventListener) {
+        listeners.set(type, listener);
+      }
+    }
+    const speak = vi.fn();
+    vi.stubGlobal("SpeechSynthesisUtterance", MockSpeechSynthesisUtterance);
+    vi.stubGlobal("window", {
+      speechSynthesis: {
+        speak,
+        cancel: vi.fn(),
+      },
+    });
+    const listenerError = new Error("listener failed");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const result = new WebSpeechSynthesisAdapter().speak("Hello");
+    const laterListener = vi.fn();
+
+    result.subscribe(() => {
+      throw listenerError;
+    });
+    result.subscribe(laterListener);
+    listeners.get("end")?.({} as Event);
+
+    expect(speak).toHaveBeenCalledWith(
+      expect.any(MockSpeechSynthesisUtterance),
+    );
+    expect(laterListener).toHaveBeenCalledOnce();
+    expect(result.status).toEqual({
+      type: "ended",
+      reason: "finished",
+      error: undefined,
+    });
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Speech synthesis listener threw an error",
+      listenerError,
+    );
+  });
+});

package/src/adapters/speech.ts

@@ -22,6 +22,21 @@ export type SpeechSynthesisAdapter = {
   speak: (text: string) => SpeechSynthesisAdapter.Utterance;
 };
 
+const notifySpeechSynthesisListeners = (
+  listeners: Iterable<() => void>,
+): void => {
+  for (const listener of listeners) {
+    try {
+      listener();
+    } catch (error) {
+      console.error(
+        "[assistant-ui] Speech synthesis listener threw an error",
+        error,
+      );
+    }
+  }
+};
+
 export namespace DictationAdapter {
   export type Status =
     | {
@@ -64,7 +79,7 @@ export class WebSpeechSynthesisAdapter implements SpeechSynthesisAdapter {
       if (res.status.type === "ended") return;
 
       res.status = { type: "ended", reason, error };
-      subscribers.forEach((handler) => handler());
+      notifySpeechSynthesisListeners(subscribers);
     };
 
     utterance.addEventListener("end", () => handleEnd("finished"));
@@ -82,7 +97,7 @@ export class WebSpeechSynthesisAdapter implements SpeechSynthesisAdapter {
         if (res.status.type === "ended") {
           let cancelled = false;
           queueMicrotask(() => {
-            if (!cancelled) callback();
+            if (!cancelled) notifySpeechSynthesisListeners([callback]);
           });
           return () => {
             cancelled = true;

package/src/adapters/thread-history.ts

@@ -65,6 +65,14 @@ export type ThreadHistoryAdapter = {
     options: ChatModelRunOptions,
   ): AsyncGenerator<ChatModelRunResult, void, unknown>;
   append(item: ExportedMessageRepositoryItem): Promise<void>;
+  /**
+   * Rewrites a previously appended message in place, keyed by its message id.
+   * Adapters that implement this let a runtime persist a run paused for tool
+   * approval and finalize the same message once the run resumes. An update may
+   * arrive for an id whose earlier write failed; treat it as an upsert keyed
+   * on the message id rather than assuming the entry exists.
+   */
+  update?(item: ExportedMessageRepositoryItem): Promise<void>;
   delete?(items: ExportedMessageRepositoryItem[]): Promise<void>;
   /** Required when used with `useAISDKRuntime` / `useChatRuntime`. */
   withFormat?<TMessage, TStorageFormat extends Record<string, unknown>>(

package/src/adapters/voice.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createVoiceSession,
+  type VoiceSessionControls,
+  type VoiceSessionHelpers,
+} from "./voice";
+
+const createTestSession = () => {
+  let helpers: VoiceSessionHelpers | undefined;
+  const session = createVoiceSession({}, async (sessionHelpers) => {
+    helpers = sessionHelpers;
+    return {
+      disconnect: vi.fn(),
+      mute: vi.fn(),
+      unmute: vi.fn(),
+    };
+  });
+
+  if (!helpers) throw new Error("Voice session setup did not start");
+  return { helpers, session };
+};
+
+const createPendingTestSession = () => {
+  let resolveControls!: (controls: VoiceSessionControls) => void;
+  const controlsPromise = new Promise<VoiceSessionControls>((resolve) => {
+    resolveControls = resolve;
+  });
+  const controls = {
+    disconnect: vi.fn(),
+    mute: vi.fn(),
+    unmute: vi.fn(),
+  };
+  const session = createVoiceSession({}, () => controlsPromise);
+
+  return {
+    controls,
+    controlsPromise,
+    resolveControls: () => resolveControls(controls),
+    session,
+  };
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("createVoiceSession", () => {
+  it("applies mute requested while setup is pending", async () => {
+    const { controls, controlsPromise, resolveControls, session } =
+      createPendingTestSession();
+
+    session.mute();
+
+    expect(session.isMuted).toBe(true);
+    expect(controls.mute).not.toHaveBeenCalled();
+
+    resolveControls();
+    await controlsPromise;
+
+    expect(controls.mute).toHaveBeenCalledOnce();
+  });
+
+  it("does not apply stale mute after unmuting during setup", async () => {
+    const { controls, controlsPromise, resolveControls, session } =
+      createPendingTestSession();
+
+    session.mute();
+    session.unmute();
+    resolveControls();
+    await controlsPromise;
+
+    expect(session.isMuted).toBe(false);
+    expect(controls.mute).not.toHaveBeenCalled();
+  });
+
+  it("continues notifying listeners when one throws", () => {
+    const listenerError = new Error("listener failed");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const { helpers, session } = createTestSession();
+
+    const transcriptListener = vi.fn();
+    session.onTranscript(() => {
+      throw listenerError;
+    });
+    session.onTranscript(transcriptListener);
+
+    const modeListener = vi.fn();
+    session.onModeChange(() => {
+      throw listenerError;
+    });
+    session.onModeChange(modeListener);
+
+    const volumeListener = vi.fn();
+    session.onVolumeChange(() => {
+      throw listenerError;
+    });
+    session.onVolumeChange(volumeListener);
+
+    const statusListener = vi.fn();
+    session.onStatusChange(() => {
+      throw listenerError;
+    });
+    session.onStatusChange(statusListener);
+
+    helpers.emitTranscript({ role: "assistant", text: "hello" });
+    helpers.emitMode("speaking");
+    helpers.emitVolume(0.5);
+    helpers.end("finished");
+
+    expect(transcriptListener).toHaveBeenCalledWith({
+      role: "assistant",
+      text: "hello",
+    });
+    expect(modeListener).toHaveBeenCalledWith("speaking");
+    expect(volumeListener).toHaveBeenCalledWith(0.5);
+    expect(statusListener).toHaveBeenCalledWith({
+      type: "ended",
+      reason: "finished",
+      error: undefined,
+    });
+    expect(helpers.isDisposed()).toBe(true);
+    expect(consoleError).toHaveBeenCalledTimes(4);
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Voice session listener threw an error",
+      listenerError,
+    );
+  });
+});

package/src/adapters/voice.ts

@@ -57,6 +57,22 @@ export type VoiceSessionHelpers = {
   isDisposed: () => boolean;
 };
 
+const notifyListeners = <T>(
+  listeners: ReadonlySet<(value: T) => void>,
+  value: T,
+) => {
+  for (const listener of listeners) {
+    try {
+      listener(value);
+    } catch (error) {
+      console.error(
+        "[assistant-ui] Voice session listener threw an error",
+        error,
+      );
+    }
+  }
+};
+
 export function createVoiceSession(
   options: { abortSignal?: AbortSignal },
   setup: (helpers: VoiceSessionHelpers) => Promise<VoiceSessionControls>,
@@ -85,25 +101,25 @@ export function createVoiceSession(
     setStatus: (status) => {
       if (disposed) return;
       currentStatus = status;
-      for (const cb of statusCbs) cb(status);
+      notifyListeners(statusCbs, status);
     },
     end: (reason, error?) => {
       if (disposed) return;
       currentStatus = { type: "ended", reason, error };
-      for (const cb of statusCbs) cb(currentStatus);
+      notifyListeners(statusCbs, currentStatus);
       cleanup();
     },
     emitTranscript: (item) => {
       if (disposed) return;
-      for (const cb of transcriptCbs) cb(item);
+      notifyListeners(transcriptCbs, item);
     },
     emitMode: (mode) => {
       if (disposed) return;
-      for (const cb of modeCbs) cb(mode);
+      notifyListeners(modeCbs, mode);
     },
     emitVolume: (volume) => {
       if (disposed) return;
-      for (const cb of volumeCbs) cb(volume);
+      notifyListeners(volumeCbs, volume);
     },
     isDisposed: () => disposed,
   };
@@ -155,7 +171,11 @@ export function createVoiceSession(
     try {
       if (disposed) return;
       controls = await setup(helpers);
-      if (disposed) controls.disconnect();
+      if (disposed) {
+        controls.disconnect();
+      } else if (isMuted) {
+        controls.mute();
+      }
     } catch (error) {
       helpers.end("error", error);
     }

package/src/internal.ts

@@ -40,7 +40,8 @@ export { CompositeContextProvider } from "./utils/composite-context-provider";
 
 // Shared attachment data-URL encoder, reused by framework adapters so the
 // FileReader fallback lives in one place.
-export { getFileDataURL } from "./adapters/attachment";
+export { getFileDataURL, fileMatchesAccept } from "./adapters/attachment";
+export { isCreateAttachment } from "./types/attachment";
 
 // Streaming-stable tool-args stringifier, reused by framework adapters so the
 // key-order stabilization lives in one place.
@@ -53,6 +54,10 @@ export {
 // validation lives in one place.
 export { isJSONValue, isRecord } from "./utils/json/is-json";
 
+// Data-URL decoder and http(s) matcher, reused by framework adapters so the
+// outbound part conversion lives in one place.
+export { httpUrlPattern, parseDataUrl } from "./utils/data-url";
+
 // Runtime extras helper for external-store adapters. Internal because the
 // tap-native runtime path replaces the `thread.extras` side-channel it wraps.
 export {

package/src/model-context/frame/host.test.ts

@@ -0,0 +1,147 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AssistantFrameHost } from "./host";
+import { type FrameMessage, FRAME_MESSAGE_CHANNEL } from "./types";
+
+const executionContext = {
+  toolCallId: "tool-call",
+  abortSignal: new AbortController().signal,
+  human: async () => undefined,
+};
+
+const createHost = () => {
+  let handleMessage: ((event: MessageEvent) => void) | undefined;
+  const addEventListener = vi.fn(
+    (_type: string, listener: EventListenerOrEventListenerObject) => {
+      handleMessage = listener as (event: MessageEvent) => void;
+    },
+  );
+  const removeEventListener = vi.fn();
+  vi.stubGlobal("window", { addEventListener, removeEventListener });
+
+  const postMessage = vi.fn();
+  const iframeWindow = { postMessage } as unknown as Window;
+  const host = new AssistantFrameHost(iframeWindow);
+
+  const dispatchMessage = (message: FrameMessage) =>
+    handleMessage?.({
+      source: iframeWindow,
+      data: {
+        channel: FRAME_MESSAGE_CHANNEL,
+        message,
+      },
+    } as unknown as MessageEvent);
+
+  dispatchMessage({
+    type: "model-context-update",
+    context: {
+      tools: {
+        search: {
+          type: "frontend",
+          parameters: { type: "object", properties: {} },
+        },
+      },
+    },
+  });
+
+  const execute = host.getModelContext().tools?.search?.execute;
+  if (!execute) throw new Error("Expected the search tool to be available");
+
+  return { dispatchMessage, execute, host, postMessage };
+};
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe("AssistantFrameHost", () => {
+  it("resolves tool calls from frame results", async () => {
+    const { dispatchMessage, execute, host } = createHost();
+    const result = Promise.resolve(
+      execute({ query: "weather" }, executionContext),
+    );
+
+    dispatchMessage({
+      type: "tool-result",
+      id: "tool-0",
+      result: "sunny",
+    });
+
+    await expect(result).resolves.toBe("sunny");
+    expect(vi.getTimerCount()).toBe(0);
+    host.dispose();
+  });
+
+  it("rejects pending tool calls when disposed", async () => {
+    const { execute, host } = createHost();
+    const result = Promise.resolve(execute({}, executionContext));
+
+    host.dispose();
+
+    await expect(result).rejects.toThrow(
+      "AssistantFrameHost has been disposed",
+    );
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("rejects pending tool calls when execution is aborted", async () => {
+    const { execute, host } = createHost();
+    const abortController = new AbortController();
+    const abortError = new Error("Run cancelled");
+    abortError.name = "AbortError";
+    const result = Promise.resolve(
+      execute(
+        {},
+        {
+          ...executionContext,
+          abortSignal: abortController.signal,
+        },
+      ),
+    );
+    const onRejected = vi.fn();
+    void result.catch(onRejected);
+
+    abortController.abort(abortError);
+    await Promise.resolve();
+
+    expect(onRejected).toHaveBeenCalledWith(abortError);
+    expect(vi.getTimerCount()).toBe(0);
+    host.dispose();
+  });
+
+  it("does not post tool calls when execution is already aborted", async () => {
+    const { execute, host, postMessage } = createHost();
+    const abortController = new AbortController();
+    const abortError = new Error("Run cancelled");
+    abortError.name = "AbortError";
+    abortController.abort(abortError);
+
+    await expect(
+      execute(
+        {},
+        {
+          ...executionContext,
+          abortSignal: abortController.signal,
+        },
+      ),
+    ).rejects.toBe(abortError);
+
+    expect(postMessage).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+    host.dispose();
+  });
+
+  it("rejects tool calls made after disposal without posting a request", async () => {
+    const { execute, host, postMessage } = createHost();
+    host.dispose();
+
+    await expect(execute({}, executionContext)).rejects.toThrow(
+      "AssistantFrameHost has been disposed",
+    );
+    expect(postMessage).toHaveBeenCalledOnce();
+  });
+});

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

@@ -40,6 +40,13 @@ const deserializeModelContext = (
   }),
 });
 
+const getAbortReason = (signal: AbortSignal): unknown => {
+  if (signal.reason !== undefined) return signal.reason;
+  const error = new Error("Tool call was aborted");
+  error.name = "AbortError";
+  return error;
+};
+
 export class AssistantFrameHost implements ModelContextProvider {
   private _context: ModelContext = {};
   private _subscribers = new Set<() => void>();
@@ -53,6 +60,7 @@ export class AssistantFrameHost implements ModelContextProvider {
   private _requestCounter = 0;
   private _iframeWindow: Window;
   private _targetOrigin: string;
+  private _disposed = false;
 
   constructor(iframeWindow: Window, targetOrigin: string = "*") {
     this._iframeWindow = iframeWindow;
@@ -104,7 +112,8 @@ export class AssistantFrameHost implements ModelContextProvider {
             name,
             {
               ...tool,
-              execute: (args: any) => this.callTool(name, args),
+              execute: (args: any, context: { abortSignal: AbortSignal }) =>
+                this.callTool(name, args, context.abortSignal),
             } as Tool<any, any>,
           ]),
         ),
@@ -112,7 +121,11 @@ export class AssistantFrameHost implements ModelContextProvider {
     this.notifySubscribers();
   }
 
-  private callTool(toolName: string, args: any): Promise<any> {
+  private callTool(
+    toolName: string,
+    args: any,
+    abortSignal: AbortSignal,
+  ): Promise<any> {
     return this.sendRequest(
       {
         type: "tool-call",
@@ -122,6 +135,7 @@ export class AssistantFrameHost implements ModelContextProvider {
       },
       30000,
       `Tool call "${toolName}" timed out`,
+      abortSignal,
     );
   }
 
@@ -129,36 +143,54 @@ export class AssistantFrameHost implements ModelContextProvider {
     message: T,
     timeout = 30000,
     timeoutMessage = "Request timed out",
+    abortSignal?: AbortSignal,
   ): Promise<any> {
-    return new Promise((resolve, reject) => {
-      this._pendingRequests.set(message.id, { resolve, reject });
-
-      this._iframeWindow.postMessage(
-        { channel: FRAME_MESSAGE_CHANNEL, message },
-        this._targetOrigin,
-      );
+    if (this._disposed) {
+      return Promise.reject(new Error("AssistantFrameHost has been disposed"));
+    }
+    if (abortSignal?.aborted) {
+      return Promise.reject(getAbortReason(abortSignal));
+    }
 
-      const timeoutId = setTimeout(() => {
+    return new Promise((resolve, reject) => {
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      const onAbort = () => {
+        if (!abortSignal) return;
         const pending = this._pendingRequests.get(message.id);
         if (pending) {
-          pending.reject(new Error(timeoutMessage));
+          pending.reject(getAbortReason(abortSignal));
           this._pendingRequests.delete(message.id);
         }
-      }, timeout);
-
-      const originalResolve = this._pendingRequests.get(message.id)!.resolve;
-      const originalReject = this._pendingRequests.get(message.id)!.reject;
+      };
+      const cleanup = () => {
+        if (timeoutId !== undefined) clearTimeout(timeoutId);
+        abortSignal?.removeEventListener("abort", onAbort);
+      };
 
       this._pendingRequests.set(message.id, {
         resolve: (value: any) => {
-          clearTimeout(timeoutId);
-          originalResolve(value);
+          cleanup();
+          resolve(value);
         },
         reject: (error: any) => {
-          clearTimeout(timeoutId);
-          originalReject(error);
+          cleanup();
+          reject(error);
         },
       });
+
+      timeoutId = setTimeout(() => {
+        const pending = this._pendingRequests.get(message.id);
+        if (pending) {
+          pending.reject(new Error(timeoutMessage));
+          this._pendingRequests.delete(message.id);
+        }
+      }, timeout);
+      abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+      this._iframeWindow.postMessage(
+        { channel: FRAME_MESSAGE_CHANNEL, message },
+        this._targetOrigin,
+      );
     });
   }
 
@@ -188,8 +220,13 @@ export class AssistantFrameHost implements ModelContextProvider {
   }
 
   dispose() {
+    this._disposed = true;
     window.removeEventListener("message", this.handleMessage);
     this._subscribers.clear();
+    const error = new Error("AssistantFrameHost has been disposed");
+    for (const pending of this._pendingRequests.values()) {
+      pending.reject(error);
+    }
     this._pendingRequests.clear();
   }
 }