@assistant-ui/core 0.3.19 → 0.3.21

package/src/react/runtimes/useExternalStoreRuntime.history-copy.test.tsx

@@ -0,0 +1,483 @@
+// @vitest-environment jsdom
+
+import { act, render } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { ThreadHistoryAdapter } from "../../adapters/thread-history";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+import { ExportedMessageRepository } from "../../runtime/utils/message-repository";
+import type { ExternalStoreAdapter } from "../../runtimes/external-store/external-store-adapter";
+import type { ThreadMessage } from "../../types/message";
+import { RuntimeAdapterProvider } from "./RuntimeAdapterProvider";
+import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
+
+const user = (id: string): ThreadMessage => ({
+  id,
+  role: "user",
+  content: [{ type: "text", text: id }],
+  attachments: [],
+  createdAt: new Date(0),
+  metadata: { custom: {} },
+});
+
+const assistant = (id: string): ThreadMessage => ({
+  id,
+  role: "assistant",
+  content: [{ type: "text", text: id }],
+  status: { type: "complete", reason: "stop" },
+  createdAt: new Date(0),
+  metadata: {
+    unstable_state: null,
+    unstable_annotations: [],
+    unstable_data: [],
+    steps: [],
+    custom: {},
+  },
+});
+
+const historyAdapter = () => {
+  const unstable_copy = vi.fn(
+    async (_branch: readonly ThreadMessage[], _ids: readonly string[]) => {},
+  );
+  const history: ThreadHistoryAdapter = {
+    load: async () => ExportedMessageRepository.fromArray([]),
+    append: async () => {},
+    unstable_copy,
+  };
+  return { history, unstable_copy };
+};
+
+const settle = async () => {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  });
+};
+
+const setup = (
+  history?: ThreadHistoryAdapter,
+  initial: ExternalStoreAdapter = {
+    messages: [],
+    isRunning: false,
+    onNew: async () => {},
+  },
+) => {
+  let store = initial;
+  let runtime: AssistantRuntime | undefined;
+  const App = () => {
+    runtime = useExternalStoreRuntime(store);
+    return null;
+  };
+  const tree = () =>
+    history ? (
+      <RuntimeAdapterProvider adapters={{ history }}>
+        <App />
+      </RuntimeAdapterProvider>
+    ) : (
+      <App />
+    );
+  const view = render(tree());
+  const update = (next: Partial<ExternalStoreAdapter>) => {
+    store = { ...store, ...next };
+    act(() => view.rerender(tree()));
+  };
+  return {
+    get runtime() {
+      return runtime!;
+    },
+    update,
+    view,
+  };
+};
+
+describe("useExternalStoreRuntime history copy", () => {
+  it("copies the settled branch in order with new message ids", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const app = setup(history);
+    app.update({ isRunning: true });
+    app.update({
+      isRunning: false,
+      messages: [user("user-1"), assistant("assistant-1")],
+    });
+    await settle();
+
+    expect(unstable_copy).toHaveBeenCalledOnce();
+    expect(
+      unstable_copy.mock.calls[0]![0].map((message) => message.id),
+    ).toEqual(["user-1", "assistant-1"]);
+    expect(unstable_copy.mock.calls[0]![1]).toEqual(["user-1", "assistant-1"]);
+    app.view.unmount();
+  });
+
+  it("does not copy while running", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const app = setup(history);
+    app.update({ isRunning: true, messages: [user("user-1")] });
+    await settle();
+    expect(unstable_copy).not.toHaveBeenCalled();
+    app.view.unmount();
+  });
+
+  it("does not copy a loaded branch until a run adds a message", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const loaded = user("loaded");
+    const app = setup(history, {
+      messages: [loaded],
+      isRunning: false,
+      onNew: async () => {},
+    });
+    await settle();
+    expect(unstable_copy).not.toHaveBeenCalled();
+
+    app.update({ isRunning: true });
+    app.update({ isRunning: false, messages: [loaded, assistant("answer")] });
+    await settle();
+    expect(
+      unstable_copy.mock.calls[0]![0].map((message) => message.id),
+    ).toEqual(["loaded", "answer"]);
+    expect(unstable_copy.mock.calls[0]![1]).toEqual(["answer"]);
+    app.view.unmount();
+  });
+
+  it("leaves unchanged messages out of the next run's ids", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const app = setup(history);
+    const first = user("user-1");
+    app.update({ isRunning: true });
+    app.update({ isRunning: false, messages: [first] });
+    await settle();
+    app.update({ isRunning: true });
+    app.update({
+      isRunning: false,
+      messages: [first, assistant("assistant-2")],
+    });
+    await settle();
+    expect(unstable_copy.mock.calls[1]![1]).toEqual(["assistant-2"]);
+    app.view.unmount();
+  });
+
+  it("skips stores that persist their own history", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const app = setup(history, {
+      messages: [],
+      isRunning: false,
+      unstable_persistsHistory: true,
+      onNew: async () => {},
+    });
+    app.update({ isRunning: true });
+    app.update({ isRunning: false, messages: [user("user-1")] });
+    await settle();
+    expect(unstable_copy).not.toHaveBeenCalled();
+    app.view.unmount();
+  });
+
+  it("skips stores that run their own thread list", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const app = setup(history, {
+      messages: [],
+      isRunning: false,
+      adapters: { threadList: { threadId: "backend-thread" } },
+      onNew: async () => {},
+    });
+    app.update({ isRunning: true });
+    app.update({ isRunning: false, messages: [user("user-1")] });
+    await settle();
+    expect(unstable_copy).not.toHaveBeenCalled();
+    app.view.unmount();
+  });
+
+  it("rejects a pending interaction when the runtime unmounts before its copy", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const toolMessage = {
+      ...assistant("assistant-1"),
+      content: [
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "choose",
+          args: {},
+          argsText: "{}",
+        },
+      ],
+    } as ThreadMessage;
+    const app = setup(history, {
+      messages: [toolMessage],
+      isRunning: false,
+      onNew: async () => {},
+    });
+    const pending = app.runtime.thread
+      .getMessageById("assistant-1")
+      .getMessagePartByToolCallId("call-1").unstable_recordInteraction!({
+      type: "action",
+      payload: {},
+    });
+    for (let tick = 0; tick < 5; tick++) await Promise.resolve();
+    app.view.unmount();
+    await expect(pending).rejects.toThrow("History copy was detached.");
+    await settle();
+    expect(unstable_copy).not.toHaveBeenCalled();
+  });
+
+  it("omits optimistic, fallback, running, and synthetic error messages", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const app = setup(history);
+    const optimistic = {
+      ...assistant("optimistic"),
+      metadata: { ...assistant("optimistic").metadata, isOptimistic: true },
+    } as ThreadMessage;
+    const running = {
+      ...assistant("running"),
+      status: { type: "running" },
+    } as ThreadMessage;
+    app.update({ isRunning: true });
+    app.update({
+      isRunning: false,
+      messages: [
+        user("user-1"),
+        optimistic,
+        user("__external_store_fallback_1"),
+        user("__error__1"),
+        running,
+        assistant("assistant-1"),
+      ],
+    });
+    await settle();
+    expect(
+      unstable_copy.mock.calls[0]![0].map((message) => message.id),
+    ).toEqual(["user-1", "assistant-1"]);
+    expect(unstable_copy.mock.calls[0]![1]).toEqual(["user-1", "assistant-1"]);
+    app.view.unmount();
+  });
+
+  it("records an interaction in the copy without changing the runtime message", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const toolMessage = {
+      ...assistant("assistant-1"),
+      content: [
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "choose",
+          args: {},
+          argsText: "{}",
+        },
+      ],
+    } as ThreadMessage;
+    const app = setup(history, {
+      messages: [toolMessage],
+      isRunning: false,
+      onNew: async () => {},
+    });
+    await act(async () => {
+      await app.runtime.thread
+        .getMessageById("assistant-1")
+        .getMessagePartByToolCallId("call-1").unstable_recordInteraction!({
+        type: "action",
+        payload: { choice: "yes" },
+      });
+    });
+
+    const copied = unstable_copy.mock.calls[0]![0][0]!;
+    expect(unstable_copy.mock.calls[0]![1]).toEqual(["assistant-1"]);
+    expect(copied.content[0]).toMatchObject({
+      unstable_interactions: {
+        entries: [{ type: "action", payload: { choice: "yes" } }],
+      },
+    });
+    expect(toolMessage.content[0]).not.toHaveProperty("unstable_interactions");
+    expect(
+      app.runtime.thread.getMessageById("assistant-1").getState().content[0],
+    ).not.toHaveProperty("unstable_interactions");
+    app.view.unmount();
+  });
+
+  it("records during a run and copies the interaction with other new messages at run end", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const toolMessage = {
+      ...assistant("assistant-1"),
+      content: [
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "choose",
+          args: {},
+          argsText: "{}",
+        },
+      ],
+    } as ThreadMessage;
+    const app = setup(history, {
+      messages: [toolMessage],
+      isRunning: false,
+      onNew: async () => {},
+    });
+    app.update({ isRunning: true });
+    app.update({ messages: [toolMessage, user("user-2")] });
+    await act(async () => {
+      await app.runtime.thread
+        .getMessageById("assistant-1")
+        .getMessagePartByToolCallId("call-1").unstable_recordInteraction!({
+        type: "action",
+        payload: {},
+      });
+    });
+    expect(unstable_copy).not.toHaveBeenCalled();
+    app.update({ isRunning: false });
+    await settle();
+    expect(unstable_copy.mock.calls[0]![1]).toEqual(["assistant-1", "user-2"]);
+    app.view.unmount();
+  });
+
+  it("keeps a store's own interaction handler", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    const onRecord = vi.fn(async () => {});
+    const toolMessage = {
+      ...assistant("assistant-1"),
+      content: [
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "choose",
+          args: {},
+          argsText: "{}",
+        },
+      ],
+    } as ThreadMessage;
+    const app = setup(history, {
+      messages: [toolMessage],
+      isRunning: false,
+      onNew: async () => {},
+      unstable_onRecordToolInteraction: onRecord,
+    });
+    await act(async () => {
+      await app.runtime.thread
+        .getMessageById("assistant-1")
+        .getMessagePartByToolCallId("call-1").unstable_recordInteraction!({
+        type: "action",
+        payload: {},
+      });
+    });
+    expect(onRecord).toHaveBeenCalledOnce();
+    expect(unstable_copy).not.toHaveBeenCalled();
+    app.view.unmount();
+  });
+
+  it("rejects an idle interaction when its copy fails", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    unstable_copy.mockRejectedValueOnce(new Error("offline"));
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const toolMessage = {
+      ...assistant("assistant-1"),
+      content: [
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "choose",
+          args: {},
+          argsText: "{}",
+        },
+      ],
+    } as ThreadMessage;
+    const app = setup(history, {
+      messages: [toolMessage],
+      isRunning: false,
+      onNew: async () => {},
+    });
+    await expect(
+      app.runtime.thread
+        .getMessageById("assistant-1")
+        .getMessagePartByToolCallId("call-1").unstable_recordInteraction!({
+        type: "action",
+        payload: {},
+      }),
+    ).rejects.toThrow("offline");
+    expect(unstable_copy).toHaveBeenCalledOnce();
+    warn.mockRestore();
+    app.view.unmount();
+  });
+
+  it("retries a failed copy with the same ids on the next run end", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    unstable_copy.mockRejectedValueOnce(new Error("offline"));
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const app = setup(history);
+    app.update({ isRunning: true });
+    app.update({ isRunning: false, messages: [user("user-1")] });
+    await settle();
+    app.update({ isRunning: true });
+    app.update({ isRunning: false });
+    await settle();
+    expect(unstable_copy.mock.calls.map((call) => call[1])).toEqual([
+      ["user-1"],
+      ["user-1"],
+    ]);
+    expect(warn).toHaveBeenCalledOnce();
+    warn.mockRestore();
+    app.view.unmount();
+  });
+
+  it("queues one more copy when a run ends during an in-flight copy", async () => {
+    const { history, unstable_copy } = historyAdapter();
+    let finishFirst!: () => void;
+    unstable_copy.mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          finishFirst = resolve;
+        }),
+    );
+    const app = setup(history);
+    const first = user("user-1");
+    app.update({ isRunning: true });
+    app.update({ isRunning: false, messages: [first] });
+    await settle();
+    app.update({ isRunning: true });
+    app.update({
+      isRunning: false,
+      messages: [first, assistant("assistant-2")],
+    });
+    await settle();
+    expect(unstable_copy).toHaveBeenCalledOnce();
+    finishFirst();
+    await settle();
+    expect(unstable_copy).toHaveBeenCalledTimes(2);
+    expect(unstable_copy.mock.calls[1]![1]).toEqual(["assistant-2"]);
+    app.view.unmount();
+  });
+
+  it.each(["no history", "history without copy"])(
+    "keeps unsupported recording behavior with %s",
+    async (caseName) => {
+      const { history, unstable_copy } = historyAdapter();
+      const toolMessage = {
+        ...assistant("assistant-1"),
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: "call-1",
+            toolName: "choose",
+            args: {},
+            argsText: "{}",
+          },
+        ],
+      } as ThreadMessage;
+      const app = setup(
+        caseName === "no history"
+          ? undefined
+          : (({ unstable_copy: _, ...rest }) => rest)(history),
+        { messages: [toolMessage], isRunning: false, onNew: async () => {} },
+      );
+      await expect(
+        app.runtime.thread
+          .getMessageById("assistant-1")
+          .getMessagePartByToolCallId("call-1").unstable_recordInteraction!({
+          type: "action",
+          payload: {},
+        }),
+      ).rejects.toThrow(
+        "Runtime does not support recording tool interactions.",
+      );
+      app.update({ isRunning: true });
+      app.update({ isRunning: false, messages: [toolMessage, user("user-2")] });
+      await settle();
+      expect(unstable_copy).not.toHaveBeenCalled();
+      app.view.unmount();
+    },
+  );
+});

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

