@assistant-ui/core 0.3.12 → 0.3.14

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

@@ -8,6 +8,8 @@ import type {
 import type { AppendMessage } from "../../types/message";
 import type { LocalRuntimeOptionsBase } from "./local-runtime-options";
 import type { ExportedMessageRepositoryItem } from "../../runtime/utils/message-repository";
+import type { ThreadSuggestion } from "../../runtime/interfaces/thread-runtime-core";
+import { isMessageNotSentError } from "../../types/error";
 
 const flush = () => new Promise((resolve) => setTimeout(resolve, 10));
 
@@ -143,6 +145,180 @@ describe("LocalThreadRuntimeCore events", () => {
   });
 });
 
+describe("LocalThreadRuntimeCore history persistence", () => {
+  it("surfaces failed user persistence without abandoning the run", async () => {
+    const persistenceError = new Error("history unavailable");
+    const run = vi.fn(async () => ({
+      content: [{ type: "text" as const, text: "done" }],
+    }));
+    const append = vi.fn(async (item: ExportedMessageRepositoryItem) => {
+      if (item.message.role === "user") throw persistenceError;
+    });
+    const thread = createThread(
+      { run },
+      {
+        history: {
+          async load() {
+            return { messages: [] };
+          },
+          append,
+        },
+      },
+    );
+
+    await expect(thread.append(userMessage("hello"))).rejects.toBe(
+      persistenceError,
+    );
+
+    expect(append).toHaveBeenCalledTimes(2);
+    expect(run).toHaveBeenCalledOnce();
+  });
+
+  it("surfaces failed persistence for messages that do not start a run", async () => {
+    const persistenceError = new Error("history unavailable");
+    const run = vi.fn();
+    const thread = createThread(
+      { run },
+      {
+        history: {
+          async load() {
+            return { messages: [] };
+          },
+          async append() {
+            throw persistenceError;
+          },
+        },
+      },
+    );
+
+    await expect(
+      thread.append({ ...userMessage("hello"), startRun: false }),
+    ).rejects.toBe(persistenceError);
+
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it("handles failed persistence before notifying no-run subscribers", async () => {
+    const persistenceError = new Error("history unavailable");
+    const listenerError = new Error("listener unavailable");
+    const thread = createThread(
+      { run: vi.fn() },
+      {
+        history: {
+          async load() {
+            return { messages: [] };
+          },
+          async append() {
+            throw persistenceError;
+          },
+        },
+      },
+    );
+    thread.subscribe(() => {
+      throw listenerError;
+    });
+
+    await expect(
+      thread.append({ ...userMessage("hello"), startRun: false }),
+    ).rejects.toBe(listenerError);
+    await flush();
+  });
+});
+
+describe("LocalThreadRuntimeCore - detach", () => {
+  it("drops a pending append when detached", async () => {
+    let resolveInitialization!: () => void;
+    const initialization = new Promise<void>((resolve) => {
+      resolveInitialization = resolve;
+    });
+    const run = vi.fn(async () => ({
+      content: [{ type: "text" as const, text: "done" }],
+    }));
+    const thread = createThread({ run });
+    thread.__internal_setGetInitializePromise(() => initialization);
+
+    const appendPromise = thread.append(userMessage("hello"));
+    await Promise.resolve();
+    thread.detach();
+    resolveInitialization();
+
+    await appendPromise;
+    expect(run).not.toHaveBeenCalled();
+    expect(thread.messages).toEqual([]);
+  });
+});
+
+describe("LocalThreadRuntimeCore optimistic append", () => {
+  it("paints the appended message before initialization resolves", async () => {
+    let resolveInitialization!: () => void;
+    const initialization = new Promise<void>((resolve) => {
+      resolveInitialization = resolve;
+    });
+    const run = vi.fn(async () => ({
+      content: [{ type: "text" as const, text: "done" }],
+    }));
+    const thread = createThread({ run });
+    thread.__internal_setGetInitializePromise(() => initialization);
+    const onUpdate = vi.fn();
+    thread.subscribe(onUpdate);
+
+    const appendPromise = thread.append(userMessage("hello"));
+    await Promise.resolve();
+
+    expect(thread.messages).toHaveLength(1);
+    expect(thread.messages[0]?.role).toBe("user");
+    expect(onUpdate).toHaveBeenCalled();
+    expect(run).not.toHaveBeenCalled();
+
+    resolveInitialization();
+    await appendPromise;
+    expect(run).toHaveBeenCalledTimes(1);
+  });
+
+  it("silently drops a detached append even when initialization rejects", async () => {
+    let rejectInitialization!: (error: unknown) => void;
+    const initialization = new Promise<void>((_, reject) => {
+      rejectInitialization = reject;
+    });
+    const run = vi.fn(async () => ({
+      content: [{ type: "text" as const, text: "done" }],
+    }));
+    const thread = createThread({ run });
+    thread.__internal_setGetInitializePromise(() => initialization);
+
+    const appendPromise = thread.append(userMessage("hello"));
+    await Promise.resolve();
+    thread.detach();
+    rejectInitialization(new Error("initialization failed"));
+
+    await expect(appendPromise).resolves.toBeUndefined();
+    expect(thread.messages).toEqual([]);
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it("rolls the optimistic message back when initialization rejects", async () => {
+    const initializationError = new Error("initialization failed");
+    const run = vi.fn(async () => ({
+      content: [{ type: "text" as const, text: "done" }],
+    }));
+    const thread = createThread({ run });
+    thread.__internal_setGetInitializePromise(() =>
+      Promise.reject(initializationError),
+    );
+
+    const error = await thread.append(userMessage("hello")).then(
+      () => {
+        throw new Error("expected the append to reject");
+      },
+      (e: unknown) => e,
+    );
+    expect(isMessageNotSentError(error)).toBe(true);
+    expect((error as Error).cause).toBe(initializationError);
+    expect(thread.messages).toEqual([]);
+    expect(run).not.toHaveBeenCalled();
+  });
+});
+
 describe("LocalThreadRuntimeCore human-in-the-loop tools", () => {
   it("pauses on requires-action while a listed tool call has no result", async () => {
     const { thread, runs } = createApprovalThread(toolCallResult("send_email"));
@@ -603,6 +779,48 @@ describe("LocalThreadRuntimeCore cancellation", () => {
 });
 
 describe("LocalThreadRuntimeCore suggestions", () => {
+  it("ignores suggestion generation from a superseded run", async () => {
+    let releaseFirst!: () => void;
+    let releaseSecond!: () => void;
+    const firstGate = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    const secondGate = new Promise<void>((resolve) => {
+      releaseSecond = resolve;
+    });
+    let runCount = 0;
+    const generate = vi.fn().mockResolvedValue([{ prompt: "follow up" }]);
+    const thread = createThread(
+      {
+        async run() {
+          runCount += 1;
+          await (runCount === 1 ? firstGate : secondGate);
+          return { content: [{ type: "text", text: "done" }] };
+        },
+      },
+      { suggestion: { generate } },
+    );
+
+    const firstAppend = thread.append(userMessage("first"));
+    await flush();
+    const secondAppend = thread.append(userMessage("second"));
+    await flush();
+
+    releaseFirst();
+    await firstAppend;
+    await flush();
+
+    expect(generate).not.toHaveBeenCalled();
+    expect(thread.suggestions).toEqual([]);
+
+    releaseSecond();
+    await secondAppend;
+    await flush();
+
+    expect(generate).toHaveBeenCalledOnce();
+    expect(thread.suggestions).toEqual([{ prompt: "follow up" }]);
+  });
+
   it("cancelRun aborts pending suggestion generation", async () => {
     const generate = vi.fn().mockImplementation(
       ({ signal }: { signal?: AbortSignal }) =>
@@ -656,8 +874,8 @@ describe("LocalThreadRuntimeCore suggestions", () => {
   });
 
   it("resolves append before suggestion generation completes", async () => {
-    let resolveSuggestions!: (value: readonly { prompt: string }[]) => void;
-    const suggestionsDeferred = new Promise<readonly { prompt: string }[]>(
+    let resolveSuggestions!: (value: readonly ThreadSuggestion[]) => void;
+    const suggestionsDeferred = new Promise<readonly ThreadSuggestion[]>(
       (resolve) => {
         resolveSuggestions = resolve;
       },
@@ -681,9 +899,15 @@ describe("LocalThreadRuntimeCore suggestions", () => {
     expect(generate).toHaveBeenCalledTimes(1);
     expect(thread.suggestions).toEqual([]);
 
-    resolveSuggestions([{ prompt: "follow up" }]);
+    resolveSuggestions([
+      { title: "Weather", label: "in SF", prompt: "What's the weather?" },
+      { prompt: "follow up" },
+    ]);
     await new Promise((r) => setTimeout(r, 0));
-    expect(thread.suggestions).toEqual([{ prompt: "follow up" }]);
+    expect(thread.suggestions).toEqual([
+      { title: "Weather", label: "in SF", prompt: "What's the weather?" },
+      { prompt: "follow up" },
+    ]);
   });
 });
 
@@ -1313,4 +1537,149 @@ describe("LocalThreadRuntimeCore runs", () => {
     expect(thread.capabilities.attachments).toBe(false);
     expect(thread.capabilities.feedback).toBe(false);
   });
+
+  it("loads history when the adapter arrives after the first load", async () => {
+    const adapter: ChatModelAdapter = {
+      run: async () => ({ content: [] }),
+    };
+    const thread = createPlainThread(adapter);
+    const load = vi.fn(async () => ({
+      headId: "restored",
+      messages: [
+        {
+          parentId: null,
+          message: {
+            id: "restored",
+            role: "user" as const,
+            content: [{ type: "text" as const, text: "hello" }],
+            createdAt: new Date(0),
+            metadata: { custom: {} },
+          },
+        },
+      ],
+    }));
+
+    thread.__internal_load();
+    expect(load).not.toHaveBeenCalled();
+    expect(thread.messages).toHaveLength(0);
+
+    thread.__internal_setOptions({
+      adapters: {
+        chatModel: adapter,
+        history: { load, append: async () => {} },
+      },
+    });
+    await flush();
+
+    expect(load).toHaveBeenCalledOnce();
+    expect(thread.messages.map((message) => message.id)).toEqual(["restored"]);
+  });
+
+  it("does not load late history over a thread that already has messages", async () => {
+    const adapter: ChatModelAdapter = {
+      run: async () => ({ content: [] }),
+    };
+    const thread = createPlainThread(adapter);
+    const load = vi.fn(async () => ({
+      headId: "restored",
+      messages: [
+        {
+          parentId: null,
+          message: {
+            id: "restored",
+            role: "user" as const,
+            content: [{ type: "text" as const, text: "hello" }],
+            createdAt: new Date(0),
+            metadata: { custom: {} },
+          },
+        },
+      ],
+    }));
+
+    thread.__internal_load();
+    await thread.append({ ...userMessage("typed"), startRun: false });
+    expect(thread.messages).toHaveLength(1);
+
+    thread.__internal_setOptions({
+      adapters: {
+        chatModel: adapter,
+        history: { load, append: async () => {} },
+      },
+    });
+    await flush();
+
+    expect(load).not.toHaveBeenCalled();
+    expect(thread.messages.map((message) => message.content)).toEqual([
+      [{ type: "text", text: "typed" }],
+    ]);
+  });
+
+  it("logs a rejected late history load", async () => {
+    const adapter: ChatModelAdapter = {
+      run: async () => ({ content: [] }),
+    };
+    const thread = createPlainThread(adapter);
+    const error = new Error("history unavailable");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    thread.__internal_load();
+    thread.__internal_setOptions({
+      adapters: {
+        chatModel: adapter,
+        history: {
+          load: async () => {
+            throw error;
+          },
+          append: async () => {},
+        },
+      },
+    });
+    await flush();
+
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] local thread history load failed:",
+      error,
+    );
+  });
+});
+
+describe("LocalRuntimeCore composer.canCancel", () => {
+  it("is true after append when the thread was created with initial messages", async () => {
+    const core = new LocalRuntimeCore(
+      {
+        adapters: {
+          chatModel: {
+            async *run({ abortSignal }) {
+              await new Promise<void>((resolve) => {
+                if (abortSignal.aborted) {
+                  resolve();
+                  return;
+                }
+                abortSignal.addEventListener("abort", () => resolve(), {
+                  once: true,
+                });
+              });
+            },
+          },
+        },
+      },
+      [
+        {
+          role: "assistant",
+          content: [{ type: "text", text: "Hello" }],
+          status: { type: "complete", reason: "stop" },
+        },
+      ],
+    );
+    const thread = core.threads.getMainThreadRuntimeCore();
+    expect(thread.composer.canCancel).toBe(false);
+
+    void thread.append(userMessage("Run"));
+    await flush();
+
+    expect(thread.composer.canCancel).toBe(true);
+    thread.cancelRun();
+  });
 });

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

@@ -22,7 +22,7 @@ import type {
   ThreadAssistantMessage,
 } from "../../types/message";
 import type { RunConfig } from "../../types/message";
-import { toAssistantError } from "../../types/error";
+import { MessageNotSentError, toAssistantError } from "../../types/error";
 import type { ModelContextProvider } from "../../model-context/types";
 import {
   createMessageQueue,
@@ -33,6 +33,11 @@ import {
   EMPTY_QUEUE_ITEMS,
   type QueueItemState,
 } from "../../store/scopes/queue-item";
+import {
+  captureThreadRuntimeGeneration,
+  invalidateThreadRuntime,
+  isThreadRuntimeGenerationCurrent,
+} from "../../runtime/utils/thread-runtime-lifecycle";
 
 class AbortError extends Error {
   override name = "AbortError";
@@ -162,6 +167,7 @@ export class LocalThreadRuntimeCore
   public __internal_setOptions(options: LocalRuntimeOptionsBase) {
     if (this._options === options) return;
 
+    const previousHistory = this._options?.adapters.history;
     this._options = options;
 
     let hasUpdates = false;
@@ -234,13 +240,31 @@ export class LocalThreadRuntimeCore
     }
 
     if (hasUpdates) this._notifySubscribers();
+
+    if (
+      this._loadRequested &&
+      !this._loadPromise &&
+      !previousHistory &&
+      options.adapters.history &&
+      this.messages.length === 0
+    ) {
+      void this.__internal_load().catch((error: unknown) => {
+        console.error(
+          "[assistant-ui] local thread history load failed:",
+          error,
+        );
+      });
+    }
   }
 
   private _loadPromise: Promise<void> | undefined;
+  private _loadRequested = false;
   public __internal_load() {
+    this._loadRequested = true;
     if (this._loadPromise) return this._loadPromise;
+    if (!this.adapters.history) return Promise.resolve();
 
-    const promise = this.adapters.history?.load() ?? Promise.resolve(null);
+    const promise = this.adapters.history.load();
 
     this._isLoading = true;
     this._notifySubscribers();
@@ -312,35 +336,72 @@ export class LocalThreadRuntimeCore
     this._queue?.adapter.remove(queueItemId);
   }
 
-  private async _runAppend(message: AppendMessage): Promise<void> {
-    this.ensureInitialized();
-
-    const initPromise = this._getInitializePromise?.();
-    if (initPromise) {
-      await initPromise;
+  private _rollbackAppend(messageId: string) {
+    try {
+      this.repository.deleteMessage(messageId);
+    } catch {
+      return;
     }
+    this._notifySubscribers();
+  }
+
+  private async _runAppend(rawMessage: AppendMessage): Promise<void> {
+    // Stamped here rather than in `append` so a queued message is gated after
+    // the flush re-pointed its parentId at the current tail.
+    const generation = captureThreadRuntimeGeneration(this);
+    const message = this.enrichAppendMetadata(rawMessage);
+    this.ensureInitialized();
 
     const newMessage = fromThreadMessageLike(message, generateId(), {
       type: "complete",
       reason: "unknown",
     });
     this.repository.addOrUpdateMessage(message.parentId, newMessage);
-    this._options.adapters.history?.append({
+    this._notifySubscribers();
+
+    // Initialization only gates the history write and the run; the message
+    // is already on screen. A failed barrier rolls the optimistic message
+    // back and rejects as an unsent message so the composer restores the
+    // draft; a thread invalidated mid-wait rolls back silently.
+    try {
+      const initPromise = this._getInitializePromise?.();
+      if (initPromise) {
+        await initPromise;
+      }
+    } catch (error) {
+      this._rollbackAppend(newMessage.id);
+      if (!isThreadRuntimeGenerationCurrent(this, generation)) return;
+      const notSent = new MessageNotSentError();
+      notSent.cause = error;
+      throw notSent;
+    }
+    if (!isThreadRuntimeGenerationCurrent(this, generation)) {
+      this._rollbackAppend(newMessage.id);
+      return;
+    }
+    const historyWrite = this._options.adapters.history?.append({
       parentId: message.parentId,
       message: newMessage,
       ...(message.runConfig !== undefined && { runConfig: message.runConfig }),
     });
+    void historyWrite?.catch(() => {});
 
     const startRun = message.startRun ?? message.role === "user";
     if (startRun) {
-      await this.startRun({
-        parentId: newMessage.id,
-        sourceId: message.sourceId,
-        runConfig: message.runConfig ?? {},
-      });
+      const [runResult, historyResult] = await Promise.allSettled([
+        this.startRun({
+          parentId: newMessage.id,
+          sourceId: message.sourceId,
+          runConfig: message.runConfig ?? {},
+        }),
+        historyWrite,
+      ]);
+      if (runResult.status === "rejected") throw runResult.reason;
+      if (historyResult.status === "rejected") throw historyResult.reason;
     } else {
       this.repository.resetHead(newMessage.id);
       this._notifySubscribers();
+      await historyWrite;
     }
   }
 
@@ -377,6 +438,10 @@ export class LocalThreadRuntimeCore
     throw new Error("Runtime does not support importing external states.");
   }
 
+  public unstable_notifySessionReset(): void {
+    throw new Error("Runtime does not support resetting sessions.");
+  }
+
   public async startRun(
     { parentId, runConfig }: StartRunConfig,
     runCallback?: ChatModelAdapter["run"],
@@ -421,6 +486,7 @@ export class LocalThreadRuntimeCore
     this._activeRun = run;
     this._runGeneration++;
 
+    let active = false;
     try {
       // mark busy for runs not started through the queue (regenerate, resume)
       this._queue?.notifyBusy();
@@ -444,7 +510,7 @@ export class LocalThreadRuntimeCore
       // the settle belongs to this run only while it is still the active run
       // or was cancelled (the engine expects a cancelled run's settle); a run
       // superseded by a newer one stays silent
-      const active = this._activeRun === run;
+      active = this._activeRun === run;
       if (active) this._activeRun = null;
       if (active || run.cancelled) {
         queueMicrotask(() => this._queue?.notifyIdle());
@@ -452,6 +518,7 @@ export class LocalThreadRuntimeCore
     }
 
     if (
+      active &&
       this.adapters.suggestion &&
       message.status?.type !== "requires-action"
     ) {
@@ -671,6 +738,7 @@ export class LocalThreadRuntimeCore
   }
 
   public detach() {
+    invalidateThreadRuntime(this);
     // drop the queue so pending items cannot dispatch on a detached thread
     this._queue = null;
     const error = new AbortError(true);

package/src/runtimes/readonly/ReadonlyThreadRuntimeCore.ts

@@ -112,6 +112,10 @@ export class ReadonlyThreadRuntimeCore
     throw READONLY_THREAD_ERROR;
   }
 
+  unstable_notifySessionReset(): void {
+    throw READONLY_THREAD_ERROR;
+  }
+
   composer = {
     attachments: [] as never[],
     attachmentAccept: "*",

package/src/runtimes/remote-thread-list/empty-thread-core.ts

@@ -91,6 +91,10 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     throw EMPTY_THREAD_ERROR;
   },
 
+  unstable_notifySessionReset() {
+    throw EMPTY_THREAD_ERROR;
+  },
+
   composer: {
     attachments: [],
     attachmentAccept: "*",

package/src/runtimes/remote-thread-list/types.ts

@@ -1,6 +1,9 @@
 import type { ThreadMessage } from "../../types/message";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import type { AssistantStream } from "assistant-stream";
+import type { ThreadHistoryAdapter } from "../../adapters/thread-history";
+import type { AttachmentAdapter } from "../../adapters/attachment";
+import type { ModelContextProvider } from "../../model-context/types";
 
 /* oxlint-disable typescript/no-explicit-any -- structural stand-in for ComponentType without depending on react types */
 type RemoteThreadListProviderProps = { children?: any };
@@ -33,6 +36,12 @@ export type RemoteThreadListPageOptions = {
   after?: string | undefined;
 };
 
+export type RuntimeAdapters = {
+  modelContext?: ModelContextProvider | undefined;
+  history?: ThreadHistoryAdapter | undefined;
+  attachments?: AttachmentAdapter | undefined;
+};
+
 export type RemoteThreadListAdapter = {
   list(params?: RemoteThreadListPageOptions): Promise<RemoteThreadListResponse>;
 
@@ -56,12 +65,33 @@ export type RemoteThreadListAdapter = {
    * inject per-thread context such as a history or attachments adapter (see
    * `useCloudThreadListAdapter` for the canonical shape).
    *
+   * `useRemoteThreadListRuntime` renders this component when present. If it
+   * is omitted, that host synthesizes a `RuntimeAdapterProvider` from
+   * `unstable_useAdapters`. The `RemoteThreadList` store entry ignores it;
+   * expose `unstable_useAdapters` for that host.
+   *
    * 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?: RemoteThreadListProviderComponent | undefined;
+
+  /**
+   * Hook the `RemoteThreadList` store entry calls once for the main-thread
+   * slot, then provides to the `thread` factory. This is not mounted per
+   * listed thread. `useRemoteThreadListRuntime` also calls it when
+   * `unstable_Provider` is omitted. Resolve `threadListItem` lazily on each
+   * adapter call; do not capture it at hook mount. The hook must keep a
+   * stable hook count across adapter swaps; a different count throws.
+   * Memoize the returned object.
+   *
+   * Per-thread history also requires the `thread` factory to be keyed by
+   * thread id (`withKey(id, thread(...))`). History loaders such as
+   * `useExternalHistory` run once per mount; an unkeyed factory keeps one
+   * instance across switches and the next thread's messages never load.
+   */
+  unstable_useAdapters?: (() => RuntimeAdapters | null | undefined) | undefined;
 };
 
 export type RemoteThreadListOptions = {