@assistant-ui/core 0.1.14 → 0.1.16

package/src/runtimes/external-store/external-store-thread-list-runtime-core.ts

@@ -30,6 +30,7 @@ export class ExternalStoreThreadListRuntimeCore
   private _archivedThreads: readonly string[] = EMPTY_ARRAY;
   private _threadData: Readonly<Record<string, ThreadListItemCoreState>> =
     DEFAULT_THREAD_DATA;
+  private adapter: ExternalStoreThreadListAdapter = {};
 
   public get isLoading() {
     return this.adapter.isLoading ?? false;
@@ -55,17 +56,16 @@ export class ExternalStoreThreadListRuntimeCore
     return RESOLVED_PROMISE;
   }
 
-  private _mainThread: ExternalStoreThreadRuntimeCore;
+  private _mainThread!: ExternalStoreThreadRuntimeCore;
 
   public get mainThreadId() {
     return this._mainThreadId;
   }
 
   constructor(
-    private adapter: ExternalStoreThreadListAdapter = {},
+    adapter: ExternalStoreThreadListAdapter = {},
     private threadFactory: ExternalStoreThreadFactory,
   ) {
-    this._mainThread = this.threadFactory();
     this.__internal_setAdapter(adapter, true);
   }
 
@@ -113,31 +113,36 @@ export class ExternalStoreThreadListRuntimeCore
       return;
     }
 
-    this._threadData = {
-      ...DEFAULT_THREAD_DATA,
-      ...Object.fromEntries(
-        adapter.threads?.map((t) => [
-          t.id,
-          {
-            ...t,
-            remoteId: t.remoteId,
-            externalId: t.externalId,
-            status: "regular",
-          },
-        ]) ?? [],
-      ),
-      ...Object.fromEntries(
-        adapter.archivedThreads?.map((t) => [
-          t.id,
-          {
-            ...t,
-            remoteId: t.remoteId,
-            externalId: t.externalId,
-            status: "archived",
-          },
-        ]) ?? [],
-      ),
-    };
+    if (
+      previousThreads !== newThreads ||
+      previousArchivedThreads !== newArchivedThreads
+    ) {
+      this._threadData = {
+        ...DEFAULT_THREAD_DATA,
+        ...Object.fromEntries(
+          adapter.threads?.map((t) => [
+            t.id,
+            {
+              ...t,
+              remoteId: t.remoteId,
+              externalId: t.externalId,
+              status: "regular",
+            },
+          ]) ?? [],
+        ),
+        ...Object.fromEntries(
+          adapter.archivedThreads?.map((t) => [
+            t.id,
+            {
+              ...t,
+              remoteId: t.remoteId,
+              externalId: t.externalId,
+              status: "archived",
+            },
+          ]) ?? [],
+        ),
+      };
+    }
 
     if (previousThreads !== newThreads) {
       this._threads = this.adapter.threads?.map((t) => t.id) ?? EMPTY_ARRAY;
@@ -148,7 +153,8 @@ export class ExternalStoreThreadListRuntimeCore
         this.adapter.archivedThreads?.map((t) => t.id) ?? EMPTY_ARRAY;
     }
 
