@assistant-ui/core 0.3.16 → 0.3.18

package/src/react/client/RemoteThreadList.ts

@@ -2,15 +2,20 @@ import {
   useCallback,
   useEffect,
   useMemo,
+  useRef,
   useState,
   useSyncExternalStore,
 } from "react";
-import { resource, withKey } from "@assistant-ui/tap";
+import { resource, withKey, type ResourceElement } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import {
   attachTransformScopes,
+  Derived,
+  useAssistantContextProvider,
+  useAssistantContextValue,
   useClientLookup,
   useClientResource,
+  useConfiguredAui,
 } from "@assistant-ui/store/client";
 import { isDevelopment, useThreadSelectionEvents } from "../../store/internal";
 import { OptimisticState } from "../../runtimes/remote-thread-list/optimistic-state";
@@ -20,6 +25,8 @@ import {
   createThreadMappingId,
   getThreadData,
   normalizeCursor,
+  reconcileInitializedThread,
+  promoteNewThreadReducer,
   updateStatusReducer,
   type RemoteThreadData,
   type RemoteThreadState,
@@ -33,13 +40,23 @@ import type {
 } 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";
 import {
   inMemoryThreadListTransformScopes,
   type InMemoryThreadListProps,
 } from "./InMemoryThreadList";
 import { AdaptedRemoteThread } from "./AdaptedRemoteThread";
+import {
+  applyTitleStream,
+  isTitleSourceMessage,
+} from "../../runtimes/remote-thread-list/title";
+import {
+  clearThreadTitleState,
+  finishThreadTitleRename,
+  runThreadTitleGeneration,
+  startThreadTitleRename,
+  type ThreadTitleState,
+} from "../../runtimes/remote-thread-list/title-generation";
 
 const RESOLVED_PROMISE = Promise.resolve();
 
@@ -61,7 +78,20 @@ export type RemoteThreadListProps = {
   onThreadIdChange?: ((threadId: string | undefined) => void) | undefined;
   onSwitchToThread?: ((threadId: string) => void) | undefined;
   onSwitchToNewThread?: (() => void) | undefined;
+  /** Called after the backing adapter successfully deletes the thread. */
   onDelete?: ((threadId: string) => void) | undefined;
+  /**
+   * Keeps every thread the session switched to mounted, so a run continues
+   * after the user switches away, per-item `isRunning` reflects background
+   * runs, and a freshly initialized thread generates its title automatically.
+   * A body unmounts on delete, detach, or an adapter replacement (`reload()`
+   * after swapping the adapter); visited threads otherwise stay mounted for
+   * the client's lifetime. Each body reads its own thread through the ambient
+   * `threadListItem` scope, and `unstable_useAdapters` runs once per mounted
+   * body. Off (the default), only the visible thread is mounted and a switch
+   * unmounts it. The mode is fixed at mount.
+   */
+  backgroundThreads?: boolean | undefined;
 };
 
 const threadNotFoundError = (threadIdOrRemoteId: string, action: string) =>
@@ -83,16 +113,6 @@ const toInitializeResult = (
   externalId: result.externalId,
 });
 
