@assistant-ui/core 0.1.15 → 0.1.17

package/src/react/runtimes/RemoteThreadListHookInstanceManager.tsx

@@ -1,12 +1,15 @@
 import {
   type FC,
+  type RefObject,
   useCallback,
   useRef,
   useEffect,
+  useLayoutEffect,
   memo,
   type PropsWithChildren,
   type ComponentType,
   useMemo,
+  Fragment,
 } from "react";
 import { type UseBoundStore, type StoreApi, create } from "zustand";
 import { useAui } from "@assistant-ui/store";
@@ -23,6 +26,15 @@ type RemoteThreadListHook = () => AssistantRuntime;
 type RemoteThreadListHookInstance = {
   runtime?: ThreadRuntimeCore;
 };
+
+const ProviderRenderDetector: FC<{
+  detectorRef: RefObject<boolean>;
+}> = ({ detectorRef }) => {
+  useLayoutEffect(() => {
+    detectorRef.current = true;
+  }, [detectorRef]);
+  return null;
+};
 export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
   private useRuntimeHook: UseBoundStore<
     StoreApi<{ useRuntime: RemoteThreadListHook }>
@@ -82,9 +94,11 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
     }
   }
 
-  private _InnerActiveThreadProvider: FC<{
-    threadId: string;
-  }> = ({ threadId }) => {
+  // Rendered outside the user's Provider so deferred `children` cannot strand the binding.
+  private _RuntimeBinder: FC<PropsWithChildren<{ threadId: string }>> = ({
+    threadId,
+    children,
+  }) => {
     const { useRuntime } = this.useRuntimeHook();
     const runtime = useRuntime();
 
@@ -138,7 +152,7 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
       });
     }, [runtime, aui]);
 
-    return null;
+    return <>{children}</>;
   };
 
   private _OuterActiveThreadProvider: FC<{
@@ -150,11 +164,30 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
       [threadId],
     );
 
+    const detectorRef = useRef(false);
+    useEffect(() => {
+      if (process.env.NODE_ENV !== "production" && Provider !== Fragment) {
+        const id = setTimeout(() => {
+          if (!detectorRef.current) {
+            console.warn(
+              "RemoteThreadListAdapter.unstable_Provider did not render its `children` synchronously. " +
+                "Render `children` on first commit; deferring them behind a loading state, Suspense boundary, " +
+                "or `useEffect` gate leaves thread context unavailable to downstream consumers.",
+            );
+          }
+        }, 100);
+        return () => clearTimeout(id);
+      }
+      return undefined;
+    }, [Provider]);
+
     return (
       <ThreadListItemRuntimeProvider runtime={runtime}>
-        <Provider>
-          <this._InnerActiveThreadProvider threadId={threadId} />
-        </Provider>
+        <this._RuntimeBinder threadId={threadId}>
+          <Provider>
+            <ProviderRenderDetector detectorRef={detectorRef} />
+          </Provider>
+        </this._RuntimeBinder>
       </ThreadListItemRuntimeProvider>
     );
   });

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/react/utils/groupParts.ts

