@assistant-ui/react 0.7.0 → 0.7.2

package/src/api/ComposerRuntime.ts

@@ -33,23 +33,23 @@ export type ComposerRuntimeCoreBinding = SubscribableWithState<
 >;
 
 type BaseComposerState = {
-  text: string;
-  role: MessageRole;
-  attachments: readonly Attachment[];
+  readonly text: string;
+  readonly role: MessageRole;
+  readonly attachments: readonly Attachment[];
 
-  canCancel: boolean;
-  isEditing: boolean;
-  isEmpty: boolean;
+  readonly canCancel: boolean;
+  readonly isEditing: boolean;
+  readonly isEmpty: boolean;
 };
 
 export type ThreadComposerState = BaseComposerState & {
-  type: "thread";
+  readonly type: "thread";
 
-  attachments: readonly PendingAttachment[];
+  readonly attachments: readonly PendingAttachment[];
 };
 
 export type EditComposerState = BaseComposerState & {
-  type: "edit";
+  readonly type: "edit";
 };
 
 export type ComposerState = ThreadComposerState | EditComposerState;
@@ -90,7 +90,7 @@ const getEditComposerState = (
 };
 
 export type ComposerRuntime = {
-  path: ComposerRuntimePath;
+  readonly path: ComposerRuntimePath;
   readonly type: "edit" | "thread";
   getState(): ComposerState;
 

package/src/api/ContentPartRuntime.ts

@@ -14,7 +14,7 @@ export type ContentPartState = (
   | ThreadUserContentPart
   | ThreadAssistantContentPart
 ) & {
-  status: ContentPartStatus | ToolCallContentPartStatus;
+  readonly status: ContentPartStatus | ToolCallContentPartStatus;
 };
 
 type ContentPartSnapshotBinding = SubscribableWithState<
@@ -23,7 +23,7 @@ type ContentPartSnapshotBinding = SubscribableWithState<
 >;
 
 export type ContentPartRuntime = {
-  path: ContentPartRuntimePath;
+  readonly path: ContentPartRuntimePath;
 
   getState(): ContentPartState;
   addToolResult(result: any): void;

package/src/api/MessageRuntime.ts

@@ -34,9 +34,9 @@ import { SKIP_UPDATE } from "./subscribable/SKIP_UPDATE";
 import { ShallowMemoizeSubject } from "./subscribable/ShallowMemoizeSubject";
 import { SubscribableWithState } from "./subscribable/Subscribable";
 
-const COMPLETE_STATUS: ContentPartStatus = {
+const COMPLETE_STATUS: ContentPartStatus = Object.freeze({
   type: "complete",
-};
+});
 
 export const toContentPartStatus = (
   message: ThreadMessage,
@@ -92,17 +92,17 @@ const getContentPartState = (
 };
 
 export type MessageState = ThreadMessage & {
-  parentId: string | null;
-  isLast: boolean;
+  readonly parentId: string | null;
+  readonly isLast: boolean;
 
-  branchNumber: number;
-  branchCount: number;
+  readonly branchNumber: number;
+  readonly branchCount: number;
 
   /**
    * @deprecated This API is still under active development and might change without notice.
    */
-  speech: SpeechState | undefined;
-  submittedFeedback: SubmittedFeedback | undefined;
+  readonly speech: SpeechState | undefined;
+  readonly submittedFeedback: SubmittedFeedback | undefined;
 };
 
 export type MessageStateBinding = SubscribableWithState<
@@ -169,7 +169,7 @@ export class MessageRuntimeImpl implements MessageRuntime {
     );
   }
 
-  public composer;
+  public readonly composer;
 
   public getState() {
     return this._core.getState();

package/src/api/RuntimePathTypes.ts

@@ -1,60 +1,60 @@
 export type ThreadListRuntimePath = {
-  ref: string;
+  readonly ref: string;
 };
 
 export type ThreadListItemRuntimePath = {
-  ref: string;
-  threadSelector:
-    | { type: "main" }
-    | { type: "index"; index: number }
-    | { type: "archiveIndex"; index: number }
-    | { type: "threadId"; threadId: string };
+  readonly ref: string;
+  readonly threadSelector:
+    | { readonly type: "main" }
+    | { readonly type: "index"; readonly index: number }
+    | { readonly type: "archiveIndex"; readonly index: number }
+    | { readonly type: "threadId"; readonly threadId: string };
 };
 
 export type ThreadRuntimePath = {
-  ref: string;
-  threadSelector: { type: "main" };
+  readonly ref: string;
+  readonly threadSelector: { type: "main" };
 };
 
 export type MessageRuntimePath = ThreadRuntimePath & {
-  messageSelector:
-    | { type: "messageId"; messageId: string }
-    | { type: "index"; index: number };
+  readonly messageSelector:
+    | { readonly type: "messageId"; readonly messageId: string }
+    | { readonly type: "index"; readonly index: number };
 };
 
 export type ContentPartRuntimePath = MessageRuntimePath & {
-  contentPartSelector:
-    | { type: "index"; index: number }
-    | { type: "toolCallId"; toolCallId: string };
+  readonly contentPartSelector:
+    | { readonly type: "index"; readonly index: number }
+    | { readonly type: "toolCallId"; readonly toolCallId: string };
 };
 
 export type AttachmentRuntimePath = (
   | (MessageRuntimePath & {
-      attachmentSource: "message" | "edit-composer";
+      readonly attachmentSource: "message" | "edit-composer";
     })
   | (ThreadRuntimePath & {
-      attachmentSource: "thread-composer";
+      readonly attachmentSource: "thread-composer";
     })
 ) & {
-  attachmentSelector:
+  readonly attachmentSelector:
     | {
-        type: "index";
-        index: number;
+        readonly type: "index";
+        readonly index: number;
       }
     | {
-        type: "index";
-        index: number;
+        readonly type: "index";
+        readonly index: number;
       }
     | {
-        type: "index";
-        index: number;
+        readonly type: "index";
+        readonly index: number;
       };
 };
 
 export type ComposerRuntimePath =
   | (ThreadRuntimePath & {
-      composerSource: "thread";
+      readonly composerSource: "thread";
     })
   | (MessageRuntimePath & {
-      composerSource: "edit";
+      readonly composerSource: "edit";
     });

package/src/api/ThreadListItemRuntime.ts

@@ -5,11 +5,11 @@ import { SubscribableWithState } from "./subscribable/Subscribable";
 import { ThreadListRuntimeCoreBinding } from "./ThreadListRuntime";
 
 export type ThreadListItemState = ThreadMetadata & {
-  isMain: boolean;
+  readonly isMain: boolean;
 };
 
-export type ThreadListItemRuntime = Readonly<{
-  path: ThreadListItemRuntimePath;
+export type ThreadListItemRuntime = {
+  readonly path: ThreadListItemRuntimePath;
   getState(): ThreadListItemState;
 
   switchTo(): Promise<void>;
@@ -19,7 +19,7 @@ export type ThreadListItemRuntime = Readonly<{
   delete(): Promise<void>;
 
   subscribe(callback: () => void): Unsubscribe;
-}>;
+};
 
 export type ThreadListItemStateBinding = SubscribableWithState<
   ThreadListItemState,

package/src/api/ThreadListRuntime.ts

@@ -10,15 +10,15 @@ import {
 import { SKIP_UPDATE } from "./subscribable/SKIP_UPDATE";
 import { ShallowMemoizeSubject } from "./subscribable/ShallowMemoizeSubject";
 
-export type ThreadListState = Readonly<{
-  mainThreadId: string;
-  newThread: string | undefined;
-  threads: readonly string[];
-  archivedThreads: readonly string[];
-}>;
-
-export type ThreadListRuntime = Readonly<{
-  path: ThreadListRuntimePath;
+export type ThreadListState = {
+  readonly mainThreadId: string;
+  readonly newThread: string | undefined;
+  readonly threads: readonly string[];
+  readonly archivedThreads: readonly string[];
+};
+
+export type ThreadListRuntime = {
+  readonly path: ThreadListRuntimePath;
   getState(): ThreadListState;
 
   subscribe(callback: () => void): Unsubscribe;
@@ -26,7 +26,7 @@ export type ThreadListRuntime = Readonly<{
   getThreadListItemById(threadId: string): ThreadListItemRuntime;
   getThreadListItemByIndex(idx: number): ThreadListItemRuntime;
   getThreadListArchivedItemByIndex(idx: number): ThreadListItemRuntime;
-}>;
+};
 
 const getThreadListState = (
   threadList: ThreadListRuntimeCore,

package/src/api/ThreadRuntime.ts

@@ -74,53 +74,53 @@ export type ThreadRuntimeCoreBinding = SubscribableWithState<
   outerSubscribe(callback: () => void): Unsubscribe;
 };
 
-export type ThreadState = Readonly<{
+export type ThreadState = {
   /**
    * The thread ID.
-   * @deprecated This field is deprecated and will be removed in 0.7.0. Use `metadata.threadId` instead.  
+   * @deprecated This field is deprecated and will be removed in 0.8.0. Use `metadata.threadId` instead.
    */
-  threadId: string;
+  readonly threadId: string;
 
   /**
    * The thread metadata.
    */
-  metadata: ThreadMetadata;
+  readonly metadata: ThreadMetadata;
 
   /**
    * Whether the thread is disabled. Disabled threads cannot receive new messages.
    */
-  isDisabled: boolean;
+  readonly isDisabled: boolean;
 
   /**
    * Whether the thread is running. A thread is considered running when there is an active stream connection to the backend.
    */
-  isRunning: boolean;
+  readonly isRunning: boolean;
 
   /**
    * The capabilities of the thread, such as whether the thread supports editing, branch switching, etc.
    */
-  capabilities: RuntimeCapabilities;
+  readonly capabilities: RuntimeCapabilities;
 
   /**
    * The messages in the currently selected branch of the thread.
    */
-  messages: readonly ThreadMessage[];
+  readonly messages: readonly ThreadMessage[];
 
   /**
    * Follow up message suggestions to show the user.
    */
-  suggestions: readonly ThreadSuggestion[];
+  readonly suggestions: readonly ThreadSuggestion[];
 
   /**
    * Custom extra information provided by the runtime.
    */
-  extras: unknown;
+  readonly extras: unknown;
 
   /**
    * @deprecated This API is still under active development and might change without notice.
    */
-  speech: SpeechState | undefined;
-}>;
+  readonly speech: SpeechState | undefined;
+};
 
 export const getThreadState = (runtime: ThreadRuntimeCore): ThreadState => {
   const lastMessage = runtime.messages.at(-1);
@@ -140,13 +140,44 @@ export const getThreadState = (runtime: ThreadRuntimeCore): ThreadState => {
   });
 };
 
-export type ThreadRuntime = Readonly<{
+export type ThreadRuntime = {
+  /**
+   * The selector for the thread runtime.
+   */
   readonly path: ThreadRuntimePath;
 
+  /**
+   * The thread composer runtime.
+   */
   readonly composer: ThreadComposerRuntime;
+
+  /**
+   * Gets a snapshot of the thread state.
+   */
   getState(): ThreadState;
 
+  /**
+   * Append a new message to the thread.
+   *
+   * @example ```ts
+   * // append a new user message with the text "Hello, world!"
+   * threadRuntime.append("Hello, world!");
+   * ```
+   *
+   * @example ```ts
+   * // append a new assistant message with the text "Hello, world!"
+   * threadRuntime.append({
+   *   role: "assistant",
+   *   content: [{ type: "text", text: "Hello, world!" }],
+   * });
+   * ```
+   */
   append(message: CreateAppendMessage): void;
+
+  /**
+   *
+   * @param parentId
+   */
   startRun(parentId: string | null): void;
   subscribe(callback: () => void): Unsubscribe;
   cancelRun(): void;
@@ -162,7 +193,7 @@ export type ThreadRuntime = Readonly<{
   stopSpeaking: () => void;
 
   unstable_on(event: ThreadRuntimeEventType, callback: () => void): Unsubscribe;
-}>;
+};
 
 export class ThreadRuntimeImpl implements ThreadRuntime {
   public get path() {

package/src/api/index.ts

@@ -15,3 +15,7 @@ export type {
 } from "./ComposerRuntime";
 export type { AttachmentRuntime, AttachmentState } from "./AttachmentRuntime";
 export type { ThreadListRuntime, ThreadListState } from "./ThreadListRuntime";
+export type {
+  ThreadListItemRuntime,
+  ThreadListItemState,
+} from "./ThreadListItemRuntime";

package/src/context/stores/AssistantToolUIs.ts

@@ -4,13 +4,20 @@ import { create } from "zustand";
 import type { ToolCallContentPartComponent } from "../../types/ContentPartComponentTypes";
 import { Unsubscribe } from "../../types";
 
-export type AssistantToolUIsState = Readonly<{
+export type AssistantToolUIsState = {
+  /**
+   * Get the tool UI configured for a given tool name.
+   */
   getToolUI: (toolName: string) => ToolCallContentPartComponent | null;
+
+  /**
+   * Registers a tool UI for a given tool name. Returns an unsubscribe function to remove the tool UI.
+   */
   setToolUI: (
     toolName: string,
     render: ToolCallContentPartComponent,
   ) => Unsubscribe;
-}>;
+};
 
 export const makeAssistantToolUIsStore = () =>
   create<AssistantToolUIsState>((set) => {

package/src/context/stores/MessageUtils.ts

@@ -1,12 +1,12 @@
 import { create } from "zustand";
 
-export type MessageUtilsState = Readonly<{
-  isCopied: boolean;
-  setIsCopied: (value: boolean) => void;
+export type MessageUtilsState = {
+  readonly isCopied: boolean;
+  readonly setIsCopied: (value: boolean) => void;
 
-  isHovering: boolean;
-  setIsHovering: (value: boolean) => void;
-}>;
+  readonly isHovering: boolean;
+  readonly setIsHovering: (value: boolean) => void;
+};
 
 export const makeMessageUtilsStore = () =>
   create<MessageUtilsState>((set) => {

package/src/context/stores/ThreadViewport.tsx

@@ -1,12 +1,11 @@
-"use client";
 import { create } from "zustand";
 import type { Unsubscribe } from "../../types/Unsubscribe";
 
-export type ThreadViewportState = Readonly<{
-  isAtBottom: boolean;
-  scrollToBottom: () => void;
-  onScrollToBottom: (callback: () => void) => Unsubscribe;
-}>;
+export type ThreadViewportState = {
+  readonly isAtBottom: boolean;
+  readonly scrollToBottom: () => void;
+  readonly onScrollToBottom: (callback: () => void) => Unsubscribe;
+};
 
 export const makeThreadViewportStore = () => {
   const scrollToBottomListeners = new Set<() => void>();

package/src/runtimes/core/ThreadRuntimeCore.tsx

@@ -7,16 +7,16 @@ import {
   ThreadComposerRuntimeCore,
 } from "./ComposerRuntimeCore";
 
-export type RuntimeCapabilities = Readonly<{
-  switchToBranch: boolean;
-  edit: boolean;
-  reload: boolean;
-  cancel: boolean;
-  unstable_copy: boolean;
-  speech: boolean;
-  attachments: boolean;
-  feedback: boolean;
-}>;
+export type RuntimeCapabilities = {
+  readonly switchToBranch: boolean;
+  readonly edit: boolean;
+  readonly reload: boolean;
+  readonly cancel: boolean;
+  readonly unstable_copy: boolean;
+  readonly speech: boolean;
+  readonly attachments: boolean;
+  readonly feedback: boolean;
+};
 
 export type AddToolResultOptions = {
   messageId: string;
@@ -34,19 +34,19 @@ export type ThreadSuggestion = {
   prompt: string;
 };
 
-export type SpeechState = Readonly<{
-  messageId: string;
-  status: SpeechSynthesisAdapter.Status;
-}>;
+export type SpeechState = {
+  readonly messageId: string;
+  readonly status: SpeechSynthesisAdapter.Status;
+};
 
-export type SubmittedFeedback = Readonly<{
-  type: "negative" | "positive";
-}>;
+export type SubmittedFeedback = {
+  readonly type: "negative" | "positive";
+};
 
 export type ThreadMetadata = Readonly<{
-  threadId: string;
-  state: "archived" | "regular" | "new" | "deleted";
-  title?: string | undefined;
+  readonly threadId: string;
+  readonly state: "archived" | "regular" | "new" | "deleted";
+  readonly title?: string | undefined;
 }>;
 
 export type ThreadRuntimeEventType =
@@ -55,15 +55,14 @@ export type ThreadRuntimeEventType =
   | "run-start"
   | "model-config-update";
 
-export type ThreadMetadataRuntimeCore = ThreadMetadata &
-  Readonly<{
-    create(title?: string): Promise<void>;
-    rename(newTitle: string): Promise<void>;
-    archive(): Promise<void>;
-    unarchive(): Promise<void>;
-    delete(): Promise<void>;
-    subscribe(callback: () => void): Unsubscribe;
-  }>;
+export type ThreadMetadataRuntimeCore = ThreadMetadata & {
+  create(title?: string): Promise<void>;
+  rename(newTitle: string): Promise<void>;
+  archive(): Promise<void>;
+  unarchive(): Promise<void>;
+  delete(): Promise<void>;
+  subscribe(callback: () => void): Unsubscribe;
+};
 
 export type ThreadRuntimeCore = Readonly<{
   metadata: ThreadMetadataRuntimeCore;

package/src/runtimes/edge/converters/fromCoreMessage.ts

@@ -42,6 +42,8 @@ export const fromCoreMessage = (
           return part;
         }),
         status,
+
+        metadata: { steps: [], custom: {} },
       } satisfies ThreadMessage;
 
     case "user":
@@ -50,6 +52,7 @@ export const fromCoreMessage = (
         role,
         content: message.content,
         attachments,
+        metadata: { custom: {} },
       } satisfies ThreadMessage;
 
     case "system":
@@ -57,6 +60,7 @@ export const fromCoreMessage = (
         ...commonProps,
         role,
         content: message.content,
+        metadata: { custom: {} },
       } satisfies ThreadMessage;
 
     default: {

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

@@ -14,6 +14,7 @@ import {
 } from "../../types";
 import {
   CoreToolCallContentPart,
+  ThreadStep,
   Unstable_AudioContentPart,
 } from "../../types/AssistantTypes";
 
@@ -33,7 +34,10 @@ export type ThreadMessageLike = {
   createdAt?: Date | undefined;
   status?: MessageStatus | undefined;
   attachments?: CompleteAttachment[] | undefined;
-  // TODO metadata
+  metadata?: {
+    steps?: ThreadStep[] | undefined;
+    custom?: Record<string, unknown> | undefined;
+  };
 };
 
 export const fromThreadMessageLike = (
@@ -41,7 +45,7 @@ export const fromThreadMessageLike = (
   fallbackId: string,
   fallbackStatus: MessageStatus,
 ): ThreadMessage => {
-  const { role, id, createdAt, attachments, status } = like;
+  const { role, id, createdAt, attachments, status, metadata } = like;
   const common = {
     id: id ?? fallbackId,
     createdAt: createdAt ?? new Date(),
@@ -53,10 +57,13 @@ export const fromThreadMessageLike = (
       : like.content;
 
   if (role !== "user" && attachments)
-    throw new Error("Attachments are only supported for user messages");
+    throw new Error("attachments are only supported for user messages");
 
   if (role !== "assistant" && status)
-    throw new Error("Status is only supported for assistant messages");
+    throw new Error("status is only supported for assistant messages");
+
+  if (role !== "assistant" && metadata?.steps)
+    throw new Error("metadata.steps is only supported for assistant messages");
 
   switch (role) {
     case "assistant":
@@ -90,6 +97,10 @@ export const fromThreadMessageLike = (
           })
           .filter((c) => !!c),
         status: status ?? fallbackStatus,
+        metadata: {
+          custom: metadata?.custom ?? {},
+          steps: metadata?.steps ?? [],
+        },
       } satisfies ThreadAssistantMessage;
 
     case "user":
@@ -112,6 +123,9 @@ export const fromThreadMessageLike = (
           }
         }),
         attachments: attachments ?? [],
+        metadata: {
+          custom: metadata?.custom ?? {},
+        },
       } satisfies ThreadUserMessage;
 
     case "system":
@@ -124,6 +138,9 @@ export const fromThreadMessageLike = (
         ...common,
         role,
         content: content as [TextContentPart],
+        metadata: {
+          custom: metadata?.custom ?? {},
+        },
       } satisfies ThreadSystemMessage;
 
     default: {

package/src/runtimes/local/ChatModelAdapter.tsx

@@ -14,11 +14,11 @@ export type ChatModelRunUpdate = {
 };
 
 export type ChatModelRunResult = {
-  content?: ThreadAssistantContentPart[];
-  status?: MessageStatus;
+  content?: ThreadAssistantContentPart[] | undefined;
+  status?: MessageStatus | undefined;
   metadata?: {
-    steps?: ThreadStep[];
-    custom?: Record<string, unknown>;
+    steps?: ThreadStep[] | undefined;
+    custom?: Record<string, unknown> | undefined;
   };
 };
 

package/src/runtimes/local/LocalThreadRuntimeCore.tsx

@@ -118,6 +118,7 @@ export class LocalThreadRuntimeCore
       role: "assistant",
       status: { type: "running" },
       content: [],
+      metadata: { steps: [], custom: {} },
       createdAt: new Date(),
     };