@assistant-ui/core 0.2.20 → 0.2.22

package/src/react/runtimes/cloud/AssistantCloudThreadHistoryAdapter.test.tsx

@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+
+import { renderHook } from "@testing-library/react";
+import type { AssistantCloud } from "assistant-cloud";
+import { describe, expect, it, vi } from "vitest";
+import { useAssistantCloudThreadHistoryAdapter } from "./AssistantCloudThreadHistoryAdapter";
+
+const mocks = vi.hoisted(() => {
+  const threadListItem = {
+    getState: () => ({ remoteId: "thread-1" }),
+  };
+
+  return {
+    assistantClient: {
+      threadListItem: () => threadListItem,
+    },
+  };
+});
+
+vi.mock("@assistant-ui/store", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@assistant-ui/store")>()),
+  useAui: () => mocks.assistantClient,
+}));
+
+const makeCloud = () =>
+  ({
+    threads: {
+      messages: {
+        list: vi.fn().mockResolvedValue({ messages: [] }),
+      },
+    },
+  }) as unknown as AssistantCloud;
+
+describe("useAssistantCloudThreadHistoryAdapter", () => {
+  it("refreshes formatted persistence when the Cloud client changes", async () => {
+    const firstCloud = makeCloud();
+    const secondCloud = makeCloud();
+    const cloudRef = { current: firstCloud };
+    const { result } = renderHook(() =>
+      useAssistantCloudThreadHistoryAdapter(cloudRef),
+    );
+    const formatted = result.current.withFormat<
+      { id: string },
+      Record<string, unknown>
+    >({
+      format: "test",
+      encode: ({ message }) => message,
+      decode: ({ parent_id, content }) => ({
+        parentId: parent_id,
+        message: content as { id: string },
+      }),
+      getId: (message) => message.id,
+    });
+
+    await formatted.load();
+    await formatted.load();
+
+    expect(firstCloud.threads.messages.list).toHaveBeenCalledTimes(2);
+
+    cloudRef.current = secondCloud;
+    await formatted.load();
+
+    expect(firstCloud.threads.messages.list).toHaveBeenCalledTimes(2);
+    expect(secondCloud.threads.messages.list).toHaveBeenCalledOnce();
+    expect(secondCloud.threads.messages.list).toHaveBeenCalledWith("thread-1", {
+      format: "test",
+    });
+  });
+});

package/src/react/runtimes/cloud/AssistantCloudThreadHistoryAdapter.ts

@@ -32,7 +32,7 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
     if (!globalPersistence.has(key)) {
       globalPersistence.set(
         key,
-        new CloudMessagePersistence(this.cloudRef.current),
+        new CloudMessagePersistence(() => this.cloudRef.current),
       );
     }
     return globalPersistence.get(key)!;

