@assistant-ui/core 0.1.15 → 0.1.17

package/src/runtime/base/base-thread-runtime-core.ts

@@ -21,6 +21,8 @@ import type {
   SpeechState,
   VoiceSessionState,
   RuntimeCapabilities,
+  ThreadRuntimeEventCallback,
+  ThreadRuntimeEventPayload,
   ThreadRuntimeEventType,
   StartRunConfig,
   ResumeRunConfig,
@@ -168,11 +170,14 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     for (const callback of this._subscriptions) callback();
   }
 
-  public _notifyEventSubscribers(event: ThreadRuntimeEventType) {
+  public _notifyEventSubscribers<E extends ThreadRuntimeEventType>(
+    event: E,
+    payload: ThreadRuntimeEventPayload[E],
+  ) {
     const subscribers = this._eventSubscribers.get(event);
     if (!subscribers) return;
 
-    for (const callback of subscribers) callback();
+    for (const callback of subscribers) callback(payload);
   }
 
   public subscribe(callback: () => void): Unsubscribe {
@@ -432,7 +437,7 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   protected ensureInitialized() {
     if (!this._isInitialized) {
       this._isInitialized = true;
-      this._notifyEventSubscribers("initialize");
+      this._notifyEventSubscribers("initialize", {});
     }
   }
 
@@ -453,24 +458,28 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
 
   private _eventSubscribers = new Map<
     ThreadRuntimeEventType,
-    Set<() => void>
+    Set<(payload?: unknown) => void>
   >();
 
-  public unstable_on(event: ThreadRuntimeEventType, callback: () => void) {
+  public unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
+  ) {
+    const wrapped = callback as (payload?: unknown) => void;
     if (event === "modelContextUpdate") {
-      return this._contextProvider.subscribe?.(callback) ?? (() => {});
+      // provider.subscribe is `() => void`; pump the typed empty payload to the user callback.
+      return this._contextProvider.subscribe?.(() => wrapped({})) ?? (() => {});
     }
 
-    const subscribers = this._eventSubscribers.get(event);
+    let subscribers = this._eventSubscribers.get(event);
     if (!subscribers) {
-      this._eventSubscribers.set(event, new Set([callback]));
-    } else {
-      subscribers.add(callback);
+      subscribers = new Set();
+      this._eventSubscribers.set(event, subscribers);
     }
+    subscribers.add(wrapped);
 
     return () => {
-      const subscribers = this._eventSubscribers.get(event)!;
-      subscribers.delete(callback);
+      this._eventSubscribers.get(event)?.delete(wrapped);
     };
   }
 }

package/src/runtime/interfaces/composer-runtime-core.ts

@@ -5,10 +5,37 @@ import type { Unsubscribe } from "../../types/unsubscribe";
 import type { RunConfig } from "../../types/message";
 import type { DictationAdapter } from "../../adapters/speech";
 
-export type ComposerRuntimeEventType =
-  | "send"
-  | "attachmentAdd"
-  | "attachmentAddError";
+export type AttachmentAddErrorReason =
+  | "no-adapter"
+  | "not-accepted"
+  | "adapter-error";
+
+export type AttachmentAddErrorEvent = {
+  readonly reason: AttachmentAddErrorReason;
+  readonly message: string;
+  readonly attachmentId?: string;
+  readonly error?: Error;
+};
+
+export type ComposerRuntimeEventPayload = {
+  /**
+   * @deprecated State-derivable. Observe `state.text` clearing via
+   * `subscribe` + `getState` instead. Kept for backward compatibility.
+   */
+  send: Record<string, never>;
+  /**
+   * @deprecated State-derivable. Observe `state.attachments` via `subscribe` +
+   * `getState` instead. Kept for backward compatibility.
+   */
+  attachmentAdd: Record<string, never>;
+  attachmentAddError: AttachmentAddErrorEvent;
+};
+
+export type ComposerRuntimeEventType = keyof ComposerRuntimeEventPayload;
+
+export type ComposerRuntimeEventCallback<E extends ComposerRuntimeEventType> = (
+  payload: ComposerRuntimeEventPayload[E],
+) => void;
 
 export type DictationState = {
   readonly status: DictationAdapter.Status;
@@ -56,9 +83,14 @@ export type ComposerRuntimeCore = Readonly<{
 
   subscribe: (callback: () => void) => Unsubscribe;
 
-  unstable_on: (
-    event: ComposerRuntimeEventType,
-    callback: () => void,
+  /**
+   * @deprecated This API is still under active development and might change without notice.
+   * For state-derivable transitions, prefer `subscribe` + `getState`. This channel is the
+   * escape hatch for transient occurrences not represented in state.
+   */
+  unstable_on: <E extends ComposerRuntimeEventType>(
+    event: E,
+    callback: ComposerRuntimeEventCallback<E>,
   ) => Unsubscribe;
 }>;
 

package/src/runtime/interfaces/thread-list-runtime-core.ts

@@ -10,6 +10,7 @@ export type ThreadListItemCoreState = {
 
   readonly status: ThreadListItemStatus;
   readonly title?: string | undefined;
+  readonly custom?: Record<string, unknown> | undefined;
 
   readonly runtime?: ThreadRuntimeCore | undefined;
 };

package/src/runtime/interfaces/thread-runtime-core.ts

@@ -69,11 +69,41 @@ export type SubmittedFeedback = {
   readonly type: "negative" | "positive";
 };
 
-export type ThreadRuntimeEventType =
-  | "runStart"
-  | "runEnd"
-  | "initialize"
-  | "modelContextUpdate";
+export type ThreadRuntimeEventPayload = {
+  /**
+   * @deprecated State-derivable. Observe `state.isRunning` flipping to `true`
+   * via `subscribe` + `getState` instead. Note: this event fires at the
+   * transition point and may run before the next subscriber notification.
+   * Kept for backward compatibility.
+   */
+  runStart: Record<string, never>;
+  /**
+   * @deprecated State-derivable. Observe `state.isRunning` flipping to `false`
+   * via `subscribe` + `getState` instead. Note: this event fires at the
+   * transition point and may run before the next subscriber notification.
+   * Kept for backward compatibility.
+   */
+  runEnd: Record<string, never>;
+  /**
+   * @deprecated State-derivable. This event fires at the initialization
+   * transition immediately BEFORE the first message is added, so reading state
+   * inside the handler still sees an empty thread; observe `state.messages`
+   * becoming non-empty via a regular `subscribe` callback instead. Kept for
+   * backward compatibility.
+   */
+  initialize: Record<string, never>;
+  /**
+   * Truly transient. The model context lives in a provider, not in thread
+   * state, so this event has no state-derivable equivalent.
+   */
+  modelContextUpdate: Record<string, never>;
+};
+
+export type ThreadRuntimeEventType = keyof ThreadRuntimeEventPayload;
+
+export type ThreadRuntimeEventCallback<E extends ThreadRuntimeEventType> = (
+  payload: ThreadRuntimeEventPayload[E],
+) => void;
 
 export type StartRunConfig = {
   parentId: string | null;
@@ -155,7 +185,15 @@ export type ThreadRuntimeCore = Readonly<{
 
   reset(initialMessages?: readonly ThreadMessageLike[]): void;
 
-  unstable_on(event: ThreadRuntimeEventType, callback: () => void): Unsubscribe;
+  /**
+   * @deprecated This API is still under active development and might change without notice.
+   * For state-derivable transitions, prefer `subscribe` + `getState`. This channel is the
+   * escape hatch for transient occurrences not represented in state.
+   */
+  unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
+  ): Unsubscribe;
 
   /**
    * @deprecated Use importExternalState instead. This method will be removed in 0.12.0.

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

@@ -236,9 +236,9 @@ export class ExternalStoreThreadRuntimeCore
 
     if ((oldStore?.isRunning ?? false) !== (store.isRunning ?? false)) {
       if (store.isRunning) {
-        this._notifyEventSubscribers("runStart");
+        this._notifyEventSubscribers("runStart", {});
       } else {
-        this._notifyEventSubscribers("runEnd");
+        this._notifyEventSubscribers("runEnd", {});
       }
     }
 

package/src/runtimes/local/local-thread-runtime-core.ts

@@ -253,7 +253,7 @@ export class LocalThreadRuntimeCore
       createdAt: new Date(),
     };
 
-    this._notifyEventSubscribers("runStart");
+    this._notifyEventSubscribers("runStart", {});
 
     try {
       this._suggestions = [];
@@ -271,7 +271,7 @@ export class LocalThreadRuntimeCore
         runCallback = undefined;
       } while (shouldContinue(message, this._options.unstable_humanToolNames));
     } finally {
-      this._notifyEventSubscribers("runEnd");
+      this._notifyEventSubscribers("runEnd", {});
     }
 
     this._suggestionsController = new AbortController();

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,3 +1,4 @@
+import type { ComponentType, PropsWithChildren } from "react";
 import type { ThreadMessage } from "../../types/message";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import type { AssistantStream } from "assistant-stream";
@@ -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/composer-runtime-client.ts

@@ -63,19 +63,15 @@ export const ComposerClient = resource(
         unsubscribers.push(unsubscribe);
       }
 
-      // attachmentAddError carries the failed attachment ID
       unsubscribers.push(
-        runtime.unstable_on("attachmentAddError", () => {
-          const errorAttachment = runtime
-            .getState()
-            .attachments.findLast(
-              (a) =>
-                a.status.type === "incomplete" && a.status.reason === "error",
-            );
+        runtime.unstable_on("attachmentAddError", (payload) => {
+          // payload.error omitted: raw Error is not store-serializable; use runtime.unstable_on for it.
           emit("composer.attachmentAddError", {
             threadId: threadIdRef.current,
             ...(messageIdRef && { messageId: messageIdRef.current }),
-            ...(errorAttachment && { attachmentId: errorAttachment.id }),
+            ...(payload.attachmentId && { attachmentId: payload.attachmentId }),
+            reason: payload.reason,
+            message: payload.message,
           });
         }),
       );

package/src/store/scopes/composer.ts

@@ -4,6 +4,7 @@ import type { QuoteInfo } from "../../types/quote";
 import type { RunConfig } from "../../types/message";
 import type { ComposerRuntime } from "../../runtime/api/composer-runtime";
 import type {
+  AttachmentAddErrorReason,
   DictationState,
   SendOptions,
 } from "../../runtime/interfaces/composer-runtime-core";
@@ -91,12 +92,22 @@ export type ComposerMeta = {
 };
 
 export type ComposerEvents = {
+  /**
+   * @deprecated State-derivable. Observe composer `text` clearing via
+   * `useAuiState` instead. Kept for backward compatibility.
+   */
   "composer.send": { threadId: string; messageId?: string };
+  /**
+   * @deprecated State-derivable. Observe composer `attachments` via
+   * `useAuiState` instead. Kept for backward compatibility.
+   */
   "composer.attachmentAdd": { threadId: string; messageId?: string };
   "composer.attachmentAddError": {
     threadId: string;
     messageId?: string;
     attachmentId?: string;
+    reason: AttachmentAddErrorReason;
+    message: string;
   };
 };
 

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 = {
@@ -31,7 +32,17 @@ export type ThreadListItemMeta = {
 };
 
 export type ThreadListItemEvents = {
+  /**
+   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
+   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
+   * compatibility.
+   */
   "threadListItem.switchedTo": { threadId: string };
+  /**
+   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
+   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
+   * compatibility.
+   */
   "threadListItem.switchedAway": { threadId: string };
 };
 

package/src/store/scopes/thread.ts

@@ -130,9 +130,26 @@ export type ThreadMeta = {
 };
 
 export type ThreadEvents = {
+  /**
+   * @deprecated State-derivable. Observe `isRunning` flipping to `true` via
+   * `useAuiState` instead. Kept for backward compatibility.
+   */
   "thread.runStart": { threadId: string };
+  /**
+   * @deprecated State-derivable. Observe `isRunning` flipping to `false` via
+   * `useAuiState` instead. Kept for backward compatibility.
+   */
   "thread.runEnd": { threadId: string };
+  /**
+   * @deprecated State-derivable. This event fires before the first message is
+   * added; observe `messages` becoming non-empty via `useAuiState` instead of
+   * reading state inside this event handler. Kept for backward compatibility.
+   */
   "thread.initialize": { threadId: string };
+  /**
+   * Truly transient. Model context lives in a provider, not in thread state,
+   * so this event has no state-derivable equivalent.
+   */
   "thread.modelContextUpdate": { threadId: string };
 };
 

package/src/subscribable/subscribable.ts

@@ -21,7 +21,10 @@ export type EventSubscribable<TEvent extends string> = {
   event: TEvent;
   binding: SubscribableWithState<
     | {
-        unstable_on: (event: TEvent, callback: () => void) => Unsubscribe;
+        unstable_on: (
+          event: TEvent,
+          callback: (payload?: unknown) => void,
+        ) => Unsubscribe;
       }
     | undefined,
     unknown
@@ -87,7 +90,7 @@ export class BaseSubscribable {
 
 // lazy connect/disconnect: only opens upstream subscription while it has subscribers
 export abstract class BaseSubject {
-  private _subscriptions = new Set<() => void>();
+  private _subscriptions = new Set<(payload?: unknown) => void>();
   private _connection: Unsubscribe | undefined;
 
   protected get isConnected() {
@@ -96,8 +99,8 @@ export abstract class BaseSubject {
 
   protected abstract _connect(): Unsubscribe;
 
-  protected notifySubscribers() {
-    for (const callback of this._subscriptions) callback();
+  protected notifySubscribers(payload?: unknown) {
+    for (const callback of this._subscriptions) callback(payload);
   }
 
   private _updateConnection() {
@@ -110,7 +113,7 @@ export abstract class BaseSubject {
     }
   }
 
-  public subscribe(callback: () => void) {
+  public subscribe(callback: (payload?: unknown) => void) {
     this._subscriptions.add(callback);
     this._updateConnection();
 
@@ -270,8 +273,8 @@ export class EventSubscriptionSubject<
   }
 
   protected _connect(): Unsubscribe {
-    const callback = () => {
-      this.notifySubscribers();
+    const callback = (payload?: unknown) => {
+      this.notifySubscribers(payload);
     };
 
     let lastState = this.config.binding.getState();

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",
+    });
+  });
+});