-    if (previousThreadId !== newThreadId) {
+    // `initialLoad ||`: `_mainThread!` must be assigned on construction.
+    if (initialLoad || previousThreadId !== newThreadId) {
       this._mainThreadId = newThreadId;
       this._mainThread = this.threadFactory();
     }

package/src/runtimes/external-store/external-store-thread-runtime-core.ts

@@ -78,6 +78,10 @@ export class ExternalStoreThreadRuntimeCore
   public get isLoading() {
     return this._store.isLoading ?? false;
   }
+  // Unlike `isLoading`: pass `undefined` through to preserve the `getThreadState` fallback.
+  public get isRunning(): boolean | undefined {
+    return this._store.isRunning;
+  }
 
   protected override _getBaseMessages(): readonly ThreadMessage[] {
     return this._messages;

package/src/runtimes/remote-thread-list/adapter/in-memory.ts

@@ -1,5 +1,5 @@
-import { AssistantStream, AssistantStreamChunk } from "assistant-stream";
-import {
+import type { AssistantStream, AssistantStreamChunk } from "assistant-stream";
+import type {
   RemoteThreadInitializeResponse,
   RemoteThreadListAdapter,
   RemoteThreadListResponse,

package/src/runtimes/remote-thread-list/remote-thread-state.ts

@@ -7,6 +7,7 @@ export type RemoteThreadData =
       readonly externalId: undefined;
       readonly status: "new";
       readonly title: undefined;
+      readonly custom: undefined;
     }
   | {
       readonly id: string;
@@ -15,6 +16,7 @@ export type RemoteThreadData =
       readonly externalId: undefined;
       readonly status: "regular" | "archived";
       readonly title?: string | undefined;
+      readonly custom: undefined;
     }
   | {
       readonly id: string;
@@ -23,6 +25,7 @@ export type RemoteThreadData =
       readonly externalId: string | undefined;
       readonly status: "regular" | "archived";
       readonly title?: string | undefined;
+      readonly custom?: Record<string, unknown> | undefined;
     };
 
 export type THREAD_MAPPING_ID = string & { __brand: "THREAD_MAPPING_ID" };

package/src/runtimes/remote-thread-list/types.ts

@@ -1,6 +1,7 @@
+import type { ComponentType, PropsWithChildren } from "react";
 import type { ThreadMessage } from "../../types/message";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
-import { AssistantStream } from "assistant-stream";
+import type { AssistantStream } from "assistant-stream";
 
 export type RemoteThreadInitializeResponse = {
   remoteId: string;
@@ -12,6 +13,7 @@ export type RemoteThreadMetadata = {
   readonly remoteId: string;
   readonly externalId?: string | undefined;
   readonly title?: string | undefined;
+  readonly custom?: Record<string, unknown> | undefined;
 };
 
 export type RemoteThreadListResponse = {
@@ -32,7 +34,17 @@ export type RemoteThreadListAdapter = {
   ): Promise<AssistantStream>;
   fetch(threadId: string): Promise<RemoteThreadMetadata>;
 
-  unstable_Provider?: ((...args: any[]) => unknown) | undefined;
+  /**
+   * Optional React component wrapped around each active thread. Use it to
+   * inject per-thread context such as a history or attachments adapter (see
+   * `useCloudThreadListAdapter` for the canonical shape).
+   *
+   * The Provider must render `children` on its first commit; deferring them
+   * behind a loading state, a Suspense boundary, or a `useEffect`-gated render
+   * is unsupported and leaves thread context unavailable to downstream
+   * consumers. Load data inside an always-mounted child instead.
+   */
+  unstable_Provider?: ComponentType<PropsWithChildren> | undefined;
 };
 
 export type RemoteThreadListOptions = {

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

@@ -1,6 +1,6 @@
 import { resource } from "@assistant-ui/tap";
-import { type ClientOutput } from "@assistant-ui/store";
-import { AttachmentRuntime } from "../../runtime/api/attachment-runtime";
+import type { ClientOutput } from "@assistant-ui/store";
+import type { AttachmentRuntime } from "../../runtime/api/attachment-runtime";
 import { tapSubscribable } from "./tap-subscribable";
 
 export const AttachmentRuntimeClient = resource(

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

@@ -12,11 +12,11 @@ import {
   tapAssistantEmit,
   tapClientLookup,
 } from "@assistant-ui/store";
-import {
+import type {
   ComposerRuntime,
   EditComposerRuntime,
 } from "../../runtime/api/composer-runtime";
-import { ComposerState } from "../scopes/composer";
+import type { ComposerState } from "../scopes/composer";
 import { AttachmentRuntimeClient } from "./attachment-runtime-client";
 import { tapSubscribable } from "./tap-subscribable";
 

package/src/store/runtime-clients/message-part-runtime-client.ts

@@ -1,6 +1,6 @@
 import { resource } from "@assistant-ui/tap";
-import { type ClientOutput } from "@assistant-ui/store";
-import { MessagePartRuntime } from "../../runtime/api/message-part-runtime";
+import type { ClientOutput } from "@assistant-ui/store";
+import type { MessagePartRuntime } from "../../runtime/api/message-part-runtime";
 import { tapSubscribable } from "./tap-subscribable";
 
 export const MessagePartClient = resource(

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

@@ -11,11 +11,11 @@ import {
   tapClientLookup,
   tapClientResource,
 } from "@assistant-ui/store";
-import { MessageRuntime } from "../../runtime/api/message-runtime";
+import type { MessageRuntime } from "../../runtime/api/message-runtime";
 import { tapSubscribable } from "./tap-subscribable";
 import { ComposerClient } from "./composer-runtime-client";
 import { MessagePartClient } from "./message-part-runtime-client";
-import { MessageState } from "../scopes/message";
+import type { MessageState } from "../scopes/message";
 import { AttachmentRuntimeClient } from "./attachment-runtime-client";
 
 const MessageAttachmentClientByIndex = resource(

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

@@ -1,7 +1,7 @@
 import type { Unsubscribe } from "../../types/unsubscribe";
 import { resource, tapEffect } from "@assistant-ui/tap";
 import { type ClientOutput, tapAssistantEmit } from "@assistant-ui/store";
-import {
+import type {
   ThreadListItemEventType,
   ThreadListItemRuntime,
 } from "../../runtime/api/thread-list-item-runtime";

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

@@ -4,12 +4,12 @@ import {
   tapClientLookup,
   tapClientResource,
 } from "@assistant-ui/store";
-import { ThreadListRuntime } from "../../runtime/api/thread-list-runtime";
-import { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+import type { ThreadListRuntime } from "../../runtime/api/thread-list-runtime";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import { tapSubscribable } from "./tap-subscribable";
 import { ThreadListItemClient } from "./thread-list-item-runtime-client";
 import { ThreadClient } from "./thread-runtime-client";
-import { ThreadsState } from "../scopes/threads";
+import type { ThreadsState } from "../scopes/threads";
 
 const ThreadListItemClientById = resource(
   ({ runtime, id }: { runtime: ThreadListRuntime; id: string }) => {
@@ -86,6 +86,7 @@ export const ThreadListClient = resource(
         await runtime.switchToNewThread();
       },
       getLoadThreadsPromise: () => runtime.getLoadThreadsPromise(),
+      reload: () => runtime.reload(),
       __internal_getAssistantRuntime: () => __internal_assistantRuntime,
     };
   },

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

@@ -1,6 +1,6 @@
 import type { Unsubscribe } from "../../types/unsubscribe";
-import { ThreadRuntimeEventType } from "../../runtime/interfaces/thread-runtime-core";
-import { ThreadRuntime } from "../../runtime/api/thread-runtime";
+import type { ThreadRuntimeEventType } from "../../runtime/interfaces/thread-runtime-core";
+import type { ThreadRuntime } from "../../runtime/api/thread-runtime";
 import {
   resource,
   tapResource,
@@ -18,7 +18,7 @@ import {
 import { ComposerClient } from "./composer-runtime-client";
 import { MessageClient } from "./message-runtime-client";
 import { tapSubscribable } from "./tap-subscribable";
-import { ThreadState } from "../scopes/thread";
+import type { ThreadState } from "../scopes/thread";
 
 const MessageClientById = resource(
   ({

package/src/store/scopes/thread-list-item.ts

@@ -7,6 +7,7 @@ export type ThreadListItemState = {
   readonly externalId: string | undefined;
   readonly title?: string | undefined;
   readonly status: ThreadListItemStatus;
+  readonly custom?: Record<string, unknown> | undefined;
 };
 
 export type ThreadListItemMethods = {

package/src/store/scopes/threads.ts

@@ -27,6 +27,7 @@ export type ThreadsMethods = {
   ): ThreadListItemMethods;
   thread(selector: "main"): ThreadMethods;
   getLoadThreadsPromise(): Promise<void>;
+  reload(): Promise<void>;
   __internal_getAssistantRuntime?(): AssistantRuntime;
 };
 

package/src/subscribable/subscribable.ts

@@ -1,16 +1,8 @@
 import type { Unsubscribe } from "../types/unsubscribe";
 
-// =============================================================================
-// Sentinel
-// =============================================================================
-
 export const SKIP_UPDATE = Symbol("skip-update");
 export type SKIP_UPDATE = typeof SKIP_UPDATE;
 
-// =============================================================================
-// Types
-// =============================================================================
-
 export type Subscribable = {
   subscribe: (callback: () => void) => Unsubscribe;
 };
@@ -36,10 +28,6 @@ export type EventSubscribable<TEvent extends string> = {
   >;
 };
 
-// =============================================================================
-// Utilities
-// =============================================================================
-
 function shallowEqual<T extends object>(
   objA: T | undefined,
   objB: T | undefined,
@@ -57,10 +45,6 @@ function shallowEqual<T extends object>(
   return true;
 }
 
-// =============================================================================
-// Base Subscribable (simple pub-sub)
-// =============================================================================
-
 export class BaseSubscribable {
   private _subscribers = new Set<() => void>();
 
@@ -101,10 +85,7 @@ export class BaseSubscribable {
   }
 }
 
-// =============================================================================
-// Base Subject (lazy connect/disconnect)
-// =============================================================================
-
+// lazy connect/disconnect: only opens upstream subscription while it has subscribers
 export abstract class BaseSubject {
   private _subscriptions = new Set<() => void>();
   private _connection: Unsubscribe | undefined;
@@ -140,10 +121,6 @@ export abstract class BaseSubject {
   }
 }
 
-// =============================================================================
-// Subject Implementations
-// =============================================================================
-
 export class ShallowMemoizeSubject<TState extends object, TPath>
   extends BaseSubject
   implements SubscribableWithState<TState, TPath>

package/src/tests/OptimisticState-list-race.test.ts

@@ -7,6 +7,7 @@ import {
   createThreadMappingId,
   updateStatusReducer,
 } from "../runtimes/remote-thread-list/remote-thread-state";
+import { deferred } from "./remote-thread-list-test-helpers";
 
 /**
  * Reproduces the race condition where a stale list() response
@@ -75,15 +76,6 @@ const applyListResult = (
   };
 };
 
-/** Creates a deferred promise for controlling resolution order. */
-function deferred<T>() {
-  let resolve!: (v: T) => void;
-  const promise = new Promise<T>((r) => {
-    resolve = r;
-  });
-  return { promise, resolve };
-}
-
 describe("list + delete race condition", () => {
   it("stale list() does not re-add a thread deleted while list was in flight", async () => {
     const state = new OptimisticState<RemoteThreadState>(EMPTY_STATE);
@@ -95,6 +87,7 @@ describe("list + delete race condition", () => {
     const listPromise = state.optimisticUpdate({
       execute: () => listDeferred.promise,
       loading: (s) => ({ ...s, isLoading: true }),
+      // biome-ignore lint/suspicious/noThenProperty: OptimisticState reducer pattern
       then: applyListResult,
     });
 
@@ -152,6 +145,7 @@ describe("list + delete race condition", () => {
     const listPromise = state.optimisticUpdate({
       execute: () => listDeferred.promise,
       loading: (s) => ({ ...s, isLoading: true }),
+      // biome-ignore lint/suspicious/noThenProperty: OptimisticState reducer pattern
       then: applyListResult,
     });
 
@@ -189,6 +183,7 @@ describe("list + delete race condition", () => {
     const listPromise = state.optimisticUpdate({
       execute: () => listDeferred.promise,
       loading: (s) => ({ ...s, isLoading: true }),
+      // biome-ignore lint/suspicious/noThenProperty: OptimisticState reducer pattern
       then: applyListResult,
     });
 
@@ -226,6 +221,7 @@ describe("list + delete race condition", () => {
     const listPromise = state.optimisticUpdate({
       execute: () => listDeferred.promise,
       loading: (s) => ({ ...s, isLoading: true }),
+      // biome-ignore lint/suspicious/noThenProperty: OptimisticState reducer pattern
       then: applyListResult,
     });
 

package/src/tests/RemoteThreadListThreadListRuntimeCore-custom-metadata.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, vi } from "vitest";
+import { createCore, makeAdapter } from "./remote-thread-list-test-helpers";
+
+describe("RemoteThreadListThreadListRuntimeCore custom metadata", () => {
+  it("preserves custom field from list() through to threadItems", async () => {
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [
+          {
+            status: "regular" as const,
+            remoteId: "thread-1",
+            externalId: "ext-1",
+            title: "Test",
+            custom: { workspaceId: "ws-1", createdAt: "2026-04-26" },
+          },
+        ],
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    const item = core.getItemById("thread-1");
+    expect(item?.custom).toEqual({
+      workspaceId: "ws-1",
+      createdAt: "2026-04-26",
+    });
+  });
+
+  it("preserves custom field from fetch() through switchToThread", async () => {
+    const adapter = makeAdapter({
+      fetch: vi.fn(async (id: string) => ({
+        status: "regular" as const,
+        remoteId: id,
+        externalId: id,
+        title: "Test",
+        custom: { ownerId: "user-42" },
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.switchToThread("thread-2");
+
+    const item = core.getItemById("thread-2");
+    expect(item?.custom).toEqual({ ownerId: "user-42" });
+  });
+
+  it("leaves custom undefined when adapter omits it", async () => {
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [
+          {
+            status: "regular" as const,
+            remoteId: "thread-3",
+            externalId: "ext-3",
+            title: "Test",
+          },
+        ],
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    const item = core.getItemById("thread-3");
+    expect(item?.custom).toBeUndefined();
+  });
+
+  it("preserves custom across rename optimistic update", async () => {
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [
+          {
+            status: "regular" as const,
+            remoteId: "thread-4",
+            externalId: "ext-4",
+            title: "Old",
+            custom: { tag: "important" },
+          },
+        ],
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+    await core.rename("thread-4", "New");
+
+    const item = core.getItemById("thread-4");
+    expect(item?.title).toBe("New");
+    expect(item?.custom).toEqual({ tag: "important" });
+  });
+
+  it("preserves custom across archive and unarchive optimistic updates", async () => {
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [
+          {
+            status: "regular" as const,
+            remoteId: "thread-5",
+            externalId: "ext-5",
+            title: "Test",
+            custom: { workspaceId: "ws-1" },
+          },
+        ],
+      })),
+    });
+
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    await core.archive("thread-5");
+    expect(core.getItemById("thread-5")?.status).toBe("archived");
+    expect(core.getItemById("thread-5")?.custom).toEqual({
+      workspaceId: "ws-1",
+    });
+
+    await core.unarchive("thread-5");
+    expect(core.getItemById("thread-5")?.status).toBe("regular");
+    expect(core.getItemById("thread-5")?.custom).toEqual({
+      workspaceId: "ws-1",
+    });
+  });
+});