@assistant-ui/core 0.3.16 → 0.3.17

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";
@@ -40,6 +45,7 @@ import {
   type InMemoryThreadListProps,
 } from "./InMemoryThreadList";
 import { AdaptedRemoteThread } from "./AdaptedRemoteThread";
+import { isTitleSourceMessage } from "../../runtimes/remote-thread-list/title";
 
 const RESOLVED_PROMISE = Promise.resolve();
 
@@ -62,6 +68,18 @@ export type RemoteThreadListProps = {
   onSwitchToThread?: ((threadId: string) => void) | undefined;
   onSwitchToNewThread?: (() => void) | undefined;
   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) =>
@@ -202,9 +220,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();
+    }, [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 +324,8 @@ const useRemoteThreadListView = ({
 }: {
   listState: RemoteThreadState;
   mainThreadId: string;
+  startedIds: readonly string[];
+  backgroundThreads: boolean;
   threadFactory: RemoteThreadListProps["thread"];
   useAdapters: RemoteThreadListAdapter["unstable_useAdapters"];
   onSwitchTo: (
@@ -243,17 +350,102 @@ 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: () =>
+        handleThreadListAction("generate title", () =>
+          onGenerateTitle(
+            data.id,
+            (backgroundThreads
+              ? bodyStateOf(data.id)?.messages
+              : mainThreadClient.state.messages) as
+              | readonly ThreadMessage[]
+              | undefined,
+          ),
+        ),
+      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 +454,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,
+        ),
       ),
     ),
   );
@@ -340,9 +505,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 +512,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,15 +558,18 @@ 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 };
+        },
         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,
@@ -406,14 +577,8 @@ const useRemoteThreadList = (
             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);
         },
@@ -444,6 +609,7 @@ const useRemoteThreadList = (
       const seeded = seedNewThread(EMPTY_LIST);
       store.reset({ ...seeded.state, isLoading: true });
       assignMainThreadId(seeded.id);
+      setStartedIds([seeded.id]);
       notifyRemoteId(undefined, true);
     } else {
       store.update({
@@ -486,7 +652,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 +773,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],
   );
@@ -728,21 +905,36 @@ const useRemoteThreadList = (
           const data = getThreadData(state, threadId);
           if (!data) return state;
           const mappingId = createThreadMappingId(threadId);
+          // A list() response that landed while this initialize was in flight
+          // could not know the remote id yet, so it may have minted its own
+          // slot for it; that slot collapses into this one.
+          const listedMappingId = state.threadIdMap[remoteId];
+          const orphan =
+            listedMappingId !== undefined && listedMappingId !== mappingId
+              ? state.threadData[listedMappingId]
+              : undefined;
+
+          const threadData = { ...state.threadData };
+          if (orphan !== undefined) delete threadData[listedMappingId!];
+          threadData[mappingId] = {
+            ...data,
+            initializeTask: Promise.resolve({ remoteId, externalId }),
+            remoteId,
+            externalId,
+          } as RemoteThreadData;
+
+          const rewire = (ids: readonly string[]) =>
+            orphan === undefined ? ids : ids.filter((id) => id !== orphan.id);
+
           return {
             ...state,
+            threadIds: rewire(state.threadIds),
+            archivedThreadIds: rewire(state.archivedThreadIds),
             threadIdMap: {
               ...state.threadIdMap,
               [remoteId]: mappingId,
             },
-            threadData: {
-              ...state.threadData,
-              [mappingId]: {
-                ...data,
-                initializeTask: Promise.resolve({ remoteId, externalId }),
-                remoteId,
-                externalId,
-              },
-            },
+            threadData,
           };
         },
       });
@@ -945,7 +1137,12 @@ 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);
@@ -970,13 +1167,23 @@ const useRemoteThreadList = (
         });
       });
     },
-    [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),
@@ -987,7 +1194,7 @@ const useRemoteThreadList = (
       onDelete: (id) => deleteThread(id),
       onGenerateTitle: (id, messages) => generateTitle(id, messages),
       onInitialize: async (id) => toInitializeResult(await initialize(id)),
-      onDetach: (id) => ensureNotMain(id),
+      onDetach: (id) => detach(id),
     });
 
   const mainRemoteId = getThreadData(listState, mainThreadId)?.remoteId;
@@ -1098,6 +1305,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);
 

package/src/react/client/Tools.ts

@@ -16,6 +16,7 @@ import type { Tool } from "assistant-stream";
 import {
   isStandaloneToolDisplay,
   makeToolCallTextComponent,
+  type ToolCallText,
   type Toolkit,
 } from "../model-context/toolbox";
 import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
@@ -59,12 +60,16 @@ const useTools = ({
     (
       toolName: string,
       render: ToolCallMessagePartComponent,
-      options?: { standalone?: boolean },
+      options?: {
+        standalone?: boolean;
+        renderText?: ToolCallText<any, any> | undefined;
+      },
     ) => {
       // One registration object per call; identity is the removal key, so
       // the per-name list stays correctly ref-counted across re-registers.
       const registration = {
         render,
+        renderText: options?.renderText,
         standalone: options?.standalone ?? false,
       };
 
@@ -105,6 +110,7 @@ const useTools = ({
         unsubscribes.push(
           setToolUI(toolName, render, {
             standalone: isStandaloneToolDisplay(tool),
+            renderText: toolRenderText,
           }),
         );
       }

package/src/react/index.ts

@@ -235,6 +235,10 @@ export { RemoteThreadListHookInstanceManager } from "./runtimes/RemoteThreadList
 export { RemoteThreadListThreadListRuntimeCore } from "./runtimes/RemoteThreadListThreadListRuntimeCore";
 export { useRemoteThreadListRuntime } from "./runtimes/useRemoteThreadListRuntime";
 export { useCloudThreadListAdapter } from "./runtimes/cloud/useCloudThreadListAdapter";
+export {
+  createCloudThreadListAdapter,
+  type CloudThreadListAdapterOptions,
+} from "./runtimes/cloud/createCloudThreadListAdapter";
 export { useCloudThreadListRuntime } from "./runtimes/cloud/useCloudThreadListRuntime";
 export {
   useAssistantTransportRuntime,