package/src/react/runtimes/cloud/CloudFileAttachmentAdapter.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AssistantCloud } from "assistant-cloud";
+import type { PendingAttachment } from "../../../types/attachment";
+import { CloudFileAttachmentAdapter } from "./CloudFileAttachmentAdapter";
+
+const makeCloud = () =>
+  ({
+    files: {
+      generatePresignedUploadUrl: vi.fn().mockResolvedValue({
+        signedUrl: "https://storage.example/upload",
+        publicUrl: "https://cdn.example/file.png",
+      }),
+    },
+  }) as unknown as AssistantCloud;
+
+const makeFile = () =>
+  new File([new Uint8Array([1, 2, 3])], "pixel.png", { type: "image/png" });
+
+const drain = async (adapter: CloudFileAttachmentAdapter) => {
+  const yields: PendingAttachment[] = [];
+  for await (const value of adapter.add({ file: makeFile() })) {
+    yields.push(value);
+  }
+  return yields;
+};
+
+describe("CloudFileAttachmentAdapter", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("marks the attachment ready when the upload succeeds", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+    const adapter = new CloudFileAttachmentAdapter(makeCloud());
+
+    const yields = await drain(adapter);
+
+    expect(yields.at(0)?.status).toEqual({
+      type: "running",
+      reason: "uploading",
+      progress: 0,
+    });
+    expect(yields.at(-1)?.status).toEqual({
+      type: "requires-action",
+      reason: "composer-send",
+    });
+
+    const complete = await adapter.send(yields.at(-1)!);
+    expect(complete.status).toEqual({ type: "complete" });
+    expect(complete.content).toEqual([
+      {
+        type: "image",
+        image: "https://cdn.example/file.png",
+        filename: "pixel.png",
+      },
+    ]);
+  });
+
+  it("uploads when Web Crypto is unavailable", async () => {
+    vi.stubGlobal("crypto", undefined);
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+    const adapter = new CloudFileAttachmentAdapter(makeCloud());
+
+    const yields = await drain(adapter);
+
+    expect(yields).toHaveLength(2);
+    expect(yields[0]?.id).toBeTruthy();
+    expect(yields[1]?.id).toBe(yields[0]?.id);
+    expect(yields.at(-1)?.status).toEqual({
+      type: "requires-action",
+      reason: "composer-send",
+    });
+  });
+
+  it("marks the attachment incomplete when the upload returns an HTTP error", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 403,
+        statusText: "Forbidden",
+      }),
+    );
+    const adapter = new CloudFileAttachmentAdapter(makeCloud());
+
+    const yields = await drain(adapter);
+
+    expect(yields.at(-1)?.status).toEqual({
+      type: "incomplete",
+      reason: "error",
+      message: "Failed to upload file: 403 Forbidden",
+    });
+    expect(errorSpy).toHaveBeenCalledWith(
+      "[assistant-ui] Failed to upload attachment:",
+      expect.objectContaining({
+        message: "Failed to upload file: 403 Forbidden",
+      }),
+    );
+    await expect(adapter.send(yields.at(-1)!)).rejects.toThrow(
+      "Attachment not uploaded",
+    );
+  });
+
+  it("marks the attachment incomplete when the upload throws", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const uploadError = new Error("network down");
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(uploadError));
+    const adapter = new CloudFileAttachmentAdapter(makeCloud());
+
+    const yields = await drain(adapter);
+
+    expect(yields.at(-1)?.status).toEqual({
+      type: "incomplete",
+      reason: "error",
+      message: "network down",
+    });
+    expect(errorSpy).toHaveBeenCalledWith(
+      "[assistant-ui] Failed to upload attachment:",
+      uploadError,
+    );
+    await expect(adapter.send(yields.at(-1)!)).rejects.toThrow(
+      "Attachment not uploaded",
+    );
+  });
+});

package/src/react/runtimes/cloud/CloudFileAttachmentAdapter.ts

@@ -6,6 +6,7 @@ import type {
 } from "../../../types/attachment";
 import type { ThreadUserMessagePart } from "../../../types/message";
 import type { AttachmentAdapter } from "../../../adapters/attachment";
