Remote Thread List Runtime#

RemoteThreadListRuntime is the core runtime for managing a server-backed list of chat threads in assistant-ui. It is the backbone behind useLangGraphRuntime, useChatRuntime, and other high-level adapter hooks.

Key source files:

Architecture#

RemoteThreadListRuntimeCore (defined inline in useRemoteThreadListRuntime.ts) extends BaseAssistantRuntimeCore and holds a single RemoteThreadListThreadListRuntimeCore as this.threads 1. The hook creates this runtime exactly once via useState and re-syncs options on each render via __internal_setOptions / __internal_load 2.

RemoteThreadListThreadListRuntimeCore extends BaseSubscribable and implements ThreadListRuntimeCore 3. All mutable list state is held in an OptimisticState<RemoteThreadState> instance 4, which supports three classes of state mutation:

• update(state) — hard replace from server data
• optimisticUpdate({ execute, optimistic?, loading?, then? }) — runs an async operation with immediate optimistic UI, safe to interleave with concurrent updates
• waitForUpdate() — promise-based barrier used by switchToNewThread when an initialization is in flight 5

Thread Switching#

switchToThread(id, opts?) and switchToNewThread() are the two public entry points for navigation 6.

Both use switch generation tracking to prevent out-of-order completions from corrupting _mainThreadId 7. Each call increments _switchGeneration and passes the generation token to the private _switchToThread / _switchToNewThread helper. After every await, the helper checks if (generation !== this._switchGeneration) return; before committing state 8.

switchToNewThread assigns a transient local ID with the format __LOCALID_<random> and status: "new" before the thread exists on the server 9. The thread is fully initialized only once initialize(threadId) is called (e.g., on first message send), at which point the state is updated with the server-assigned remoteId 10.

If a switch targets an unknown ID, switchToThread calls adapter.fetch(remoteId) to retrieve metadata and inject the thread into local state before navigating to it 11.

onThreadIdChange and the Echo Problem#

onThreadIdChange is a callback in RemoteThreadListOptions that fires whenever the active thread's settled remote ID changes. The implementation centers on two private members in RemoteThreadListThreadListRuntimeCore:

• _mainThreadRemoteId — derives the remote ID from the active thread's RemoteThreadData.remoteId 12. Returns undefined for new/optimistic threads so that __LOCALID_* strings are never surfaced to consumers.
• _notifyThreadIdChange() — deduplicates against _lastNotifiedThreadId before invoking the callback 13.

The notification fires from two sites:

1. The _state subscriber (catches the optimistic→settled transition after initialize() resolves) 14
2. At the end of _switchToThread after setting _mainThreadId (catches explicit navigation) 15

In the React hook, the callback is wrapped with useEffectEvent so it always calls the latest consumer closure without causing the stableOptions memo to invalidate 16.

The Echo Problem#

The echo problem is the scenario where:

1. Parent updates threadId prop → hook calls switchToThread(id) → _notifyThreadIdChange fires onThreadIdChange(id) → parent updates URL → React re-renders → threadId prop changes again → loop.

The deduplication guard in _notifyThreadIdChange (comparing against _lastNotifiedThreadId) breaks this cycle: if the threadId flowing back from onThreadIdChange matches what was already notified, switchToThread completes but the callback does not fire a second time 17. The hook's useEffect for threadId also skips the switch if options.threadId hasn't changed from prevThreadIdRef.current 18.

However, a navigation loop can still occur when the threadId prop change triggers a full React remount or RSC refetch (e.g., via router.push in Next.js), causing adapter.fetch and adapter.list to fire twice. The recommended workaround is to write the URL via window.history.pushState inside onThreadIdChange rather than navigating via the router, so no new React render or RSC round-trip is triggered 19.

State Shape and Subscriptions#

RemoteThreadState 4 holds:

Subscribers register via BaseSubscribable.subscribe. The state subscriber in the constructor calls both _notifySubscribers() (list UI) and _notifyThreadIdChange() (URL routing) on every state change 14.

Key Behaviors and Gotchas#

• __LOCALID_* is never emitted by onThreadIdChange. While a thread is optimistic, the callback fires undefined. 12
• adapter.fetch on unknown IDs: Switching to a remote ID not yet in local state triggers adapter.fetch. The fetched metadata is injected into both threadData and the appropriate threadIds / archivedThreadIds list 20.
• Nesting guard: If useRemoteThreadListRuntime is rendered inside another RemoteThreadListRuntime, it throws unless allowNesting: true is set, in which case it becomes a no-op that calls runtimeHook() directly 21.
• initialThreadId is deprecated — use the reactive threadId option instead 22.
• onThreadIdChange forwarding: All major adapter hooks (useLangGraphRuntime, useChatRuntime, useStreamRuntime, useAdkRuntime, etc.) forward onThreadIdChange to the underlying useRemoteThreadListRuntime 23.