@assistant-ui/core 0.3.14 → 0.3.16

package/src/react/client/RemoteThreadList.ts

@@ -13,21 +13,25 @@ import {
   useClientResource,
 } from "@assistant-ui/store/client";
 import { isDevelopment, useThreadSelectionEvents } from "../../store/internal";
-import { generateId } from "../../utils/id";
 import { OptimisticState } from "../../runtimes/remote-thread-list/optimistic-state";
 import {
   classifyThreads,
+  createEmptyRemoteThreadState,
   createThreadMappingId,
   getThreadData,
   normalizeCursor,
   updateStatusReducer,
   type RemoteThreadData,
   type RemoteThreadState,
+  preserveMidLoadTransitions,
+  seedNewThread,
+  statusSnapshot,
 } from "../../runtimes/remote-thread-list/remote-thread-state";
 import type {
   RemoteThreadInitializeResponse,
   RemoteThreadListAdapter,
 } from "../../runtimes/remote-thread-list/types";
+import { ThreadListAdapterChangedError } from "../../runtimes/remote-thread-list/adapter-changed";
 import type { ThreadMessage } from "../../types/message";
 import { AssistantMessageStream } from "assistant-stream";
 import { handleThreadListAction } from "../../store/runtime-clients/handle-thread-list-action";
@@ -39,20 +43,11 @@ import { AdaptedRemoteThread } from "./AdaptedRemoteThread";
 
 const RESOLVED_PROMISE = Promise.resolve();
 
