@assistant-ui/react 0.10.26 → 0.10.28

package/src/api/ThreadRuntime.ts

@@ -9,6 +9,7 @@ import {
 } from "../runtimes/core/ThreadRuntimeCore";
 import { ExportedMessageRepository } from "../runtimes/utils/MessageRepository";
 import { AppendMessage, ThreadMessage, Unsubscribe } from "../types";
+import { ThreadMessageLike } from "../runtimes/external-store";
 import {
   MessageRuntime,
   MessageRuntimeImpl,
@@ -266,6 +267,14 @@ export type ThreadRuntime = {
 
   export(): ExportedMessageRepository;
   import(repository: ExportedMessageRepository): void;
+
+  /**
+   * Reset the thread with optional initial messages.
+   *
+   * @param initialMessages - Optional array of initial messages to populate the thread
+   */
+  reset(initialMessages?: readonly ThreadMessageLike[]): void;
+
   getMesssageByIndex(idx: number): MessageRuntime;
   getMesssageById(messageId: string): MessageRuntime;
 
@@ -340,6 +349,7 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     this.stopSpeaking = this.stopSpeaking.bind(this);
     this.export = this.export.bind(this);
     this.import = this.import.bind(this);
+    this.reset = this.reset.bind(this);
     this.getMesssageByIndex = this.getMesssageByIndex.bind(this);
     this.getMesssageById = this.getMesssageById.bind(this);
     this.subscribe = this.subscribe.bind(this);
@@ -403,6 +413,10 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     this._threadBinding.getState().import(data);
   }
 
+  public reset(initialMessages?: readonly ThreadMessageLike[]) {
+    this._threadBinding.getState().reset(initialMessages);
+  }
+
   public getMesssageByIndex(idx: number) {
     if (idx < 0) throw new Error("Message index must be >= 0");
 

package/src/primitives/message/MessagePartsGroupedByParentId.tsx

@@ -0,0 +1,415 @@
+"use client";
+
+import {
+  type ComponentType,
+  type FC,
+  memo,
+  PropsWithChildren,
+  useMemo,
+} from "react";
+import {
+  TextMessagePartProvider,
+  useMessagePart,
+  useMessagePartRuntime,
+  useToolUIs,
+} from "../../context";
+import {
+  useMessage,
+  useMessageRuntime,
+} from "../../context/react/MessageContext";
+import { MessagePartRuntimeProvider } from "../../context/providers/MessagePartRuntimeProvider";
+import { MessagePartPrimitiveText } from "../messagePart/MessagePartText";
+import { MessagePartPrimitiveImage } from "../messagePart/MessagePartImage";
+import type {
+  Unstable_AudioMessagePartComponent,
+  EmptyMessagePartComponent,
+  TextMessagePartComponent,
+  ImageMessagePartComponent,
+  SourceMessagePartComponent,
+  ToolCallMessagePartComponent,
+  ToolCallMessagePartProps,
+  FileMessagePartComponent,
+  ReasoningMessagePartComponent,
+} from "../../types/MessagePartComponentTypes";
+import { MessagePartPrimitiveInProgress } from "../messagePart/MessagePartInProgress";
+import { MessagePartStatus } from "../../types/AssistantTypes";
+
+type MessagePartGroup = {
+  parentId: string | undefined;
+  indices: number[];
+};
+
+/**
+ * Groups message parts by their parent ID.
+ * Parts without a parent ID appear after grouped parts and remain ungrouped.
+ * The position of groups is based on the first occurrence of each parent ID.
+ */
+const groupMessagePartsByParentId = (
+  parts: readonly any[],
+): MessagePartGroup[] => {
+  const groups: MessagePartGroup[] = [];
+  const parentIdToGroupIndex = new Map<string | undefined, number>();
+  const processedIndices = new Set<number>();
+
+  // First pass: process all parts with parent IDs
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    const parentId = part?.parentId as string | undefined;
+
+    if (parentId !== undefined) {
+      let groupIndex = parentIdToGroupIndex.get(parentId);
+
+      if (groupIndex === undefined) {
+        // Create new group for this parent ID
+        groupIndex = groups.length;
+        groups.push({ parentId, indices: [] });
+        parentIdToGroupIndex.set(parentId, groupIndex);
+      }
+
+      groups[groupIndex]!.indices.push(i);
+      processedIndices.add(i);
+    }
+  }
+
+  // Second pass: add ungrouped parts (those without parent ID)
+  for (let i = 0; i < parts.length; i++) {
+    if (!processedIndices.has(i)) {
+      // Add individual group for parts without parent ID
+      groups.push({ parentId: undefined, indices: [i] });
+    }
+  }
+
+  return groups;
+};
+
+const useMessagePartsGroupedByParentId = (): MessagePartGroup[] => {
+  const parts = useMessage((m) => m.content);
+
+  return useMemo(() => {
+    if (parts.length === 0) {
+      return [];
+    }
+    return groupMessagePartsByParentId(parts);
+  }, [parts]);
+};
+
+export namespace MessagePrimitiveUnstable_PartsGroupedByParentId {
+  export type Props = {
+    /**
+     * Component configuration for rendering different types of message content.
+     *
+     * You can provide custom components for each content type (text, image, file, etc.)
+     * and configure tool rendering behavior. If not provided, default components will be used.
+     */
+    components?:
+      | {
+          /** Component for rendering empty messages */
+          Empty?: EmptyMessagePartComponent | undefined;
+          /** Component for rendering text content */
+          Text?: TextMessagePartComponent | undefined;
+          /** Component for rendering reasoning content (typically hidden) */
+          Reasoning?: ReasoningMessagePartComponent | undefined;
+          /** Component for rendering source content */
+          Source?: SourceMessagePartComponent | undefined;
+          /** Component for rendering image content */
+          Image?: ImageMessagePartComponent | undefined;
+          /** Component for rendering file content */
+          File?: FileMessagePartComponent | undefined;
+          /** Component for rendering audio content (experimental) */
+          Unstable_Audio?: Unstable_AudioMessagePartComponent | undefined;
+          /** Configuration for tool call rendering */
+          tools?:
+            | {
+                /** Map of tool names to their specific components */
+                by_name?:
+                  | Record<string, ToolCallMessagePartComponent | undefined>
+                  | undefined;
+                /** Fallback component for unregistered tools */
+                Fallback?: ComponentType<ToolCallMessagePartProps> | undefined;
+              }
+            | {
+                /** Override component that handles all tool calls */
+                Override: ComponentType<ToolCallMessagePartProps>;
+              }
+            | undefined;
+
+          /**
+           * Component for rendering grouped message parts with the same parent ID.
+           *
+           * When provided, this component will automatically wrap message parts that share
+           * the same parent ID, allowing you to create collapsible sections, custom styling,
+           * or other grouped presentations.
+           *
+           * The component receives:
+           * - `parentId`: The parent ID shared by all parts in the group (or undefined for ungrouped parts)
+           * - `indices`: Array of indices for the parts in this group
+           * - `children`: The rendered message part components
+           *
+           * @example
+           * ```tsx
+           * // Collapsible parent ID group
+           * Group: ({ parentId, indices, children }) => {
+           *   if (!parentId) return <>{children}</>;
+           *   return (
+           *     <details className="parent-group">
+           *       <summary>
+           *         Group {parentId} ({indices.length} parts)
+           *       </summary>
+           *       <div className="parent-group-content">
+           *         {children}
+           *       </div>
+           *     </details>
+           *   );
+           * }
+           * ```
+           *
+           * @example
+           * ```tsx
+           * // Custom styled parent ID group
+           * Group: ({ parentId, indices, children }) => {
+           *   if (!parentId) return <>{children}</>;
+           *   return (
+           *     <div className="border rounded-lg p-4 my-2">
+           *       <div className="text-sm text-gray-600 mb-2">
+           *         Related content ({parentId})
+           *       </div>
+           *       <div className="space-y-2">
+           *         {children}
+           *       </div>
+           *     </div>
+           *   );
+           * }
+           * ```
+           *
+           * @param parentId - The parent ID shared by all parts in this group (undefined for ungrouped parts)
+           * @param indices - Array of indices for the parts in this group
+           * @param children - Rendered message part components to display within the group
+           */
+          Group?: ComponentType<
+            PropsWithChildren<{
+              parentId: string | undefined;
+              indices: number[];
+            }>
+          >;
+        }
+      | undefined;
+  };
+}
+
+const ToolUIDisplay = ({
+  Fallback,
+  ...props
+}: {
+  Fallback: ToolCallMessagePartComponent | undefined;
+} & ToolCallMessagePartProps) => {
+  const Render = useToolUIs((s) => s.getToolUI(props.toolName)) ?? Fallback;
+  if (!Render) return null;
+  return <Render {...props} />;
+};
+
+const defaultComponents = {
+  Text: () => (
+    <p style={{ whiteSpace: "pre-line" }}>
+      <MessagePartPrimitiveText />
+      <MessagePartPrimitiveInProgress>
+        <span style={{ fontFamily: "revert" }}>{" \u25CF"}</span>
+      </MessagePartPrimitiveInProgress>
+    </p>
+  ),
+  Reasoning: () => null,
+  Source: () => null,
+  Image: () => <MessagePartPrimitiveImage />,
+  File: () => null,
+  Unstable_Audio: () => null,
+  Group: ({ children }) => children,
+} satisfies MessagePrimitiveUnstable_PartsGroupedByParentId.Props["components"];
+
+type MessagePartComponentProps = {
+  components: MessagePrimitiveUnstable_PartsGroupedByParentId.Props["components"];
+};
+
+const MessagePartComponent: FC<MessagePartComponentProps> = ({
+  components: {
+    Text = defaultComponents.Text,
+    Reasoning = defaultComponents.Reasoning,
+    Image = defaultComponents.Image,
+    Source = defaultComponents.Source,
+    File = defaultComponents.File,
+    Unstable_Audio: Audio = defaultComponents.Unstable_Audio,
+    tools = {},
+  } = {},
+}) => {
+  const MessagePartRuntime = useMessagePartRuntime();
+
+  const part = useMessagePart();
+
+  const type = part.type;
+  if (type === "tool-call") {
+    const addResult = (result: any) => MessagePartRuntime.addToolResult(result);
+    if ("Override" in tools)
+      return <tools.Override {...part} addResult={addResult} />;
+    const Tool = tools.by_name?.[part.toolName] ?? tools.Fallback;
+    return <ToolUIDisplay {...part} Fallback={Tool} addResult={addResult} />;
+  }
+
+  if (part.status.type === "requires-action")
+    throw new Error("Encountered unexpected requires-action status");
+
+  switch (type) {
+    case "text":
+      return <Text {...part} />;
+
+    case "reasoning":
+      return <Reasoning {...part} />;
+
+    case "source":
+      return <Source {...part} />;
+
+    case "image":
+      // eslint-disable-next-line jsx-a11y/alt-text
+      return <Image {...part} />;
+
+    case "file":
+      return <File {...part} />;
+
+    case "audio":
+      return <Audio {...part} />;
+
+    default:
+      const unhandledType: never = type;
+      throw new Error(`Unknown message part type: ${unhandledType}`);
+  }
+};
+
+type MessagePartProps = {
+  partIndex: number;
+  components: MessagePrimitiveUnstable_PartsGroupedByParentId.Props["components"];
+};
+
+const MessagePartImpl: FC<MessagePartProps> = ({ partIndex, components }) => {
+  const messageRuntime = useMessageRuntime();
+  const runtime = useMemo(
+    () => messageRuntime.getMessagePartByIndex(partIndex),
+    [messageRuntime, partIndex],
+  );
+
+  return (
+    <MessagePartRuntimeProvider runtime={runtime}>
+      <MessagePartComponent components={components} />
+    </MessagePartRuntimeProvider>
+  );
+};
+
+const MessagePart = memo(
+  MessagePartImpl,
+  (prev, next) =>
+    prev.partIndex === next.partIndex &&
+    prev.components?.Text === next.components?.Text &&
+    prev.components?.Reasoning === next.components?.Reasoning &&
+    prev.components?.Source === next.components?.Source &&
+    prev.components?.Image === next.components?.Image &&
+    prev.components?.File === next.components?.File &&
+    prev.components?.Unstable_Audio === next.components?.Unstable_Audio &&
+    prev.components?.tools === next.components?.tools &&
+    prev.components?.Group === next.components?.Group,
+);
+
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({
+  type: "complete",
+});
+
+const EmptyPartFallback: FC<{
+  status: MessagePartStatus;
+  component: TextMessagePartComponent;
+}> = ({ status, component: Component }) => {
+  return (
+    <TextMessagePartProvider text="" isRunning={status.type === "running"}>
+      <Component type="text" text="" status={status} />
+    </TextMessagePartProvider>
+  );
+};
+
+const EmptyPartsImpl: FC<MessagePartComponentProps> = ({ components }) => {
+  const status =
+    useMessage((s) => s.status as MessagePartStatus) ?? COMPLETE_STATUS;
+
+  if (components?.Empty) return <components.Empty status={status} />;
+
+  return (
+    <EmptyPartFallback
+      status={status}
+      component={components?.Text ?? defaultComponents.Text}
+    />
+  );
+};
+
+const EmptyParts = memo(
+  EmptyPartsImpl,
+  (prev, next) =>
+    prev.components?.Empty === next.components?.Empty &&
+    prev.components?.Text === next.components?.Text,
+);
+
+/**
+ * Renders the parts of a message grouped by their parent ID.
+ *
+ * This component automatically groups message parts that share the same parent ID,
+ * allowing you to create hierarchical or related content presentations. Parts without
+ * a parent ID appear after grouped parts and remain ungrouped.
+ *
+ * @example
+ * ```tsx
+ * <MessagePrimitive.Unstable_PartsGroupedByParentId
+ *   components={{
+ *     Text: ({ text }) => <p className="message-text">{text}</p>,
+ *     Image: ({ image }) => <img src={image} alt="Message image" />,
+ *     Group: ({ parentId, indices, children }) => {
+ *       if (!parentId) return <>{children}</>;
+ *       return (
+ *         <div className="parent-group border rounded p-4">
+ *           <h4>Related Content</h4>
+ *           {children}
+ *         </div>
+ *       );
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+export const MessagePrimitiveUnstable_PartsGroupedByParentId: FC<
+  MessagePrimitiveUnstable_PartsGroupedByParentId.Props
+> = ({ components }) => {
+  const contentLength = useMessage((s) => s.content.length);
+  const messageGroups = useMessagePartsGroupedByParentId();
+
+  const partsElements = useMemo(() => {
+    if (contentLength === 0) {
+      return <EmptyParts components={components} />;
+    }
+
+    return messageGroups.map((group, groupIndex) => {
+      const GroupComponent = components?.Group ?? defaultComponents.Group;
+
+      return (
+        <GroupComponent
+          key={`group-${groupIndex}-${group.parentId ?? "ungrouped"}`}
+          parentId={group.parentId}
+          indices={group.indices}
+        >
+          {group.indices.map((partIndex) => (
+            <MessagePart
+              key={partIndex}
+              partIndex={partIndex}
+              components={components}
+            />
+          ))}
+        </GroupComponent>
+      );
+    });
+  }, [messageGroups, components, contentLength]);
+
+  return <>{partsElements}</>;
+};
+
+MessagePrimitiveUnstable_PartsGroupedByParentId.displayName =
+  "MessagePrimitive.Unstable_PartsGroupedByParentId";

package/src/primitives/message/index.ts

@@ -4,3 +4,4 @@ export { MessagePrimitiveParts as Content } from "./MessageParts";
 export { MessagePrimitiveIf as If } from "./MessageIf";
 export { MessagePrimitiveAttachments as Attachments } from "./MessageAttachments";
 export { MessagePrimitiveError as Error } from "./MessageError";
+export { MessagePrimitiveUnstable_PartsGroupedByParentId as Unstable_PartsGroupedByParentId } from "./MessagePartsGroupedByParentId";

package/src/runtimes/core/BaseThreadRuntimeCore.tsx

@@ -22,6 +22,7 @@ import { FeedbackAdapter } from "../adapters/feedback/FeedbackAdapter";
 import { AttachmentAdapter } from "../adapters/attachment";
 import { getThreadMessageText } from "../../utils/getThreadMessageText";
 import { ModelContextProvider } from "../../model-context";
+import { ThreadMessageLike } from "../external-store";
 
 type BaseThreadAdapters = {
   speech?: SpeechSynthesisAdapter | undefined;
@@ -194,6 +195,10 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     this._notifySubscribers();
   }
 
+  public reset(initialMessages?: readonly ThreadMessageLike[]) {
+    this.import(ExportedMessageRepository.fromArray(initialMessages ?? []));
+  }
+
   private _eventSubscribers = new Map<
     ThreadRuntimeEventType,
     Set<() => void>

package/src/runtimes/core/ThreadRuntimeCore.tsx

@@ -6,6 +6,7 @@ import type { Unsubscribe } from "../../types/Unsubscribe";
 import { SpeechSynthesisAdapter } from "../adapters/speech/SpeechAdapterTypes";
 import { ChatModelRunOptions, ChatModelRunResult } from "../local";
 import { ExportedMessageRepository } from "../utils/MessageRepository";
+import { ThreadMessageLike } from "../external-store";
 import {
   ComposerRuntimeCore,
   ThreadComposerRuntimeCore,
@@ -118,5 +119,7 @@ export type ThreadRuntimeCore = Readonly<{
   import(repository: ExportedMessageRepository): void;
   export(): ExportedMessageRepository;
 
+  reset(initialMessages?: readonly ThreadMessageLike[]): void;
+
   unstable_on(event: ThreadRuntimeEventType, callback: () => void): Unsubscribe;
 }>;

package/src/runtimes/external-store/ExternalStoreAdapter.tsx

@@ -8,6 +8,7 @@ import {
 import { FeedbackAdapter } from "../adapters/feedback/FeedbackAdapter";
 import { SpeechSynthesisAdapter } from "../adapters/speech/SpeechAdapterTypes";
 import { ThreadMessageLike } from "./ThreadMessageLike";
+import { ExportedMessageRepository } from "../utils/MessageRepository";
 
 export type ExternalStoreThreadData<TState extends "regular" | "archived"> = {
   status: TState;
@@ -53,7 +54,8 @@ type ExternalStoreAdapterBase<T> = {
   isDisabled?: boolean | undefined;
   isRunning?: boolean | undefined;
   isLoading?: boolean | undefined;
-  messages: readonly T[];
+  messages?: readonly T[];
+  messageRepository?: ExportedMessageRepository;
   suggestions?: readonly ThreadSuggestion[] | undefined;
   extras?: unknown;
 

package/src/runtimes/external-store/ExternalStoreThreadRuntimeCore.tsx

@@ -108,46 +108,79 @@ export class ExternalStoreThreadRuntimeCore
       feedback: !!this._store.adapters?.feedback,
     };
 
-    if (oldStore) {
-      // flush the converter cache when the convertMessage prop changes
-      if (oldStore.convertMessage !== store.convertMessage) {
-        this._converter = new ThreadMessageConverter();
-      } else if (
+    let messages: readonly ThreadMessage[];
+
+    if (store.messageRepository) {
+      // Handle messageRepository
+      if (
+        oldStore &&
         oldStore.isRunning === store.isRunning &&
-        oldStore.messages === store.messages
+        oldStore.messageRepository === store.messageRepository
       ) {
         this._notifySubscribers();
-        // no conversion update
         return;
       }
-    }
 
-    const messages = !store.convertMessage
-      ? store.messages
-      : this._converter.convertMessages(store.messages, (cache, m, idx) => {
-          if (!store.convertMessage) return m;
-
-          const isLast = idx === store.messages.length - 1;
-          const autoStatus = getAutoStatus(isLast, isRunning);
-
-          if (
-            cache &&
-            (cache.role !== "assistant" ||
-              !isAutoStatus(cache.status) ||
-              cache.status === autoStatus)
-          )
-            return cache;
-
-          const messageLike = store.convertMessage(m, idx);
-          const newMessage = fromThreadMessageLike(
-            messageLike,
-            idx.toString(),
-            autoStatus,
-          );
-          (newMessage as any)[symbolInnerMessage] = m;
-          return newMessage;
-        });
+      // Clear and import the message repository
+      this.repository.clear();
+      this.repository.import(store.messageRepository);
+
+      messages = this.repository.getMessages();
+    } else if (store.messages) {
+      // Handle messages array
+
+      if (oldStore) {
+        // flush the converter cache when the convertMessage prop changes
+        if (oldStore.convertMessage !== store.convertMessage) {
+          this._converter = new ThreadMessageConverter();
+        } else if (
+          oldStore.isRunning === store.isRunning &&
+          oldStore.messages === store.messages
+        ) {
+          this._notifySubscribers();
+          // no conversion update
+          return;
+        }
+      }
+
+      messages = !store.convertMessage
+        ? store.messages
+        : this._converter.convertMessages(store.messages, (cache, m, idx) => {
+            if (!store.convertMessage) return m;
+
+            const isLast = idx === store.messages!.length - 1;
+            const autoStatus = getAutoStatus(isLast, isRunning);
+
+            if (
+              cache &&
+              (cache.role !== "assistant" ||
+                !isAutoStatus(cache.status) ||
+                cache.status === autoStatus)
+            )
+              return cache;
+
+            const messageLike = store.convertMessage(m, idx);
+            const newMessage = fromThreadMessageLike(
+              messageLike,
+              idx.toString(),
+              autoStatus,
+            );
+            (newMessage as any)[symbolInnerMessage] = m;
+            return newMessage;
+          });
+
+      for (let i = 0; i < messages.length; i++) {
+        const message = messages[i]!;
+        const parent = messages[i - 1];
+        this.repository.addOrUpdateMessage(parent?.id ?? null, message);
+      }
+    } else {
+      throw new Error(
+        "ExternalStoreAdapter must provide either 'messages' or 'messageRepository'",
+      );
+    }
 
+    // Common logic for both paths
     if (messages.length > 0) this.ensureInitialized();
 
     if (oldStore?.isRunning ?? false !== store.isRunning ?? false) {
@@ -158,12 +191,6 @@ export class ExternalStoreThreadRuntimeCore
       }
     }
 
-    for (let i = 0; i < messages.length; i++) {
-      const message = messages[i]!;
-      const parent = messages[i - 1];
-      this.repository.addOrUpdateMessage(parent?.id ?? null, message);
-    }
-
     if (this.assistantOptimisticId) {
       this.repository.deleteMessage(this.assistantOptimisticId);
       this.assistantOptimisticId = null;

package/src/runtimes/external-store/ThreadMessageLike.tsx

@@ -41,6 +41,7 @@ export type ThreadMessageLike = {
             readonly artifact?: any;
             readonly result?: any | undefined;
             readonly isError?: boolean | undefined;
+            readonly parentId?: string | undefined;
           }
       )[];
   readonly id?: string | undefined;
@@ -104,17 +105,22 @@ export const fromThreadMessageLike = (
                 return part;
 
               case "tool-call": {
+                const { parentId, ...basePart } = part;
+                const commonProps = {
+                  ...basePart,
+                  toolCallId: part.toolCallId ?? "tool-" + generateId(),
+                  ...(parentId !== undefined && { parentId }),
+                };
+
                 if (part.args) {
                   return {
-                    ...part,
-                    toolCallId: part.toolCallId ?? "tool-" + generateId(),
+                    ...commonProps,
                     args: part.args,
                     argsText: JSON.stringify(part.args),
                   };
                 }
                 return {
-                  ...part,
-                  toolCallId: part.toolCallId ?? "tool-" + generateId(),
+                  ...commonProps,
                   args:
                     part.args ??
                     parsePartialJsonObject(part.argsText ?? "") ??

package/src/runtimes/remote-thread-list/EMPTY_THREAD_CORE.tsx

@@ -163,6 +163,10 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     return { messages: [] };
   },
 
+  reset() {
+    throw EMPTY_THREAD_ERROR;
+  },
+
   unstable_on() {
     return () => {};
   },