@assistant-ui/core 0.3.20 → 0.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/core",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "description": "Framework-agnostic core runtime for assistant-ui",
   "keywords": [
     "assistant",
@@ -59,15 +59,15 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.44",
+    "assistant-stream": "^0.3.45",
     "nanoid": "^6.0.1"
   },
   "optionalDevDependencies": {
     "@assistant-ui/x-generative-compiler": ">=0.0.3"
   },
   "peerDependencies": {
-    "@assistant-ui/store": "^0.3.14",
-    "@assistant-ui/tap": "^0.9.18",
+    "@assistant-ui/store": "^0.3.15",
+    "@assistant-ui/tap": "^0.9.19",
     "@types/react": "*",
     "react": "^18 || ^19",
     "assistant-cloud": "^0.2.1"
@@ -84,17 +84,18 @@
     }
   },
   "devDependencies": {
-    "@assistant-ui/store": "0.3.14",
-    "@assistant-ui/tap": "0.9.18",
-    "@assistant-ui/vite": "0.0.18",
-    "@assistant-ui/x-buildutils": "0.0.28",
+    "@assistant-ui/store": "0.3.15",
+    "@assistant-ui/tap": "0.9.19",
+    "@assistant-ui/vite": "0.0.19",
+    "@assistant-ui/x-buildutils": "0.0.29",
     "@testing-library/react": "^16.3.3",
     "@types/react": "^19.3.0",
-    "assistant-cloud": "0.2.2",
+    "assistant-cloud": "0.2.3",
     "jsdom": "^30.0.1",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.1",
+    "zod": "^4.6.5"
   },
   "publishConfig": {
     "access": "public",

package/src/adapters/attachment.test.ts

@@ -1,9 +1,11 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { getEventListeners } from "node:events";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   type AttachmentAdapter,
   CompositeAttachmentAdapter,
   getFileDataURL,
   SimpleImageAttachmentAdapter,
+  SimpleTextAttachmentAdapter,
 } from "./attachment";
 
 const originalFileReader = globalThis.FileReader;
@@ -80,6 +82,70 @@ describe("getFileDataURL", () => {
       `data:application/octet-stream;base64,${originalBuffer.from(bytes).toString("base64")}`,
     );
   });
+
+  it("aborts a FileReader read when the signal aborts", async () => {
+    const abort = vi.fn();
+    class PendingFileReader {
+      onload: (() => void) | null = null;
+      onerror: ((error: unknown) => void) | null = null;
+      abort = abort;
+      readAsDataURL() {}
+    }
+    globalThis.FileReader = PendingFileReader as unknown as typeof FileReader;
+    const controller = new AbortController();
+
+    const reading = getFileDataURL(new File(["hello"], "a.txt"), {
+      signal: controller.signal,
+    });
+    controller.abort();
+
+    await expect(reading).rejects.toBe(controller.signal.reason);
+    expect(abort).toHaveBeenCalledOnce();
+  });
+
+  it("does not start a read once the signal has aborted", async () => {
+    const readAsDataURL = vi.fn();
+    class FakeFileReader {
+      readAsDataURL = readAsDataURL;
+    }
+    globalThis.FileReader = FakeFileReader as unknown as typeof FileReader;
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      getFileDataURL(new File(["hello"], "a.txt"), {
+        signal: controller.signal,
+      }),
+    ).rejects.toBe(controller.signal.reason);
+    expect(readAsDataURL).not.toHaveBeenCalled();
+  });
+
+  it("releases the abort listener when a read fails to start", async () => {
+    const failure = new Error("parameter 1 is not of type 'Blob'");
+    class ThrowingFileReader {
+      readAsDataURL() {
+        throw failure;
+      }
+    }
+    globalThis.FileReader = ThrowingFileReader as unknown as typeof FileReader;
+    const controller = new AbortController();
+
+    await expect(
+      getFileDataURL(new File(["hello"], "a.txt"), {
+        signal: controller.signal,
+      }),
+    ).rejects.toBe(failure);
+    expect(getEventListeners(controller.signal, "abort")).toHaveLength(0);
+  });
+
+  it("rejects with an AbortError when the aborted signal carries no reason", async () => {
+    globalThis.FileReader = undefined as unknown as typeof FileReader;
+    const signal = { aborted: true, reason: undefined } as AbortSignal;
+
+    await expect(
+      getFileDataURL(new File(["hello"], "a.txt"), { signal }),
+    ).rejects.toMatchObject({ name: "AbortError" });
+  });
 });
 
 describe("SimpleImageAttachmentAdapter", () => {
@@ -154,3 +220,34 @@ describe("CompositeAttachmentAdapter", () => {
     },
   );
 });
