@assistant-ui/core 0.3.12 → 0.3.13

package/src/store/clients/external-thread.ts

@@ -27,6 +27,7 @@ import type {
   RespondToToolApprovalOptions,
   ResumeToolCallOptions,
   SpeechState,
+  ThreadSuggestion,
 } from "../../runtime/interfaces/thread-runtime-core";
 import type {
   ExternalThreadQueueAdapter,
@@ -45,13 +46,14 @@ import { getThreadMessageText } from "../../utils/text";
 import { resolveToolApprovalResponse } from "../../runtime/utils/resolveToolApprovalResponse";
 import { toMessagePartStatus } from "../../utils/normalizePartStatus";
 import { ModelContext } from "./model-context-client";
-import { Suggestions } from "./suggestions";
+import { ThreadSuggestions } from "./suggestions";
 import { Tools } from "../../react/client/Tools";
 import { DataRenderers } from "../../react/client/DataRenderers";
 import { SingleThreadList } from "./single-thread-list";
 
 const EMPTY_QUEUE_ITEMS: readonly QueueItemState[] = [];
 const EMPTY_BRANCH_IDS: readonly string[] = [];
+const EMPTY_SUGGESTIONS: readonly ThreadSuggestion[] = [];
 
 export type ExternalThreadMessage = ThreadMessage & {
   id: string;
@@ -93,6 +95,13 @@ export type ExternalThreadProps = {
   onStartRun?: () => void;
   onCancel?: () => void;
   onResume?: (() => void) | undefined;
+  /**
+   * Handler for re-fetching this thread's state in place, driving
+   * `threads.reloadMainThread()`. Unrelated to `onReload`, which re-generates
+   * an assistant message. Presence enables the `refetchThread` capability;
+   * rejections propagate to the caller.
+   */
+  onRefetchThread?: (() => Promise<void>) | undefined;
   onAddToolResult?: ((options: AddToolResultOptions) => void) | undefined;
   /** Callback for resuming a tool call that is waiting for human input. */
   onResumeToolCall?: ((options: ResumeToolCallOptions) => void) | undefined;
@@ -401,6 +410,7 @@ const AttachmentResource = resource(useAttachmentResource);
 type ComposerClientResourceProps = {
   type: "thread" | "edit";
   canCancel: boolean;
+  isRunning?: boolean;
   isSendDisabled?: boolean;
   onCancel?: () => void;
   onBeginEdit?: () => void;
@@ -410,6 +420,53 @@ type ComposerClientResourceProps = {
   attachmentAdapter?: AttachmentAdapter | undefined;
 };
 
+type AttachmentAddOperation = {
+  cancelled: boolean;
+  attachmentIds: Set<string>;
+};
+
+class AttachmentAddOperations {
+  private readonly operations = new Set<AttachmentAddOperation>();
+
+  start() {
+    const operation: AttachmentAddOperation = {
+      cancelled: false,
+      attachmentIds: new Set(),
+    };
+    this.operations.add(operation);
+    return operation;
+  }
+
+  accept(operation: AttachmentAddOperation, attachmentId: string) {
+    if (operation.cancelled) return false;
+    operation.attachmentIds.add(attachmentId);
+    return true;
+  }
+
+  finish(operation: AttachmentAddOperation) {
+    this.operations.delete(operation);
+  }
+
+  isCancelled(operation: AttachmentAddOperation) {
+    return operation.cancelled;
+  }
+
+  cancel(attachmentId: string) {
+    for (const operation of [...this.operations]) {
+      if (!operation.attachmentIds.has(attachmentId)) continue;
+      operation.cancelled = true;
+      this.operations.delete(operation);
+    }
+  }
+
+  cancelAll() {
+    for (const operation of this.operations) {
+      operation.cancelled = true;
+    }
+    this.operations.clear();
+  }
+}
+
 const useQueueItemClient = ({
   item,
   onMove,
@@ -431,11 +488,11 @@ const QueueItemClient = resource(useQueueItemClient);
 
 const drainAdapterAdd = async (
   result: ReturnType<AttachmentAdapter["add"]>,
-  upsert: (attachment: Attachment) => void,
+  upsert: (attachment: Attachment) => boolean,
 ) => {
   if (Symbol.asyncIterator in result) {
     for await (const attachment of result) {
-      upsert(attachment);
+      if (!upsert(attachment)) break;
     }
   } else {
     upsert(await result);
@@ -460,6 +517,7 @@ const useLiveState = <T>(initial: T) => {
 const useComposerClientResource = ({
   type,
   canCancel,
+  isRunning = false,
   isSendDisabled = false,
   onCancel,
   onBeginEdit,
@@ -484,6 +542,10 @@ const useComposerClientResource = ({
   const [quote, setQuote, quoteRef] = useLiveState<
     { readonly text: string; readonly messageId: string } | undefined
   >(undefined);
+  const attachmentAddOperations = useMemo(
+    () => new AttachmentAddOperations(),
+    [],
+  );
 
   const updateFromMessage = () => {
     if (!message) return;
@@ -503,6 +565,7 @@ const useComposerClientResource = ({
         AttachmentResource({
           attachment,
           onRemove: async () => {
+            attachmentAddOperations.cancel(attachment.id);
             await attachmentAdapter?.remove(attachment);
             setAttachments((prev) =>
               prev.filter((a) => a.id !== attachment.id),
@@ -607,10 +670,22 @@ const useComposerClientResource = ({
           );
       }
       if (!isCreateAttachment(fileOrAttachment) && attachmentAdapter) {
-        await drainAdapterAdd(
-          attachmentAdapter.add({ file: fileOrAttachment }),
-          upsertAttachment,
-        );
+        const operation = attachmentAddOperations.start();
+        try {
+          await drainAdapterAdd(
+            attachmentAdapter.add({ file: fileOrAttachment }),
+            (attachment) => {
+              if (!attachmentAddOperations.accept(operation, attachment.id))
+                return false;
+              upsertAttachment(attachment);
+              return true;
+            },
+          );
+          attachmentAddOperations.finish(operation);
+        } catch (error) {
+          attachmentAddOperations.finish(operation);
+          if (!attachmentAddOperations.isCancelled(operation)) throw error;
+        }
       } else if (!isCreateAttachment(fileOrAttachment)) {
         const newAttachment: Attachment = {
           id: Math.random().toString(36).substring(7),
@@ -635,6 +710,7 @@ const useComposerClientResource = ({
       }
     },
     clearAttachments: async () => {
+      attachmentAddOperations.cancelAll();
       const removed = attachmentsRef.current;
       setAttachments([]);
       await removePendingAttachments(removed);
@@ -646,6 +722,7 @@ const useComposerClientResource = ({
       return attachmentClients.get(selector);
     },
     reset: async () => {
+      attachmentAddOperations.cancelAll();
       const removed = attachmentsRef.current;
       setText("");
       setRole("user");
@@ -657,18 +734,21 @@ const useComposerClientResource = ({
     send: (opts?: ComposerSendOptions) => {
       const currentQuote = quoteRef.current;
       const currentText = textRef.current;
+      const currentRole = roleRef.current;
+      const currentRunConfig = runConfigRef.current;
       const currentAttachments = attachmentsRef.current;
       const isEmpty = !currentText.trim() && !currentAttachments.length;
       if (!isEditingRef.current) throw new Error("Composer is not available");
       if (isEmpty || isSendDisabled) return;
 
+      attachmentAddOperations.cancelAll();
       setText("");
       setAttachments([]);
       setQuote(undefined);
 
       const dispatch = (sendAttachments: readonly Attachment[]) => {
         const composedMessage: AppendMessage = {
-          role: roleRef.current,
+          role: currentRole,
           content: currentText
             ? [{ type: "text" as const, text: currentText }]
             : [],
@@ -676,7 +756,7 @@ const useComposerClientResource = ({
           createdAt: new Date(),
           parentId: null,
           sourceId: null,
-          runConfig: runConfigRef.current,
+          runConfig: currentRunConfig,
           startRun: opts?.startRun,
           metadata: {
             custom: { ...(currentQuote ? { quote: currentQuote } : {}) },
@@ -684,7 +764,7 @@ const useComposerClientResource = ({
         };
         // edit sends carry a sourceId contract; only thread sends queue
         if (queue && type === "thread") {
-          if (opts?.steer ?? canCancel) queue.steer(composedMessage);
+          if (opts?.steer ?? isRunning) queue.steer(composedMessage);
           else queue.enqueue(composedMessage);
         } else {
           onSend?.(composedMessage);
@@ -829,6 +909,7 @@ const useExternalThread = ({
   onStartRun,
   onCancel,
   onResume,
+  onRefetchThread,
   onAddToolResult,
   onResumeToolCall,
   onLoadExternalState,
@@ -942,7 +1023,15 @@ const useExternalThread = ({
   );
 
   const handleCancelRun = () => {
-    onCancel?.();
+    // Nothing is aborted without a handler, so pausing the queue would hold
+    // the pending items against a run that keeps going.
+    if (!onCancel) return;
+
+    // Before the run is aborted, so the settle it produces keeps the pending
+    // items instead of dispatching the next one at the moment the user
+    // stopped.
+    queue?.__internal_notifyCancelled?.();
+    onCancel();
   };
 
   const handleSendNew = (message: AppendMessage) => {
@@ -952,6 +1041,8 @@ const useExternalThread = ({
   };
 
   const headId = messages.at(-1)?.id ?? null;
+  const hasCancel = !!onCancel;
+  const hasRefetchThread = !!onRefetchThread;
   const composerQueue = useMemo(
     (): ExternalThreadQueueAdapter | undefined =>
       queue && {
@@ -967,7 +1058,8 @@ const useExternalThread = ({
   const composerClient = useClientResource(
     ComposerClientResource({
       type: "thread",
-      canCancel: isRunning,
+      canCancel: isRunning && hasCancel,
+      isRunning,
       isSendDisabled,
       onCancel: handleCancelRun,
       onSend: handleSendNew,
@@ -975,6 +1067,9 @@ const useExternalThread = ({
       attachmentAdapter,
     }),
   );
+  const suggestionsClient = useClientResource(
+    ThreadSuggestions(EMPTY_SUGGESTIONS),
+  );
 
   const hasQueue = !!queue;
   const hasBranches = !!branches;
@@ -998,8 +1093,8 @@ const useExternalThread = ({
         edit: hasEdit,
         delete: false,
         reload: hasReload,
-        refetchThread: false,
-        cancel: isRunning,
+        refetchThread: hasRefetchThread,
+        cancel: hasCancel,
         speech: hasSpeech,
         attachments: hasAttachments,
         feedback: hasFeedback,
@@ -1012,7 +1107,7 @@ const useExternalThread = ({
       },
       messages: messageStates,
       state: threadState ?? {},
-      suggestions: [],
+      suggestions: EMPTY_SUGGESTIONS,
       extras,
       speech,
       voice: undefined,
@@ -1028,6 +1123,8 @@ const useExternalThread = ({
     hasBranches,
     hasEdit,
     hasReload,
+    hasCancel,
+    hasRefetchThread,
     hasAttachments,
     hasFeedback,
     hasSpeech,
@@ -1039,6 +1136,7 @@ const useExternalThread = ({
   return {
     getState: () => state,
     composer: () => composerClient.methods,
+    suggestions: () => suggestionsClient.methods,
     append: (message) => {
       const appendMessage: AppendMessage =
         typeof message === "string"
@@ -1081,6 +1179,7 @@ const useExternalThread = ({
       onResume();
     },
     cancelRun: handleCancelRun,
+    ...(onRefetchThread && { unstable_refetchThread: onRefetchThread }),
     importExternalState: (state: unknown) => {
       if (!onLoadExternalState)
         throw new Error(
@@ -1147,6 +1246,10 @@ attachTransformScopes(useExternalThread, (scopes, parent) => {
     scopes.dataRenderers = DataRenderers();
   }
   if (!scopes.suggestions && parent.suggestions.source === null) {
-    scopes.suggestions = Suggestions();
+    scopes.suggestions = Derived({
+      source: "thread",
+      query: {},
+      get: (aui) => aui.thread.suggestions(),
+    });
   }
 });

package/src/store/clients/runtime-adapter.ts

@@ -1,7 +1,6 @@
 import type { AssistantClient, ScopesConfig } from "@assistant-ui/store";
 import { Derived } from "@assistant-ui/store/client";
 import { ModelContext } from "./model-context-client";
-import { Suggestions } from "./suggestions";
 
 export const baseRuntimeAdapterTransformScopes = (
   scopes: ScopesConfig,
@@ -27,6 +26,10 @@ export const baseRuntimeAdapterTransformScopes = (
     scopes.modelContext = ModelContext();
   }
   if (!scopes.suggestions && parent.suggestions.source === null) {
-    scopes.suggestions = Suggestions();
+    scopes.suggestions = Derived({
+      source: "thread",
+      query: {},
+      get: (aui) => aui.thread.suggestions(),
+    });
   }
 };

package/src/store/clients/single-thread-list.ts

@@ -79,7 +79,8 @@ const useSingleThreadList = ({
     },
     getLoadThreadsPromise: () => RESOLVED_PROMISE,
     reload: () => RESOLVED_PROMISE,
-    reloadMainThread: () => RESOLVED_PROMISE,
+    reloadMainThread: () =>
+      threadClient.methods.unstable_refetchThread?.() ?? RESOLVED_PROMISE,
     loadMore: () => RESOLVED_PROMISE,
     item: (selector) => {
       if (

package/src/store/clients/suggestions.ts

@@ -1,9 +1,10 @@
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import { resource, withKey } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import { useClientLookup } from "@assistant-ui/store/client";
 import type { SuggestionsState } from "../scopes/suggestions";
 import type { SuggestionState } from "../scopes/suggestion";
+import type { ThreadSuggestion } from "../../runtime/interfaces/thread-runtime-core";
 
 export type SuggestionConfig =
   | string
@@ -19,7 +20,24 @@ const useSuggestionClient = (
 
 const SuggestionClient = resource(useSuggestionClient);
 
-const useSuggestionsResource = (
+const useSuggestionsClient = (
+  state: SuggestionsState,
+): ClientOutput<"suggestions"> => {
+  const suggestionClients = useClientLookup(
+    state.suggestions.map((suggestion, index) =>
+      withKey(index, SuggestionClient(suggestion), [suggestion]),
+    ),
+  );
+
+  return {
+    getState: () => state,
+    suggestion: ({ index }: { index: number }) => {
+      return suggestionClients.get({ index });
+    },
+  };
+};
+
+const useStaticSuggestions = (
   suggestions?: SuggestionConfig[],
 ): ClientOutput<"suggestions"> => {
   const [state] = useState<SuggestionsState>(() => {
@@ -43,18 +61,26 @@ const useSuggestionsResource = (
     };
   });
 
-  const suggestionClients = useClientLookup(
-    state.suggestions.map((suggestion, index) =>
-      withKey(index, SuggestionClient(suggestion), [suggestion]),
-    ),
+  return useSuggestionsClient(state);
+};
+
+export const Suggestions = resource(useStaticSuggestions);
+
+const useThreadSuggestions = (
+  suggestions: readonly ThreadSuggestion[],
+): ClientOutput<"suggestions"> => {
+  const state = useMemo<SuggestionsState>(
+    () => ({
+      suggestions: suggestions.map((s) => ({
+        title: s.prompt,
+        label: "",
+        prompt: s.prompt,
+      })),
+    }),
+    [suggestions],
   );
 
-  return {
-    getState: () => state,
-    suggestion: ({ index }: { index: number }) => {
-      return suggestionClients.get({ index });
-    },
-  };
+  return useSuggestionsClient(state);
 };
 
-export const Suggestions = resource(useSuggestionsResource);
+export const ThreadSuggestions = resource(useThreadSuggestions);

package/src/store/runtime-clients/thread-list-item-runtime-client.ts

@@ -1,12 +1,8 @@
-import type { Unsubscribe } from "../../types/unsubscribe";
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { resource } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import { useAssistantEmit } from "@assistant-ui/store/client";
-import type {
-  ThreadListItemEventType,
-  ThreadListItemRuntime,
-} from "../../runtime/api/thread-list-item-runtime";
+import type { ThreadListItemRuntime } from "../../runtime/api/thread-list-item-runtime";
 import { useSubscribable } from "./useSubscribable";
 
 const useThreadListItemClient = ({
@@ -28,29 +24,18 @@ const useThreadListItemClient = ({
   }, [runtimeState, mainThreadIsRunning]);
   const emit = useAssistantEmit();
 
-  // Bind thread list item events to event manager
+  // Emitted after the flush that rebinds the derived scopes; the runtime's own
+  // synchronous notification would be delivered against the pre-switch binding.
+  const { isMain, id: threadId } = runtimeState;
+  const selectionRef = useRef({ isMain, threadId });
   useEffect(() => {
-    const unsubscribers: Unsubscribe[] = [];
-
-    // Subscribe to thread list item events
-    const threadListItemEvents: ThreadListItemEventType[] = [
-      "switchedTo",
-      "switchedAway",
-    ];
-
-    for (const event of threadListItemEvents) {
-      const unsubscribe = runtime.unstable_on(event, () => {
-        emit(`threadListItem.${event}`, {
-          threadId: runtime.getState()!.id,
-        });
-      });
-      unsubscribers.push(unsubscribe);
-    }
-
-    return () => {
-      for (const unsub of unsubscribers) unsub();
-    };
-  }, [runtime, emit]);
+    const previous = selectionRef.current;
+    if (previous.isMain === isMain && previous.threadId === threadId) return;
+    selectionRef.current = { isMain, threadId };
+    emit(isMain ? "threadListItem.switchedTo" : "threadListItem.switchedAway", {
+      threadId,
+    });
+  }, [isMain, threadId, emit]);
 
   return {
     getState: () => state,

package/src/store/runtime-clients/thread-runtime-client.ts

@@ -12,6 +12,7 @@ import {
 } from "@assistant-ui/store/client";
 import { ComposerClient } from "./composer-runtime-client";
 import { MessageClient } from "./message-runtime-client";
+import { ThreadSuggestions } from "../clients/suggestions";
 import { useSubscribable } from "./useSubscribable";
 import type { ThreadState } from "../scopes/thread";
 
@@ -78,6 +79,9 @@ const useThreadClient = ({
       threadIdRef,
     }),
   );
+  const suggestions = useClientResource(
+    ThreadSuggestions(runtimeState.suggestions),
+  );
   const messages = useClientLookup(
     runtimeState.messages.map((m) =>
       withKey(m.id, MessageClientById({ runtime, id: m.id, threadIdRef }), [
@@ -109,6 +113,7 @@ const useThreadClient = ({
   return {
     getState: () => state,
     composer: () => composer.methods,
+    suggestions: () => suggestions.methods,
     append: runtime.append,
     deleteMessage: runtime.deleteMessage,
     startRun: runtime.startRun,

package/src/store/scopes/suggestions.ts

@@ -15,6 +15,12 @@ export type SuggestionsMethods = {
   suggestion(query: { index: number }): SuggestionMethods;
 };
 
+export type SuggestionsMeta = {
+  source: "thread";
+  query: Record<string, never>;
+};
+
 export type SuggestionsClientSchema = {
   methods: SuggestionsMethods;
+  meta: SuggestionsMeta;
 };

package/src/store/scopes/thread.ts

@@ -17,6 +17,7 @@ import type {
 import type { ModelContext } from "../../model-context/types";
 import type { MessageMethods, MessageState } from "./message";
 import type { ComposerMethods, ComposerState } from "./composer";
+import type { SuggestionsMethods } from "./suggestions";
 
 export type ThreadState = {
   /**
@@ -71,6 +72,10 @@ export type ThreadMethods = {
    * The thread composer runtime.
    */
   composer(): ComposerMethods;
+  /**
+   * The suggestions shown for this thread.
+   */
+  suggestions(): SuggestionsMethods;
   /**
    * Append a new message to the thread.
    *
@@ -100,6 +105,18 @@ export type ThreadMethods = {
    */
   resumeRun(config: CreateResumeRunConfig): void;
   cancelRun(): void;
+  /**
+   * Re-fetch this thread's state from its backing store, in place: the tap
+   * thread's refetch hook, which `threads.reloadMainThread()` prefers and
+   * whose rejection it propagates. `capabilities.refetchThread` is the
+   * portable feature-detection signal; a legacy-bridged thread reports it
+   * there while routing the refetch through its runtime, not this method.
+   * The method-shorthand optionality is load-bearing: an explicit
+   * `| undefined` stops `ThreadMethods` satisfying `ClientMethods` and
+   * collapses the client schema, which only a workspace-level app typecheck
+   * surfaces.
+   */
+  unstable_refetchThread?(): Promise<void>;
   getModelContext(): ModelContext;
   export(): ExportedMessageRepository;
   import(repository: ExportedMessageRepository): void;