@assistant-ui/core 0.3.13 → 0.3.14

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

@@ -0,0 +1,191 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { RealtimeVoiceAdapter } from "../../adapters/voice";
+import type { AppendMessage } from "../../types/message";
+import type {
+  AddToolResultOptions,
+  ResumeRunConfig,
+  ResumeToolCallOptions,
+  RespondToToolApprovalOptions,
+  RuntimeCapabilities,
+  StartRunConfig,
+  ThreadSuggestion,
+} from "../interfaces/thread-runtime-core";
+import { BaseThreadRuntimeCore } from "./base-thread-runtime-core";
+
+const createVoiceAdapter = () => {
+  let volumeCallback: ((volume: number) => void) | undefined;
+  const session: RealtimeVoiceAdapter.Session = {
+    status: { type: "running" },
+    isMuted: false,
+    disconnect: vi.fn(),
+    mute: vi.fn(),
+    unmute: vi.fn(),
+    onStatusChange: () => () => {},
+    onTranscript: () => () => {},
+    onModeChange: () => () => {},
+    onVolumeChange: (callback) => {
+      volumeCallback = callback;
+      return () => {
+        volumeCallback = undefined;
+      };
+    },
+  };
+
+  return {
+    adapter: { connect: () => session },
+    emitVolume: (volume: number) => volumeCallback?.(volume),
+    session,
+  } satisfies {
+    adapter: RealtimeVoiceAdapter;
+    emitVolume: (volume: number) => void;
+    session: RealtimeVoiceAdapter.Session;
+  };
+};
+
+class TestRuntime extends BaseThreadRuntimeCore {
+  private readonly voiceAdapter: ReturnType<typeof createVoiceAdapter>;
+
+  constructor(voiceAdapter: ReturnType<typeof createVoiceAdapter>) {
+    super({ getModelContext: () => ({}) });
+    this.voiceAdapter = voiceAdapter;
+  }
+
+  get adapters() {
+    return { voice: this.voiceAdapter.adapter };
+  }
+
+  get isDisabled() {
+    return false;
+  }
+
+  get isSendDisabled() {
+    return false;
+  }
+
+  get isLoading() {
+    return false;
+  }
+
+  get suggestions(): readonly ThreadSuggestion[] {
+    return [];
+  }
+
+  get extras() {
+    return undefined;
+  }
+
+  get capabilities(): RuntimeCapabilities {
+    return {
+      switchToBranch: false,
+      switchBranchDuringRun: false,
+      edit: false,
+      delete: false,
+      reload: false,
+      refetchThread: false,
+      cancel: false,
+      unstable_copy: false,
+      speech: false,
+      dictation: false,
+      voice: true,
+      attachments: false,
+      feedback: false,
+      queue: false,
+    };
+  }
+
+  append(_message: AppendMessage) {}
+  deleteMessage(_messageId: string) {}
+  startRun(_config: StartRunConfig) {}
+  resumeRun(_config: ResumeRunConfig) {}
+  addToolResult(_options: AddToolResultOptions) {}
+  resumeToolCall(_options: ResumeToolCallOptions) {}
+  respondToToolApproval(_options: RespondToToolApprovalOptions) {}
+  cancelRun() {}
+  exportExternalState() {
+    return {};
+  }
+  importExternalState(_state: unknown) {}
+  unstable_notifySessionReset() {}
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("BaseThreadRuntimeCore voice volume subscriptions", () => {
+  it("continues notifying subscribers when one throws", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const voice = createVoiceAdapter();
+    const runtime = new TestRuntime(voice);
+    runtime.connectVoice();
+
+    const listenerError = new Error("listener failed");
+    const laterListener = vi.fn();
+    runtime.subscribeVoiceVolume(() => {
+      throw listenerError;
+    });
+    runtime.subscribeVoiceVolume(laterListener);
+
+    expect(() => voice.emitVolume(0.5)).not.toThrow();
+    expect(laterListener).toHaveBeenCalledOnce();
+    expect(runtime.getVoiceVolume()).toBe(0.5);
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Voice volume listener threw an error",
+      listenerError,
+    );
+  });
+
+  it("continues disconnect cleanup when a subscriber throws", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const voice = createVoiceAdapter();
+    const runtime = new TestRuntime(voice);
+    runtime.connectVoice();
+
+    const listenerError = new Error("disconnect listener failed");
+    const laterListener = vi.fn();
+    runtime.subscribeVoiceVolume(() => {
+      throw listenerError;
+    });
+    runtime.subscribeVoiceVolume(laterListener);
+
+    expect(() => runtime.disconnectVoice()).not.toThrow();
+    expect(laterListener).toHaveBeenCalledOnce();
+    expect(runtime.getVoiceVolume()).toBe(0);
+    expect(runtime.voice).toBeUndefined();
+    expect(voice.session.disconnect).toHaveBeenCalledOnce();
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Voice volume listener threw an error",
+      listenerError,
+    );
+  });
+
+  it("reports rejected subscriber thenables", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const voice = createVoiceAdapter();
+    const runtime = new TestRuntime(voice);
+    runtime.connectVoice();
+
+    const listenerError = new Error("async listener failed");
+    const laterListener = vi.fn();
+    runtime.subscribeVoiceVolume(async () => {
+      throw listenerError;
+    });
+    runtime.subscribeVoiceVolume(laterListener);
+
+    voice.emitVolume(0.5);
+
+    await vi.waitFor(() => {
+      expect(laterListener).toHaveBeenCalledOnce();
+      expect(consoleError).toHaveBeenCalledWith(
+        "[assistant-ui] Voice volume listener threw an error",
+        listenerError,
+      );
+    });
+  });
+});

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