+
+describe("built-in adapters under an aborted send", () => {
+  it.each([
+    ["image/png", "a.png"],
+    ["text/plain", "a.txt"],
+  ])(
+    "stops reading a file of type %s when the send aborts mid-read",
+    async (type, name) => {
+      globalThis.FileReader = undefined as unknown as typeof FileReader;
+      const composite = new CompositeAttachmentAdapter([
+        new SimpleImageAttachmentAdapter(),
+        new SimpleTextAttachmentAdapter(),
+      ]);
+      const controller = new AbortController();
+
+      const sending = composite.send(
+        {
+          id: "a",
+          type: "file",
+          name,
+          file: new File(["bytes"], name, { type }),
+          status: { type: "requires-action", reason: "composer-send" },
+        },
+        { signal: controller.signal },
+      );
+      controller.abort();
+
+      await expect(sending).rejects.toBe(controller.signal.reason);
+    },
+  );
+});

package/src/adapters/attachment.ts

@@ -12,7 +12,10 @@ export type AttachmentAdapter = {
     file: File;
   }): Promise<PendingAttachment> | AsyncGenerator<PendingAttachment, void>;
   remove(attachment: Attachment): Promise<void>;
-  send(attachment: PendingAttachment): Promise<CompleteAttachment>;
+  send(
+    attachment: PendingAttachment,
+    options?: { signal?: AbortSignal },
+  ): Promise<CompleteAttachment>;
 };
 
 export class SimpleImageAttachmentAdapter implements AttachmentAdapter {
@@ -31,6 +34,7 @@ export class SimpleImageAttachmentAdapter implements AttachmentAdapter {
 
   public async send(
     attachment: PendingAttachment,
+    options?: { signal?: AbortSignal },
   ): Promise<CompleteAttachment> {
     return {
       ...attachment,
@@ -38,7 +42,7 @@ export class SimpleImageAttachmentAdapter implements AttachmentAdapter {
       content: [
         {
           type: "image",
-          image: await getFileDataURL(attachment.file),
+          image: await getFileDataURL(attachment.file, options),
         },
       ],
     };
@@ -68,19 +72,59 @@ const bytesToBase64 = (bytes: Uint8Array): string => {
   return btoa(binary);
 };
 
+// React Native's AbortSignal polyfill carries no `reason`.
+const abortReason = (signal: AbortSignal | undefined): unknown => {
+  if (signal?.reason !== undefined) return signal.reason;
+  const error = new Error("The attachment read was aborted");
+  error.name = "AbortError";
+  return error;
+};
+
+const throwIfAborted = (signal: AbortSignal | undefined) => {
+  if (signal?.aborted) throw abortReason(signal);
+};
+
+const readWithFileReader = (
+  read: (reader: FileReader) => void,
+  signal: AbortSignal | undefined,
+) =>
+  new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    const onAbort = () => {
+      reader.abort();
+      reject(abortReason(signal));
+    };
+    reader.onload = () => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve(reader.result as string);
+    };
+    reader.onerror = (error) => {
+      signal?.removeEventListener("abort", onAbort);
+      reject(error);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      read(reader);
+    } catch (error) {
+      signal?.removeEventListener("abort", onAbort);
+      reject(error);
+    }
+  });
+
 // React Native's Blob polyfill has FileReader but not file.text()/arrayBuffer(); Node has
 // the reverse. Prefer FileReader when present, falling back to the Blob methods otherwise.
-export const getFileDataURL = async (file: File): Promise<string> => {
+export const getFileDataURL = async (
+  file: File,
+  options?: { signal?: AbortSignal },
+): Promise<string> => {
+  const signal = options?.signal;
+  throwIfAborted(signal);
   if (typeof FileReader === "undefined") {
     const buffer = await file.arrayBuffer();
+    throwIfAborted(signal);
     return `data:${file.type || "application/octet-stream"};base64,${bytesToBase64(new Uint8Array(buffer))}`;
   }
-  return new Promise<string>((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onload = () => resolve(reader.result as string);
-    reader.onerror = (error) => reject(error);
-    reader.readAsDataURL(file);
-  });
+  return readWithFileReader((reader) => reader.readAsDataURL(file), signal);
 };
 
 const escapeAttachmentName = (name: string) =>
@@ -107,6 +151,7 @@ export class SimpleTextAttachmentAdapter implements AttachmentAdapter {
 
   public async send(
     attachment: PendingAttachment,
+    options?: { signal?: AbortSignal },
   ): Promise<CompleteAttachment> {
     return {
       ...attachment,
@@ -114,7 +159,7 @@ export class SimpleTextAttachmentAdapter implements AttachmentAdapter {
       content: [
         {
           type: "text",
-          text: `<attachment name="${escapeAttachmentName(attachment.name)}">\n${await getFileText(attachment.file)}\n</attachment>`,
+          text: `<attachment name="${escapeAttachmentName(attachment.name)}">\n${await getFileText(attachment.file, options)}\n</attachment>`,
         },
       ],
     };
@@ -125,16 +170,18 @@ export class SimpleTextAttachmentAdapter implements AttachmentAdapter {
   }
 }
 
-const getFileText = async (file: File): Promise<string> => {
+const getFileText = async (
+  file: File,
+  options?: { signal?: AbortSignal },
+): Promise<string> => {
+  const signal = options?.signal;
+  throwIfAborted(signal);
   if (typeof FileReader === "undefined") {
-    return file.text();
+    const text = await file.text();
+    throwIfAborted(signal);
+    return text;
   }
-  return new Promise<string>((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onload = () => resolve(reader.result as string);
-    reader.onerror = (error) => reject(error);
-    reader.readAsText(file);
-  });
+  return readWithFileReader((reader) => reader.readAsText(file), signal);
 };
 
 export function fileMatchesAccept(
@@ -271,11 +318,14 @@ export class CompositeAttachmentAdapter implements AttachmentAdapter {
     throw new Error("No matching adapter found for file");
   }
 
-  public async send(attachment: PendingAttachment) {
+  public async send(
+    attachment: PendingAttachment,
+    options?: { signal?: AbortSignal },
+  ) {
     const adapters = this._adapters.slice();
     for (const adapter of adapters) {
       if (fileMatchesAccept(attachment.file, adapter.accept)) {
-        return adapter.send(attachment);
+        return adapter.send(attachment, options);
       }
     }
     throw new Error("No matching adapter found for attachment");

package/src/adapters/speech.test.ts

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { WebSpeechDictationAdapter, WebSpeechSynthesisAdapter } from "./speech";
 
 afterEach(() => {
+  vi.useRealTimers();
   vi.restoreAllMocks();
   vi.unstubAllGlobals();
 });
@@ -40,6 +41,34 @@ describe("WebSpeechSynthesisAdapter", () => {
     },
   );
 
+  it.each(["end", "error"] as const)(
+    "handles a synchronous %s event while starting playback",
+    (eventType) => {
+      class MockSpeechSynthesisUtterance extends EventTarget {}
+      vi.stubGlobal("SpeechSynthesisUtterance", MockSpeechSynthesisUtterance);
+      vi.stubGlobal("window", {
+        speechSynthesis: {
+          speak: (utterance: EventTarget) => {
+            const event = new Event(eventType);
+            if (eventType === "error") {
+              Object.assign(event, { error: "synthesis-failed" });
+            }
+            utterance.dispatchEvent(event);
+          },
+          cancel: vi.fn(),
+        },
+      });
+
+      const result = new WebSpeechSynthesisAdapter().speak("Hello");
+
+      expect(result.status).toEqual({
+        type: "ended",
+        reason: eventType === "end" ? "finished" : "error",
+        error: eventType === "end" ? undefined : "synthesis-failed",
+      });
+    },
+  );
+
   it("cancels active playback once and leaves later playback alone", () => {
     const { cancel } = stubSpeechSynthesis();
     const adapter = new WebSpeechSynthesisAdapter();
@@ -179,6 +208,71 @@ describe("WebSpeechDictationAdapter", () => {
     } as unknown as Event);
   };
 
+  it("cancels a stop that never receives a terminal browser event", async () => {
+    vi.useFakeTimers();
+    const abort = vi.fn();
+    class MockSpeechRecognition extends EventTarget {
+      lang = "";
+      continuous = false;
+      interimResults = false;
+      start() {}
+      stop() {}
+      abort() {
+        abort();
+        this.dispatchEvent(
+          Object.assign(new Event("error"), {
+            error: "network",
+            message: "late error",
+          }),
+        );
+      }
+    }
+    vi.stubGlobal("window", {
+      SpeechRecognition: MockSpeechRecognition,
+    });
+    const session = new WebSpeechDictationAdapter().listen();
+    let settled = false;
+
+    const stopping = session.stop().then(() => {
+      settled = true;
+    });
+    await vi.advanceTimersByTimeAsync(4_999);
+    expect(settled).toBe(false);
+    expect(abort).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    await stopping;
+
+    expect(abort).toHaveBeenCalledOnce();
+    expect(session.status).toEqual({ type: "ended", reason: "cancelled" });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("resolves stop from the browser end event without aborting", async () => {
+    const abort = vi.fn();
+    class MockSpeechRecognition extends EventTarget {
+      lang = "";
+      continuous = false;
+      interimResults = false;
+      start() {}
+      stop() {
+        this.dispatchEvent(new Event("end"));
+      }
+      abort() {
+        abort();
+      }
+    }
+    vi.stubGlobal("window", {
+      SpeechRecognition: MockSpeechRecognition,
+    });
+    const session = new WebSpeechDictationAdapter().listen();
+
+    await expect(session.stop()).resolves.toBeUndefined();
+
+    expect(abort).not.toHaveBeenCalled();
+    expect(session.status).toEqual({ type: "ended", reason: "stopped" });
+  });
+
   it("publishes the entire interim suffix when only its last result changes", () => {
     const listeners = stubSpeechRecognition();
     const session = new WebSpeechDictationAdapter().listen();

package/src/adapters/speech.ts

@@ -1,6 +1,8 @@
 import type { Unsubscribe } from "../types/unsubscribe";
 import { notifyEventListeners } from "../utils/notify-event-listeners";
 
+const DICTATION_STOP_TIMEOUT_MS = 5_000;
+
 export namespace SpeechSynthesisAdapter {
   export type Status =
     | {
@@ -71,8 +73,6 @@ export class WebSpeechSynthesisAdapter implements SpeechSynthesisAdapter {
     utterance.addEventListener("end", () => handleEnd("finished"));
     utterance.addEventListener("error", (e) => handleEnd("error", e.error));
 
-    window.speechSynthesis.speak(utterance);
-
     const res: SpeechSynthesisAdapter.Utterance = {
       status: { type: "running" },
       cancel: () => {
@@ -99,6 +99,7 @@ export class WebSpeechSynthesisAdapter implements SpeechSynthesisAdapter {
         }
       },
     };
+    window.speechSynthesis.speak(utterance);
     return res;
   }
 }
@@ -215,9 +216,21 @@ export class WebSpeechDictationAdapter implements DictationAdapter {
       stop: async () => {
         recognition.stop();
         return new Promise<void>((resolve) => {
+          const timeoutAt = Date.now() + DICTATION_STOP_TIMEOUT_MS;
           const checkEnded = () => {
             if (session.status.type === "ended") {
               resolve();
+            } else if (Date.now() >= timeoutAt) {
+              updateStatus({ type: "ended", reason: "cancelled" });
+              try {
+                recognition.abort();
+              } catch (error) {
+                console.error(
+                  "Dictation cancellation after stop timeout failed:",
+                  error,
+                );
+              }
+              resolve();
             } else {
               setTimeout(checkEnded, 50);
             }
@@ -322,6 +335,7 @@ export class WebSpeechDictationAdapter implements DictationAdapter {
     });
 
     recognition.addEventListener("error", (event) => {
+      if (session.status.type === "ended") return;
       const errorEvent = event as unknown as SpeechRecognitionErrorEvent;
       if (errorEvent.error === "aborted") {
         updateStatus({ type: "ended", reason: "cancelled" });

package/src/adapters/thread-history.ts

@@ -60,6 +60,21 @@ export type GenericThreadHistoryAdapter<TMessage> = {
 };
 
 export type ThreadHistoryAdapter = {
+  /**
+   * Keeps a copy of messages whose source of truth is the runtime's backend.
+   * `branch` is the conversation from its first message to its last, and
+   * `messageIds` names the ones in it that are new or changed; the adapter
+   * stores those, and first any earlier message of the branch it does not hold
+   * yet, keyed by each message's own id. It is undefined while the adapter
+   * keeps no copies, so the runtime then neither copies nor records tool
+   * interactions.
+   */
+  unstable_copy?:
+    | ((
+        branch: readonly ThreadMessage[],
+        messageIds: readonly string[],
+      ) => Promise<void>)
+    | undefined;
   load(): Promise<
     ExportedMessageRepository & {
       state?: ReadonlyJSONValue;
@@ -71,11 +86,7 @@ export type ThreadHistoryAdapter = {
   ): 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.
+   * 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, finalize the same message once the run resumes, and record a tool result that arrives after the message settled, which can be a message later turns follow. 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>;