@assistant-ui/core 0.3.12 → 0.3.14

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

@@ -6,6 +6,7 @@ import {
   type PendingAttachment,
 } from "../../types/attachment";
 import type { MessageRole, AppendMessage } from "../../types/message";
+import { isMessageNotSentError } from "../../types/error";
 import type { QuoteInfo } from "../../types/quote";
 import type { Unsubscribe } from "../../types/unsubscribe";
 import type { RunConfig } from "../../types/message";
@@ -118,15 +119,22 @@ export abstract class BaseComposerRuntimeCore
     if (this._text === value) return;
 
     this._text = value;
-    if (this._dictation) {
-      this._dictationBaseText = value;
-      this._currentInterimText = "";
-      const { status, inputDisabled } = this._dictation;
-      this._dictation = inputDisabled ? { status, inputDisabled } : { status };
-    }
+    this._rebaseDictation(value);
     this._notifySubscribers();
   }
 
+  // A live dictation session appends to the text it last saw, so any write
+  // that bypasses `setText` has to move that baseline or the next transcript
+  // overwrites what was just written.
+  private _rebaseDictation(value: string) {
+    if (!this._dictation) return;
+
+    this._dictationBaseText = value;
+    this._currentInterimText = "";
+    const { status, inputDisabled } = this._dictation;
+    this._dictation = inputDisabled ? { status, inputDisabled } : { status };
+  }
+
   public setRole(role: MessageRole) {
     if (this._role === role) return;
 
@@ -232,6 +240,8 @@ export abstract class BaseComposerRuntimeCore
     const originalAttachments = this.attachments;
     const text = this.text;
     const quote = this._quote;
+    const role = this.role;
+    const runConfig = this.runConfig;
     this._quote = undefined;
     this._text = "";
     this._isSending = true;
@@ -245,6 +255,7 @@ export abstract class BaseComposerRuntimeCore
       if (generation === this._sendGeneration) {
         if (!this.text.trim() && this._quote === undefined) {
           this._text = text;
+          this._rebaseDictation(text);
           this._quote = quote;
           this._notifySubscribers();
         }
@@ -282,18 +293,101 @@ export abstract class BaseComposerRuntimeCore
 
     const message: Omit<AppendMessage, "parentId" | "sourceId"> = {
       createdAt: new Date(),
-      role: this.role,
+      role,
       content: text ? [{ type: "text", text }] : [],
       attachments: finalAttachments,
-      runConfig: this.runConfig,
+      runConfig,
       metadata: { custom: { ...(quote ? { quote } : {}) } },
     };
 
-    const sendTask = this.handleSend(message, options);
-    if (sendTask) void sendTask.catch(() => {});
+    const draft = { text, quote, attachments: finalAttachments };
+    let sendTask: void | Promise<void>;
+    try {
+      sendTask = this.handleSend(message, options);
+    } catch (error) {
+      this._restoreUnsentDraft(error, generation, draft);
+      throw error;
+    }
+    if (sendTask)
+      void sendTask.catch((error) => {
+        this._restoreUnsentDraft(error, generation, draft);
+      });
     this._notifyEventSubscribers("send", {});
   }
 
+  /**
+   * Take a message back into the composer when it has nowhere else to live:
+   * a send the runtime never dispatched, or a message a cancelled run is
+   * removing from the thread. Reports whether the composer accepted it, so a
+   * caller that is also removing the message can keep it instead of dropping
+   * it. Refused, and left untouched, while the composer holds anything of its
+   * own.
+   */
+  public restoreDraft(draft: {
+    text: string;
+    quote?: QuoteInfo | undefined;
+    attachments?: readonly Attachment[] | undefined;
+  }): boolean {
+    if (
+      this._text.trim() ||
+      this._quote !== undefined ||
+      this._attachments.length > 0
+    )
+      return false;
+
+    this._text = draft.text;
+    this._rebaseDictation(draft.text);
+    this._quote = draft.quote;
+    this._attachments = draft.attachments ?? [];
+    this._notifySubscribers();
+    return true;
+  }
+
+  /**
+   * Inverse of `restoreDraft`: clears the composer while it still holds
+   * exactly the given draft. A draft the user has edited since is left
+   * untouched.
+   */
+  public retractDraft(draft: {
+    text: string;
+    quote?: QuoteInfo | undefined;
+    attachments?: readonly Attachment[] | undefined;
+  }): void {
+    const attachmentsUntouched =
+      draft.attachments !== undefined
+        ? this._attachments === draft.attachments
+        : this._attachments.length === 0;
+    if (
+      this._text !== draft.text ||
+      this._quote !== draft.quote ||
+      !attachmentsUntouched
+    )
+      return;
+
+    this._text = "";
+    this._rebaseDictation("");
+    this._quote = undefined;
+    this._attachments = [];
+    this._notifySubscribers();
+  }
+
+  // The generation check is what a reset and a later send use to invalidate a
+  // draft, so of several queued drafts only the most recent one is still
+  // restorable.
+  private _restoreUnsentDraft(
+    error: unknown,
+    generation: number,
+    draft: {
+      text: string;
+      quote: QuoteInfo | undefined;
+      attachments: readonly CompleteAttachment[];
+    },
+  ) {
+    if (!isMessageNotSentError(error)) return;
+    if (generation !== this._sendGeneration) return;
+    this.restoreDraft(draft);
+  }
+
   public cancel() {
     this.handleCancel();
   }
@@ -626,9 +720,8 @@ export abstract class BaseComposerRuntimeCore
 
     const session = this._dictationSession;
     const sessionId = this._activeDictationSessionId;
-    session.stop().finally(() => {
-      this._cleanupDictation({ sessionId });
-    });
+    const cleanup = () => this._cleanupDictation({ sessionId });
+    void session.stop().then(cleanup, cleanup);
   }
 
   private _cleanupDictation(options?: { sessionId: number | undefined }): void {

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

@@ -35,6 +35,7 @@ import type { AttachmentAdapter } from "../../adapters/attachment";
 import type { RealtimeVoiceAdapter } from "../../adapters/voice";
 import type { ThreadMessageLike } from "../utils/thread-message-like";
 import { notifyEventListeners } from "../../utils/notify-event-listeners";
+import { gateInteractableComposerMetadata } from "../../model-context/interactable-composer-metadata";
 
 type BaseThreadAdapters = {
   speech?: SpeechSynthesisAdapter | undefined;
@@ -68,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;
@@ -123,6 +125,41 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     return this._contextProvider.getModelContext();
   }
 
+  /**
+   * Stamps provider-contributed composer metadata onto an outgoing message.
+   * Called at dispatch rather than in the composer, so programmatic sends are
+   * covered too, and exactly once per message: a queued send is stamped when
+   * it leaves the lane, never when it enters.
+   *
+   * Only user messages are stamped, matching the readers: both the version
+   * fold and the model injection skip every other role.
+   *
+   * @param anchorId Message the gated branch prefix ends at. A queued send
+   * passes the current tail, having waited through a run that grew the prefix
+   * past the parent it was created with.
+   */
+  protected enrichAppendMetadata(
+    message: AppendMessage,
+    anchorId: string | null = message.parentId,
+  ): AppendMessage {
+    if (message.role !== "user") return message;
+    const messages = this.messages;
+    const parentIndex =
+      anchorId === null ? -1 : messages.findIndex((m) => m.id === anchorId);
+    const composerMetadata = gateInteractableComposerMetadata(
+      this.getModelContext().unstable_composerMetadata,
+      messages.slice(0, parentIndex + 1),
+    );
+    if (!composerMetadata) return message;
+    return {
+      ...message,
+      metadata: {
+        ...message.metadata,
+        custom: { ...message.metadata?.custom, ...composerMetadata },
+      },
+    };
+  }
+
   private _editComposers = new Map<string, DefaultEditComposerRuntimeCore>();
   public getEditComposer(messageId: string) {
     return this._editComposers.get(messageId);
@@ -319,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",
+        );
       }),
     );
 