@@ -0,0 +1,152 @@
+/**
+ * Hierarchical adjacent-coalescing grouping for message parts.
+ *
+ * Given a group path per part (from `groupBy`), builds a tree of group
+ * nodes wrapping individual parts. Adjacent parts sharing a path prefix
+ * coalesce into the same group; ungrouped parts are direct children of
+ * the root.
+ *
+ * Each node gets a structural `nodeKey` built from sibling indices
+ * (`"0.1.0"`), stable under append-only streaming.
+ */
+
+/**
+ * Public group key type. Group keys must be prefixed with `group-` so
+ * that a unified `switch (part.type)` in the renderer can distinguish
+ * a group key (e.g. `"group-thought"`) from a real part type
+ * (`"text"`, `"tool-call"`).
+ */
+export type GroupKey<TKey extends `group-${string}` = `group-${string}`> =
+  | TKey
+  | readonly TKey[]
+  | null
+  | undefined;
+
+export type GroupNode = GroupNodeGroup | GroupNodePart;
+
+export interface GroupNodeGroup {
+  readonly type: "group";
+  /** Current-level group key (last segment of the path). */
+  readonly key: string;
+  /** Structural React key: sibling-index path, e.g. `"0.1.0"`. */
+  readonly nodeKey: string;
+  /** Indices of parts in this subtree, in order. */
+  readonly indices: readonly number[];
+  readonly children: readonly GroupNode[];
+}
+
+export interface GroupNodePart {
+  readonly type: "part";
+  /** Index of the part in the message. */
+  readonly index: number;
+  /** Structural React key: sibling-index path within parent. */
+  readonly nodeKey: string;
+}
+
+const EMPTY_PATH: readonly string[] = Object.freeze([]);
+
+/**
+ * Normalize a `groupBy` return value to a path array.
+ * `null`/`undefined`/`[]` → `[]` (ungrouped).
+ * `"foo"` → `["foo"]`. Arrays pass through.
+ */
+export const normalizeGroupKey = (key: GroupKey): readonly string[] => {
+  if (key == null) return EMPTY_PATH;
+  if (typeof key === "string") return [key];
+  return key;
+};
+
+interface BuildFrame {
+  key: string;
+  nodeKey: string;
+  indices: number[];
+  children: GroupNode[];
+  nextChildIdx: number;
+}
+
+const makeChildNodeKey = (parent: BuildFrame): string => {
+  const idx = parent.nextChildIdx++;
+  return parent.nodeKey === "" ? String(idx) : `${parent.nodeKey}.${idx}`;
+};
+
+/**
+ * Build the group tree from an array of normalized group paths.
+ * `paths[i]` is the path for part `i`. The output tree contains one
+ * `part` node per part and one `group` node per coalesced run.
+ */
+export const buildGroupTree = (
+  paths: readonly (readonly string[])[],
+): readonly GroupNode[] => {
+  const root: BuildFrame = {
+    key: "",
+    nodeKey: "",
+    indices: [],
+    children: [],
+    nextChildIdx: 0,
+  };
+  const stack: BuildFrame[] = [root];
+
+  const closeTop = (): void => {
+    const closing = stack.pop()!;
+    const parent = stack[stack.length - 1]!;
+    parent.children.push({
+      type: "group",
+      key: closing.key,
+      nodeKey: closing.nodeKey,
+      indices: closing.indices,
+      children: closing.children,
+    });
+  };
+
+  for (let i = 0; i < paths.length; i++) {
+    const path = paths[i]!;
+
+    // Find the longest prefix shared between currently-open groups
+    // (excluding root) and this part's path.
+    let common = 0;
+    while (
+      common < stack.length - 1 &&
+      common < path.length &&
+      stack[common + 1]!.key === path[common]
+    ) {
+      common++;
+    }
+
+    // Close groups not on this path.
+    while (stack.length - 1 > common) {
+      closeTop();
+    }
+
+    // Open new groups down to the part's depth.
+    while (stack.length - 1 < path.length) {
+      const parent = stack[stack.length - 1]!;
+      stack.push({
+        key: path[stack.length - 1]!,
+        nodeKey: makeChildNodeKey(parent),
+        indices: [],
+        children: [],
+        nextChildIdx: 0,
+      });
+    }
+
+    // Push this part as a leaf in the deepest open group (or root).
+    const top = stack[stack.length - 1]!;
+    top.children.push({
+      type: "part",
+      index: i,
+      nodeKey: makeChildNodeKey(top),
+    });
+
+    // Record the part index in every open ancestor group.
+    for (let s = 1; s < stack.length; s++) {
+      stack[s]!.indices.push(i);
+    }
+  }
+
+  // Close any still-open groups.
+  while (stack.length > 1) {
+    closeTop();
+  }
+
+  return root.children;
+};

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