-const applyTitleStream = async (
-  stream: Parameters<typeof AssistantMessageStream.fromAssistantStream>[0],
-  onTitle: (title: string | undefined) => Promise<void>,
-) => {
-  const messageStream = AssistantMessageStream.fromAssistantStream(stream);
-  for await (const result of messageStream) {
-    await onTitle(result.parts.filter((part) => part.type === "text")[0]?.text);
-  }
-};
-
 const useThreadListItemClient = (props: {
   data: RemoteThreadData;
   isRunning: boolean;
@@ -102,7 +122,7 @@ const useThreadListItemClient = (props: {
   onArchive: () => void;
   onUnarchive: () => void;
   onDelete: () => void;
-  onGenerateTitle: () => void;
+  onGenerateTitle: (options?: { automatic?: boolean }) => void;
   onInitialize: () => Promise<{
     remoteId: string;
     externalId: string | undefined;
@@ -202,9 +222,96 @@ const isSameThread = (
   return data !== undefined && itemMatchesId(data, listState, right);
 };
 
+const useRemoteThreadBody = ({
+  id,
+  status,
+  remoteId,
+  item,
+  thread,
+}: {
+  id: string;
+  status: RemoteThreadData["status"];
+  remoteId: string | undefined;
+  item: (isRunning: boolean) => ResourceElement<ClientOutput<"threadListItem">>;
+  thread: ResourceElement<ClientOutput<"thread">>;
+}): ClientOutput<"thread"> => {
+  const parent = useAssistantContextValue();
+  const [isRunning, setIsRunning] = useState(false);
+  // The item client is mounted inside the body and served to the subtree
+  // through a Derived scope, which keeps the graft on the derived-only (no
+  // nested client host) path; resolving `parent.threads` here instead would
+  // read the threads scope during its own construction.
+  const itemHandle = useClientResource(item(isRunning));
+  const { client } = useConfiguredAui(parent, {
+    threadListItem: Derived({
+      source: "threads",
+      query: { type: "id", id },
+      get: () => itemHandle.methods,
+    }),
+  });
+  // Auto-title arms only for a thread born "new" in this body's lifetime;
+  // threads loaded or fetched from the adapter already carry their title. The
+  // settled (non-optimistic) initialize is what writes remoteId, so its
+  // arrival is the initialization signal.
+  const bornNewRef = useRef(status === "new");
+  const titleFiredRef = useRef(false);
+  return useAssistantContextProvider(client, function useBoundRemoteBody() {
+    const body = useClientResource(thread);
+    const bodyRunning = body.state.isRunning === true;
+    useEffect(() => {
+      setIsRunning(bodyRunning);
+    }, [bodyRunning]);
+    const armed =
+      bornNewRef.current && !titleFiredRef.current && remoteId !== undefined;
+    const hasTitleSource =
+      armed &&
+      (
+        body.state.messages as readonly {
+          status?: { type: string } | undefined;
+        }[]
+      ).some(isTitleSourceMessage);
+    useEffect(() => {
+      if (!hasTitleSource || titleFiredRef.current) return;
+      titleFiredRef.current = true;
+      client.threadListItem.generateTitle({ automatic: true });
+    }, [hasTitleSource]);
+    return body.methods;
+  });
+};
+
+const RemoteThreadBody = resource(useRemoteThreadBody);
+
+// `thread("main")` keeps one identity across switches, like the single
+// useClientResource slot it replaced: consumers (the ambient `thread` scope,
+// captured clients) hold the facade while it delegates to whichever body is
+// currently main. Publishing the target during commit keeps abandoned
+// concurrent renders from changing the facade observed by committed consumers.
+const useMainThreadFacade = (
+  current: ClientOutput<"thread">,
+): ClientOutput<"thread"> => {
+  const currentRef = useRef(current);
+  useEffect(() => {
+    currentRef.current = current;
+  }, [current]);
+  const [facade] = useState(
+    () =>
+      new Proxy({} as ClientOutput<"thread">, {
+        get: (_, prop) =>
+          (currentRef.current as unknown as Record<PropertyKey, unknown>)[prop],
+        has: (_, prop) => prop in (currentRef.current as object),
+        ownKeys: () => Reflect.ownKeys(currentRef.current as object),
+        getOwnPropertyDescriptor: (_, prop) =>
+          Reflect.getOwnPropertyDescriptor(currentRef.current as object, prop),
+      }),
+  );
+  return facade;
+};
+
 const useRemoteThreadListView = ({
   listState,
   mainThreadId,
+  startedIds,
+  backgroundThreads,
   threadFactory,
   useAdapters,
   onSwitchTo,
@@ -219,6 +326,8 @@ const useRemoteThreadListView = ({
 }: {
   listState: RemoteThreadState;
   mainThreadId: string;
+  startedIds: readonly string[];
+  backgroundThreads: boolean;
   threadFactory: RemoteThreadListProps["thread"];
   useAdapters: RemoteThreadListAdapter["unstable_useAdapters"];
   onSwitchTo: (
@@ -236,6 +345,7 @@ const useRemoteThreadListView = ({
   onGenerateTitle: (
     threadId: string,
     messages: readonly ThreadMessage[] | undefined,
+    options?: { automatic?: boolean },
   ) => Promise<void>;
   onInitialize: (threadId: string) => Promise<{
     remoteId: string;
@@ -243,17 +353,103 @@ const useRemoteThreadListView = ({
   }>;
   onDetach: (threadId: string) => Promise<void>;
 }) => {
-  const thread = threadFactory(mainThreadId);
-  const wrapped =
-    useAdapters === undefined
-      ? thread
-      : AdaptedRemoteThread({
-          useAdapters,
-          thread,
-        });
-  const mainThreadClient = useClientResource(
-    thread.key === undefined ? wrapped : withKey(thread.key, wrapped),
+  const bodyIds = useMemo(() => {
+    if (!backgroundThreads) return [mainThreadId];
+    const seen = new Set<string>();
+    const seenRemoteIds = new Set<string>();
+    const ids: string[] = [];
+    for (const id of startedIds) {
+      const data = getThreadData(listState, id);
+      if (!data || seen.has(data.id)) continue;
+      if (data.remoteId !== undefined && seenRemoteIds.has(data.remoteId)) {
+        continue;
+      }
+      seen.add(data.id);
+      if (data.remoteId !== undefined) seenRemoteIds.add(data.remoteId);
+      ids.push(data.id);
+    }
+    return ids;
+  }, [backgroundThreads, listState, mainThreadId, startedIds]);
+
+  const itemElementFor = (data: RemoteThreadData, isRunning: boolean) =>
+    ThreadListItemClient({
+      data,
+      isRunning,
+      onSwitchTo: (options) =>
+        handleThreadListAction("switch", () => onSwitchTo(data.id, options)),
+      onRename: (title) =>
+        handleThreadListAction("rename", () => onRename(data.id, title)),
+      onUpdateCustom: (custom) =>
+        handleThreadListAction("update custom metadata", () =>
+          onUpdateCustom(data.id, custom),
+        ),
+      onArchive: () =>
+        handleThreadListAction("archive", () => onArchive(data.id)),
+      onUnarchive: () =>
+        handleThreadListAction("unarchive", () => onUnarchive(data.id)),
+      onDelete: () => handleThreadListAction("delete", () => onDelete(data.id)),
+      onGenerateTitle: (options) =>
+        handleThreadListAction("generate title", () =>
+          onGenerateTitle(
+            data.id,
+            (backgroundThreads
+              ? bodyStateOf(data.id)?.messages
+              : mainThreadClient.state.messages) as
+              | readonly ThreadMessage[]
+              | undefined,
+            options,
+          ),
+        ),
+      onInitialize: () => onInitialize(data.id),
+      onDetach: () => handleThreadListAction("detach", () => onDetach(data.id)),
+    });
+
+  const bodies = useClientLookup(
+    bodyIds.map((id) => {
+      const made = threadFactory(id);
+      // Background bodies never change occupant, so an unkeyed factory
+      // element is keyed by the mapping id here; per-body history loads
+      // without requiring the factory to key itself.
+      const thread =
+        backgroundThreads && made.key === undefined ? withKey(id, made) : made;
+      const wrapped =
+        useAdapters === undefined
+          ? thread
+          : AdaptedRemoteThread({
+              useAdapters,
+              thread,
+            });
+      const data = getThreadData(listState, id);
+      const element =
+        backgroundThreads && data !== undefined
+          ? RemoteThreadBody({
+              id,
+              status: data.status,
+              remoteId: data.remoteId,
+              item: (isRunning) => itemElementFor(data, isRunning),
+              thread: wrapped,
+            })
+          : wrapped;
+      return withKey(backgroundThreads ? id : (made.key ?? "main"), element);
+    }),
   );
+  // A reload can remap a local thread id to its remote identity while the
+  // body stays keyed by the original mapping id, so lookups fall back to
+  // remote-identity matching.
+  const bodyIndexOf = (id: string) => {
+    const direct = bodyIds.indexOf(id);
+    if (direct !== -1) return direct;
+    return bodyIds.findIndex((bodyId) => isSameThread(listState, bodyId, id));
+  };
+  const bodyStateOf = (id: string) => {
+    const index = bodyIndexOf(id);
+    return index === -1 ? undefined : bodies.state[index];
+  };
+  const mainIndex = bodyIndexOf(mainThreadId);
+  const mainThreadClient = {
+    state: bodies.state[mainIndex]!,
+    methods: useMainThreadFacade(bodies.get({ index: mainIndex })),
+  };
   const itemOrder = useMemo(
     () => collectItemOrder(listState, mainThreadId),
     [listState, mainThreadId],
@@ -262,40 +458,13 @@ const useRemoteThreadListView = ({
     itemOrder.map((data) =>
       withKey(
         data.id,
-        ThreadListItemClient({
+        itemElementFor(
           data,
-          isRunning:
-            itemMatchesId(data, listState, mainThreadId) &&
-            mainThreadClient.state.isRunning,
-          onSwitchTo: (options) =>
-            handleThreadListAction("switch", () =>
-              onSwitchTo(data.id, options),
-            ),
-          onRename: (title) =>
-            handleThreadListAction("rename", () => onRename(data.id, title)),
-          onUpdateCustom: (custom) =>
-            handleThreadListAction("update custom metadata", () =>
-              onUpdateCustom(data.id, custom),
-            ),
-          onArchive: () =>
-            handleThreadListAction("archive", () => onArchive(data.id)),
-          onUnarchive: () =>
-            handleThreadListAction("unarchive", () => onUnarchive(data.id)),
-          onDelete: () =>
-            handleThreadListAction("delete", () => onDelete(data.id)),
-          onGenerateTitle: () =>
-            handleThreadListAction("generate title", () =>
-              onGenerateTitle(
-                data.id,
-                mainThreadClient.state.messages as
-                  | readonly ThreadMessage[]
-                  | undefined,
-              ),
-            ),
-          onInitialize: () => onInitialize(data.id),
-          onDetach: () =>
-            handleThreadListAction("detach", () => onDetach(data.id)),
-        }),
+          backgroundThreads
+            ? (bodyStateOf(data.id)?.isRunning ?? false)
+            : itemMatchesId(data, listState, mainThreadId) &&
+                mainThreadClient.state.isRunning,
+        ),
       ),
     ),
   );
@@ -324,6 +493,7 @@ const useRemoteThreadList = (
         adapter,
         adapterAtLoad: adapter,
         adapterGeneration: 0,
+        titleStates: new Map<string, ThreadTitleState>(),
         loadGeneration: 0,
         switchGeneration: 0,
         loadPromise: undefined as Promise<void> | undefined,
@@ -340,9 +510,6 @@ 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,
@@ -350,15 +517,21 @@ const useRemoteThreadList = (
   );
 
   const [mainThreadId, setMainThreadId] = useState(initialMainId);
+  const [startedIds, setStartedIds] = useState<readonly string[]>([
+    initialMainId,
+  ]);
+  const [backgroundThreads] = useState(props.backgroundThreads === true);
   const assignMainThreadId = useCallback(
     (id: string) => {
       session.mainThreadId = id;
       setMainThreadId(id);
+      setStartedIds((prev) => (prev.includes(id) ? prev : [...prev, id]));
     },
     [session],
   );
   useThreadSelectionEvents(mainThreadId);
   useEffect(() => {
+    // Publishing after commit keeps imperative actions on the adapter the committed tree renders with; an abandoned render must not reach them.
     session.adapter = adapter;
     session.mainThreadId = mainThreadId;
     session.onThreadIdChange = onThreadIdChange;
@@ -390,30 +563,28 @@ const useRemoteThreadList = (
     session.loadPromise = store
       .optimisticUpdate({
         execute: () => adapter.list(),
-        loading: (state) => ({ ...state, isLoading: true }),
+        loading: (state) => {
+          if (generation !== session.loadGeneration) return state;
+          return { ...state, isLoading: true, loadError: undefined };
+        },
         then: (state, page) => {
           if (generation !== session.loadGeneration) return state;
           session.adapterAtLoad = adapter;
           const fresh = classifyThreads(page.threads, {
             threadIds: [],
             archivedThreadIds: [],
-            threadIdMap: {},
-            threadData: {},
+            threadIdMap: { ...state.threadIdMap },
+            threadData: { ...state.threadData },
           });
           const merged = {
             ...state,
             isLoading: false,
+            loadError: undefined,
             cursor: normalizeCursor(page.nextCursor),
             threadIds: fresh.threadIds,
             archivedThreadIds: fresh.archivedThreadIds,
-            threadIdMap: {
-              ...state.threadIdMap,
-              ...fresh.threadIdMap,
-            },
-            threadData: {
-              ...state.threadData,
-              ...fresh.threadData,
-            },
+            threadIdMap: fresh.threadIdMap,
+            threadData: fresh.threadData,
           };
           return preserveMidLoadTransitions(merged, state, statusAtRequest);
         },
@@ -425,6 +596,7 @@ const useRemoteThreadList = (
         store.update({
           ...store.baseValue,
           isLoading: false,
+          loadError: error,
         });
       })
       .then(() => {});
@@ -438,12 +610,14 @@ const useRemoteThreadList = (
     session.loadMorePromise = undefined;
     if (adapterChanged) {
       session.adapterGeneration++;
+      session.titleStates.clear();
       session.switchGeneration++;
       session.switchTask = undefined;
       session.adapterAtLoad = adapter;
       const seeded = seedNewThread(EMPTY_LIST);
       store.reset({ ...seeded.state, isLoading: true });
       assignMainThreadId(seeded.id);
+      setStartedIds([seeded.id]);
       notifyRemoteId(undefined, true);
     } else {
       store.update({
@@ -461,6 +635,26 @@ const useRemoteThreadList = (
     store,
   ]);
 
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+
+    const retryAfterError = () => {
+      if (store.value.loadError !== undefined) void getLoadThreadsPromise();
+    };
+    const retryAfterVisible = () => {
+      if (document.visibilityState === "visible") retryAfterError();
+    };
+
+    window.addEventListener("online", retryAfterError);
+    document.addEventListener("visibilitychange", retryAfterVisible);
+    return () => {
+      window.removeEventListener("online", retryAfterError);
+      document.removeEventListener("visibilitychange", retryAfterVisible);
+    };
+  }, [getLoadThreadsPromise, store]);
+
   useEffect(() => {
     void getLoadThreadsPromise();
   }, [getLoadThreadsPromise]);
@@ -486,7 +680,10 @@ const useRemoteThreadList = (
     const task = store
       .optimisticUpdate({
         execute: () => currentAdapter.list({ after: cursor }),
-        loading: (state) => ({ ...state, isLoadingMore: true }),
+        loading: (state) => {
+          if (generation !== session.loadGeneration) return state;
+          return { ...state, isLoadingMore: true };
+        },
         then: (state, page) => {
           if (generation !== session.loadGeneration) return state;
           const appended = classifyThreads(page.threads, {
@@ -604,22 +801,30 @@ const useRemoteThreadList = (
           throw threadNotFoundError(threadIdOrRemoteId, "switching to it");
         }
         if (isSameThread(store.value, data.id, session.mainThreadId)) return;
-        if (data.status === "archived" && options?.unarchive !== false) {
-          const current = data;
+
+        const targetId = data.id;
+        let current: RemoteThreadData | undefined = data;
+
+        if (current.status === "archived" && options?.unarchive !== false) {
           const { remoteId } = await current.initializeTask;
           if (generation !== session.switchGeneration) return;
-          await store.optimisticUpdate({
-            execute: () => session.adapter.unarchive(remoteId),
-            optimistic: (state) =>
-              updateStatusReducer(state, current.id, "regular"),
-          });
-          if (generation !== session.switchGeneration) return;
-          data = getThreadData(store.value, current.id) ?? current;
+          current = getThreadData(store.value, targetId);
+          if (current?.id !== targetId) return;
+          if (current.status === "archived") {
+            await store.optimisticUpdate({
+              execute: () => session.adapter.unarchive(remoteId),
+              optimistic: (state) =>
+                updateStatusReducer(state, targetId, "regular"),
+            });
+            if (generation !== session.switchGeneration) return;
+            current = getThreadData(store.value, targetId);
+            if (current?.id !== targetId) return;
+          }
         }
         if (generation !== session.switchGeneration) return;
-        assignMainThreadId(data.id);
-        notifyRemoteId(data.remoteId, emitThreadIdChange);
-        session.onSwitchToThread?.(data.id);
+        assignMainThreadId(current.id);
+        notifyRemoteId(current.remoteId, emitThreadIdChange);
+        session.onSwitchToThread?.(current.id);
       }),
     [assignMainThreadId, notifyRemoteId, session, startSwitch, store],
   );
@@ -704,55 +909,60 @@ const useRemoteThreadList = (
         requireAdapterGeneration(adapterGeneration);
         return result;
       }
+      requireAdapterGeneration(adapterGeneration);
+      const initializeTask = currentAdapter.initialize(threadId);
+      let removedMappingId: string | undefined;
+      let replacementMainThreadId: string | undefined;
       const result = await store.optimisticUpdate({
-        execute: () => {
-          requireAdapterGeneration(adapterGeneration);
-          return currentAdapter.initialize(threadId);
-        },
-        optimistic: (state) => updateStatusReducer(state, threadId, "regular"),
-        loading: (state, task) => {
-          const mappingId = createThreadMappingId(threadId);
-          return {
-            ...state,
-            threadData: {
-              ...state.threadData,
-              [mappingId]: {
-                ...state.threadData[mappingId],
-                initializeTask: task,
-              },
-            },
-          };
-        },
+        execute: () => initializeTask,
+        optimistic: (state) =>
+          promoteNewThreadReducer(state, threadId, initializeTask),
         then: (state, { remoteId, externalId }) => {
           if (adapterGeneration !== session.adapterGeneration) return state;
-          const data = getThreadData(state, threadId);
-          if (!data) return state;
-          const mappingId = createThreadMappingId(threadId);
-          return {
-            ...state,
-            threadIdMap: {
-              ...state.threadIdMap,
-              [remoteId]: mappingId,
-            },
-            threadData: {
-              ...state.threadData,
-              [mappingId]: {
-                ...data,
-                initializeTask: Promise.resolve({ remoteId, externalId }),
-                remoteId,
-                externalId,
-              },
-            },
-          };
+          // Background mode still owns the initializing body. Single-body mode
+          // has already replaced it, so retain the currently mounted body.
+          const retainedThreadId = backgroundThreads
+            ? threadId
+            : session.mainThreadId;
+          const reconciliation = reconcileInitializedThread(
+            state,
+            threadId,
+            remoteId,
+            externalId,
+            retainedThreadId,
+          );
+          removedMappingId = reconciliation.removedMappingId;
+          if (removedMappingId === session.mainThreadId) {
+            replacementMainThreadId = reconciliation.survivorMappingId;
+          }
+          return reconciliation.state;
         },
       });
       requireAdapterGeneration(adapterGeneration);
+      if (removedMappingId !== undefined) {
+        setStartedIds((prev) =>
+          prev.filter((startedId) => startedId !== removedMappingId),
+        );
+      }
+      if (
+        replacementMainThreadId !== undefined &&
+        session.mainThreadId === removedMappingId
+      ) {
+        assignMainThreadId(replacementMainThreadId);
+      }
       if (threadId === session.mainThreadId) {
         notifyRemoteId(result.remoteId, true);
       }
       return toInitializeResult(result);
     },
-    [notifyRemoteId, requireAdapterGeneration, session, store],
+    [
+      assignMainThreadId,
+      backgroundThreads,
+      notifyRemoteId,
+      requireAdapterGeneration,
+      session,
+      store,
+    ],
   );
 
   const rename = useCallback(
@@ -764,27 +974,43 @@ const useRemoteThreadList = (
       if (data.status === "new") {
         throw threadStatusError(threadIdOrRemoteId, data.status, "be renamed");
       }
-      return store.optimisticUpdate({
-        execute: async () => {
-          const { remoteId } = await data.initializeTask;
-          requireAdapterGeneration(adapterGeneration);
-          return currentAdapter.rename(remoteId, newTitle);
-        },
-        optimistic: (state) => {
-          const current = getThreadData(state, threadIdOrRemoteId);
-          if (!current) return state;
-          return {
-            ...state,
-            threadData: {
-              ...state.threadData,
-              [current.id]: {
-                ...current,
-                title: newTitle,
+      const claim = startThreadTitleRename(
+        session.titleStates,
+        data.id,
+        newTitle,
+      );
+      return store
+        .optimisticUpdate({
+          execute: async () => {
+            const { remoteId } = await data.initializeTask;
+            requireAdapterGeneration(adapterGeneration);
+            return currentAdapter.rename(remoteId, newTitle);
+          },
+          optimistic: (state) => {
+            const current = getThreadData(state, threadIdOrRemoteId);
+            if (!current) return state;
+            return {
+              ...state,
+              threadData: {
+                ...state.threadData,
+                [current.id]: {
+                  ...current,
+                  title: newTitle,
+                },
               },
-            },
-          };
-        },
-      });
+            };
+          },
+        })
+        .then(
+          (result) => {
+            finishThreadTitleRename(session.titleStates, data.id, claim, true);
+            return result;
+          },
+          (error: unknown) => {
+            finishThreadTitleRename(session.titleStates, data.id, claim, false);
+            throw error;
+          },
+        );
     },
     [requireAdapterGeneration, session, store],
   );
@@ -912,8 +1138,7 @@ const useRemoteThreadList = (
       }
       await ensureNotMain(data.id);
       requireAdapterGeneration(adapterGeneration);
-      onDelete?.(data.id);
-      return store.optimisticUpdate({
+      const result = await store.optimisticUpdate({
         execute: async () => {
           const { remoteId } = await data.initializeTask;
           requireAdapterGeneration(adapterGeneration);
@@ -921,6 +1146,13 @@ const useRemoteThreadList = (
         },
         optimistic: (state) => updateStatusReducer(state, data.id, "deleted"),
       });
+      // An adapter swap resets the optimistic layer, and a listed thread's slot
+      // id is its remote id, so a replacement adapter can re-list this slot
+      // while the deletion is in flight.
+      if (getThreadData(store.value, data.id) !== undefined) return result;
+      clearThreadTitleState(session.titleStates, data.id);
+      onDelete?.(data.id);
+      return result;
     },
     [ensureNotMain, onDelete, requireAdapterGeneration, session, store],
   );
@@ -929,6 +1161,7 @@ const useRemoteThreadList = (
     async (
       threadIdOrRemoteId: string,
       messages: readonly ThreadMessage[] | undefined,
+      options?: { automatic?: boolean },
     ) => {
       const currentAdapter = session.adapter;
       const adapterGeneration = session.adapterGeneration;
@@ -945,38 +1178,65 @@ const useRemoteThreadList = (
       }
       const { remoteId } = await data.initializeTask;
       requireAdapterGeneration(adapterGeneration);
-      if (!isSameThread(store.value, data.id, session.mainThreadId)) return;
+      if (
+        !backgroundThreads &&
+        !isSameThread(store.value, data.id, session.mainThreadId)
+      ) {
+        return;
+      }
       if (!messages) return;
-      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,
+      await runThreadTitleGeneration({
+        states: session.titleStates,
+        threadId: data.id,
+        automatic: options?.automatic === true,
+        generate: async (onTitle) => {
+          const stream = await currentAdapter.generateTitle(remoteId, messages);
+          requireAdapterGeneration(adapterGeneration);
+          await applyTitleStream(stream, onTitle);
+        },
+        rename: async (title) => {
+          requireAdapterGeneration(adapterGeneration);
+          await currentAdapter.rename(remoteId, title);
+        },
+        applyTitle: async (title) => {
+          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,
+                  },
                 },
-              },
-            };
-          },
-        });
+              };
+            },
+          });
+        },
       });
     },
-    [requireAdapterGeneration, session, store],
+    [backgroundThreads, requireAdapterGeneration, session, store],
+  );
+
+  const detach = useCallback(
+    async (threadId: string) => {
+      await ensureNotMain(threadId);
+      setStartedIds((prev) => prev.filter((id) => id !== threadId));
+    },
+    [ensureNotMain],
   );
 
   const { mainThreadClient, itemOrder, threadListItems } =
     useRemoteThreadListView({
       listState,
       mainThreadId,
+      startedIds,
+      backgroundThreads,
       threadFactory,
       useAdapters: adapter.unstable_useAdapters,
       onSwitchTo: (id, options) => switchToThread(id, options),
@@ -985,9 +1245,10 @@ const useRemoteThreadList = (
       onArchive: (id) => archive(id),
       onUnarchive: (id) => unarchive(id),
       onDelete: (id) => deleteThread(id),
-      onGenerateTitle: (id, messages) => generateTitle(id, messages),
+      onGenerateTitle: (id, messages, options) =>
+        generateTitle(id, messages, options),
       onInitialize: async (id) => toInitializeResult(await initialize(id)),
-      onDetach: (id) => ensureNotMain(id),
+      onDetach: (id) => detach(id),
     });
 
   const mainRemoteId = getThreadData(listState, mainThreadId)?.remoteId;
@@ -1023,6 +1284,7 @@ const useRemoteThreadList = (
       mainThreadId,
       newThreadId: listState.newThreadId ?? null,
       isLoading: listState.isLoading,
+      loadError: listState.loadError,
       isLoadingMore: listState.isLoadingMore,
       hasMore: listState.cursor !== undefined,
       threadIds: listState.threadIds,
@@ -1034,6 +1296,7 @@ const useRemoteThreadList = (
       listState.archivedThreadIds,
       listState.cursor,
       listState.isLoading,
+      listState.loadError,
       listState.isLoadingMore,
       listState.newThreadId,
       listState.threadIds,
@@ -1098,6 +1361,9 @@ const useRemoteThreadList = (
  * and attachments come from `unstable_useAdapters`. `useRemoteThreadListRuntime`
  * uses the same hook when `unstable_Provider` is omitted. Key the factory
  * with `withKey` so history reloads when the visible thread changes.
+ * With `backgroundThreads`, every visited thread stays mounted: runs continue
+ * across switches, per-item `isRunning` is live, and freshly initialized
+ * threads title themselves.
  */
 export const RemoteThreadList = resource(useRemoteThreadList);