@assistant-ui/core 0.3.13 → 0.3.15

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,
+              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,
+                  }),
                 }),
-                ...(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,21 +652,30 @@ 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.");
 
+    const generation = captureThreadRuntimeGeneration(this);
+
     // Abort any in-flight client-side tool executions. Fire-and-forget —
     // the abort resolves once executions settle, but we don't gate the
     // cancel on it.
@@ -625,7 +686,7 @@ export class ExternalStoreThreadRuntimeCore
     // stopped.
     this._store.queue?.__internal_notifyCancelled?.();
 
-    this._store.onCancel();
+    observeAdapterCallback("onCancel", this._store.onCancel());
 
     this.dropEmptyOptimisticHead();
 
@@ -672,6 +733,8 @@ export class ExternalStoreThreadRuntimeCore
     // tick. Read the repository at flush time and re-apply the rollbacks to
     // it, instead of stamping a snapshot captured above over the newer state.
     setTimeout(() => {
+      if (!isThreadRuntimeGenerationCurrent(this, generation)) return;
+
       this.dropEmptyOptimisticHead();
       if (movedLeaf) {
         const current = this.repository.getMessages();
@@ -700,7 +763,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 +792,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[]) {

package/src/runtimes/inert/InertThreadRuntimeCore.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, it } from "vitest";
+import { BaseSubscribable } from "../../subscribable/subscribable";
+import { ReadonlyThreadRuntimeCore } from "../readonly/ReadonlyThreadRuntimeCore";
+import { EMPTY_THREAD_CORE } from "../remote-thread-list/empty-thread-core";
+
+const READONLY_ERROR = /readonly thread/;
+const EMPTY_ERROR = /empty thread/;
+
+const SHARED_THROWING_METHODS = [
+  "switchToBranch",
+  "append",
+  "deleteMessage",
+  "startRun",
+  "resumeRun",
+  "unstable_notifySessionReset",
+  "addToolResult",
+  "resumeToolCall",
+  "respondToToolApproval",
+  "speak",
+  "connectVoice",
+  "muteVoice",
+  "unmuteVoice",
+  "submitFeedback",
+  "exportExternalState",
+  "importExternalState",
+  "beginEdit",
+  "import",
+  "reset",
+] as const;
+
+const SHARED_THROWING_COMPOSER_METHODS = [
+  "setText",
+  "setRole",
+  "setRunConfig",
+  "send",
+  "startDictation",
+  "setQuote",
+] as const;
+
+const SHARED_NOOP_COMPOSER_METHODS = [
+  "cancel",
+  "stopDictation",
+  "moveQueueItem",
+  "removeQueueItem",
+] as const;
+
+type AnyCore = Record<string, any>;
+
+const cores = [
+  [
+    "ReadonlyThreadRuntimeCore",
+    () => new ReadonlyThreadRuntimeCore() as unknown as AnyCore,
+    READONLY_ERROR,
+  ],
+  [
+    "EMPTY_THREAD_CORE",
+    () => EMPTY_THREAD_CORE as unknown as AnyCore,
+    EMPTY_ERROR,
+  ],
+] as const;
+
+describe.each(cores)("%s shared inert surface", (_name, makeCore, error) => {
+  it.each(SHARED_THROWING_METHODS)("%s throws the core's error", (method) => {
+    expect(() => makeCore()[method]!()).toThrow(error);
+  });
+
+  it.each(SHARED_THROWING_COMPOSER_METHODS)(
+    "composer.%s throws the core's error",
+    (method) => {
+      expect(() => makeCore().composer[method]!()).toThrow(error);
+    },
+  );
+
+  it.each(["addAttachment", "removeAttachment"] as const)(
+    "composer.%s rejects with the core's error",
+    async (method) => {
+      await expect(makeCore().composer[method]!()).rejects.toThrow(error);
+    },
+  );
+
+  it.each(SHARED_NOOP_COMPOSER_METHODS)("composer.%s is a no-op", (method) => {
+    expect(() => makeCore().composer[method]!()).not.toThrow();
+  });
+
+  it("composer.reset and composer.clearAttachments resolve without throwing", async () => {
+    const core = makeCore();
+    await expect(core.composer.reset()).resolves.toBeUndefined();
+    await expect(core.composer.clearAttachments()).resolves.toBeUndefined();
+  });
+
+  it("reports every capability as disabled", () => {
+    expect(makeCore().capabilities).toEqual({
+      switchToBranch: false,
+      switchBranchDuringRun: false,
+      edit: false,
+      delete: false,
+      reload: false,
+      refetchThread: false,
+      cancel: false,
+      unstable_copy: false,
+      speech: false,
+      dictation: false,
+      voice: false,
+      attachments: false,
+      feedback: false,
+      queue: false,
+    });
+  });
+
+  it("exposes inert read-only state", () => {
+    const core = makeCore();
+    expect(core.getModelContext()).toEqual({});
+    expect(core.getEditComposer()).toBeUndefined();
+    expect(core.getVoiceVolume()).toBe(0);
+    expect(core.speech).toBeUndefined();
+    expect(core.voice).toBeUndefined();
+    expect(core.state).toBeNull();
+    expect(core.suggestions).toEqual([]);
+    expect(core.extras).toBeUndefined();
+    expect(core.isDisabled).toBe(false);
+    expect(core.isSendDisabled).toBe(false);
+  });
+
+  it("exposes an empty composer that accepts everything and holds nothing", () => {
+    const composer = makeCore().composer;
+    expect(composer.attachmentAccept).toBe("*");
+    expect(composer.attachments).toEqual([]);
+    expect(composer.text).toBe("");
+    expect(composer.role).toBe("user");
+    expect(composer.runConfig).toEqual({});
+    expect(composer.queue).toEqual([]);
+    expect(composer.dictation).toBeUndefined();
+    expect(composer.quote).toBeUndefined();
+    expect(composer.isEmpty).toBe(true);
+    expect(composer.canSend).toBe(false);
+    expect(composer.canCancel).toBe(false);
+  });
+
+  it("throws one stable error object from every mutator", () => {
+    const core = makeCore();
+    const thrown = SHARED_THROWING_METHODS.map((method) => {
+      try {
+        core[method]!();
+        return undefined;
+      } catch (e) {
+        return e;
+      }
+    });
+
+    expect(thrown[0]).toBeInstanceOf(Error);
+    expect(thrown.every((e) => e === thrown[0])).toBe(true);
+  });
+
+  it("throws a receiver TypeError when a mutator is detached", () => {
+    const detached = makeCore().append!;
+    expect(() => detached()).toThrow(TypeError);
+  });
+
+  it("subscribeVoiceVolume and unstable_on hand back no-op unsubscribers", () => {
+    const core = makeCore();
+    expect(() => core.subscribeVoiceVolume(() => {})()).not.toThrow();
+    expect(() => core.unstable_on("runStart", () => {})()).not.toThrow();
+  });
+});
+
+describe("no-op versus throw divergences", () => {
+  it.each(["cancelRun", "stopSpeaking", "disconnectVoice"] as const)(
+    "%s is a no-op on the readonly core but throws on the empty core",
+    (method) => {
+      const readonly = new ReadonlyThreadRuntimeCore() as unknown as AnyCore;
+      expect(() => readonly[method]!()).not.toThrow();
+      expect(() =>
+        (EMPTY_THREAD_CORE as unknown as AnyCore)[method]!(),
+      ).toThrow(EMPTY_ERROR);
+    },
+  );
+
+  it("readonly is not loading; empty is loading so it is not read as an empty conversation", () => {
+    expect(new ReadonlyThreadRuntimeCore().isLoading).toBe(false);
+    expect(EMPTY_THREAD_CORE.isLoading).toBe(true);
+  });
+
+  it("readonly composer is not editing; empty composer is", () => {
+    expect(new ReadonlyThreadRuntimeCore().composer.isEditing).toBe(false);
+    expect(EMPTY_THREAD_CORE.composer.isEditing).toBe(true);
+  });
+
+  it("the two cores carry distinct error objects and messages", () => {
+    const grab = (fn: () => void) => {
+      try {
+        fn();
+        return undefined;
+      } catch (e) {
+        return e as Error;
+      }
+    };
+
+    const readonlyError = grab(() => new ReadonlyThreadRuntimeCore().append());
+    const emptyError = grab(() =>
+      (EMPTY_THREAD_CORE as unknown as AnyCore).append!(),
+    );
+
+    expect(readonlyError).not.toBe(emptyError);
+    expect(readonlyError?.message).toBe(
+      "This is a readonly thread. You cannot perform mutations on readonly threads.",
+    );
+    expect(emptyError?.message).toMatch(/placeholder for the main thread/);
+  });
+});
+
+describe("readonly notifications", () => {
+  it("notifies subscribers and settles waitForUpdate when messages change", async () => {
+    const core = new ReadonlyThreadRuntimeCore();
+    const seen: number[] = [];
+    const unsubscribe = core.subscribe(() => {
+      seen.push(core.messages.length);
+    });
+    const update = core.waitForUpdate();
+
+    core.setMessages([
+      {
+        id: "m1",
+        role: "user",
+        content: [{ type: "text", text: "hi" }],
+        createdAt: new Date(0),
+        status: { type: "complete", reason: "stop" },
+        metadata: { custom: {} },
+      } as any,
+    ]);
+
+    await expect(update).resolves.toBeUndefined();
+    expect(seen).toEqual([1]);
+    unsubscribe();
+  });
+});
+
+describe("empty singleton", () => {
+  it("does not retain subscribe callbacks", () => {
+    const subscribers = (
+      EMPTY_THREAD_CORE as unknown as Record<string, unknown>
+    )._subscribers as Set<unknown>;
+    const before = subscribers.size;
+    const unsubscribe = EMPTY_THREAD_CORE.subscribe(() => undefined);
+    expect(subscribers.size).toBe(before);
+    expect(() => unsubscribe()).not.toThrow();
+  });
+
+  it("rejects waitForUpdate instead of hanging", async () => {
+    await expect(
+      (EMPTY_THREAD_CORE as unknown as BaseSubscribable).waitForUpdate(),
+    ).rejects.toThrow(EMPTY_ERROR);
+  });
+});

package/src/runtimes/inert/InertThreadRuntimeCore.ts

@@ -0,0 +1,232 @@
+import type { Unsubscribe } from "../../types/unsubscribe";
+import type { ThreadMessage } from "../../types/message";
+import type { ThreadRuntimeCore } from "../../runtime/interfaces/thread-runtime-core";
+import type { ExportedMessageRepository } from "../../runtime/utils/message-repository";
+import { BaseSubscribable } from "../../subscribable/subscribable";
+
+export const createInertComposer = <TIsEditing extends boolean>(
+  error: Error,
+  isEditing: TIsEditing,
+) => ({
+  attachments: [] as never[],
+  attachmentAccept: "*",
+
+  async addAttachment() {
+    throw error;
+  },
+
+  async removeAttachment() {
+    throw error;
+  },
+
+  isEditing,
+  canCancel: false,
+  canSend: false,
+  isEmpty: true,
+  text: "",
+
+  setText() {
+    throw error;
+  },
+
+  role: "user" as const,
+
+  setRole() {
+    throw error;
+  },
+
+  runConfig: {},
+
+  setRunConfig() {
+    throw error;
+  },
+
+  async reset() {},
+
+  async clearAttachments() {},
+
+  send() {
+    throw error;
+  },
+
+  cancel() {},
+
+  queue: [] as never[],
+  moveQueueItem() {},
+  removeQueueItem() {},
+
+  dictation: undefined,
+
+  startDictation() {
+    throw error;
+  },
+
+  stopDictation() {},
+
+  quote: undefined,
+
+  setQuote() {
+    throw error;
+  },
+
+  subscribe() {
+    return () => {};
+  },
+
+  unstable_on() {
+    return () => {};
+  },
+});
+
+export abstract class InertThreadRuntimeCore
+  extends BaseSubscribable
+  implements ThreadRuntimeCore
+{
+  protected abstract get error(): Error;
+
+  abstract readonly messages: readonly ThreadMessage[];
+  abstract readonly isLoading: boolean;
+  abstract readonly composer: ThreadRuntimeCore["composer"];
+
+  abstract getMessageById(messageId: string):
+    | {
+        parentId: string | null;
+        message: ThreadMessage;
+        index: number;
+      }
+    | undefined;
+
+  abstract getBranches(messageId: string): readonly string[];
+
+  abstract export(): ExportedMessageRepository;
+
+  switchToBranch(): void {
+    throw this.error;
+  }
+
+  append(): void {
+    throw this.error;
+  }
+
+  deleteMessage(): void {
+    throw this.error;
+  }
+
+  startRun(): void {
+    throw this.error;
+  }
+
+  resumeRun(): void {
+    throw this.error;
+  }
+
+  cancelRun(): void {
+    throw this.error;
+  }
+
+  unstable_notifySessionReset(): void {
+    throw this.error;
+  }
+
+  addToolResult(): void {
+    throw this.error;
+  }
+
+  resumeToolCall(): void {
+    throw this.error;
+  }
+
+  respondToToolApproval(): void {
+    throw this.error;
+  }
+
+  speak(): void {
+    throw this.error;
+  }
+
+  stopSpeaking(): void {
+    throw this.error;
+  }
+
+  connectVoice(): void {
+    throw this.error;
+  }
+
+  disconnectVoice(): void {
+    throw this.error;
+  }
+
+  muteVoice(): void {
+    throw this.error;
+  }
+
+  unmuteVoice(): void {
+    throw this.error;
+  }
+
+  submitFeedback(): void {
+    throw this.error;
+  }
+
+  exportExternalState(): void {
+    throw this.error;
+  }
+
+  importExternalState(): void {
+    throw this.error;
+  }
+
+  beginEdit(): void {
+    throw this.error;
+  }
+
+  import(): void {
+    throw this.error;
+  }
+
+  reset(): void {
+    throw this.error;
+  }
+
+  getModelContext() {
+    return {};
+  }
+
+  getEditComposer() {
+    return undefined;
+  }
+
+  getVoiceVolume = () => 0;
+  subscribeVoiceVolume = (): Unsubscribe => () => {};
+
+  speech = undefined;
+  voice = undefined;
+
+  capabilities = {
+    switchToBranch: false,
+    switchBranchDuringRun: false,
+    edit: false,
+    delete: false,
+    reload: false,
+    refetchThread: false,
+    cancel: false,
+    unstable_copy: false,
+    speech: false,
+    dictation: false,
+    voice: false,
+    attachments: false,
+    feedback: false,
+    queue: false,
+  } as const;
+
+  isDisabled = false;
+  isSendDisabled = false;
+
+  state = null;
+  suggestions = [] as never[];
+  extras = undefined;
+
+  unstable_on(): Unsubscribe {
+    return () => {};
+  }
+}