@@ -69,6 +69,7 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   public abstract cancelRun(): void;
   public abstract exportExternalState(): any;
   public abstract importExternalState(state: any): void;
+  public abstract unstable_notifySessionReset(): void;
 
   protected _voiceMessages: ThreadMessage[] = [];
   protected _voiceGeneration = 0;
@@ -355,7 +356,11 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     unsubs.push(
       session.onVolumeChange((volume) => {
         this._voiceVolume = volume;
-        for (const cb of this._voiceVolumeSubscribers) cb();
+        notifyEventListeners(
+          this._voiceVolumeSubscribers,
+          undefined,
+          "Voice volume",
+        );
       }),
     );
 
@@ -454,7 +459,11 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     this._voiceSession = undefined;
     this.voice = undefined;
     this._voiceVolume = 0;
-    for (const cb of this._voiceVolumeSubscribers) cb();
+    notifyEventListeners(
+      this._voiceVolumeSubscribers,
+      undefined,
+      "Voice volume",
+    );
     this._voiceMessages = [];
     this._markVoiceMessagesDirty();
     this._notifySubscribers();

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

@@ -6,6 +6,7 @@ import type {
   ThreadComposerRuntimeCore,
 } from "../interfaces/composer-runtime-core";
 import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
+import { getThreadRuntimeCoreIsRunning } from "../api/thread-runtime";
 import type { QueuePlacement } from "../queue/external-thread-queue-adapter";
 import {
   EMPTY_QUEUE_ITEMS,
@@ -13,13 +14,18 @@ import {
 } from "../../store/scopes/queue-item";
 import { BaseComposerRuntimeCore } from "./base-composer-runtime-core";
 
+const isCancelable = (runtime: Omit<ThreadRuntimeCore, "composer">) => {
+  // capabilities is a subclass field assigned after this composer is constructed
+  if (!runtime.capabilities?.cancel) return false;
+  return getThreadRuntimeCoreIsRunning(runtime);
+};
+
 export class DefaultThreadComposerRuntimeCore
   extends BaseComposerRuntimeCore
   implements ThreadComposerRuntimeCore
 {
-  private _canCancel = false;
   public get canCancel() {
-    return this._canCancel;
+    return isCancelable(this.runtime);
   }
 
   public get canSend() {
@@ -94,12 +100,14 @@ export class DefaultThreadComposerRuntimeCore
   }
 
   public connect() {
+    let lastCanCancel = false;
     let lastIsSendDisabled = this.runtime.isSendDisabled;
     let lastQueue = this.queue;
     return this.runtime.subscribe(() => {
       let changed = false;
-      if (this.canCancel !== this.runtime.capabilities.cancel) {
-        this._canCancel = this.runtime.capabilities.cancel;
+      const nextCanCancel = this.canCancel;
+      if (lastCanCancel !== nextCanCancel) {
+        lastCanCancel = nextCanCancel;
         changed = true;
       }
       if (lastIsSendDisabled !== this.runtime.isSendDisabled) {

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

@@ -72,6 +72,11 @@ export type SubmitFeedbackOptions = {
 };
 
 export type ThreadSuggestion = {
+  /** Display heading for the suggestion. Falls back to the prompt when absent. */
+  title?: string;
+  /** Secondary display text shown alongside the title. */
+  label?: string;
+  /** The message text sent when the suggestion is selected. */
   prompt: string;
 };
 
@@ -156,6 +161,7 @@ export type ThreadRuntimeCore = Readonly<{
   startRun: (config: StartRunConfig) => void;
   resumeRun: (config: ResumeRunConfig) => void;
   cancelRun: () => void;
+  unstable_notifySessionReset: () => void;
 
   addToolResult: (options: AddToolResultOptions) => void;
   resumeToolCall: (options: ResumeToolCallOptions) => void;

package/src/runtime/queue/message-queue.ts

@@ -8,6 +8,7 @@ import {
   type QueueItemState,
 } from "../../store/scopes/queue-item";
 import { generateId } from "../../utils/id";
+import { notifyEventListeners } from "../../utils/notify-event-listeners";
 import { getThreadMessageText } from "../../utils/text";
 import type {
   ExternalThreadQueueAdapter,
@@ -87,7 +88,7 @@ export const createMessageQueue = (
   let interrupting = false;
 
   const notify = () => {
-    for (const callback of subscribers) callback();
+    notifyEventListeners(subscribers, undefined, "Message queue");
   };
 
   const setLanes = (next: Record<Lane, readonly QueueItemState[]>) => {

package/src/runtime/utils/thread-runtime-lifecycle.ts

@@ -0,0 +1,18 @@
+import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
+
+// Invalidation must stay re-entrant: StrictMode's simulated unmount runs the
+// effect cleanup while the runtime object survives into the next mount, so a
+// permanent disposed mark would swallow every later append.
+const generations = new WeakMap<ThreadRuntimeCore, number>();
+
+export const captureThreadRuntimeGeneration = (runtime: ThreadRuntimeCore) =>
+  generations.get(runtime) ?? 0;
+
+export const isThreadRuntimeGenerationCurrent = (
+  runtime: ThreadRuntimeCore,
+  generation: number,
+) => captureThreadRuntimeGeneration(runtime) === generation;
+
+export const invalidateThreadRuntime = (runtime: ThreadRuntimeCore) => {
+  generations.set(runtime, captureThreadRuntimeGeneration(runtime) + 1);
+};

package/src/runtimes/external-store/external-store-shared-options.ts

@@ -14,5 +14,7 @@ export const pickExternalStoreSharedOptions = (
     unstable_capabilities: options.unstable_capabilities,
     suggestions: options.suggestions,
   }) satisfies {
-    [K in keyof Required<ExternalStoreSharedOptions>]: ExternalStoreSharedOptions[K];
+    [
+      K in keyof Required<ExternalStoreSharedOptions>
+    ]: ExternalStoreSharedOptions[K];
   };

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

@@ -5,6 +5,8 @@ import type {
   ThreadListRuntimeCore,
 } from "../../runtime/interfaces/thread-list-runtime-core";
 import type { ExternalStoreThreadListAdapter } from "./external-store-adapter";
+import { invalidateThreadRuntime } from "../../runtime/utils/thread-runtime-lifecycle";
+import { notifySubscribers } from "../../subscribable/subscribable";
 
 export type ExternalStoreThreadFactory = () => ExternalStoreThreadRuntimeCore;
 
@@ -150,6 +152,7 @@ export class ExternalStoreThreadListRuntimeCore implements ThreadListRuntimeCore
 
     // `initialLoad ||`: `_mainThread!` must be assigned on construction.
     if (initialLoad || previousThreadId !== newThreadId) {
+      if (!initialLoad) invalidateThreadRuntime(this._mainThread);
       this._mainThreadId = newThreadId;
       this._mainThread = this.threadFactory();
     }
@@ -268,6 +271,6 @@ export class ExternalStoreThreadListRuntimeCore implements ThreadListRuntimeCore
   }
 
   private _notifySubscribers() {
-    for (const callback of this._subscriptions) callback();
+    notifySubscribers(this._subscriptions);
   }
 }

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

@@ -42,9 +42,25 @@ import { generateId } from "../../utils/id";
 import { ToolInvocationTracker } from "../tool-invocations/ToolInvocationTracker";
 import { EMPTY_QUEUE_ITEMS } from "../../store/scopes/queue-item";
 import type { QuoteInfo } from "../../types/quote";
+import {
+  captureThreadRuntimeGeneration,
+  isThreadRuntimeGenerationCurrent,
+} from "../../runtime/utils/thread-runtime-lifecycle";
 
 const EMPTY_ARRAY: readonly ThreadSuggestion[] = Object.freeze([]);
 
+const observeAdapterCallback = (
+  name: "onAddToolResult" | "onRespondToToolApproval" | "onCancel",
+  result: Promise<void> | void,
+) => {
+  void Promise.resolve(result).catch((error) => {
+    console.error(
+      `[ExternalStoreThreadRuntimeCore] ${name} callback rejected`,
+      error,
+    );
+  });
+};
+
 const shallowEqual = (a: object, b: object): boolean => {
   const aKeys = Object.keys(a);
   if (aKeys.length !== Object.keys(b).length) return false;
@@ -122,6 +138,14 @@ export class ExternalStoreThreadRuntimeCore
 
   private _store!: ExternalStoreAdapter<any>;
 
+  private _getInitializePromise?: () => Promise<unknown> | undefined;
+
+  public __internal_setGetInitializePromise(
+    getPromise: () => Promise<unknown> | undefined,
+  ) {
+    this._getInitializePromise = getPromise;
+  }
+
   private _transformedQueue: ExternalThreadQueueAdapter | undefined;
 
   /**
@@ -375,19 +399,22 @@ export class ExternalStoreThreadRuntimeCore
                 // rolled back). Drop the result.
                 return;
               }
-              this._store.onAddToolResult?.({
-                messageId,
-                toolCallId: command.toolCallId,
-                toolName: command.toolName,
-                result: command.result,
-                isError: command.isError,
-                ...(command.artifact !== undefined && {
-                  artifact: command.artifact,
-                }),
-                ...(command.modelContent !== undefined && {
-                  modelContent: command.modelContent,
+              observeAdapterCallback(
+                "onAddToolResult",
+                this._store.onAddToolResult?.({
+                  messageId,
+                  toolCallId: command.toolCallId,
+                  toolName: command.toolName,
+                  result: command.result,
+                  isError: command.isError,
+                  ...(command.artifact !== undefined && {
+                    artifact: command.artifact,
+                  }),
+                  ...(command.modelContent !== undefined && {
+                    modelContent: command.modelContent,
+                  }),
                 }),
-              });
+              );
             } catch (err) {
               console.error(
                 "[ExternalStoreThreadRuntimeCore] onAddToolResult dispatch failed",
@@ -492,22 +519,46 @@ export class ExternalStoreThreadRuntimeCore
       rawMessage.sourceId != null ||
       rawMessage.parentId !== (this.messages.at(-1)?.id ?? null);
 
-    // Buffering does not start a run, so the tool-abort below must wait until
-    // the queue flushes. By then the prior run (and its tools) has settled.
+    // A transformed-queue send is stamped at flush; any other queue's
+    // transform would gate against its own thread's messages, so those stamp
+    // at send.
+    const message =
+      !isEdit &&
+      this._store.queue &&
+      this._store.queue === this._transformedQueue
+        ? rawMessage
+        : this.enrichAppendMetadata(rawMessage);
+
+    const generation = captureThreadRuntimeGeneration(this);
+    this.ensureInitialized();
+
+    // The getter call is what starts thread initialization.
+    const initPromise = this._getInitializePromise?.();
+
+    // The queue driver dispatches through the host adapter, outside this
+    // core, so the initialization barrier must run before a message can
+    // enter the queue.
     if (!isEdit && this._store.queue) {
-      // Skip only for the queue this core actually installed on: another
-      // core's transform would gate against its own thread's messages.
-      const queued =
-        this._store.queue === this._transformedQueue
-          ? rawMessage
-          : this.enrichAppendMetadata(rawMessage);
-      if (queued.steer ?? this._store.isRunning ?? false)
-        this._store.queue.steer(queued);
-      else this._store.queue.enqueue(queued);
+      if (initPromise) {
+        await initPromise;
+      }
+      if (!isThreadRuntimeGenerationCurrent(this, generation)) return;
+
+      // Buffering does not start a run, so the tool-abort below must wait
+      // until the queue flushes. By then the prior run (and its tools) has
+      // settled.
+      if (message.steer ?? this._store.isRunning ?? false)
+        this._store.queue.steer(message);
+      else this._store.queue.enqueue(message);
       return;
     }
 
-    const message = this.enrichAppendMetadata(rawMessage);
+    // The optimistic insert lives inside the adapter's dispatch, so holding
+    // `onNew` on initialization would keep the message off screen for the
+    // whole roundtrip. Seams that need the remote identity await
+    // `threadListItem.initialize()` themselves, and a rejection surfaces
+    // there.
+    void initPromise?.catch(() => {});
 
     // Auto-abort in-flight client-side tool executions when a new run is
     // about to start. Without this, a tool that finishes after the new turn
@@ -518,6 +569,7 @@ export class ExternalStoreThreadRuntimeCore
     if (message.startRun ?? message.role === "user") {
       await this._toolInvocations?.abort();
     }
+    if (!isThreadRuntimeGenerationCurrent(this, generation)) return;
 
     if (isEdit) {
       if (!this._store.onEdit)
@@ -600,17 +652,24 @@ export class ExternalStoreThreadRuntimeCore
     // imported state) is treated as historical — no streamCall/execute
     // fires for the loaded tool calls. The adapter is expected to update
     // its messages in response to onLoadExternalState; that update flows
-    // back here via __internal_setAdapter. We only clear adapter-side
-    // tool statuses when the tracker is the source of truth — otherwise
-    // we'd wipe statuses the adapter is managing on its own.
-    if (this._toolInvocations) {
-      this._toolInvocations.reset();
-      this._store.setToolStatuses?.({});
-    }
+    // back here via __internal_setAdapter. The tracker publishes the
+    // cleared status map itself, so adapter-side statuses reset only when
+    // the tracker is the source of truth.
+    this._toolInvocations?.reset();
 
     this._store.onLoadExternalState(state);
   }
 
+  /**
+   * Adapter-facing notification that the backing session was discarded.
+   * Clears session-scoped tool-invocation state and parks queued work,
+   * without run-cancel semantics (`onCancel`, composer draft restoration).
+   */
+  public unstable_notifySessionReset(): void {
+    this._toolInvocations?.reset();
+    this._store.queue?.__internal_notifyCancelled?.();
+  }
+
   public cancelRun(): void {
     if (!this._store.onCancel)
       throw new Error("Runtime does not support cancelling runs.");
@@ -625,7 +684,7 @@ export class ExternalStoreThreadRuntimeCore
     // stopped.
     this._store.queue?.__internal_notifyCancelled?.();
 
-    this._store.onCancel();
+    observeAdapterCallback("onCancel", this._store.onCancel());
 
     this.dropEmptyOptimisticHead();
 
@@ -700,7 +759,10 @@ export class ExternalStoreThreadRuntimeCore
   public addToolResult(options: AddToolResultOptions) {
     if (!this._store.onAddToolResult)
       throw new Error("Runtime does not support tool results.");
-    this._store.onAddToolResult?.(options);
+    observeAdapterCallback(
+      "onAddToolResult",
+      this._store.onAddToolResult(options),
+    );
   }
 
   public resumeToolCall(options: ResumeToolCallOptions) {
@@ -726,7 +788,10 @@ export class ExternalStoreThreadRuntimeCore
   public respondToToolApproval(options: RespondToToolApprovalOptions) {
     if (!this._store.onRespondToToolApproval)
       throw new Error("Runtime does not support tool approvals.");
-    this._store.onRespondToToolApproval(options);
+    observeAdapterCallback(
+      "onRespondToToolApproval",
+      this._store.onRespondToToolApproval(options),
+    );
   }
 
   public override reset(initialMessages?: readonly ThreadMessageLike[]) {