+import { generateId } from "../../../utils/id";
 
 const guessAttachmentType = (
   contentType: string,
@@ -27,7 +28,7 @@ export class CloudFileAttachmentAdapter implements AttachmentAdapter {
   }: {
     file: File;
   }): AsyncGenerator<PendingAttachment, void> {
-    const id = crypto.randomUUID();
+    const id = generateId();
     const type = guessAttachmentType(file.type);
     let attachment: PendingAttachment = {
       id,
@@ -44,7 +45,7 @@ export class CloudFileAttachmentAdapter implements AttachmentAdapter {
         await this.cloud.files.generatePresignedUploadUrl({
           filename: file.name,
         });
-      await fetch(signedUrl, {
+      const res = await fetch(signedUrl, {
         method: "PUT",
         body: file,
         headers: {
@@ -52,16 +53,26 @@ export class CloudFileAttachmentAdapter implements AttachmentAdapter {
         },
         mode: "cors",
       });
+      if (!res.ok) {
+        throw new Error(
+          `Failed to upload file: ${res.status} ${res.statusText}`,
+        );
+      }
       this.uploadedUrls.set(id, publicUrl);
       attachment = {
         ...attachment,
         status: { type: "requires-action", reason: "composer-send" },
       };
       yield attachment;
-    } catch {
+    } catch (error) {
+      console.error("[assistant-ui] Failed to upload attachment:", error);
       attachment = {
         ...attachment,
-        status: { type: "incomplete", reason: "error" },
+        status: {
+          type: "incomplete",
+          reason: "error",
+          message: error instanceof Error ? error.message : String(error),
+        },
       };
       yield attachment;
     }

package/src/react/runtimes/cloud/auiV0.ts

@@ -1,8 +1,14 @@
 import type {
+  DataMessagePart,
+  FileMessagePart,
+  ImageMessagePart,
   MessageStatus,
   SourceProviderMetadata,
   ThreadMessage,
+  TextMessagePart,
+  Unstable_AudioMessagePart,
 } from "../../../types/message";
+import type { CompleteAttachment } from "../../../types/attachment";
 import { fromThreadMessageLike } from "../../../runtime/utils/thread-message-like";
 import type { CloudMessage } from "assistant-cloud";
 import { isJSONValue } from "../../../utils/json/is-json";
@@ -65,10 +71,27 @@ type AuiV0MessagePart =
       readonly filename?: string;
     };
 
+type AuiV0AttachmentPart =
+  | TextMessagePart
+  | ImageMessagePart
+  | FileMessagePart
+  | Unstable_AudioMessagePart
+  | DataMessagePart<ReadonlyJSONValue>;
+
+type AuiV0Attachment = {
+  readonly id: string;
+  readonly type: CompleteAttachment["type"];
+  readonly name: string;
+  readonly contentType?: string;
+  readonly status: CompleteAttachment["status"];
+  readonly content: readonly AuiV0AttachmentPart[];
+};
+
 type AuiV0Message = {
   readonly role: "assistant" | "user" | "system";
   readonly status?: MessageStatus;
   readonly content: readonly AuiV0MessagePart[];
+  readonly attachments?: readonly AuiV0Attachment[];
   readonly metadata: {
     readonly unstable_state?: ReadonlyJSONValue;
     readonly unstable_annotations: readonly ReadonlyJSONValue[];
@@ -83,14 +106,59 @@ type AuiV0Message = {
   };
 };
 
+const encodeAttachmentPart = (
+  part: CompleteAttachment["content"][number],
+): AuiV0AttachmentPart => {
+  const type = part.type;
+  switch (type) {
+    case "text":
+    case "image":
+    case "file":
+    case "audio":
+      return part;
+
+    case "data": {
+      if (!isJSONValue(part.data)) {
+        console.warn(`attachment data is not JSON! ${JSON.stringify(part)}`);
+      }
+      return { ...part, data: part.data as ReadonlyJSONValue };
+    }
+
+    default: {
+      const unhandledType: never = type;
+      throw new Error(
+        `Attachment part type not supported by aui/v0: ${unhandledType}`,
+      );
+    }
+  }
+};
+
+const encodeAttachments = (
+  message: ThreadMessage,
+): readonly AuiV0Attachment[] | undefined => {
+  if (message.role !== "user" || message.attachments.length === 0) {
+    return undefined;
+  }
+
+  return message.attachments.map(
+    ({ id, type, name, contentType, status, content }) => ({
+      id,
+      type,
+      name,
+      status,
+      ...(contentType != null ? { contentType } : undefined),
+      content: content.map(encodeAttachmentPart),
+    }),
+  );
+};
+
 export function auiV0Encode(message: ThreadMessage): AuiV0Message {
-  // TODO attachments are currently intentionally ignored
   // info: ID and createdAt are ignored (we use the server value instead)
-
   const status: MessageStatus | undefined =
     message.status?.type === "running"
       ? { type: "incomplete", reason: "cancelled" }
       : message.status;
+  const attachments = encodeAttachments(message);
 
   return {
     role: message.role,
@@ -172,6 +240,7 @@ export function auiV0Encode(message: ThreadMessage): AuiV0Message {
     }),
     metadata: message.metadata as AuiV0Message["metadata"],
     ...(status ? { status } : undefined),
+    ...(attachments ? { attachments } : undefined),
   };
 }
 

package/src/react/runtimes/external-message-converter.test.tsx

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { useExternalMessageConverter } from "./external-message-converter";
+
+type TestMessage = {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+};
+
+type TestMetadata = useExternalMessageConverter.Metadata & {
+  optimisticMessageId?: string;
+};
+
+const convert: useExternalMessageConverter.Callback<TestMessage> = (
+  message,
+  metadata,
+) => ({
+  role: message.role,
+  id: message.id,
+  content: [{ type: "text", text: message.text }],
+  metadata: {
+    ...(message.role === "assistant" &&
+      message.id === (metadata as TestMetadata).optimisticMessageId && {
+        isOptimistic: true,
+      }),
+  },
+});
+
+const MESSAGES: TestMessage[] = [
+  { id: "u1", role: "user", text: "hi" },
+  { id: "a1", role: "assistant", text: "hello" },
+];
+
+const EMPTY: TestMetadata = {};
+
+type Props = {
+  callback?: useExternalMessageConverter.Callback<TestMessage>;
+  metadata?: TestMetadata;
+};
+
+const renderConverter = (initialProps: Props = {}) =>
+  renderHook(
+    ({ callback = convert, metadata = EMPTY }: Props) =>
+      useExternalMessageConverter<TestMessage>({
+        callback,
+        messages: MESSAGES,
+        isRunning: false,
+        metadata,
+      }),
+    { initialProps },
+  );
+
+describe("useExternalMessageConverter", () => {
+  it("reuses converted messages across rerenders when inputs are unchanged", () => {
+    const { result, rerender } = renderConverter();
+
+    const first = result.current;
+    rerender({});
+
+    expect(result.current[0]).toBe(first[0]);
+    expect(result.current[1]).toBe(first[1]);
+  });
+
+  it("re-converts cached messages when metadata changes", () => {
+    const { result, rerender } = renderConverter({
+      metadata: { optimisticMessageId: "a1" },
+    });
+
+    expect(result.current.at(-1)?.metadata.isOptimistic).toBe(true);
+
+    rerender({ metadata: {} });
+
+    expect(result.current.at(-1)?.metadata.isOptimistic).toBeUndefined();
+  });
+
+  it("re-converts cached messages when the callback changes", () => {
+    const upper: useExternalMessageConverter.Callback<TestMessage> = (
+      message,
+    ) => ({
+      role: message.role,
+      id: message.id,
+      content: [{ type: "text", text: message.text.toUpperCase() }],
+    });
+
+    const { result, rerender } = renderConverter();
+
+    expect(result.current[1]?.content[0]).toMatchObject({
+      type: "text",
+      text: "hello",
+    });
+
+    rerender({ callback: upper });
+
+    expect(result.current[1]?.content[0]).toMatchObject({
+      type: "text",
+      text: "HELLO",
+    });
+  });
+
+  it.each([
+    ["false", false],
+    ["zero", 0],
+    ["an empty string", ""],
+  ])("preserves %s assistant state", (_label, state) => {
+    const callback: useExternalMessageConverter.Callback<TestMessage> = (
+      message,
+    ) => ({
+      role: message.role,
+      id: message.id,
+      content: [{ type: "text", text: message.text }],
+      ...(message.role === "assistant"
+        ? { metadata: { unstable_state: state } }
+        : undefined),
+    });
+
+    const { result } = renderConverter({ callback });
+
+    expect(result.current[1]?.metadata.unstable_state).toBe(state);
+  });
+});

package/src/react/runtimes/external-message-converter.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
 import { ThreadMessageConverter } from "../../runtimes/external-store/thread-message-converter";
 import {
   getExternalStoreMessages,
@@ -76,6 +76,11 @@ type CallbackResult<T> = {
   outputs: useExternalMessageConverter.Message[];
 };
 
+type CallbackCacheEntry<T> = CallbackResult<T> & {
+  metadata: useExternalMessageConverter.Metadata;
+  callback: useExternalMessageConverter.Callback<T>;
+};
+
 type ChunkResult<T> = {
   inputs: T[];
   outputs: useExternalMessageConverter.Message[];
@@ -165,7 +170,7 @@ const joinExternalMessages = (
 
             if (output.metadata) {
               assistantMessage.metadata ??= {};
-              if (output.metadata.unstable_state) {
+              if (output.metadata.unstable_state !== undefined) {
                 assistantMessage.metadata.unstable_state =
                   output.metadata.unstable_state;
               }
@@ -404,28 +409,48 @@ export const useExternalMessageConverter = <T extends WeakKey>({
   joinStrategy?: JoinStrategy | undefined;
   metadata?: useExternalMessageConverter.Metadata | undefined;
 }) => {
+  // The caches live for the component lifetime; React Compiler hoists
+  // allocations without reactive dependencies out of useMemo, so re-creating
+  // them on dependency change would not survive compilation. Staleness is
+  // instead tracked per entry via the metadata/callback that produced it,
+  // keeping correctness independent of memoization (which React treats as
+  // droppable). A "use no memo" opt-out would restore the useMemo semantics
+  // but leave cache flushing coupled to memo firing.
+  const [caches] = useState(() => ({
+    callbackCache: new WeakMap<T, CallbackCacheEntry<T>>(),
+    chunkCache: new WeakMap<
+      useExternalMessageConverter.Message,
+      ChunkResult<T>
+    >(),
+    converterCache: new ThreadMessageConverter(),
+  }));
+
   const state = useMemo(
     () => ({
       metadata: metadata ?? {},
       callback,
-      callbackCache: new WeakMap<T, CallbackResult<T>>(),
-      chunkCache: new WeakMap<
-        useExternalMessageConverter.Message,
-        ChunkResult<T>
-      >(),
-      converterCache: new ThreadMessageConverter(),
+      ...caches,
     }),
-    [callback, metadata],
+    [callback, metadata, caches],
   );
 
   return useMemo(() => {
     const callbackResults: CallbackResult<T>[] = [];
     for (const message of messages) {
       let result = state.callbackCache.get(message);
-      if (!result) {
+      if (
+        !result ||
+        result.metadata !== state.metadata ||
+        result.callback !== state.callback
+      ) {
         const output = state.callback(message, state.metadata);
         const outputs = Array.isArray(output) ? output : [output];
-        result = { input: message, outputs };
+        result = {
+          input: message,
+          outputs,
+          metadata: state.metadata,
+          callback: state.callback,
+        };
         state.callbackCache.set(message, result);
       }
       callbackResults.push(result);

package/src/react/runtimes/useLocalRuntime.test.tsx

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+
+import { render, waitFor } from "@testing-library/react";
+import { StrictMode } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ChatModelAdapter } from "../../runtime/utils/chat-model-adapter";
+import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
+import { useLocalRuntime } from "./useLocalRuntime";
+
+const chatModel: ChatModelAdapter = {
+  run: async () => ({ content: [] }),
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("useLocalRuntime", () => {
+  it("handles rejected history loads", async () => {
+    const error = new Error("history unavailable");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const history = {
+      load: vi.fn().mockRejectedValue(error),
+      append: vi.fn().mockResolvedValue(undefined),
+    };
+
+    const App = () => {
+      const runtime = useLocalRuntime(chatModel, { adapters: { history } });
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <div />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    const renderApp = () => (
+      <StrictMode>
+        <App />
+      </StrictMode>
+    );
+    const { rerender } = render(renderApp());
+
+    await waitFor(() => {
+      expect(consoleError).toHaveBeenCalledWith(
+        "[assistant-ui] local thread history load failed:",
+        error,
+      );
+    });
+
+    rerender(renderApp());
+    expect(history.load).toHaveBeenCalledTimes(1);
+    expect(consoleError).toHaveBeenCalledTimes(1);
+  });
+});

package/src/react/runtimes/useLocalRuntime.ts

@@ -35,6 +35,7 @@ const useLocalThreadRuntime = (
   const [runtime] = useState(() => new LocalRuntimeCore(opt, initialMessages));
 
   const threadIdRef = useRef<string | undefined>(undefined);
+  const historyLoadPromiseRef = useRef<Promise<void> | undefined>(undefined);
   threadIdRef.current = useAuiState((s) => s.threadListItem.remoteId);
 
   useEffect(() => {
@@ -51,9 +52,20 @@ const useLocalThreadRuntime = (
 
   useEffect(() => {
     runtime.threads.getMainThreadRuntimeCore().__internal_setOptions(opt);
-    runtime.threads.getMainThreadRuntimeCore().__internal_load();
   });
 
+  useEffect(() => {
+    const loadPromise = runtime.threads
+      .getMainThreadRuntimeCore()
+      .__internal_load();
+    if (historyLoadPromiseRef.current === loadPromise) return;
+
+    historyLoadPromiseRef.current = loadPromise;
+    void loadPromise.catch((error: unknown) => {
+      console.error("[assistant-ui] local thread history load failed:", error);
+    });
+  }, [runtime]);
+
   useEffect(() => {
     if (!modelContext) return undefined;
     return runtime.registerModelContextProvider(modelContext);