@@ -1,12 +1,16 @@
 // @vitest-environment jsdom
 
-import { StrictMode } from "react";
+import { Activity, StrictMode, useEffect } from "react";
 import { act, render } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
+import { useRemoteThreadListRuntime } from "./useRemoteThreadListRuntime";
+import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
+import { InMemoryThreadListAdapter } from "../../runtimes/remote-thread-list/adapter/in-memory";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import type { ThreadMessage } from "../../types/message";
 import { RuntimeAdapterProvider } from "./RuntimeAdapterProvider";
+import type { RealtimeVoiceAdapter } from "../../adapters/voice";
 
 const userMessage: ThreadMessage = {
   id: "user-1",
@@ -18,6 +22,77 @@ const userMessage: ThreadMessage = {
 };
 
 describe("useExternalStoreRuntime lifecycle", () => {
+  it("keeps voice through Activity hide and reveal when hosted by a remote thread list", async () => {
+    const disconnect = vi.fn();
+    const onVoiceTranscript = vi.fn();
+    let emitTranscript!: (item: RealtimeVoiceAdapter.TranscriptItem) => void;
+    const session: RealtimeVoiceAdapter.Session = {
+      status: { type: "running" },
+      isMuted: false,
+      disconnect,
+      mute: vi.fn(),
+      unmute: vi.fn(),
+      onStatusChange: () => () => {},
+      onTranscript: (callback) => {
+        emitTranscript = callback;
+        return () => {};
+      },
+      onModeChange: () => () => {},
+      onVolumeChange: () => () => {},
+    };
+    const adapter = new InMemoryThreadListAdapter();
+    const capture: { runtime: AssistantRuntime | null } = { runtime: null };
+    let connected = false;
+    const App = () => {
+      const runtime = useRemoteThreadListRuntime({
+        runtimeHook: function RuntimeHook() {
+          return useExternalStoreRuntime<ThreadMessage>({
+            messages: [],
+            onNew: async () => {},
+            onVoiceTranscript,
+            adapters: { voice: { connect: () => session } },
+          });
+        },
+        adapter,
+      });
+      capture.runtime = runtime;
+      useEffect(() => {
+        if (connected) return;
+        connected = true;
+        runtime.thread.connectVoice();
+      }, [runtime]);
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <div />
+        </AssistantRuntimeProvider>
+      );
+    };
+    const renderApp = (mode: "visible" | "hidden") => (
+      <Activity mode={mode}>
+        <App />
+      </Activity>
+    );
+
+    const view = render(renderApp("visible"));
+    await act(async () => Promise.resolve());
+    view.rerender(renderApp("hidden"));
+    await act(async () => Promise.resolve());
+    view.rerender(renderApp("visible"));
+    await act(async () => Promise.resolve());
+
+    expect(disconnect).not.toHaveBeenCalled();
+    expect(capture.runtime!.thread.getState().voice).toBeDefined();
+
+    act(() =>
+      emitTranscript({ role: "user", text: "after reveal", isFinal: true }),
+    );
+    expect(onVoiceTranscript).toHaveBeenCalledOnce();
+
+    view.unmount();
+    await act(async () => Promise.resolve());
+    expect(disconnect).toHaveBeenCalledOnce();
+  });
+
   it("uses feedback supplied by the per-thread adapter context", () => {
     const submit = vi.fn();
     const capture: { runtime: AssistantRuntime | null } = { runtime: null };
@@ -52,7 +127,10 @@ describe("useExternalStoreRuntime lifecycle", () => {
     const onNew = vi.fn(async () => {});
     const capture: { runtime: AssistantRuntime | null } = { runtime: null };
     const App = () => {
-      const runtime = useExternalStoreRuntime({ messages: [], onNew });
+      const runtime = useExternalStoreRuntime<ThreadMessage>({
+        messages: [],
+        onNew,
+      });
       capture.runtime = runtime;
       return null;
     };
@@ -81,7 +159,10 @@ describe("useExternalStoreRuntime lifecycle", () => {
     const onNew = vi.fn(async () => {});
     const capture: { runtime: AssistantRuntime | null } = { runtime: null };
     const App = () => {
-      const runtime = useExternalStoreRuntime({ messages: [], onNew });
+      const runtime = useExternalStoreRuntime<ThreadMessage>({
+        messages: [],
+        onNew,
+      });
       capture.runtime = runtime;
       return null;
     };

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

@@ -10,6 +10,7 @@ import {
   type AssistantClient,
 } from "@assistant-ui/store";
 import type { ThreadSuggestion } from "../../runtime/interfaces/thread-runtime-core";
+import type { ThreadMessage } from "../../types/message";
 import { Suggestions } from "../../store/clients/suggestions";
 import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
 import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
@@ -32,13 +33,16 @@ const App = ({
   config?: AuiConfig;
   strict?: boolean;
 }) => {
-  const runtime = useExternalStoreRuntime({
+  const runtime = useExternalStoreRuntime<ThreadMessage>({
     messages: [],
     onNew: async () => {},
     ...(suggestions && { suggestions }),
   });
   const tree = (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
+    <AssistantRuntimeProvider
+      runtime={runtime}
+      {...(config === undefined ? {} : { config })}
+    >
       <Consumer />
     </AssistantRuntimeProvider>
   );

package/src/react/runtimes/useExternalStoreRuntime.ts

@@ -7,18 +7,30 @@ import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import { AssistantRuntimeImpl } from "../../runtime/internal";
 import { invalidateThreadRuntime } from "../../runtime/utils/thread-runtime-lifecycle";
 import { useRuntimeAdapters } from "./RuntimeAdapterProvider";
+import { ExternalStoreHistoryCopy } from "./external-store-history-copy";
 
 export const useExternalStoreRuntime = <T>(
   store: ExternalStoreAdapter<T>,
 ): AssistantRuntime => {
-  const { modelContext, feedback } = useRuntimeAdapters() ?? {};
+  const { modelContext, feedback, history } = useRuntimeAdapters() ?? {};
+  const [historyCopy] = useState(() => new ExternalStoreHistoryCopy());
+  const copiesHistory =
+    !!history?.unstable_copy &&
+    !store.unstable_persistsHistory &&
+    !store.adapters?.threadList;
   const adaptedStore = useMemo(() => {
-    if (!feedback || store.adapters?.feedback) return store;
+    const withFeedback =
+      feedback && !store.adapters?.feedback
+        ? { ...store, adapters: { ...store.adapters, feedback } }
+        : store;
+    if (!copiesHistory || store.unstable_onRecordToolInteraction) {
+      return withFeedback;
+    }
     return {
-      ...store,
-      adapters: { ...store.adapters, feedback },
+      ...withFeedback,
+      unstable_onRecordToolInteraction: historyCopy.recordInteraction,
     };
-  }, [feedback, store]);
+  }, [copiesHistory, feedback, historyCopy, store]);
   const [runtime] = useState(() => new ExternalStoreRuntimeCore(adaptedStore));
 
   useEffect(() => {
@@ -31,6 +43,14 @@ export const useExternalStoreRuntime = <T>(
     runtime.setAdapter(adaptedStore);
   });
 
+  useEffect(() => {
+    if (!copiesHistory || !history) return;
+    return historyCopy.attach(
+      runtime.threads.getMainThreadRuntimeCore(),
+      history,
+    );
+  }, [copiesHistory, history, historyCopy, runtime]);
+
   useEffect(() => {
     if (!modelContext) return undefined;
     return runtime.registerModelContextProvider(modelContext);