@@ -12,6 +12,7 @@ import {
   SKIP_UPDATE,
 } from "../../subscribable/subscribable";
 import type {
+  ComposerRuntimeEventCallback,
   ComposerRuntimeEventType,
   DictationState,
   EditComposerRuntimeCore,
@@ -136,8 +137,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>;
@@ -220,9 +223,9 @@ export type ComposerRuntime = {
   /**
    * @deprecated This API is still under active development and might change without notice.
    */
-  unstable_on(
-    event: ComposerRuntimeEventType,
-    callback: () => void,
+  unstable_on<E extends ComposerRuntimeEventType>(
+    event: E,
+    callback: ComposerRuntimeEventCallback<E>,
   ): Unsubscribe;
 };
 
@@ -330,19 +333,19 @@ export abstract class ComposerRuntimeImpl implements ComposerRuntime {
     EventSubscriptionSubject<ComposerRuntimeEventType>
   >();
 
-  public unstable_on(
-    event: ComposerRuntimeEventType,
-    callback: () => void,
+  public unstable_on<E extends ComposerRuntimeEventType>(
+    event: E,
+    callback: ComposerRuntimeEventCallback<E>,
   ): Unsubscribe {
     let subject = this._eventSubscriptionSubjects.get(event);
     if (!subject) {
-      subject = new EventSubscriptionSubject({
-        event: event,
+      subject = new EventSubscriptionSubject<ComposerRuntimeEventType>({
+        event,
         binding: this._core,
       });
       this._eventSubscriptionSubjects.set(event, subject);
     }
-    return subject.subscribe(callback);
+    return subject.subscribe(callback as (payload?: unknown) => void);
   }
 
   public abstract getAttachmentByIndex(idx: number): AttachmentRuntime;

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

@@ -3,7 +3,26 @@ import type { SubscribableWithState } from "../../subscribable/subscribable";
 import type { ThreadListItemRuntimePath } from "./paths";
 import type { ThreadListRuntimeCoreBinding } from "./thread-list-runtime";
 
-export type ThreadListItemEventType = "switchedTo" | "switchedAway";
+export type ThreadListItemEventPayload = {
+  /**
+   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
+   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
+   * compatibility.
+   */
+  switchedTo: Record<string, never>;
+  /**
+   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
+   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
+   * compatibility.
+   */
+  switchedAway: Record<string, never>;
+};
+
+export type ThreadListItemEventType = keyof ThreadListItemEventPayload;
+
+export type ThreadListItemEventCallback<E extends ThreadListItemEventType> = (
+  payload: ThreadListItemEventPayload[E],
+) => void;
 
 import type { ThreadListItemState } from "./bindings";
 import type { ThreadListItemStatus } from "../interfaces/thread-list-runtime-core";
@@ -27,9 +46,9 @@ export type ThreadListItemRuntime = {
 
   subscribe(callback: () => void): Unsubscribe;
 
-  unstable_on(
-    event: ThreadListItemEventType,
-    callback: () => void,
+  unstable_on<E extends ThreadListItemEventType>(
+    event: E,
+    callback: ThreadListItemEventCallback<E>,
   ): Unsubscribe;
 
   __internal_getRuntime(): ThreadListItemRuntime;
@@ -112,7 +131,10 @@ export class ThreadListItemRuntimeImpl implements ThreadListItemRuntime {
     return this._threadListBinding.generateTitle(state.id);
   }
 
-  public unstable_on(event: ThreadListItemEventType, callback: () => void) {
+  public unstable_on<E extends ThreadListItemEventType>(
+    event: E,
+    callback: ThreadListItemEventCallback<E>,
+  ) {
     let prevIsMain = this._core.getState().isMain;
     let prevThreadId = this._core.getState().id;
     return this.subscribe(() => {
@@ -125,7 +147,7 @@ export class ThreadListItemRuntimeImpl implements ThreadListItemRuntime {
 
       if (event === "switchedTo" && !newIsMain) return;
       if (event === "switchedAway" && newIsMain) return;
-      callback();
+      (callback as (payload?: unknown) => 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/api/thread-runtime.ts

@@ -4,6 +4,7 @@ import type {
   ThreadRuntimeCore,
   SpeechState,
   VoiceSessionState,
+  ThreadRuntimeEventCallback,
   ThreadRuntimeEventType,
   StartRunConfig,
   ResumeRunConfig,
@@ -329,7 +330,10 @@ export type ThreadRuntime = {
   muteVoice(): void;
   unmuteVoice(): void;
 
-  unstable_on(event: ThreadRuntimeEventType, callback: () => void): Unsubscribe;
+  unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
+  ): Unsubscribe;
 };
 
 export class ThreadRuntimeImpl implements ThreadRuntime {
@@ -601,18 +605,18 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     EventSubscriptionSubject<ThreadRuntimeEventType>
   >();
 
-  public unstable_on(
-    event: ThreadRuntimeEventType,
-    callback: () => void,
+  public unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
   ): Unsubscribe {
     let subject = this._eventSubscriptionSubjects.get(event);
     if (!subject) {
-      subject = new EventSubscriptionSubject({
-        event: event,
+      subject = new EventSubscriptionSubject<ThreadRuntimeEventType>({
+        event,
         binding: this._threadBinding,
       });
       this._eventSubscriptionSubjects.set(event, subject);
     }
-    return subject.subscribe(callback);
+    return subject.subscribe(callback as (payload?: unknown) => void);
   }
 }

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

@@ -14,7 +14,10 @@ import {
   fileMatchesAccept,
 } from "../../adapters/attachment";
 import type {
+  AttachmentAddErrorReason,
   ComposerRuntimeCore,
+  ComposerRuntimeEventCallback,
+  ComposerRuntimeEventPayload,
   ComposerRuntimeEventType,
   DictationState,
   SendOptions,
@@ -189,7 +192,7 @@ export abstract class BaseComposerRuntimeCore
     };
 
     this.handleSend(message, options);
-    this._notifyEventSubscribers("send");
+    this._notifyEventSubscribers("send", {});
   }
 
   public cancel() {
@@ -204,6 +207,28 @@ 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,
+        )
+      ) {
+        const message = `File type ${fileOrAttachment.contentType || "unknown"} is not accepted. Accepted types: ${adapter.accept}`;
+        const err = new Error(message);
+        this._safeEmitAttachmentAddError(
+          "not-accepted",
+          message,
+          undefined,
+          err,
+        );
+        throw err;
+      }
+
       const a: CompleteAttachment = {
         id: fileOrAttachment.id ?? generateId(),
         type: fileOrAttachment.type ?? "document",
@@ -213,25 +238,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,
@@ -249,6 +260,26 @@ export abstract class BaseComposerRuntimeCore
       this._notifySubscribers();
     };
 
+    const adapter = this.getAttachmentAdapter();
+    if (!adapter) {
+      const message = "Attachments are not supported";
+      const err = new Error(message);
+      this._safeEmitAttachmentAddError("no-adapter", message, undefined, err);
+      throw err;
+    }
+
+    if (
+      !fileMatchesAccept(
+        { name: fileOrAttachment.name, type: fileOrAttachment.type },
+        adapter.accept,
+      )
+    ) {
+      const message = `File type ${fileOrAttachment.type || "unknown"} is not accepted. Accepted types: ${adapter.accept}`;
+      const err = new Error(message);
+      this._safeEmitAttachmentAddError("not-accepted", message, undefined, err);
+      throw err;
+    }
+
     let lastAttachment: PendingAttachment | undefined;
     try {
       const promiseOrGenerator = adapter.add({ file: fileOrAttachment });
@@ -268,20 +299,48 @@ export abstract class BaseComposerRuntimeCore
           status: { type: "incomplete", reason: "error" },
         });
       }
-      try {
-        this._notifyEventSubscribers("attachmentAddError");
-      } catch {
-        // prevent subscriber errors from masking the adapter error
-      }
+      this._safeEmitAttachmentAddError(
+        "adapter-error",
+        e instanceof Error ? e.message : String(e),
+        lastAttachment?.id,
+        e instanceof Error ? e : undefined,
+      );
       throw e;
     }
 
     const hasError =
       lastAttachment?.status.type === "incomplete" &&
       lastAttachment.status.reason === "error";
-    this._notifyEventSubscribers(
-      hasError ? "attachmentAddError" : "attachmentAdd",
-    );
+    if (hasError) {
+      this._safeEmitAttachmentAddError(
+        "adapter-error",
+        "Attachment upload did not complete successfully.",
+        lastAttachment?.id,
+      );
+    } else {
+      this._notifyEventSubscribers("attachmentAdd", {});
+    }
+  }
+
+  private _safeEmitAttachmentAddError(
+    reason: AttachmentAddErrorReason,
+    message: string,
+    attachmentId?: string,
+    error?: Error,
+  ) {
+    try {
+      this._notifyEventSubscribers("attachmentAddError", {
+        reason,
+        message,
+        ...(attachmentId !== undefined && { attachmentId }),
+        ...(error !== undefined && { error }),
+      });
+    } catch (subscriberError) {
+      console.error(
+        "[assistant-ui] attachmentAddError subscriber threw:",
+        subscriberError,
+      );
+    }
   }
 
   async removeAttachment(attachmentId: string) {
@@ -450,28 +509,33 @@ export abstract class BaseComposerRuntimeCore
 
   private _eventSubscribers = new Map<
     ComposerRuntimeEventType,
-    Set<() => void>
+    Set<(payload?: unknown) => void>
   >();
 
-  protected _notifyEventSubscribers(event: ComposerRuntimeEventType) {
+  protected _notifyEventSubscribers<E extends ComposerRuntimeEventType>(
+    event: E,
+    payload: ComposerRuntimeEventPayload[E],
+  ) {
     const subscribers = this._eventSubscribers.get(event);
     if (!subscribers) return;
 
-    for (const callback of subscribers) callback();
+    for (const callback of subscribers) callback(payload);
   }
 
-  public unstable_on(event: ComposerRuntimeEventType, callback: () => void) {
-    const subscribers = this._eventSubscribers.get(event);
+  public unstable_on<E extends ComposerRuntimeEventType>(
+    event: E,
+    callback: ComposerRuntimeEventCallback<E>,
+  ) {
+    const wrapped = callback as (payload?: unknown) => void;
+    let subscribers = this._eventSubscribers.get(event);
     if (!subscribers) {
-      this._eventSubscribers.set(event, new Set([callback]));
-    } else {
-      subscribers.add(callback);
+      subscribers = new Set();
+      this._eventSubscribers.set(event, subscribers);
     }
+    subscribers.add(wrapped);
 
     return () => {
-      const subscribers = this._eventSubscribers.get(event);
-      if (!subscribers) return;
-      subscribers.delete(callback);
+      this._eventSubscribers.get(event)?.delete(wrapped);
     };
   }
 }