@assistant-ui/core 0.1.15 → 0.1.16

package/src/react/runtimes/RemoteThreadListThreadListRuntimeCore.tsx

@@ -15,14 +15,7 @@ import {
 } from "../../runtimes/remote-thread-list/remote-thread-state";
 import type { RemoteThreadListOptions } from "../../runtimes/remote-thread-list/types";
 import { RemoteThreadListHookInstanceManager } from "./RemoteThreadListHookInstanceManager";
-import {
-  type ComponentType,
-  type FC,
-  Fragment,
-  type PropsWithChildren,
-  useEffect,
-  useId,
-} from "react";
+import { type FC, Fragment, useEffect, useId } from "react";
 import { create } from "zustand";
 import { AssistantMessageStream } from "assistant-stream";
 import type { ModelContextProvider } from "../../model-context/types";
@@ -98,6 +91,7 @@ export class RemoteThreadListThreadListRuntimeCore
                 externalId: thread.externalId,
                 status: thread.status,
                 title: thread.title,
+                custom: thread.custom,
                 initializeTask: Promise.resolve({
                   remoteId: thread.remoteId,
                   externalId: thread.externalId,
@@ -150,8 +144,7 @@ export class RemoteThreadListThreadListRuntimeCore
       this,
     );
     this.useProvider = create(() => ({
-      Provider: (options.adapter.unstable_Provider ??
-        Fragment) as ComponentType<PropsWithChildren>,
+      Provider: options.adapter.unstable_Provider ?? Fragment,
     }));
     this.__internal_setOptions(options);
     this.switchToNewThread();
@@ -165,8 +158,7 @@ export class RemoteThreadListThreadListRuntimeCore
 
     this._options = options;
 
-    const Provider = (options.adapter.unstable_Provider ??
-      Fragment) as ComponentType<PropsWithChildren>;
+    const Provider = options.adapter.unstable_Provider ?? Fragment;
     if (Provider !== this.useProvider.getState().Provider) {
       this.useProvider.setState({ Provider }, true);
     }
@@ -250,6 +242,7 @@ export class RemoteThreadListThreadListRuntimeCore
           externalId: remoteMetadata.externalId,
           status: remoteMetadata.status,
           title: remoteMetadata.title,
+          custom: remoteMetadata.custom,
         } as RemoteThreadData,
       };
 
@@ -335,6 +328,7 @@ export class RemoteThreadListThreadListRuntimeCore
             remoteId: undefined,
             externalId: undefined,
             title: undefined,
+            custom: undefined,
           } satisfies RemoteThreadData,
         },
       });

package/src/runtime/api/bindings.ts

@@ -47,4 +47,5 @@ export type ThreadListItemState = {
   readonly externalId: string | undefined;
   readonly status: import("../interfaces/thread-list-runtime-core").ThreadListItemStatus;
   readonly title?: string | undefined;
+  readonly custom?: Record<string, unknown> | undefined;
 };

package/src/runtime/api/composer-runtime.ts

@@ -136,8 +136,10 @@ export type ComposerRuntime = {
   /**
    * Add an attachment to the composer. Accepts either a standard File object
    * (processed through the AttachmentAdapter) or a CreateAttachment descriptor
-   * for external-source attachments (URLs, API data, CMS references) that
-   * bypasses the adapter entirely.
+   * for external-source attachments (URLs, API data, CMS references). External
+   * descriptors bypass the adapter's `add()` step but still respect
+   * `adapter.accept` when an adapter is configured; without an adapter they
+   * are added as-is.
    * @param fileOrAttachment The file or attachment descriptor to add.
    */
   addAttachment(fileOrAttachment: File | CreateAttachment): Promise<void>;

package/src/runtime/api/thread-list-runtime.ts

@@ -80,6 +80,7 @@ const getThreadListItemState = (
     externalId: threadData.externalId,
     title: threadData.title,
     status: threadData.status,
+    custom: threadData.custom,
     isMain: threadData.id === threadList.mainThreadId,
   };
 };

package/src/runtime/base/base-composer-runtime-core.ts

