@assistant-ui/react 0.12.17 → 0.12.20

package/src/client/ExternalThread.ts

@@ -6,6 +6,7 @@ import {
   tapEffectEvent,
 } from "@assistant-ui/tap";
 import {
+  type ClientElement,
   type ClientOutput,
   tapClientLookup,
   attachTransformScopes,
@@ -14,34 +15,60 @@ import {
 } from "@assistant-ui/store";
 import { withKey } from "@assistant-ui/tap";
 import type {
+  AppendMessage,
   Attachment,
   CreateAttachment,
   ThreadAssistantMessagePart,
   ThreadUserMessagePart,
   ThreadMessage,
 } from "@assistant-ui/core";
+import type { QueueItemState } from "@assistant-ui/core/store";
+import type { ComposerSendOptions } from "@assistant-ui/core/store";
 import { ModelContext, Suggestions } from "@assistant-ui/core/store";
 import { Tools, DataRenderers } from "@assistant-ui/core/react";
+import { SingleThreadList } from "./SingleThreadList";
+
+const EMPTY_QUEUE_ITEMS: readonly QueueItemState[] = [];
 
 export type ExternalThreadMessage = ThreadMessage & {
   id: string;
 };
 
+export type ExternalThreadQueueAdapter = {
+  /** The current queue items. */
+  items: readonly QueueItemState[];
+  /** Called when a message is submitted via the composer. Receives the steer preference. */
+  enqueue: (message: AppendMessage, opts: { steer: boolean }) => void;
+  /** Called to promote an existing queue item (cancel current run, run this immediately). */
+  steer: (queueItemId: string) => void;
+  /** Called to remove an item from the queue. */
+  remove: (queueItemId: string) => void;
+  /** Called to clear all pending queue items, with the reason for clearing. */
+  clear: (reason: "edit" | "reload" | "cancel-run") => void;
+};
+
 export type ExternalThreadProps = {
   messages: readonly ExternalThreadMessage[];
   isRunning?: boolean;
-  onNew?: (message: any) => void;
-  onEdit?: (message: any) => void;
+  /**
+   * Callback for new messages (non-queue runtimes).
+   * @note Unused when `queue` is provided — new messages are routed through `queue.enqueue` instead.
+   */
+  onNew?: (message: AppendMessage) => void;
+  onEdit?: (message: AppendMessage) => void;
   onReload?: (parentId: string | null) => void;
   onStartRun?: () => void;
   onCancel?: () => void;
+  /** Queue adapter for runtimes that support message queuing and steering. */
+  queue?: ExternalThreadQueueAdapter;
 };
 
 type MessageClientProps = {
   message: ExternalThreadMessage;
   index: number;
-  onEdit?: (message: any) => void;
+  onEdit?: (message: AppendMessage) => void;
   onReload?: () => void;
+  queue?: ExternalThreadQueueAdapter | undefined;
 };
 
 // Message Client - minimal implementation
@@ -51,6 +78,7 @@ const MessageClient = resource(
     index,
     onEdit,
     onReload,
+    queue,
   }: MessageClientProps): ClientOutput<"message"> => {
     const [isCopied, setIsCopied] = tapState(false);
     const [isHovering, setIsHovering] = tapState(false);
@@ -86,7 +114,8 @@ const MessageClient = resource(
       setIsEditing(false);
     };
 
-    const handleSendEdit = (msg: any) => {
+    const handleSendEdit = (msg: AppendMessage) => {
+      queue?.clear("edit");
       onEdit?.({
         ...msg,
         parentId: message.id,
@@ -104,6 +133,7 @@ const MessageClient = resource(
         onBeginEdit: handleBeginEdit,
         onSend: handleSendEdit,
         message,
+        queue,
       }),
     );
 
@@ -214,10 +244,29 @@ type ComposerClientResourceProps = {
   canCancel: boolean;
   onCancel: () => void;
   onBeginEdit?: () => void;
-  onSend?: (message: any) => void;
+  onSend?: (message: AppendMessage) => void;
   message?: ExternalThreadMessage;
+  queue?: ExternalThreadQueueAdapter | undefined;
 };
 
+const QueueItemClient = resource(
+  ({
+    item,
+    onSteer,
+    onRemove,
+  }: {
+    item: QueueItemState;
+    onSteer: () => void;
+    onRemove: () => void;
+  }): ClientOutput<"queueItem"> => {
+    return {
+      getState: () => item,
+      steer: onSteer,
+      remove: onRemove,
+    };
+  },
+);
+
 // Composer Client - minimal implementation
 const ComposerClientResource = resource(
   ({
@@ -228,6 +277,7 @@ const ComposerClientResource = resource(
     onBeginEdit,
     onSend,
     message,
+    queue,
   }: ComposerClientResourceProps): ClientOutput<"composer"> => {
     const [text, setText] = tapState("");
     const [role, setRole] = tapState<"user" | "assistant" | "system">("user");
@@ -276,6 +326,22 @@ const ComposerClientResource = resource(
       [attachments],
     );
 
+    const queueItems = queue?.items ?? EMPTY_QUEUE_ITEMS;
+    const queueItemClients = tapClientLookup(
+      () =>
+        queueItems.map((item) =>
+          withKey(
+            item.id,
+            QueueItemClient({
+              item,
+              onSteer: () => queue?.steer(item.id),
+              onRemove: () => queue?.remove(item.id),
+            }),
+          ),
+        ),
+      [queueItems],
+    );
+
     const state = tapMemo(
       () => ({
         text,
@@ -289,6 +355,7 @@ const ComposerClientResource = resource(
         type,
         dictation: undefined,
         quote,
+        queue: queueItems,
       }),
       [
         text,
@@ -300,6 +367,7 @@ const ComposerClientResource = resource(
         type,
         attachments.length,
         quote,
+        queueItems,
       ],
     );
 
@@ -348,19 +416,25 @@ const ComposerClientResource = resource(
         setAttachments([]);
         setQuote(undefined);
       },
-      send: () => {
+      send: (opts?: ComposerSendOptions) => {
         const currentQuote = quote;
-        const message = {
+        const composedMessage: AppendMessage = {
           role,
           content: text ? [{ type: "text" as const, text }] : [],
           attachments: attachments as any,
           createdAt: new Date(),
+          parentId: null,
+          sourceId: null,
           runConfig,
           metadata: {
             custom: { ...(currentQuote ? { quote: currentQuote } : {}) },
           },
         };
-        onSend?.(message);
+        if (queue) {
+          queue.enqueue(composedMessage, { steer: opts?.steer ?? false });
+        } else {
+          onSend?.(composedMessage);
+        }
         setText("");
         setAttachments([]);
         setQuote(undefined);
@@ -372,6 +446,9 @@ const ComposerClientResource = resource(
       startDictation: () => {},
       stopDictation: () => {},
       setQuote,
+      queueItem: (selector: { index: number }) => {
+        return queueItemClients.get(selector);
+      },
     };
   },
 );
@@ -386,12 +463,14 @@ export const ExternalThread = resource(
     onReload,
     onStartRun,
     onCancel,
+    queue,
   }: ExternalThreadProps): ClientOutput<"thread"> => {
     const handleReload = (messageId: string) => {
       const messageIndex = messages.findIndex((m) => m.id === messageId);
       if (messageIndex === -1) return;
 
       const parentId = messageIndex > 0 ? messages[messageIndex - 1]!.id : null;
+      queue?.clear("reload");
       onReload?.(parentId);
     };
 
@@ -402,18 +481,20 @@ export const ExternalThread = resource(
             message: msg,
             index,
             onReload: () => handleReload(msg.id),
+            queue,
           };
           if (onEdit) props.onEdit = onEdit;
           return withKey(msg.id, MessageClient(props));
         }),
-      [messages, onEdit],
+      [messages, onEdit, queue],
     );
 
     const handleCancelRun = () => {
+      queue?.clear("cancel-run");
       onCancel?.();
     };
 
-    const handleSendNew = (message: any) => {
+    const handleSendNew = (message: AppendMessage) => {
       onNew?.(message);
     };
 
@@ -424,9 +505,11 @@ export const ExternalThread = resource(
         canCancel: isRunning,
         onCancel: handleCancelRun,
         onSend: handleSendNew,
+        queue,
       }),
     );
 
+    const hasQueue = !!queue;
     const state = tapMemo(() => {
       const messageStates = messageClients.state.map((s, idx, arr) => ({
         ...s,
@@ -449,6 +532,7 @@ export const ExternalThread = resource(
           switchBranchDuringRun: false,
           unstable_copy: false,
           dictation: false,
+          queue: hasQueue,
         },
         messages: messageStates,
         state: {},
@@ -457,17 +541,51 @@ export const ExternalThread = resource(
         speech: undefined,
         composer: composerClient.state,
       };
-    }, [messages, isRunning, messageClients.state, composerClient.state]);
+    }, [
+      messages,
+      isRunning,
+      hasQueue,
+      messageClients.state,
+      composerClient.state,
+    ]);
 
     return {
       getState: () => state,
       composer: () => composerClient.methods,
       append: (message) => {
-        onNew?.(message);
+        const appendMessage: AppendMessage =
+          typeof message === "string"
+            ? {
+                createdAt: new Date(),
+                parentId: messages.at(-1)?.id ?? null,
+                sourceId: null,
+                runConfig: {},
+                role: "user",
+                content: [{ type: "text", text: message }],
+                attachments: [],
+                metadata: { custom: {} },
+              }
+            : {
+                createdAt: message.createdAt ?? new Date(),
+                parentId: message.parentId ?? messages.at(-1)?.id ?? null,
+                sourceId: message.sourceId ?? null,
+                role: message.role ?? "user",
+                content: message.content,
+                attachments: message.attachments ?? [],
+                metadata: message.metadata ?? { custom: {} },
+                runConfig: message.runConfig ?? {},
+                startRun: message.startRun,
+              };
+        if (queue) {
+          queue.enqueue(appendMessage, { steer: false });
+        } else {
+          onNew?.(appendMessage);
+        }
       },
       startRun: () => {
         onStartRun?.();
       },
+      resumeRun: () => {},
       unstable_resumeRun: () => {},
       cancelRun: handleCancelRun,
       getModelContext: () => ({ tools: {}, config: {} }),
@@ -488,29 +606,40 @@ export const ExternalThread = resource(
 );
 
 attachTransformScopes(ExternalThread, (scopes, parent) => {
-  const result = {
-    ...scopes,
-    composer:
-      scopes.composer ??
-      Derived({
-        source: "thread",
-        query: {},
-        get: (aui) => aui.thread().composer(),
-      }),
-  };
+  if (!scopes.threads && parent.threads.source === null) {
+    const threadElement = scopes.thread as ClientElement<"thread">;
+    scopes.threads = SingleThreadList({ thread: threadElement });
+    scopes.thread = Derived({
+      source: "threads",
+      query: { type: "main" },
+      get: (aui) => aui.threads().thread("main"),
+    });
+  }
+
+  if (!scopes.threadListItem && parent.threadListItem.source === null) {
+    scopes.threadListItem = Derived({
+      source: "threads",
+      query: { type: "main" },
+      get: (aui) => aui.threads().item("main"),
+    });
+  }
 
-  if (!result.modelContext && parent.modelContext.source === null) {
-    result.modelContext = ModelContext();
+  scopes.composer ??= Derived({
+    source: "thread",
+    query: {},
+    get: (aui) => aui.thread().composer(),
+  });
+
+  if (!scopes.modelContext && parent.modelContext.source === null) {
+    scopes.modelContext = ModelContext();
   }
-  if (!result.tools && parent.tools.source === null) {
-    result.tools = Tools({});
+  if (!scopes.tools && parent.tools.source === null) {
+    scopes.tools = Tools({});
   }
-  if (!result.dataRenderers && parent.dataRenderers.source === null) {
-    result.dataRenderers = DataRenderers();
+  if (!scopes.dataRenderers && parent.dataRenderers.source === null) {
+    scopes.dataRenderers = DataRenderers();
   }
-  if (!result.suggestions && parent.suggestions.source === null) {
-    result.suggestions = Suggestions();
+  if (!scopes.suggestions && parent.suggestions.source === null) {
+    scopes.suggestions = Suggestions();
   }
-
-  return result;
 });

package/src/client/InMemoryThreadList.ts

@@ -168,43 +168,32 @@ export const InMemoryThreadList = resource(
 );
 
 attachTransformScopes(InMemoryThreadList, (scopes, parent) => {
-  const result = {
-    ...scopes,
-    thread:
-      scopes.thread ??
-      Derived({
-        source: "threads",
-        query: { type: "main" },
-        get: (aui) => aui.threads().thread("main"),
-      }),
-    threadListItem:
-      scopes.threadListItem ??
-      Derived({
-        source: "threads",
-        query: { type: "main" },
-        get: (aui) => aui.threads().item("main"),
-      }),
-    composer:
-      scopes.composer ??
-      Derived({
-        source: "thread",
-        query: {},
-        get: (aui) => aui.threads().thread("main").composer(),
-      }),
-  };
-
-  if (!result.modelContext && parent.modelContext.source === null) {
-    result.modelContext = ModelContext();
+  scopes.thread ??= Derived({
+    source: "threads",
+    query: { type: "main" },
+    get: (aui) => aui.threads().thread("main"),
+  });
+  scopes.threadListItem ??= Derived({
+    source: "threads",
+    query: { type: "main" },
+    get: (aui) => aui.threads().item("main"),
+  });
+  scopes.composer ??= Derived({
+    source: "thread",
+    query: {},
+    get: (aui) => aui.threads().thread("main").composer(),
+  });
+
+  if (!scopes.modelContext && parent.modelContext.source === null) {
+    scopes.modelContext = ModelContext();
   }
-  if (!result.tools && parent.tools.source === null) {
-    result.tools = Tools({});
+  if (!scopes.tools && parent.tools.source === null) {
+    scopes.tools = Tools({});
   }
-  if (!result.dataRenderers && parent.dataRenderers.source === null) {
-    result.dataRenderers = DataRenderers();
+  if (!scopes.dataRenderers && parent.dataRenderers.source === null) {
+    scopes.dataRenderers = DataRenderers();
   }
-  if (!result.suggestions && parent.suggestions.source === null) {
-    result.suggestions = Suggestions();
+  if (!scopes.suggestions && parent.suggestions.source === null) {
+    scopes.suggestions = Suggestions();
   }
-
-  return result;
 });

package/src/client/SingleThreadList.ts

@@ -0,0 +1,95 @@
+import { resource, tapMemo } from "@assistant-ui/tap";
+import {
+  type ClientElement,
+  type ClientOutput,
+  tapClientResource,
+} from "@assistant-ui/store";
+
+const THREAD_ID = "default";
+
+const SingleThreadListItem = resource((): ClientOutput<"threadListItem"> => {
+  return {
+    getState: () => ({
+      id: THREAD_ID,
+      remoteId: undefined,
+      externalId: undefined,
+      title: undefined,
+      status: "regular",
+    }),
+    switchTo: () => {},
+    rename: () => {},
+    archive: () => {},
+    unarchive: () => {},
+    delete: () => {},
+    generateTitle: () => {},
+    initialize: async () => ({ remoteId: THREAD_ID, externalId: undefined }),
+    detach: () => {},
+  };
+});
+
+type SingleThreadListProps = {
+  thread: ClientElement<"thread">;
+};
+
+/**
+ * A minimal threads scope that wraps a single thread.
+ * Automatically provided by ExternalThread when no threads scope exists.
+ * Mounts the provided thread resource element.
+ */
+export const SingleThreadList = resource(
+  ({ thread }: SingleThreadListProps): ClientOutput<"threads"> => {
+    const itemClient = tapClientResource(SingleThreadListItem());
+    const threadClient = tapClientResource(thread);
+
+    const state = tapMemo(
+      () => ({
+        mainThreadId: THREAD_ID,
+        newThreadId: null,
+        isLoading: false,
+        threadIds: [THREAD_ID],
+        archivedThreadIds: [],
+        threadItems: [itemClient.state],
+        main: threadClient.state,
+      }),
+      [itemClient.state, threadClient.state],
+    );
+
+    return {
+      getState: () => state,
+      switchToThread: () => {
+        throw new Error("SingleThreadList does not support switchToThread");
+      },
+      switchToNewThread: () => {
+        throw new Error("SingleThreadList does not support switchToNewThread");
+      },
+      item: (selector) => {
+        if (
+          selector !== "main" &&
+          !(
+            typeof selector === "object" &&
+            "id" in selector &&
+            selector.id === THREAD_ID
+          ) &&
+          !(
+            typeof selector === "object" &&
+            "index" in selector &&
+            selector.index === 0
+          )
+        ) {
+          throw new Error(
+            `SingleThreadList: unknown item selector ${JSON.stringify(selector)}`,
+          );
+        }
+        return itemClient.methods;
+      },
+      thread: (selector) => {
+        if (selector !== "main" && selector !== THREAD_ID) {
+          throw new Error(
+            `SingleThreadList: unknown thread selector ${JSON.stringify(selector)}`,
+          );
+        }
+        return threadClient.methods;
+      },
+    };
+  },
+);

package/src/context/index.ts

@@ -1,3 +1,67 @@
-export * from "./providers";
-export * from "./stores";
-export * from "./react";
+export { AssistantRuntimeProvider } from "../legacy-runtime/AssistantRuntimeProvider";
+export {
+  ThreadListItemByIndexProvider,
+  ThreadListItemRuntimeProvider,
+} from "./providers/ThreadListItemProvider";
+export { MessageByIndexProvider } from "./providers/MessageByIndexProvider";
+export { SuggestionByIndexProvider } from "./providers/SuggestionByIndexProvider";
+export { PartByIndexProvider } from "./providers/PartByIndexProvider";
+export {
+  MessageAttachmentByIndexProvider,
+  ComposerAttachmentByIndexProvider,
+} from "./providers/AttachmentByIndexProvider";
+export { TextMessagePartProvider } from "./providers/TextMessagePartProvider";
+export { MessageProvider } from "./providers/MessageProvider";
+export { ChainOfThoughtByIndicesProvider } from "./providers/ChainOfThoughtByIndicesProvider";
+export { ReadonlyThreadProvider } from "@assistant-ui/core/react";
+
+export type { ThreadViewportState } from "./stores/ThreadViewport";
+
+export {
+  useThreadViewport,
+  useThreadViewportStore,
+} from "./react/ThreadViewportContext";
+
+export {
+  useAssistantRuntime,
+  useThreadList,
+} from "../legacy-runtime/hooks/AssistantContext";
+
+export {
+  useAttachmentRuntime,
+  useAttachment,
+  useThreadComposerAttachmentRuntime,
+  useThreadComposerAttachment,
+  useEditComposerAttachmentRuntime,
+  useEditComposerAttachment,
+  useMessageAttachment,
+  useMessageAttachmentRuntime,
+} from "../legacy-runtime/hooks/AttachmentContext";
+
+export {
+  useComposerRuntime,
+  useComposer,
+} from "../legacy-runtime/hooks/ComposerContext";
+
+export {
+  useMessageRuntime,
+  useEditComposer,
+  useMessage,
+} from "../legacy-runtime/hooks/MessageContext";
+
+export {
+  useMessagePartRuntime,
+  useMessagePart,
+} from "../legacy-runtime/hooks/MessagePartContext";
+
+export {
+  useThreadRuntime,
+  useThread,
+  useThreadComposer,
+  useThreadModelContext,
+} from "../legacy-runtime/hooks/ThreadContext";
+
+export {
+  useThreadListItemRuntime,
+  useThreadListItem,
+} from "../legacy-runtime/hooks/ThreadListItemContext";

package/src/context/react/ThreadViewportContext.ts

@@ -5,7 +5,7 @@ import { ReadonlyStore } from "../ReadonlyStore";
 import { UseBoundStore } from "zustand";
 import { createContextHook } from "./utils/createContextHook";
 import { createContextStoreHook } from "./utils/createContextStoreHook";
-import { ThreadViewportState } from "../stores";
+import { ThreadViewportState } from "../stores/ThreadViewport";
 
 export type ThreadViewportContextValue = {
   useThreadViewport: UseBoundStore<ReadonlyStore<ThreadViewportState>>;

package/src/hooks/useMessageQuote.ts

@@ -1,7 +1,8 @@
 "use client";
 
-import { useAuiState } from "@assistant-ui/store";
 import type { QuoteInfo } from "@assistant-ui/core";
+import { getMessageQuote } from "@assistant-ui/core/react";
+import { useAuiState } from "@assistant-ui/store";
 
 /**
  * Hook that returns the quote info for the current message, if any.
@@ -18,10 +19,5 @@ import type { QuoteInfo } from "@assistant-ui/core";
  * ```
  */
 export const useMessageQuote = (): QuoteInfo | undefined => {
-  return useAuiState(
-    (s) =>
-      (s.message.metadata?.custom as Record<string, unknown>)?.quote as
-        | QuoteInfo
-        | undefined,
-  );
+  return useAuiState(getMessageQuote);
 };