@@ -418,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-edit-composer-runtime-core.ts

@@ -7,7 +7,6 @@ import type { DictationAdapter } from "../../adapters/speech";
 import type { SendOptions } from "../interfaces/composer-runtime-core";
 import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
 import { BaseComposerRuntimeCore } from "./base-composer-runtime-core";
-import { gateInteractableComposerMetadata } from "../../model-context/interactable-composer-metadata";
 
 export class DefaultEditComposerRuntimeCore extends BaseComposerRuntimeCore {
   public get canCancel() {
@@ -97,21 +96,8 @@ export class DefaultEditComposerRuntimeCore extends BaseComposerRuntimeCore {
             ...this._nonTextPassthrough,
           ] as AppendMessage["content"])
         : message.content;
-    // Gate live state against the new branch's prefix (messages up to the
-    // parent): an unchanged interactable re-stamps the prior baseline, an
-    // interactable edited since the original message stamps its newest state.
-    const messages = this.runtime.messages;
-    const parentIndex =
-      this._parentId === null
-        ? -1
-        : messages.findIndex((m) => m.id === this._parentId);
-    const composerMetadata = gateInteractableComposerMetadata(
-      this.runtime.getModelContext().unstable_composerMetadata,
-      messages.slice(0, parentIndex + 1),
-    );
-    const enriched = this.enrichWithComposerMetadata(message, composerMetadata);
     const appendTask = this.runtime.append({
-      ...enriched,
+      ...message,
       content,
       parentId: this._parentId,
       sourceId: this._sourceId,

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

@@ -6,21 +6,26 @@ 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,
   type QueueItemState,
 } from "../../store/scopes/queue-item";
 import { BaseComposerRuntimeCore } from "./base-composer-runtime-core";
-import { gateInteractableComposerMetadata } from "../../model-context/interactable-composer-metadata";
+
+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() {
@@ -95,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) {
@@ -119,17 +126,8 @@ export class DefaultThreadComposerRuntimeCore
     message: Omit<AppendMessage, "parentId" | "sourceId">,
     options?: SendOptions,
   ) {
-    // Merge provider-contributed metadata onto the outgoing user message
-    // (same metadata.custom append path quotes ride). The interactables gate
-    // runs here because it needs thread history, unavailable to the provider.
-    const composerMetadata = gateInteractableComposerMetadata(
-      this.runtime.getModelContext().unstable_composerMetadata,
-      this.runtime.messages,
-    );
-    const enriched = this.enrichWithComposerMetadata(message, composerMetadata);
-
     return this.runtime.append({
-      ...(enriched as AppendMessage),
+      ...(message as AppendMessage),
       parentId: this.runtime.messages.at(-1)?.id ?? null,
       sourceId: null,
       startRun: options?.startRun,

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/external-thread-queue-adapter.ts

@@ -27,4 +27,21 @@ export type ExternalThreadQueueAdapter = {
   move: (queueItemId: string, placement: QueuePlacement) => void;
   edit: (queueItemId: string, message: AppendMessage) => void;
   remove: (queueItemId: string) => void;
+  /**
+   * Installed by the owning runtime, applied to a message as it leaves a lane.
+   * A message can wait through an entire run, so state the runtime attaches at
+   * send time is recomputed against the thread it actually lands on. Adapters
+   * from `createMessageQueue` provide this; a hand-rolled adapter that omits
+   * it dispatches whatever was enqueued.
+   */
+  __internal_setDispatchTransform?:
+    | ((transform: (message: AppendMessage) => AppendMessage) => void)
+    | undefined;
+  /**
+   * Called by the owning runtime when the user cancels the run, before the run
+   * is aborted. Pauses the queue so the cancelled run's settle keeps the
+   * pending items instead of dispatching the next one; the next send re-arms
+   * draining. A hand-rolled adapter that omits it drains on cancel.
+   */
+  __internal_notifyCancelled?: (() => void) | undefined;
 };

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,
@@ -79,13 +80,15 @@ export const createMessageQueue = (
 
   let running = false;
   let paused = false;
+  let dispatchTransform: (message: AppendMessage) => AppendMessage = (m) => m;
   // swallow the cancelled run's settle when steering so it does not double-advance
   let suppressIdle = 0;
   // settles from cancelled runs that must drop `running` without advancing
   let cancelSettles = 0;
+  let interrupting = false;
 
   const notify = () => {
-    for (const callback of subscribers) callback();
+    notifyEventListeners(subscribers, undefined, "Message queue");
   };
 
   const setLanes = (next: Record<Lane, readonly QueueItemState[]>) => {
@@ -117,7 +120,7 @@ export const createMessageQueue = (
     setLanes({ ...lanes, [lane]: lanes[lane].slice(1) });
     if (!message) return;
     running = true;
-    driver.run(message, { steer: false });
+    driver.run(dispatchTransform(message), { steer: false });
   };
 
   const interrupt = (message: AppendMessage) => {
@@ -126,9 +129,17 @@ export const createMessageQueue = (
     // already cancel-notified
     suppressIdle += Math.max(cancelSettles, 1);
     cancelSettles = 0;
-    driver.cancel!();
+    // a driver whose cancel routes through the runtime notifies this queue
+    // back; the interrupt already accounted for that settle and is dispatching
+    // in its place
+    interrupting = true;
+    try {
+      driver.cancel!();
+    } finally {
+      interrupting = false;
+    }
     running = true;
-    driver.run(message, { steer: true });
+    driver.run(dispatchTransform(message), { steer: true });
   };
 
   const push = (lane: Lane, message: AppendMessage) => {
@@ -241,6 +252,14 @@ export const createMessageQueue = (
     });
   };
 
+  const notifyCancelled = () => {
+    if (interrupting) return;
+    if (running && cancelSettles === 0) {
+      paused = true;
+      cancelSettles = 1;
+    }
+  };
+
   const adapter: ExternalThreadQueueAdapter = {
     items: lanes.queue,
     steerItems: lanes.steer,
@@ -249,6 +268,10 @@ export const createMessageQueue = (
     move,
     edit,
     remove,
+    __internal_setDispatchTransform: (transform) => {
+      dispatchTransform = transform;
+    },
+    __internal_notifyCancelled: notifyCancelled,
   };
 
   return {
@@ -270,12 +293,7 @@ export const createMessageQueue = (
       running = false;
       advance();
     },
-    notifyCancelled: () => {
-      if (running && cancelSettles === 0) {
-        paused = true;
-        cancelSettles = 1;
-      }
-    },
+    notifyCancelled,
     clear: () => {
       messages.clear();
       setLanes({ queue: EMPTY_QUEUE_ITEMS, steer: EMPTY_QUEUE_ITEMS });