@@ -204,6 +204,27 @@ export abstract class BaseComposerRuntimeCore
 
   async addAttachment(fileOrAttachment: File | CreateAttachment) {
     if (!(fileOrAttachment instanceof File)) {
+      const adapter = this.getAttachmentAdapter();
+      if (
+        adapter &&
+        !fileMatchesAccept(
+          {
+            name: fileOrAttachment.name,
+            type: fileOrAttachment.contentType ?? "",
+          },
+          adapter.accept,
+        )
+      ) {
+        try {
+          this._notifyEventSubscribers("attachmentAddError");
+        } catch {
+          // prevent subscriber errors from masking the original error
+        }
+        throw new Error(
+          `File type ${fileOrAttachment.contentType || "unknown"} is not accepted. Accepted types: ${adapter.accept}`,
+        );
+      }
+
       const a: CompleteAttachment = {
         id: fileOrAttachment.id ?? generateId(),
         type: fileOrAttachment.type ?? "document",
@@ -213,25 +234,11 @@ export abstract class BaseComposerRuntimeCore
         status: { type: "complete" },
       };
       this._attachments = [...this._attachments, a];
-      this._notifyEventSubscribers("attachmentAdd");
       this._notifySubscribers();
+      this._notifyEventSubscribers("attachmentAdd");
       return;
     }
 
-    const adapter = this.getAttachmentAdapter();
-    if (!adapter) throw new Error("Attachments are not supported");
-
-    if (
-      !fileMatchesAccept(
-        { name: fileOrAttachment.name, type: fileOrAttachment.type },
-        adapter.accept,
-      )
-    ) {
-      throw new Error(
-        `File type ${fileOrAttachment.type || "unknown"} is not accepted. Accepted types: ${adapter.accept}`,
-      );
-    }
-
     const upsertAttachment = (a: PendingAttachment) => {
       const idx = this._attachments.findIndex(
         (attachment) => attachment.id === a.id,
@@ -251,6 +258,20 @@ export abstract class BaseComposerRuntimeCore
 
     let lastAttachment: PendingAttachment | undefined;
     try {
+      const adapter = this.getAttachmentAdapter();
+      if (!adapter) throw new Error("Attachments are not supported");
+
+      if (
+        !fileMatchesAccept(
+          { name: fileOrAttachment.name, type: fileOrAttachment.type },
+          adapter.accept,
+        )
+      ) {
+        throw new Error(
+          `File type ${fileOrAttachment.type || "unknown"} is not accepted. Accepted types: ${adapter.accept}`,
+        );
+      }
+
       const promiseOrGenerator = adapter.add({ file: fileOrAttachment });
       if (Symbol.asyncIterator in promiseOrGenerator) {
         for await (const r of promiseOrGenerator) {
@@ -271,7 +292,7 @@ export abstract class BaseComposerRuntimeCore
       try {
         this._notifyEventSubscribers("attachmentAddError");
       } catch {
-        // prevent subscriber errors from masking the adapter error
+        // prevent subscriber errors from masking the original error
       }
       throw e;
     }

package/src/runtime/interfaces/thread-list-runtime-core.ts

@@ -10,6 +10,7 @@ export type ThreadListItemCoreState = {
 
   readonly status: ThreadListItemStatus;
   readonly title?: string | undefined;
+  readonly custom?: Record<string, unknown> | undefined;
 
   readonly runtime?: ThreadRuntimeCore | undefined;
 };

package/src/runtimes/remote-thread-list/remote-thread-state.ts

@@ -7,6 +7,7 @@ export type RemoteThreadData =
       readonly externalId: undefined;
       readonly status: "new";
       readonly title: undefined;
+      readonly custom: undefined;
     }
   | {
       readonly id: string;
@@ -15,6 +16,7 @@ export type RemoteThreadData =
       readonly externalId: undefined;
       readonly status: "regular" | "archived";
       readonly title?: string | undefined;
+      readonly custom: undefined;
     }
   | {
       readonly id: string;
@@ -23,6 +25,7 @@ export type RemoteThreadData =
       readonly externalId: string | undefined;
       readonly status: "regular" | "archived";
       readonly title?: string | undefined;
+      readonly custom?: Record<string, unknown> | undefined;
     };
 
 export type THREAD_MAPPING_ID = string & { __brand: "THREAD_MAPPING_ID" };

package/src/runtimes/remote-thread-list/types.ts

@@ -1,3 +1,4 @@
+import type { ComponentType, PropsWithChildren } from "react";
 import type { ThreadMessage } from "../../types/message";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import type { AssistantStream } from "assistant-stream";
@@ -12,6 +13,7 @@ export type RemoteThreadMetadata = {
   readonly remoteId: string;
   readonly externalId?: string | undefined;
   readonly title?: string | undefined;
+  readonly custom?: Record<string, unknown> | undefined;
 };
 
 export type RemoteThreadListResponse = {
@@ -32,7 +34,17 @@ export type RemoteThreadListAdapter = {
   ): Promise<AssistantStream>;
   fetch(threadId: string): Promise<RemoteThreadMetadata>;
 
-  unstable_Provider?: ((...args: any[]) => unknown) | undefined;
+  /**
+   * Optional React component wrapped around each active thread. Use it to
+   * inject per-thread context such as a history or attachments adapter (see
+   * `useCloudThreadListAdapter` for the canonical shape).
+   *
+   * The Provider must render `children` on its first commit; deferring them
+   * behind a loading state, a Suspense boundary, or a `useEffect`-gated render
+   * is unsupported and leaves thread context unavailable to downstream
+   * consumers. Load data inside an always-mounted child instead.
+   */
+  unstable_Provider?: ComponentType<PropsWithChildren> | undefined;
 };
 
 export type RemoteThreadListOptions = {

package/src/store/scopes/thread-list-item.ts

@@ -7,6 +7,7 @@ export type ThreadListItemState = {
   readonly externalId: string | undefined;
   readonly title?: string | undefined;
   readonly status: ThreadListItemStatus;
+  readonly custom?: Record<string, unknown> | undefined;
 };
 
 export type ThreadListItemMethods = {

package/src/tests/RemoteThreadListThreadListRuntimeCore-custom-metadata.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, vi } from "vitest";
+import { createCore, makeAdapter } from "./remote-thread-list-test-helpers";
+
+describe("RemoteThreadListThreadListRuntimeCore custom metadata", () => {
+  it("preserves custom field from list() through to threadItems", async () => {
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [
+          {
+            status: "regular" as const,
+            remoteId: "thread-1",
+            externalId: "ext-1",
+            title: "Test",
+            custom: { workspaceId: "ws-1", createdAt: "2026-04-26" },
+          },
+        ],
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    const item = core.getItemById("thread-1");
+    expect(item?.custom).toEqual({
+      workspaceId: "ws-1",
+      createdAt: "2026-04-26",
+    });
+  });
+
+  it("preserves custom field from fetch() through switchToThread", async () => {
+    const adapter = makeAdapter({
+      fetch: vi.fn(async (id: string) => ({
+        status: "regular" as const,
+        remoteId: id,
+        externalId: id,
+        title: "Test",
+        custom: { ownerId: "user-42" },
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.switchToThread("thread-2");
+
+    const item = core.getItemById("thread-2");
+    expect(item?.custom).toEqual({ ownerId: "user-42" });
+  });
+
+  it("leaves custom undefined when adapter omits it", async () => {
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [
+          {
+            status: "regular" as const,
+            remoteId: "thread-3",
+            externalId: "ext-3",
+            title: "Test",
+          },
+        ],
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    const item = core.getItemById("thread-3");
+    expect(item?.custom).toBeUndefined();
+  });
+
+  it("preserves custom across rename optimistic update", async () => {
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [
+          {
+            status: "regular" as const,
+            remoteId: "thread-4",
+            externalId: "ext-4",
+            title: "Old",
+            custom: { tag: "important" },
+          },
+        ],
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+    await core.rename("thread-4", "New");
+
+    const item = core.getItemById("thread-4");
+    expect(item?.title).toBe("New");
+    expect(item?.custom).toEqual({ tag: "important" });
+  });
+
+  it("preserves custom across archive and unarchive optimistic updates", async () => {
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [
+          {
+            status: "regular" as const,
+            remoteId: "thread-5",
+            externalId: "ext-5",
+            title: "Test",
+            custom: { workspaceId: "ws-1" },
+          },
+        ],
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    await core.archive("thread-5");
+    expect(core.getItemById("thread-5")?.status).toBe("archived");
+    expect(core.getItemById("thread-5")?.custom).toEqual({
+      workspaceId: "ws-1",
+    });
+
+    await core.unarchive("thread-5");
+    expect(core.getItemById("thread-5")?.status).toBe("regular");
+    expect(core.getItemById("thread-5")?.custom).toEqual({
+      workspaceId: "ws-1",
+    });
+  });
+});

package/src/tests/base-composer-runtime-core-addAttachment.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } from "vitest";
+import { DefaultThreadComposerRuntimeCore } from "../runtime/base/default-thread-composer-runtime-core";
+import type { AttachmentAdapter } from "../adapters/attachment";
+import type { ThreadRuntimeCore } from "../runtime/interfaces/thread-runtime-core";
+import type { PendingAttachment } from "../types/attachment";
+
+const makeAdapter = (
+  overrides: Partial<AttachmentAdapter> = {},
+): AttachmentAdapter => ({
+  accept: "image/*",
+  add: async ({ file }: { file: File }): Promise<PendingAttachment> => ({
+    id: "att-1",
+    type: "image",
+    name: file.name,
+    contentType: file.type,
+    file,
+    status: { type: "running", reason: "uploading", progress: 0 },
+  }),
+  remove: async () => {},
+  send: async (a) => ({ ...a, status: { type: "complete" }, content: [] }),
+  ...overrides,
+});
+
+const makeComposer = (adapter?: AttachmentAdapter) => {
+  const runtime = {
+    append: vi.fn(),
+    cancelRun: vi.fn(),
+    subscribe: vi.fn(() => () => {}),
+    capabilities: { cancel: false },
+    messages: [],
+    adapters: adapter ? { attachments: adapter } : undefined,
+  } as unknown as Omit<ThreadRuntimeCore, "composer"> & {
+    adapters?: { attachments?: AttachmentAdapter };
+  };
+  return new DefaultThreadComposerRuntimeCore(runtime);
+};
+
+describe("BaseComposerRuntimeCore.addAttachment error events", () => {
+  it("emits attachmentAddError when no adapter is configured", async () => {
+    const composer = makeComposer();
+    const onError = vi.fn();
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAddError", onError);
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    await expect(
+      composer.addAttachment(new File(["x"], "f.txt", { type: "text/plain" })),
+    ).rejects.toThrow("Attachments are not supported");
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onAdd).not.toHaveBeenCalled();
+  });
+
+  it("emits attachmentAddError when file type is rejected by adapter.accept", async () => {
+    const composer = makeComposer(makeAdapter());
+    const onError = vi.fn();
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAddError", onError);
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    await expect(
+      composer.addAttachment(new File(["x"], "f.txt", { type: "text/plain" })),
+    ).rejects.toThrow(/File type text\/plain is not accepted/);
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onAdd).not.toHaveBeenCalled();
+  });
+
+  it("emits attachmentAddError when adapter.add throws", async () => {
+    const composer = makeComposer(
+      makeAdapter({
+        add: async () => {
+          throw new Error("upload failed");
+        },
+      }),
+    );
+    const onError = vi.fn();
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAddError", onError);
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    await expect(
+      composer.addAttachment(new File(["x"], "f.png", { type: "image/png" })),
+    ).rejects.toThrow("upload failed");
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onAdd).not.toHaveBeenCalled();
+  });
+
+  it("emits attachmentAdd on successful add", async () => {
+    const composer = makeComposer(makeAdapter());
+    const onError = vi.fn();
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAddError", onError);
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    await composer.addAttachment(
+      new File(["x"], "f.png", { type: "image/png" }),
+    );
+
+    expect(onAdd).toHaveBeenCalledTimes(1);
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("does not let subscriber errors mask the original throw", async () => {
+    const composer = makeComposer(makeAdapter());
+    composer.unstable_on("attachmentAddError", () => {
+      throw new Error("subscriber boom");
+    });
+
+    await expect(
+      composer.addAttachment(new File(["x"], "f.txt", { type: "text/plain" })),
+    ).rejects.toThrow(/File type text\/plain is not accepted/);
+  });
+
+  it("emits attachmentAddError when async generator adapter throws mid-iteration", async () => {
+    const composer = makeComposer(
+      makeAdapter({
+        async *add({ file }: { file: File }) {
+          yield {
+            id: "att-1",
+            type: "image" as const,
+            name: file.name,
+            contentType: file.type,
+            file,
+            status: {
+              type: "running" as const,
+              reason: "uploading" as const,
+              progress: 0,
+            },
+          };
+          throw new Error("network error");
+        },
+      }),
+    );
+    const onError = vi.fn();
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAddError", onError);
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    await expect(
+      composer.addAttachment(new File(["x"], "f.png", { type: "image/png" })),
+    ).rejects.toThrow("network error");
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onAdd).not.toHaveBeenCalled();
+    expect(composer.attachments).toHaveLength(1);
+    const att = composer.attachments[0]!;
+    expect(att.status.type).toBe("incomplete");
+    if (att.status.type === "incomplete") {
+      expect(att.status.reason).toBe("error");
+    }
+  });
+});