-const EMPTY_LIST: RemoteThreadState = {
-  isLoading: true,
-  isLoadingMore: false,
-  cursor: undefined,
-  newThreadId: undefined,
-  threadIds: [],
-  archivedThreadIds: [],
-  threadIdMap: {},
-  threadData: {},
-};
+const EMPTY_LIST = createEmptyRemoteThreadState();
 
 export type RemoteThreadListProps = {
   /**
-   * Swapping this to a different backing store does not reload the list. Call `reload()` after a genuine swap. A recreated object for the same store is a no-op.
+   * Swapping this to a different backing store does not reload the list. Call `reload()` after a genuine swap. A recreated object for the same store is a no-op. `reload()` after a different adapter instance resets selection and cached records before loading.
    */
   adapter: RemoteThreadListAdapter;
   /**
@@ -90,46 +85,14 @@ const toInitializeResult = (
 
 const applyTitleStream = async (
   stream: Parameters<typeof AssistantMessageStream.fromAssistantStream>[0],
-  onTitle: (title: string | undefined) => void,
+  onTitle: (title: string | undefined) => Promise<void>,
 ) => {
   const messageStream = AssistantMessageStream.fromAssistantStream(stream);
   for await (const result of messageStream) {
-    onTitle(result.parts.filter((part) => part.type === "text")[0]?.text);
+    await onTitle(result.parts.filter((part) => part.type === "text")[0]?.text);
   }
 };
 
-const seedNewThread = (
-  state: RemoteThreadState,
-): { id: string; state: RemoteThreadState } => {
-  let id: string;
-  do {
-    id = `__LOCALID_${generateId()}`;
-  } while (state.threadIdMap[id]);
-  const mappingId = createThreadMappingId(id);
-  return {
-    id,
-    state: {
-      ...state,
-      newThreadId: id,
-      threadIdMap: {
-        ...state.threadIdMap,
-        [id]: mappingId,
-      },
-      threadData: {
-        ...state.threadData,
-        [mappingId]: {
-          status: "new",
-          id,
-          remoteId: undefined,
-          externalId: undefined,
-          title: undefined,
-          custom: undefined,
-        },
-      },
-    },
-  };
-};
-
 const useThreadListItemClient = (props: {
   data: RemoteThreadData;
   isRunning: boolean;
@@ -359,6 +322,8 @@ const useRemoteThreadList = (
       initialMainId: seeded.id,
       session: {
         adapter,
+        adapterAtLoad: adapter,
+        adapterGeneration: 0,
         loadGeneration: 0,
         switchGeneration: 0,
         loadPromise: undefined as Promise<void> | undefined,
@@ -375,6 +340,9 @@ const useRemoteThreadList = (
     };
   });
 
+  // Config updates can invoke `reload()` in the same turn as the re-render, before the effect below runs.
+  session.adapter = adapter;
+
   const listState = useSyncExternalStore(
     (onStoreChange) => store.subscribe(onStoreChange),
     () => store.value,
@@ -417,19 +385,22 @@ const useRemoteThreadList = (
   const getLoadThreadsPromise = useCallback(() => {
     if (session.loadPromise) return session.loadPromise;
     const generation = session.loadGeneration;
+    const adapter = session.adapter;
+    const statusAtRequest = statusSnapshot(store.baseValue);
     session.loadPromise = store
       .optimisticUpdate({
-        execute: () => session.adapter.list(),
+        execute: () => adapter.list(),
         loading: (state) => ({ ...state, isLoading: true }),
         then: (state, page) => {
           if (generation !== session.loadGeneration) return state;
+          session.adapterAtLoad = adapter;
           const fresh = classifyThreads(page.threads, {
             threadIds: [],
             archivedThreadIds: [],
             threadIdMap: {},
             threadData: {},
           });
-          return {
+          const merged = {
             ...state,
             isLoading: false,
             cursor: normalizeCursor(page.nextCursor),
@@ -444,6 +415,7 @@ const useRemoteThreadList = (
               ...fresh.threadData,
             },
           };
+          return preserveMidLoadTransitions(merged, state, statusAtRequest);
         },
       })
       .catch((error: unknown) => {
@@ -460,15 +432,34 @@ const useRemoteThreadList = (
   }, [session, store]);
 
   const reload = useCallback(() => {
+    const adapterChanged = adapter !== session.adapterAtLoad;
     session.loadGeneration++;
     session.loadPromise = undefined;
     session.loadMorePromise = undefined;
-    store.update({
-      ...store.baseValue,
-      cursor: undefined,
-    });
+    if (adapterChanged) {
+      session.adapterGeneration++;
+      session.switchGeneration++;
+      session.switchTask = undefined;
+      session.adapterAtLoad = adapter;
+      const seeded = seedNewThread(EMPTY_LIST);
+      store.reset({ ...seeded.state, isLoading: true });
+      assignMainThreadId(seeded.id);
+      notifyRemoteId(undefined, true);
+    } else {
+      store.update({
+        ...store.baseValue,
+        cursor: undefined,
+      });
+    }
     return getLoadThreadsPromise();
-  }, [getLoadThreadsPromise, session, store]);
+  }, [
+    adapter,
+    assignMainThreadId,
+    getLoadThreadsPromise,
+    notifyRemoteId,
+    session,
+    store,
+  ]);
 
   useEffect(() => {
     void getLoadThreadsPromise();
@@ -516,6 +507,7 @@ const useRemoteThreadList = (
         },
       })
       .catch((error: unknown) => {
+        if (generation !== session.loadGeneration) return;
         console.error("[assistant-ui] thread list loadMore failed:", error);
       })
       .then(() => {
@@ -689,18 +681,34 @@ const useRemoteThreadList = (
     [session, store, switchToNewThread],
   );
 
+  const requireAdapterGeneration = useCallback(
+    (generation: number) => {
+      if (generation !== session.adapterGeneration) {
+        throw new ThreadListAdapterChangedError();
+      }
+    },
+    [session],
+  );
+
   const initialize = useCallback(
     async (threadId: string) => {
+      const currentAdapter = session.adapter;
+      const adapterGeneration = session.adapterGeneration;
       if (store.value.newThreadId !== threadId) {
         const data = getThreadData(store.value, threadId);
         if (!data) throw threadNotFoundError(threadId, "initializing it");
         if (data.status === "new") {
           throw threadStatusError(threadId, data.status, "be initialized here");
         }
-        return toInitializeResult(await data.initializeTask);
+        const result = toInitializeResult(await data.initializeTask);
+        requireAdapterGeneration(adapterGeneration);
+        return result;
       }
       const result = await store.optimisticUpdate({
-        execute: () => session.adapter.initialize(threadId),
+        execute: () => {
+          requireAdapterGeneration(adapterGeneration);
+          return currentAdapter.initialize(threadId);
+        },
         optimistic: (state) => updateStatusReducer(state, threadId, "regular"),
         loading: (state, task) => {
           const mappingId = createThreadMappingId(threadId);
@@ -716,6 +724,7 @@ const useRemoteThreadList = (
           };
         },
         then: (state, { remoteId, externalId }) => {
+          if (adapterGeneration !== session.adapterGeneration) return state;
           const data = getThreadData(state, threadId);
           if (!data) return state;
           const mappingId = createThreadMappingId(threadId);
@@ -737,16 +746,19 @@ const useRemoteThreadList = (
           };
         },
       });
+      requireAdapterGeneration(adapterGeneration);
       if (threadId === session.mainThreadId) {
         notifyRemoteId(result.remoteId, true);
       }
       return toInitializeResult(result);
     },
-    [notifyRemoteId, session, store],
+    [notifyRemoteId, requireAdapterGeneration, session, store],
   );
 
   const rename = useCallback(
     (threadIdOrRemoteId: string, newTitle: string) => {
+      const currentAdapter = session.adapter;
+      const adapterGeneration = session.adapterGeneration;
       const data = getThreadData(store.value, threadIdOrRemoteId);
       if (!data) throw threadNotFoundError(threadIdOrRemoteId, "renaming it");
       if (data.status === "new") {
@@ -755,7 +767,8 @@ const useRemoteThreadList = (
       return store.optimisticUpdate({
         execute: async () => {
           const { remoteId } = await data.initializeTask;
-          return session.adapter.rename(remoteId, newTitle);
+          requireAdapterGeneration(adapterGeneration);
+          return currentAdapter.rename(remoteId, newTitle);
         },
         optimistic: (state) => {
           const current = getThreadData(state, threadIdOrRemoteId);
@@ -773,7 +786,7 @@ const useRemoteThreadList = (
         },
       });
     },
-    [session, store],
+    [requireAdapterGeneration, session, store],
   );
 
   const updateCustom = useCallback(
@@ -781,6 +794,8 @@ const useRemoteThreadList = (
       threadIdOrRemoteId: string,
       custom: Record<string, unknown> | undefined,
     ) => {
+      const currentAdapter = session.adapter;
+      const adapterGeneration = session.adapterGeneration;
       const data = getThreadData(store.value, threadIdOrRemoteId);
       if (!data) {
         throw threadNotFoundError(
@@ -795,7 +810,7 @@ const useRemoteThreadList = (
           "update custom metadata",
         );
       }
-      if (!session.adapter.updateCustom) {
+      if (!currentAdapter.updateCustom) {
         throw new Error(
           "Remote thread list adapter does not support updating custom metadata",
         );
@@ -803,7 +818,7 @@ const useRemoteThreadList = (
       return store.optimisticUpdate({
         execute: async () => {
           const { remoteId } = await data.initializeTask;
-          const currentAdapter = session.adapter;
+          requireAdapterGeneration(adapterGeneration);
           if (!currentAdapter.updateCustom) {
             throw new Error(
               "Remote thread list adapter does not support updating custom metadata",
@@ -827,30 +842,36 @@ const useRemoteThreadList = (
         },
       });
     },
-    [session, store],
+    [requireAdapterGeneration, session, store],
   );
 
   const archive = useCallback(
     async (threadIdOrRemoteId: string) => {
+      const currentAdapter = session.adapter;
+      const adapterGeneration = session.adapterGeneration;
       const data = getThreadData(store.value, threadIdOrRemoteId);
       if (!data) throw threadNotFoundError(threadIdOrRemoteId, "archiving it");
       if (data.status !== "regular") {
         throw threadStatusError(threadIdOrRemoteId, data.status, "be archived");
       }
       await ensureNotMain(data.id);
+      requireAdapterGeneration(adapterGeneration);
       return store.optimisticUpdate({
         execute: async () => {
           const { remoteId } = await data.initializeTask;
-          return session.adapter.archive(remoteId);
+          requireAdapterGeneration(adapterGeneration);
+          return currentAdapter.archive(remoteId);
         },
         optimistic: (state) => updateStatusReducer(state, data.id, "archived"),
       });
     },
-    [ensureNotMain, session, store],
+    [ensureNotMain, requireAdapterGeneration, session, store],
   );
 
   const unarchive = useCallback(
     (threadIdOrRemoteId: string) => {
+      const currentAdapter = session.adapter;
+      const adapterGeneration = session.adapterGeneration;
       const data = getThreadData(store.value, threadIdOrRemoteId);
       if (!data)
         throw threadNotFoundError(threadIdOrRemoteId, "unarchiving it");
@@ -865,36 +886,43 @@ const useRemoteThreadList = (
         execute: async () => {
           try {
             const { remoteId } = await data.initializeTask;
-            return await session.adapter.unarchive(remoteId);
+            requireAdapterGeneration(adapterGeneration);
+            return await currentAdapter.unarchive(remoteId);
           } catch (error) {
-            await ensureNotMain(data.id);
+            if (adapterGeneration === session.adapterGeneration) {
+              await ensureNotMain(data.id);
+            }
             throw error;
           }
         },
         optimistic: (state) => updateStatusReducer(state, data.id, "regular"),
       });
     },
-    [ensureNotMain, session, store],
+    [ensureNotMain, requireAdapterGeneration, session, store],
   );
 
   const deleteThread = useCallback(
     async (threadIdOrRemoteId: string) => {
+      const currentAdapter = session.adapter;
+      const adapterGeneration = session.adapterGeneration;
       const data = getThreadData(store.value, threadIdOrRemoteId);
       if (!data) throw threadNotFoundError(threadIdOrRemoteId, "deleting it");
       if (data.status !== "regular" && data.status !== "archived") {
         throw threadStatusError(threadIdOrRemoteId, data.status, "be deleted");
       }
       await ensureNotMain(data.id);
+      requireAdapterGeneration(adapterGeneration);
       onDelete?.(data.id);
       return store.optimisticUpdate({
         execute: async () => {
           const { remoteId } = await data.initializeTask;
-          return session.adapter.delete(remoteId);
+          requireAdapterGeneration(adapterGeneration);
+          return currentAdapter.delete(remoteId);
         },
         optimistic: (state) => updateStatusReducer(state, data.id, "deleted"),
       });
     },
-    [ensureNotMain, onDelete, session, store],
+    [ensureNotMain, onDelete, requireAdapterGeneration, session, store],
   );
 
   const generateTitle = useCallback(
@@ -902,6 +930,8 @@ const useRemoteThreadList = (
       threadIdOrRemoteId: string,
       messages: readonly ThreadMessage[] | undefined,
     ) => {
+      const currentAdapter = session.adapter;
+      const adapterGeneration = session.adapterGeneration;
       const data = getThreadData(store.value, threadIdOrRemoteId);
       if (!data) {
         throw threadNotFoundError(threadIdOrRemoteId, "generating its title");
@@ -914,26 +944,33 @@ const useRemoteThreadList = (
         );
       }
       const { remoteId } = await data.initializeTask;
+      requireAdapterGeneration(adapterGeneration);
       if (!isSameThread(store.value, data.id, session.mainThreadId)) return;
       if (!messages) return;
-      const stream = await session.adapter.generateTitle(remoteId, messages);
-      await applyTitleStream(stream, (newTitle) => {
-        const state = store.baseValue;
-        const current = getThreadData(state, data.id);
-        if (!current) return;
-        store.update({
-          ...state,
-          threadData: {
-            ...state.threadData,
-            [current.id]: {
-              ...current,
-              title: newTitle,
-            },
+      const stream = await currentAdapter.generateTitle(remoteId, messages);
+      requireAdapterGeneration(adapterGeneration);
+      await applyTitleStream(stream, async (newTitle) => {
+        await store.optimisticUpdate({
+          execute: async () => {},
+          optimistic: (state) => {
+            if (adapterGeneration !== session.adapterGeneration) return state;
+            const current = getThreadData(state, data.id);
+            if (!current) return state;
+            return {
+              ...state,
+              threadData: {
+                ...state.threadData,
+                [current.id]: {
+                  ...current,
+                  title: newTitle,
+                },
+              },
+            };
           },
         });
       });
     },
-    [session, store],
+    [requireAdapterGeneration, session, store],
   );
 
   const { mainThreadClient, itemOrder, threadListItems } =

package/src/react/interactables-legacy/Interactables.ts

@@ -17,8 +17,7 @@ import { toJSONSchema, toPartialJSONSchema } from "assistant-stream";
 import { ModelContext } from "../../store";
 import { buildInteractableModelContext } from "./interactable-model-context";
 import { notifySubscribers as notifyStateSubscribers } from "../../subscribable/subscribable";
-
-const PERSISTENCE_DEBOUNCE_MS = 500;
+import { useInteractablePersistenceQueue } from "../interactables-shared/useInteractablePersistenceQueue";
 
 const useInteractables = (): ClientOutput<"interactables"> => {
   const [state, setState] = useState<InteractablesState>(() => ({
@@ -48,26 +47,6 @@ const useInteractables = (): ClientOutput<"interactables"> => {
   const adapterRef = useRef<InteractablePersistenceAdapter | undefined>(
     undefined,
   );
-  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
-    undefined,
-  );
-  const syncSeqRef = useRef(0);
-  const latestSyncSeqByIdRef = useRef(new Map<string, number>());
-  const inFlightPersistenceRef = useRef(0);
-  const flushResolversRef = useRef<Array<() => void>>([]);
-  const dirtyIdsRef = useRef(new Set<string>());
-
-  type PersistenceBatch = {
-    adapter: InteractablePersistenceAdapter;
-    payload: InteractablePersistedState;
-    dirtyIds: Set<string>;
-    seq: number;
-  };
-
-  const outgoingQueueRef = useRef<PersistenceBatch[]>([]);
-  const runPersistenceRef = useRef<(batch?: PersistenceBatch) => void>(
-    () => {},
-  );
 
   const exportState = useCallback((): InteractablePersistedState => {
     const result: InteractablePersistedState = {};
@@ -77,139 +56,28 @@ const useInteractables = (): ClientOutput<"interactables"> => {
     return result;
   }, []);
 
-  const takeDirtyBatch = useCallback(
-    (adapter: InteractablePersistenceAdapter): PersistenceBatch | undefined => {
-      if (dirtyIdsRef.current.size === 0) return;
-      const dirtyIds = new Set(dirtyIdsRef.current);
-      dirtyIdsRef.current.clear();
-      const seq = ++syncSeqRef.current;
-      for (const id of dirtyIds) latestSyncSeqByIdRef.current.set(id, seq);
-      return { adapter, payload: exportState(), dirtyIds, seq };
-    },
-    [exportState],
-  );
-
-  const enqueuePersistence = useCallback(
-    (adapter: InteractablePersistenceAdapter) => {
-      const batch = takeDirtyBatch(adapter);
-      if (!batch) return;
-      if (inFlightPersistenceRef.current === 0) {
-        runPersistenceRef.current(batch);
-      } else {
-        outgoingQueueRef.current.push(batch);
-      }
-    },
-    [takeDirtyBatch],
-  );
-
-  const runPersistence = useCallback(
-    async (batch?: PersistenceBatch) => {
-      const resolved =
-        batch ??
-        (adapterRef.current ? takeDirtyBatch(adapterRef.current) : undefined);
-      if (!resolved) {
-        if (inFlightPersistenceRef.current === 0) {
-          for (const resolve of flushResolversRef.current) resolve();
-          flushResolversRef.current = [];
-        }
-        return;
-      }
-
-      const { adapter, payload, dirtyIds, seq } = resolved;
-      inFlightPersistenceRef.current += 1;
-
-      setStateAndRef((prev) => ({
-        ...prev,
-        persistence: {
-          ...prev.persistence,
-          ...Object.fromEntries(
-            [...dirtyIds].map((id) => [
-              id,
-              { isPending: true, error: undefined },
-            ]),
-          ),
-        },
-      }));
-
-      try {
-        await adapter.save(payload);
-        setStateAndRef((prev) => {
-          let changed = false;
-          const persistence = { ...prev.persistence };
-          for (const id of dirtyIds) {
-            if (
-              latestSyncSeqByIdRef.current.get(id) !== seq ||
-              dirtyIdsRef.current.has(id)
-            )
-              continue;
-            latestSyncSeqByIdRef.current.delete(id);
-            delete persistence[id];
-            changed = true;
-          }
-          return changed ? { ...prev, persistence } : prev;
-        });
-      } catch (e) {
-        setStateAndRef((prev) => {
-          let changed = false;
-          const persistence = { ...prev.persistence };
-          for (const id of dirtyIds) {
-            if (
-              latestSyncSeqByIdRef.current.get(id) !== seq ||
-              dirtyIdsRef.current.has(id)
-            )
-              continue;
-            latestSyncSeqByIdRef.current.delete(id);
-            persistence[id] = { isPending: false, error: e };
-            changed = true;
-          }
-          return changed ? { ...prev, persistence } : prev;
-        });
-      } finally {
-        inFlightPersistenceRef.current -= 1;
-        const next =
-          outgoingQueueRef.current.shift() ??
-          (adapterRef.current && dirtyIdsRef.current.size > 0
-            ? takeDirtyBatch(adapterRef.current)
-            : undefined);
-        if (next) {
-          if (debounceTimerRef.current !== undefined) {
-            clearTimeout(debounceTimerRef.current);
-            debounceTimerRef.current = undefined;
-          }
-          runPersistenceRef.current(next);
-        } else if (inFlightPersistenceRef.current === 0) {
-          for (const resolve of flushResolversRef.current) resolve();
-          flushResolversRef.current = [];
-        }
-      }
+  const updatePersistenceStatus = useCallback(
+    (
+      updater: (
+        prev: InteractablesState["persistence"],
+      ) => InteractablesState["persistence"],
+    ) => {
+      setStateAndRef((prev) => {
+        const persistence = updater(prev.persistence);
+        return persistence === prev.persistence
+          ? prev
+          : { ...prev, persistence };
+      });
     },
-    [setStateAndRef, takeDirtyBatch],
+    [setStateAndRef],
   );
-  runPersistenceRef.current = (nextBatch) => {
-    void runPersistence(nextBatch);
-  };
 
-  const schedulePersistence = useCallback(
-    (id: string) => {
-      if (!adapterRef.current) return;
-      dirtyIdsRef.current.add(id);
-      if (debounceTimerRef.current !== undefined) {
-        clearTimeout(debounceTimerRef.current);
-      }
-      debounceTimerRef.current = setTimeout(() => {
-        debounceTimerRef.current = undefined;
-        if (inFlightPersistenceRef.current === 0 && adapterRef.current) {
-          enqueuePersistence(adapterRef.current);
-        } else {
-          debounceTimerRef.current = setTimeout(() => {
-            debounceTimerRef.current = undefined;
-            if (adapterRef.current) enqueuePersistence(adapterRef.current);
-          }, PERSISTENCE_DEBOUNCE_MS);
-        }
-      }, PERSISTENCE_DEBOUNCE_MS);
-    },
-    [enqueuePersistence],
-  );
+  const { flushIfPending, schedulePersistence, flush } =
+    useInteractablePersistenceQueue({
+      adapterRef,
+      snapshot: exportState,
+      updatePersistenceStatus,
+    });
 
   const importState = useCallback(
     (saved: InteractablePersistedState) => {
@@ -231,31 +99,6 @@ const useInteractables = (): ClientOutput<"interactables"> => {
     [setStateAndRef],
   );
 
-  const flushIfPending = useCallback(() => {
-    if (debounceTimerRef.current !== undefined) {
-      clearTimeout(debounceTimerRef.current);
-      debounceTimerRef.current = undefined;
-    }
-    if (adapterRef.current) enqueuePersistence(adapterRef.current);
-  }, [enqueuePersistence]);
-
-  const flush = useCallback(async () => {
-    if (debounceTimerRef.current !== undefined) {
-      clearTimeout(debounceTimerRef.current);
-      debounceTimerRef.current = undefined;
-    }
-    const hasWork =
-      inFlightPersistenceRef.current > 0 ||
-      dirtyIdsRef.current.size > 0 ||
-      outgoingQueueRef.current.length > 0;
-    if (!hasWork) return;
-    const p = new Promise<void>((resolve) => {
-      flushResolversRef.current.push(resolve);
-    });
-    if (adapterRef.current) enqueuePersistence(adapterRef.current);
-    return p;
-  }, [enqueuePersistence]);
-
   const setPersistenceAdapter = useCallback(
     (adapter: InteractablePersistenceAdapter | undefined) => {
       if (adapterRef.current !== adapter) flushIfPending();