@assistant-ui/core 0.3.15 → 0.3.17

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

@@ -1,6 +1,8 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { RealtimeVoiceAdapter } from "../../adapters/voice";
+import type { ModelContextProvider } from "../../model-context/types";
 import type { AppendMessage } from "../../types/message";
+import { CompositeContextProvider } from "../../utils/composite-context-provider";
 import type {
   AddToolResultOptions,
   ResumeRunConfig,
@@ -45,8 +47,11 @@ const createVoiceAdapter = () => {
 class TestRuntime extends BaseThreadRuntimeCore {
   private readonly voiceAdapter: ReturnType<typeof createVoiceAdapter>;
 
-  constructor(voiceAdapter: ReturnType<typeof createVoiceAdapter>) {
-    super({ getModelContext: () => ({}) });
+  constructor(
+    voiceAdapter: ReturnType<typeof createVoiceAdapter>,
+    contextProvider: ModelContextProvider = { getModelContext: () => ({}) },
+  ) {
+    super(contextProvider);
     this.voiceAdapter = voiceAdapter;
   }
 
@@ -99,7 +104,7 @@ class TestRuntime extends BaseThreadRuntimeCore {
   resumeRun(_config: ResumeRunConfig) {}
   addToolResult(_options: AddToolResultOptions) {}
   resumeToolCall(_options: ResumeToolCallOptions) {}
-  respondToToolApproval(_options: RespondToToolApprovalOptions) {}
+  async respondToToolApproval(_options: RespondToToolApprovalOptions) {}
   cancelRun() {}
   exportExternalState() {
     return {};
@@ -112,6 +117,108 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
+describe("BaseThreadRuntimeCore subscriptions", () => {
+  it("notifies later subscribers when an earlier subscriber throws", () => {
+    const runtime = new TestRuntime(createVoiceAdapter());
+    const error = new Error("subscriber failed");
+    const laterSubscriber = vi.fn();
+
+    runtime.subscribe(() => {
+      throw error;
+    });
+    runtime.subscribe(laterSubscriber);
+
+    expect(() => runtime.reset()).toThrow(error);
+    expect(laterSubscriber).toHaveBeenCalledOnce();
+  });
+
+  it("isolates initialize listener errors during late replay", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const runtime = new TestRuntime(createVoiceAdapter());
+    runtime.reset();
+
+    const syncError = new Error("sync listener failed");
+    const asyncError = new Error("async listener failed");
+    runtime.unstable_on("initialize", () => {
+      throw syncError;
+    });
+    runtime.unstable_on("initialize", async () => {
+      throw asyncError;
+    });
+
+    await vi.waitFor(() => {
+      expect(consoleError).toHaveBeenCalledTimes(2);
+      expect(consoleError).toHaveBeenCalledWith(
+        '[assistant-ui] Thread runtime "initialize" listener threw an error',
+        syncError,
+      );
+      expect(consoleError).toHaveBeenCalledWith(
+        '[assistant-ui] Thread runtime "initialize" listener threw an error',
+        asyncError,
+      );
+    });
+  });
+
+  it("isolates modelContextUpdate listener errors during context updates", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const provider = new CompositeContextProvider();
+    const runtime = new TestRuntime(createVoiceAdapter(), provider);
+    const listenerError = new Error("model context listener failed");
+    const laterListener = vi.fn();
+
+    runtime.unstable_on("modelContextUpdate", () => {
+      throw listenerError;
+    });
+    runtime.unstable_on("modelContextUpdate", laterListener);
+
+    const unregister = provider.registerModelContextProvider({
+      getModelContext: () => ({}),
+    });
+
+    expect(laterListener).toHaveBeenCalledOnce();
+    expect(consoleError).toHaveBeenNthCalledWith(
+      1,
+      '[assistant-ui] Thread runtime "modelContextUpdate" listener threw an error',
+      listenerError,
+    );
+    expect(() => unregister()).not.toThrow();
+    expect(laterListener).toHaveBeenCalledTimes(2);
+    expect(consoleError).toHaveBeenNthCalledWith(
+      2,
+      '[assistant-ui] Thread runtime "modelContextUpdate" listener threw an error',
+      listenerError,
+    );
+  });
+
+  it("observes rejected modelContextUpdate listener promises", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const provider = new CompositeContextProvider();
+    const runtime = new TestRuntime(createVoiceAdapter(), provider);
+    const listenerError = new Error("async model context listener failed");
+
+    runtime.unstable_on("modelContextUpdate", async () => {
+      throw listenerError;
+    });
+
+    expect(() =>
+      provider.registerModelContextProvider({ getModelContext: () => ({}) }),
+    ).not.toThrow();
+
+    await vi.waitFor(() => {
+      expect(consoleError).toHaveBeenCalledWith(
+        '[assistant-ui] Thread runtime "modelContextUpdate" listener threw an error',
+        listenerError,
+      );
+    });
+  });
+});
+
 describe("BaseThreadRuntimeCore voice volume subscriptions", () => {
   it("continues notifying subscribers when one throws", () => {
     const consoleError = vi

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

@@ -36,6 +36,7 @@ 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";
+import { BaseSubscribable } from "../../subscribable/subscribable";
 
 type BaseThreadAdapters = {
   speech?: SpeechSynthesisAdapter | undefined;
@@ -44,11 +45,13 @@ type BaseThreadAdapters = {
   voice?: RealtimeVoiceAdapter | undefined;
 };
 
-export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
-  private _subscriptions = new Set<() => void>();
+export abstract class BaseThreadRuntimeCore
+  extends BaseSubscribable
+  implements ThreadRuntimeCore
+{
   private _isInitialized = false;
 
-  protected readonly repository = new MessageRepository();
+  protected repository = new MessageRepository();
   public abstract get adapters(): BaseThreadAdapters | undefined;
   public abstract get isDisabled(): boolean;
   public abstract get isSendDisabled(): boolean;
@@ -65,7 +68,7 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   public abstract resumeToolCall(options: ResumeToolCallOptions): void;
   public abstract respondToToolApproval(
     options: RespondToToolApprovalOptions,
-  ): void;
+  ): Promise<void>;
   public abstract cancelRun(): void;
   public abstract exportExternalState(): any;
   public abstract importExternalState(state: any): void;
@@ -118,6 +121,7 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   private readonly _contextProvider: ModelContextProvider;
 
   constructor(_contextProvider: ModelContextProvider) {
+    super();
     this._contextProvider = _contextProvider;
   }
 
@@ -213,10 +217,6 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     this._notifySubscribers();
   }
 
-  protected _notifySubscribers() {
-    for (const callback of this._subscriptions) callback();
-  }
-
   public _notifyEventSubscribers<E extends ThreadRuntimeEventType>(
     event: E,
     payload: ThreadRuntimeEventPayload[E],
@@ -227,11 +227,6 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     notifyEventListeners(subscribers, payload, `Thread runtime "${event}"`);
   }
 
-  public subscribe(callback: () => void): Unsubscribe {
-    this._subscriptions.add(callback);
-    return () => this._subscriptions.delete(callback);
-  }
-
   public submitFeedback({ messageId, type }: SubmitFeedbackOptions) {
     const adapter = this.adapters?.feedback;
     if (!adapter) throw new Error("Feedback adapter not configured");
@@ -523,7 +518,11 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     const wrapped = callback as (payload?: unknown) => void;
     if (event === "modelContextUpdate") {
       // provider.subscribe is `() => void`; pump the typed empty payload to the user callback.
-      return this._contextProvider.subscribe?.(() => wrapped({})) ?? (() => {});
+      return (
+        this._contextProvider.subscribe?.(() =>
+          notifyEventListeners([wrapped], {}, `Thread runtime "${event}"`),
+        ) ?? (() => {})
+      );
     }
 
     let subscribers = this._eventSubscribers.get(event);
@@ -537,7 +536,9 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     // after the thread already initialized, mirroring a BehaviorSubject.
     if (event === "initialize" && this._isInitialized) {
       queueMicrotask(() => {
-        if (subscribers.has(wrapped)) wrapped({});
+        if (subscribers.has(wrapped)) {
+          notifyEventListeners([wrapped], {}, `Thread runtime "${event}"`);
+        }
       });
     }
 

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

@@ -8,10 +8,7 @@ import type {
 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 { EMPTY_QUEUE_ITEMS, type QueueItemState } from "../queue/queue-item";
 import { BaseComposerRuntimeCore } from "./base-composer-runtime-core";
 
 const isCancelable = (runtime: Omit<ThreadRuntimeCore, "composer">) => {

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

@@ -4,7 +4,7 @@ import type { Attachment, CreateAttachment } from "../../types/attachment";
 import type { Unsubscribe } from "../../types/unsubscribe";
 import type { RunConfig } from "../../types/message";
 import type { DictationAdapter } from "../../adapters/speech";
-import type { QueueItemState } from "../../store/scopes/queue-item";
+import type { QueueItemState } from "../queue/queue-item";
 import type { QueuePlacement } from "../queue/external-thread-queue-adapter";
 
 export type AttachmentAddErrorReason =

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

@@ -1,5 +1,8 @@
 import type { Unsubscribe } from "../../types/unsubscribe";
-import type { ThreadRuntimeCore } from "./thread-runtime-core";
+import type {
+  ThreadRuntimeCore,
+  ThreadRuntimeEventType,
+} from "./thread-runtime-core";
 
 export type ThreadListItemStatus = "archived" | "regular" | "new" | "deleted";
 
@@ -16,6 +19,11 @@ export type ThreadListItemCoreState = {
   readonly runtime?: ThreadRuntimeCore | undefined;
 };
 
+export type ThreadListRuntimeEvent = {
+  readonly threadId: string;
+  readonly type: ThreadRuntimeEventType;
+};
+
 export type ThreadListRuntimeCore = {
   readonly isLoading: boolean;
   readonly isLoadingMore?: boolean;
@@ -41,6 +49,17 @@ export type ThreadListRuntimeCore = {
    */
   unstable_isThreadRunning?(threadId: string): boolean;
 
+  /**
+   * Lifecycle events from every thread this list keeps alive, including
+   * threads that are not the main one. Implemented by thread lists that keep
+   * runtimes alive for non-main threads. A thread list that mounts only the
+   * main thread leaves this undefined: its other threads have no runtime and so
+   * emit nothing, and the main thread's runtime is observed directly.
+   */
+  unstable_subscribeThreadEvents?(
+    callback: (event: ThreadListRuntimeEvent) => void,
+  ): Unsubscribe;
+
   getItemById(threadId: string): ThreadListItemCoreState | undefined;
 
   switchToThread(

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

@@ -16,7 +16,7 @@ import type {
   EditComposerRuntimeCore,
   ThreadComposerRuntimeCore,
 } from "./composer-runtime-core";
-import type { QueueItemState } from "../../store/scopes/queue-item";
+import type { QueueItemState } from "../queue/queue-item";
 import type { QueuePlacement } from "../queue/external-thread-queue-adapter";
 
 export type RuntimeCapabilities = {
@@ -63,6 +63,8 @@ export type RespondToToolApprovalOptions = {
   approved: boolean;
   /** The approval option that produced this decision, when the request carried options. */
   optionId?: string;
+  /** The free-form answer, when the request asked for one. */
+  text?: string;
   reason?: string;
 };
 
@@ -165,7 +167,21 @@ export type ThreadRuntimeCore = Readonly<{
 
   addToolResult: (options: AddToolResultOptions) => void;
   resumeToolCall: (options: ResumeToolCallOptions) => void;
-  respondToToolApproval: (options: RespondToToolApprovalOptions) => void;
+  /**
+   * Records a decision on a tool approval gate. Resolves once the runtime has
+   * accepted the response and rejects when it could not be recorded, so a
+   * caller can leave the gate retryable rather than spending it. A capability
+   * or state precondition still throws synchronously; a failure to record
+   * arrives as a rejection, including one an adapter raises synchronously.
+   *
+   * Acceptance is as far as the runtime can see the response: one that records
+   * the decision locally settles on the record, while one that answers by
+   * resuming a run settles on the resume. A failure of the work the decision
+   * unblocks is reported through the runtime's own error channel, not here.
+   */
+  respondToToolApproval: (
+    options: RespondToToolApprovalOptions,
+  ) => Promise<void>;
 
   speak: (messageId: string) => void;
   stopSpeaking: () => void;

package/src/runtime/internal.ts

@@ -56,3 +56,8 @@ export {
   MessageRepository,
 } from "./utils/message-repository";
 export type { ExportedMessageRepositoryItem } from "./utils/message-repository";
+export { createMessageRepositorySession } from "./utils/message-repository-session";
+export type {
+  MessageRepositorySession,
+  MessageRepositorySessionOptions,
+} from "./utils/message-repository-session";

package/src/runtime/queue/external-thread-queue-adapter.ts

@@ -1,5 +1,5 @@
 import type { AppendMessage } from "../../types/message";
-import type { QueueItemState } from "../../store/scopes/queue-item";
+import type { QueueItemState } from "./queue-item";
 
 export type QueuePlacement = {
   readonly lane?: "queue" | "steer";

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

@@ -3,10 +3,7 @@ import type {
   FileMessagePart,
   TextMessagePart,
 } from "../../types/message";
-import {
-  EMPTY_QUEUE_ITEMS,
-  type QueueItemState,
-} from "../../store/scopes/queue-item";
+import { EMPTY_QUEUE_ITEMS, type QueueItemState } from "./queue-item";
 import { generateId } from "../../utils/id";
 import { notifyEventListeners } from "../../utils/notify-event-listeners";
 import { getThreadMessageText } from "../../utils/text";

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

@@ -0,0 +1,10 @@
+import type { FileMessagePart, TextMessagePart } from "../../types/message";
+
+export type QueueItemState = {
+  readonly id: string;
+  /** @deprecated Derive from the text parts of `parts` instead. Removal after 2026-11-05. */
+  readonly prompt: string;
+  readonly parts: readonly (FileMessagePart | TextMessagePart)[];
+};
+
+export const EMPTY_QUEUE_ITEMS: readonly QueueItemState[] = Object.freeze([]);

package/src/runtime/utils/abortable-thread-load.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from "vitest";
+import { createAbortableThreadLoad } from "./abortable-thread-load";
+
+const callbacks = () => ({
+  onSettled: vi.fn(),
+  onInitialError: vi.fn(),
+});
+
+describe("createAbortableThreadLoad", () => {
+  it("defers a reload to an in-flight initial load", async () => {
+    let resolveInitial!: () => void;
+    const initialLoad = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveInitial = resolve;
+        }),
+    );
+    const reloadLoad = vi.fn(() => Promise.resolve());
+    const controller = createAbortableThreadLoad();
+
+    const initial = controller.run({
+      purpose: "initial",
+      load: initialLoad,
+      ...callbacks(),
+    });
+    const reload = controller.run({
+      purpose: "reload",
+      load: reloadLoad,
+      ...callbacks(),
+    });
+
+    expect(reloadLoad).not.toHaveBeenCalled();
+    resolveInitial();
+    await Promise.all([initial, reload]);
+  });
+
+  it("aborts a superseded load and swallows its failure", async () => {
+    let rejectFirst!: (error: Error) => void;
+    let firstSignal!: AbortSignal;
+    const controller = createAbortableThreadLoad();
+    const first = controller.run({
+      purpose: "reload",
+      load: (signal) => {
+        firstSignal = signal;
+        return new Promise<void>((_, reject) => {
+          rejectFirst = reject;
+        });
+      },
+      ...callbacks(),
+    });
+
+    const second = controller.run({
+      purpose: "initial",
+      load: () => Promise.resolve(),
+      ...callbacks(),
+    });
+    rejectFirst(new Error("aborted"));
+
+    expect(firstSignal.aborted).toBe(true);
+    await expect(first).resolves.toBeUndefined();
+    await second;
+  });
+
+  it("swallows initial failures and surfaces reload failures", async () => {
+    const controller = createAbortableThreadLoad();
+    const initialCallbacks = callbacks();
+    const initialError = new Error("initial");
+
+    await expect(
+      controller.run({
+        purpose: "initial",
+        load: () => Promise.reject(initialError),
+        ...initialCallbacks,
+      }),
+    ).resolves.toBeUndefined();
+    expect(initialCallbacks.onInitialError).toHaveBeenCalledWith(initialError);
+
+    const reloadError = new Error("reload");
+    await expect(
+      controller.run({
+        purpose: "reload",
+        load: () => Promise.reject(reloadError),
+        ...callbacks(),
+      }),
+    ).rejects.toBe(reloadError);
+  });
+});

package/src/runtime/utils/abortable-thread-load.ts

@@ -0,0 +1,53 @@
+export type AbortableThreadLoadPurpose = "initial" | "reload";
+
+type AbortableThreadLoadOptions = {
+  purpose?: AbortableThreadLoadPurpose;
+  load: (signal: AbortSignal) => Promise<void>;
+  onSettled: () => void;
+  onInitialError: (error: unknown) => void;
+};
+
+export const createAbortableThreadLoad = () => {
+  let current: {
+    controller: AbortController;
+    purpose: AbortableThreadLoadPurpose;
+    promise?: Promise<void>;
+  } | null = null;
+
+  return {
+    abort(purpose?: AbortableThreadLoadPurpose) {
+      if (purpose !== undefined && current?.purpose !== purpose) return;
+      current?.controller.abort();
+    },
+    run({
+      purpose = "initial",
+      load,
+      onSettled,
+      onInitialError,
+    }: AbortableThreadLoadOptions): Promise<void> {
+      if (purpose === "reload" && current?.purpose === "initial") {
+        return current.promise ?? Promise.resolve();
+      }
+
+      current?.controller.abort();
+      const controller = new AbortController();
+      const record: NonNullable<typeof current> = { controller, purpose };
+      current = record;
+
+      const task = load(controller.signal)
+        .catch((error: unknown) => {
+          if (controller.signal.aborted) return;
+          throw error;
+        })
+        .finally(() => {
+          if (current?.controller === controller) current = null;
+          if (controller.signal.aborted) return;
+          onSettled();
+        });
+      record.promise = task;
+
+      if (purpose === "reload") return task;
+      return task.catch(onInitialError);
+    },
+  };
+};

package/src/runtime/utils/attachment-add-operations.ts

@@ -0,0 +1,59 @@
+export type AttachmentAddOperation = {
+  cancelled: boolean;
+  attachmentIds: Set<string>;
+};
+
+export class AttachmentAddOperations {
+  private readonly operations = new Set<AttachmentAddOperation>();
+
+  start() {
+    const operation: AttachmentAddOperation = {
+      cancelled: false,
+      attachmentIds: new Set(),
+    };
+    this.operations.add(operation);
+    return operation;
+  }
+
+  accept(operation: AttachmentAddOperation, attachmentId: string) {
+    if (operation.cancelled) return false;
+    operation.attachmentIds.add(attachmentId);
+    return true;
+  }
+
+  finish(operation: AttachmentAddOperation) {
+    this.operations.delete(operation);
+  }
+
+  isCancelled(operation: AttachmentAddOperation) {
+    return operation.cancelled;
+  }
+
+  cancel(attachmentId: string) {
+    for (const operation of [...this.operations]) {
+      if (!operation.attachmentIds.has(attachmentId)) continue;
+      operation.cancelled = true;
+      this.operations.delete(operation);
+    }
+  }
+
+  cancelAll() {
+    for (const operation of this.operations) {
+      operation.cancelled = true;
+    }
+    this.operations.clear();
+  }
+}
+
+export const drainAttachmentAdd = async <T>(
+  result: Promise<T> | AsyncIterable<T>,
+  accept: (attachment: T) => boolean,
+) => {
+  if (Symbol.asyncIterator in result) {
+    for await (const attachment of result) {
+      if (!accept(attachment)) break;
+    }
+  } else {
+    accept(await result);
+  }
+};

package/src/runtime/utils/auto-status.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { getAutoStatus } from "./auto-status";
+
+describe("getAutoStatus", () => {
+  it("reports a cancelled message as incomplete", () => {
+    expect(
+      getAutoStatus(true, false, false, false, undefined, true),
+    ).toMatchObject({ type: "incomplete", reason: "cancelled" });
+  });
+
+  it("keeps a cancelled message incomplete once a later message arrives", () => {
+    expect(
+      getAutoStatus(false, false, false, false, undefined, true),
+    ).toMatchObject({ type: "incomplete", reason: "cancelled" });
+  });
+
+  it("reports an uncancelled message as complete", () => {
+    expect(
+      getAutoStatus(true, false, false, false, undefined, false),
+    ).toMatchObject({ type: "complete", reason: "unknown" });
+  });
+
+  it.each([
+    ["running", { type: "running" }, true, false, false, undefined],
+    [
+      "an interrupted tool call",
+      { type: "requires-action", reason: "interrupt" },
+      false,
+      true,
+      true,
+      undefined,
+    ],
+    [
+      "a pending tool call",
+      { type: "requires-action", reason: "tool-calls" },
+      false,
+      false,
+      true,
+      undefined,
+    ],
+    [
+      "an error",
+      { type: "incomplete", reason: "error", error: "boom" },
+      false,
+      false,
+      false,
+      "boom",
+    ],
+  ])(
+    "keeps %s ahead of cancellation",
+    (_label, expected, isRunning, interrupted, pending, error) => {
+      expect(
+        getAutoStatus(true, isRunning, interrupted, pending, error, true),
+      ).toMatchObject(expected);
+    },
+  );
+});