@assistant-ui/core 0.3.17 → 0.3.18

package/src/react/runtimes/cloud/createCloudThreadListAdapter.test.ts

@@ -5,6 +5,21 @@ import { renderHook } from "@testing-library/react";
 import type { AssistantCloud } from "assistant-cloud";
 import { createCloudThreadListAdapter } from "./createCloudThreadListAdapter";
 
+vi.mock("@assistant-ui/store", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@assistant-ui/store")>()),
+  useAui: () => ({
+    threads: {
+      getState: () => ({ mainThreadId: "local-1", threadItems: [] }),
+    },
+    thread: { getState: () => ({ isEmpty: true, suggestions: [] }) },
+    threadListItem: {
+      getState: () => ({ id: "local-1", remoteId: "remote-1" }),
+    },
+    on: () => () => {},
+    subscribe: () => () => {},
+  }),
+}));
+
 const makeCloud = () =>
   ({
     threads: {

package/src/react/runtimes/cloud/createCloudThreadListAdapter.ts

@@ -43,6 +43,7 @@ export const useCloudRuntimeAdapters = (
     () => ({
       history,
       attachments,
+      feedback: history.feedback,
     }),
     [history, attachments],
   );

package/src/react/runtimes/useExternalStoreRuntime.lifecycle.test.tsx

@@ -5,8 +5,49 @@ import { act, render } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+import type { ThreadMessage } from "../../types/message";
+import { RuntimeAdapterProvider } from "./RuntimeAdapterProvider";
+
+const userMessage: ThreadMessage = {
+  id: "user-1",
+  role: "user",
+  content: [{ type: "text", text: "hello" }],
+  attachments: [],
+  createdAt: new Date(0),
+  metadata: { custom: {} },
+};
 
 describe("useExternalStoreRuntime lifecycle", () => {
+  it("uses feedback supplied by the per-thread adapter context", () => {
+    const submit = vi.fn();
+    const capture: { runtime: AssistantRuntime | null } = { runtime: null };
+    const App = () => {
+      const runtime = useExternalStoreRuntime({
+        messages: [userMessage],
+        onNew: async () => {},
+      });
+      capture.runtime = runtime;
+      return null;
+    };
+
+    render(
+      <RuntimeAdapterProvider adapters={{ feedback: { submit } }}>
+        <App />
+      </RuntimeAdapterProvider>,
+    );
+
+    expect(capture.runtime!.thread.getState().capabilities.feedback).toBe(true);
+    act(() => {
+      capture
+        .runtime!.thread.getMessageById("user-1")
+        .submitFeedback({ type: "positive" });
+    });
+    expect(submit).toHaveBeenCalledWith({
+      message: expect.objectContaining({ id: "user-1" }),
+      type: "positive",
+    });
+  });
+
   it("keeps dispatching appends after StrictMode's simulated remount", async () => {
     const onNew = vi.fn(async () => {});
     const capture: { runtime: AssistantRuntime | null } = { runtime: null };

package/src/react/runtimes/useExternalStoreRuntime.ts

@@ -11,7 +11,15 @@ import { useRuntimeAdapters } from "./RuntimeAdapterProvider";
 export const useExternalStoreRuntime = <T>(
   store: ExternalStoreAdapter<T>,
 ): AssistantRuntime => {
-  const [runtime] = useState(() => new ExternalStoreRuntimeCore(store));
+  const { modelContext, feedback } = useRuntimeAdapters() ?? {};
+  const adaptedStore = useMemo(() => {
+    if (!feedback || store.adapters?.feedback) return store;
+    return {
+      ...store,
+      adapters: { ...store.adapters, feedback },
+    };
+  }, [feedback, store]);
+  const [runtime] = useState(() => new ExternalStoreRuntimeCore(adaptedStore));
 
   useEffect(() => {
     return () => {
@@ -20,11 +28,9 @@ export const useExternalStoreRuntime = <T>(
   }, [runtime]);
 
   useEffect(() => {
-    runtime.setAdapter(store);
+    runtime.setAdapter(adaptedStore);
   });
 
-  const { modelContext } = useRuntimeAdapters() ?? {};
-
   useEffect(() => {
     if (!modelContext) return undefined;
     return runtime.registerModelContextProvider(modelContext);

package/src/react/runtimes/useLocalRuntime.test.tsx

@@ -32,6 +32,26 @@ afterEach(() => {
 });
 
 describe("useLocalRuntime", () => {
+  it("enables feedback for Cloud threads", async () => {
+    const cloud = makeCloud();
+    let runtime: ReturnType<typeof useLocalRuntime> | null = null;
+    const App = () => {
+      runtime = useLocalRuntime(chatModel, { cloud });
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <div />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<App />);
+
+    await waitFor(() => {
+      expect(cloud.threads.list).toHaveBeenCalledTimes(2);
+      expect(runtime!.thread.getState().capabilities.feedback).toBe(true);
+    });
+  });
+
   it("surfaces the live thread after mount without user input", async () => {
     const auiRef: { current: ReturnType<typeof useAui> | null } = {
       current: null,

package/src/react/runtimes/useRemoteThreadListRuntime.load-error.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+import { makeAdapter } from "../../tests/remote-thread-list-test-helpers";
+import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
+import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
+import { useRemoteThreadListRuntime } from "./useRemoteThreadListRuntime";
+
+const EMPTY_MESSAGES: readonly never[] = [];
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe("useRemoteThreadListRuntime load recovery", () => {
+  it("reloads once when the browser comes online after a failed load", async () => {
+    const error = new Error("offline");
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const list = vi
+      .fn()
+      .mockRejectedValueOnce(error)
+      .mockResolvedValueOnce({ threads: [] });
+    const adapter = makeAdapter({ list });
+    const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+    const useThreadRuntime = () =>
+      useExternalStoreRuntime({
+        messages: EMPTY_MESSAGES,
+        onNew: async () => {},
+      } as never);
+
+    const App = () => {
+      const runtime = useRemoteThreadListRuntime({
+        adapter,
+        runtimeHook: useThreadRuntime,
+      });
+      runtimeRef.current = runtime;
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          {null}
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<App />);
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(runtimeRef.current!.threads.getState().loadError).toBe(error),
+    );
+
+    act(() => window.dispatchEvent(new Event("online")));
+
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(2));
+    await act(async () => {});
+    expect(list).toHaveBeenCalledTimes(2);
+    expect(runtimeRef.current!.threads.getState().loadError).toBeUndefined();
+  });
+
+  it("reloads once when the page becomes visible after a failed load", async () => {
+    const error = new Error("offline");
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
+    const list = vi
+      .fn()
+      .mockRejectedValueOnce(error)
+      .mockResolvedValueOnce({ threads: [] });
+    const adapter = makeAdapter({ list });
+    const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+    const useThreadRuntime = () =>
+      useExternalStoreRuntime({
+        messages: EMPTY_MESSAGES,
+        onNew: async () => {},
+      } as never);
+
+    const App = () => {
+      const runtime = useRemoteThreadListRuntime({
+        adapter,
+        runtimeHook: useThreadRuntime,
+      });
+      runtimeRef.current = runtime;
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          {null}
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<App />);
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(runtimeRef.current!.threads.getState().loadError).toBe(error),
+    );
+
+    act(() => document.dispatchEvent(new Event("visibilitychange")));
+
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(2));
+    await waitFor(() =>
+      expect(runtimeRef.current!.threads.getState().loadError).toBeUndefined(),
+    );
+
+    act(() => document.dispatchEvent(new Event("visibilitychange")));
+    await act(async () => {});
+
+    expect(list).toHaveBeenCalledTimes(2);
+  });
+});

package/src/react/runtimes/useRemoteThreadListRuntime.ts

@@ -1,6 +1,7 @@
 import {
   useState,
   useEffect,
+  useInsertionEffect,
   useMemo,
   useRef,
   useCallback,
@@ -39,11 +40,43 @@ const useRemoteThreadListRuntimeImpl = (
   options: RemoteThreadListOptions,
 ): AssistantRuntime => {
   const [runtime] = useState(() => new RemoteThreadListRuntimeCore(options));
+
+  // Insertion-effect cleanup runs only when React deletes the fiber, so a
+  // hidden <Activity> or a re-suspended boundary keeps the threads alive; the
+  // disposal is deferred to a microtask because it notifies subscribers and
+  // React forbids scheduling updates from an insertion effect.
+  useInsertionEffect(
+    () => () => queueMicrotask(() => runtime.threads.__internal_dispose()),
+    [runtime],
+  );
+
   useEffect(() => {
     runtime.threads.__internal_setOptions(options);
     runtime.threads.__internal_load();
   }, [runtime, options]);
 
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+
+    const reloadAfterError = () => {
+      if (runtime.threads.loadError !== undefined) {
+        void runtime.threads.reload();
+      }
+    };
+    const reloadAfterVisible = () => {
+      if (document.visibilityState === "visible") reloadAfterError();
+    };
+
+    window.addEventListener("online", reloadAfterError);
+    document.addEventListener("visibilitychange", reloadAfterVisible);
+    return () => {
+      window.removeEventListener("online", reloadAfterError);
+      document.removeEventListener("visibilitychange", reloadAfterVisible);
+    };
+  }, [runtime]);
+
   return useMemo(() => new AssistantRuntimeImpl(runtime), [runtime]);
 };
 

package/src/runtime/api/message-runtime.test.ts

@@ -11,6 +11,7 @@ import {
   type MessageStateBinding,
 } from "./message-runtime";
 import { toMessagePartStatus } from "../../utils/normalizePartStatus";
+import { convertExternalMessageChunk } from "../utils/external-message-conversion";
 
 const messagePath = {
   ref: "threads.main.messages[0]",
@@ -256,6 +257,80 @@ describe("toMessagePartStatus", () => {
 });
 
 describe("MessageRuntimeImpl paths", () => {
+  it.each([undefined, ""])(
+    "looks up separate tool calls with ID %s without breaking provider result matching",
+    (toolCallId) => {
+      const id = toolCallId === undefined ? {} : { toolCallId };
+      const converted = convertExternalMessageChunk(
+        {
+          inputs: [{}],
+          outputs: [
+            {
+              role: "assistant",
+              content: [
+                { type: "tool-call", ...id, toolName: "weather", args: {} },
+                { type: "tool-call", ...id, toolName: "search", args: {} },
+                {
+                  type: "tool-call",
+                  toolCallId: "provider-call",
+                  toolName: "calendar",
+                  args: { day: "Monday" },
+                },
+              ],
+            },
+            {
+              role: "assistant",
+              content: [
+                {
+                  type: "tool-call",
+                  toolCallId: "provider-call",
+                  toolName: "calendar",
+                  args: { day: "Tuesday" },
+                },
+              ],
+            },
+            {
+              role: "tool",
+              toolCallId: "provider-call",
+              toolName: "calendar",
+              result: "Meeting at noon",
+            },
+          ],
+        },
+        0,
+        1,
+        false,
+        undefined,
+      );
+      const runtime = new MessageRuntimeImpl(
+        {
+          ...messageBinding,
+          getState: () => ({ ...message, ...converted }),
+        },
+        threadBinding,
+      );
+      const calls = converted.content.filter(
+        (part) => part.type === "tool-call",
+      );
+
+      expect(
+        calls.map((call) =>
+          runtime.getMessagePartByToolCallId(call.toolCallId).getState(),
+        ),
+      ).toMatchObject([
+        { type: "tool-call", toolName: "weather" },
+        { type: "tool-call", toolName: "search" },
+        {
+          type: "tool-call",
+          toolCallId: "provider-call",
+          toolName: "calendar",
+          args: { day: "Tuesday" },
+          result: "Meeting at noon",
+        },
+      ]);
+    },
+  );
+
   it("appends nested selectors to the message path", () => {
     const runtime = new MessageRuntimeImpl(messageBinding, threadBinding);
 

package/src/runtime/api/thread-list-item-runtime.ts

@@ -30,12 +30,17 @@ import type { ThreadListItemStatus } from "../interfaces/thread-list-runtime-cor
 
 export type { ThreadListItemState, ThreadListItemStatus };
 
+export type ThreadListItemGenerateTitleOptions = {
+  /** Marks a generation started by the automatic title trigger. */
+  automatic?: boolean;
+};
+
 export type ThreadListItemRuntime = {
   readonly path: ThreadListItemRuntimePath;
   getState(): ThreadListItemState;
 
   initialize(): Promise<{ remoteId: string; externalId: string | undefined }>;
-  generateTitle(): Promise<void>;
+  generateTitle(options?: ThreadListItemGenerateTitleOptions): Promise<void>;
 
   switchTo(options?: { unarchive?: boolean }): Promise<void>;
   rename(newTitle: string): Promise<void>;
@@ -147,9 +152,11 @@ export class ThreadListItemRuntimeImpl implements ThreadListItemRuntime {
     return this._threadListBinding.initialize(state.id);
   }
 
-  public generateTitle(): Promise<void> {
+  public generateTitle(
+    options?: ThreadListItemGenerateTitleOptions,
+  ): Promise<void> {
     const state = this._core.getState();
-    return this._threadListBinding.generateTitle(state.id);
+    return this._threadListBinding.generateTitle(state.id, options);
   }
 
   public unstable_on<E extends ThreadListItemEventType>(

package/src/runtime/api/thread-list-runtime.ts

@@ -15,6 +15,7 @@ import {
   type ThreadListItemRuntime,
   ThreadListItemRuntimeImpl,
   type ThreadListItemState,
+  type ThreadListItemStateBinding,
 } from "./thread-list-item-runtime";
 import {
   type ThreadListItemRuntimeBinding,
@@ -32,6 +33,8 @@ export type ThreadListState = {
   readonly threadIds: readonly string[];
   readonly archivedThreadIds: readonly string[];
   readonly isLoading: boolean;
+  /** The error thrown by the most recent thread list load that failed, cleared when a later load starts. */
+  readonly loadError: unknown;
   readonly isLoadingMore: boolean;
   readonly hasMore: boolean;
   readonly threadItems: Readonly<
@@ -97,6 +100,7 @@ const getThreadListState = (
     threadIds: threadList.threadIds,
     archivedThreadIds: threadList.archivedThreadIds,
     isLoading: threadList.isLoading,
+    loadError: threadList.loadError,
     isLoadingMore: threadList.isLoadingMore ?? false,
     hasMore: threadList.hasMore ?? false,
     threadItems: threadList.threadItems,
@@ -250,6 +254,21 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
     return this._mainThreadListItemRuntime;
   }
 
+  private _createItemStateBinding(
+    threadId: string,
+  ): ThreadListItemStateBinding {
+    return new ShallowMemoizeSubject({
+      path: {
+        ref: `threadItems[threadId=${threadId}]`,
+        threadSelector: { type: "threadId", threadId },
+      },
+      getState: () => {
+        return getThreadListItemState(this._core, threadId);
+      },
+      subscribe: (callback) => this._core.subscribe(callback),
+    });
+  }
+
   public getById(threadId: string) {
     return new this._runtimeFactory(
       new NestedSubscriptionSubject({
@@ -260,7 +279,7 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
         getState: () => this._core.getThreadRuntimeCore(threadId),
         subscribe: (callback) => this._core.subscribe(callback),
       }),
-      this.mainItem,
+      this._createItemStateBinding(threadId),
     );
   }
 
@@ -301,16 +320,7 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
 
   public getItemById(threadId: string) {
     return new ThreadListItemRuntimeImpl(
-      new ShallowMemoizeSubject({
-        path: {
-          ref: `threadItems[threadId=${threadId}]`,
-          threadSelector: { type: "threadId", threadId },
-        },
-        getState: () => {
-          return getThreadListItemState(this._core, threadId);
-        },
-        subscribe: (callback) => this._core.subscribe(callback),
-      }),
+      this._createItemStateBinding(threadId),
       this._core,
     );
   }

package/src/runtime/api/thread-runtime.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from "vitest";
+import { LocalRuntimeCore } from "../../runtimes/local/local-runtime-core";
+import { ExternalStoreRuntimeCore } from "../../runtimes/external-store/external-store-runtime-core";
+import { AssistantRuntimeImpl } from "./assistant-runtime";
+
+describe("ThreadRuntime.append", () => {
+  it.each([
+    { parent: { parentId: null }, expectedParent: null, visible: ["new"] },
+    {
+      parent: {},
+      expectedParent: "tail",
+      visible: ["root", "tail", "new"],
+    },
+    {
+      parent: { parentId: "root" },
+      expectedParent: "root",
+      visible: ["root", "new"],
+    },
+  ])(
+    "selects the branch under $expectedParent",
+    ({ parent, expectedParent, visible }) => {
+      const core = new LocalRuntimeCore(
+        { adapters: { chatModel: { run: async () => ({ content: [] }) } } },
+        [
+          { id: "root", role: "user", content: "root" },
+          { id: "tail", role: "assistant", content: "tail" },
+        ],
+      );
+      const thread = new AssistantRuntimeImpl(core).thread;
+
+      thread.append({
+        ...parent,
+        content: [{ type: "text", text: "new" }],
+        startRun: false,
+      });
+
+      expect(
+        thread.getState().messages.map((message) => message.content),
+      ).toEqual(visible.map((text) => [{ type: "text", text }]));
+      expect(thread.export().messages.at(-1)?.parentId).toBe(expectedParent);
+    },
+  );
+});
+
+describe("ThreadRuntime.append with an external store", () => {
+  it("routes an explicit root parent to onEdit instead of onNew", async () => {
+    const onNew = vi.fn(async () => {});
+    const onEdit = vi.fn(async () => {});
+    const core = new ExternalStoreRuntimeCore({
+      messages: [
+        {
+          id: "old",
+          role: "user",
+          content: [{ type: "text", text: "old" }],
+          createdAt: new Date(0),
+          attachments: [],
+          metadata: { custom: {} },
+        },
+      ],
+      onNew,
+      onEdit,
+    });
+    const thread = new AssistantRuntimeImpl(core).thread;
+
+    thread.append({
+      parentId: null,
+      content: [{ type: "text", text: "new root" }],
+      startRun: false,
+    });
+
+    await vi.waitFor(() =>
+      expect(onEdit).toHaveBeenCalledExactlyOnceWith(
+        expect.objectContaining({ parentId: null }),
+      ),
+    );
+    expect(onNew).not.toHaveBeenCalled();
+  });
+});

package/src/runtime/api/thread-runtime.ts

@@ -77,6 +77,10 @@ const toStartRunConfig = (message: CreateStartRunConfig): StartRunConfig => {
 export type CreateAppendMessage =
   | string
   | {
+      /**
+       * An omitted value or `undefined` selects the current tail.
+       * `null` selects a root branch.
+       */
       parentId?: string | null | undefined;
       sourceId?: string | null | undefined;
       role?: AppendMessage["role"] | undefined;
@@ -107,7 +111,10 @@ const toAppendMessage = (
 
   return {
     createdAt: message.createdAt ?? new Date(),
-    parentId: message.parentId ?? messages.at(-1)?.id ?? null,
+    parentId:
+      message.parentId === undefined
+        ? (messages.at(-1)?.id ?? null)
+        : message.parentId,
     sourceId: message.sourceId ?? null,
     role: message.role ?? "user",
     content: message.content,