@ulearning/ai-sdk-adapter 0.0.0-stage → 1.0.0-next.0

package/src/runtime/useMessageQueue.effects.test.tsx

@@ -0,0 +1,88 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, render, waitFor } from "./__tests__/vue";
+import { defineComponent, h, shallowRef } from "vue";
+import { useTapRoot } from "@ulearning/ai-tap";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AppendMessage } from "@ulearning/ai-core";
+import { useMessageQueue } from "./useMessageQueue";
+
+const passiveEffects = vi.hoisted(() => ({ deferred: false }));
+
+vi.mock("@ulearning/ai-tap", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@ulearning/ai-tap")>();
+  return {
+    ...actual,
+    useEffect: (...[effect, deps]: Parameters<typeof actual.useEffect>) =>
+      actual.useEffect(() => {
+        if (!passiveEffects.deferred) return effect();
+        return undefined;
+      }, deps),
+  };
+});
+
+const message: AppendMessage = {
+  role: "user",
+  content: [{ type: "text", text: "pending" }],
+  attachments: [],
+  createdAt: new Date(0),
+  parentId: null,
+  sourceId: null,
+  runConfig: {},
+  metadata: { custom: {} },
+};
+
+afterEach(() => {
+  passiveEffects.deferred = false;
+  cleanup();
+});
+
+describe("useMessageQueue before passive effects", () => {
+  it.each([true, false])(
+    "holds sends while busy (busy on mount: %s)",
+    async (initiallyBusy) => {
+      passiveEffects.deferred = initiallyBusy;
+      const send = vi.fn(async (_message: AppendMessage) => {});
+      const isRunning = shallowRef(initiallyBusy);
+      let root!: useTapRoot.Root<ReturnType<typeof useMessageQueue>>;
+      render(
+        h(
+          defineComponent({
+            setup() {
+              root = useTapRoot(() =>
+                useMessageQueue({
+                  enabled: true,
+                  isRunning: isRunning.value,
+                  isSendDisabled: false,
+                  send,
+                  cancel: async () => {},
+                }),
+              );
+              return () => null;
+            },
+          }),
+        ),
+      );
+      const result = {
+        get current() {
+          return root.getValue();
+        },
+      };
+      const rerender = (next: { isRunning: boolean }) => {
+        isRunning.value = next.isRunning;
+      };
+      if (!initiallyBusy) {
+        passiveEffects.deferred = true;
+        rerender({ isRunning: true });
+      }
+      await act(async () => result.current.adapter!.enqueue(message));
+      expect(send).not.toHaveBeenCalled();
+
+      passiveEffects.deferred = false;
+      rerender({ isRunning: false });
+      await waitFor(() =>
+        expect(send).toHaveBeenCalledExactlyOnceWith(message),
+      );
+    },
+  );
+});

package/src/runtime/useMessageQueue.test.tsx

@@ -0,0 +1,256 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, renderHook, waitFor } from "./__tests__/tap";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AppendMessage } from "@ulearning/ai-core";
+import { useMessageQueue } from "./useMessageQueue";
+
+const message = (text: string): AppendMessage => ({
+  role: "user",
+  content: [{ type: "text", text }],
+  attachments: [],
+  createdAt: new Date(0),
+  parentId: null,
+  sourceId: null,
+  runConfig: {},
+  metadata: { custom: {} },
+});
+
+afterEach(cleanup);
+
+describe("useMessageQueue lifecycle", () => {
+  it("releases a cleared rejection without surfacing its stale error", async () => {
+    const error = new Error("discarded send rejected");
+    let reject!: (error: Error) => void;
+    const pending = new Promise<void>((_resolve, fail) => {
+      reject = fail;
+    });
+    const send = vi.fn(async (_message: AppendMessage) => {});
+    send.mockReturnValueOnce(pending);
+    const onError = vi.fn();
+    const logged = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const { result } = renderHook(() =>
+        useMessageQueue({
+          enabled: true,
+          isRunning: false,
+          isSendDisabled: false,
+          send,
+          cancel: async () => {},
+          onError,
+        }),
+      );
+      await act(async () => result.current.adapter!.enqueue(message("first")));
+      act(() => {
+        result.current.clear();
+        result.current.adapter!.enqueue(message("replacement"));
+      });
+      await act(async () => {
+        reject(error);
+        await pending.catch(() => {});
+      });
+      expect(send).toHaveBeenCalledTimes(2);
+      expect(send).toHaveBeenLastCalledWith(message("replacement"));
+      expect(result.current.adapter!.items).toEqual([]);
+      expect(onError).not.toHaveBeenCalledWith(error);
+    } finally {
+      logged.mockRestore();
+    }
+  });
+
+  it("pauses later prompts after a rejected send and retries the failed prompt first", async () => {
+    const error = new Error("send rejected");
+    let reject!: (error: Error) => void;
+    const pending = new Promise<void>((_resolve, fail) => {
+      reject = fail;
+    });
+    const send = vi.fn(async (_message: AppendMessage) => {});
+    send.mockReturnValueOnce(pending);
+    const onError = vi.fn();
+    const logged = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const { result } = renderHook(() =>
+        useMessageQueue({
+          enabled: true,
+          isRunning: false,
+          isSendDisabled: false,
+          send,
+          cancel: async () => {},
+          onError,
+        }),
+      );
+      await act(async () => result.current.adapter!.enqueue(message("first")));
+      act(() => result.current.adapter!.enqueue(message("later")));
+      await act(async () => {
+        reject(error);
+        await pending.catch(() => {});
+      });
+      expect(send).toHaveBeenCalledOnce();
+      expect(onError).toHaveBeenLastCalledWith(error);
+      expect(result.current.adapter!.items.map((item) => item.prompt)).toEqual([
+        "first",
+        "later",
+      ]);
+
+      await act(async () => result.current.adapter!.enqueue(message("retry")));
+      await waitFor(() =>
+        expect(send.mock.calls.map(([m]) => m.content[0])).toEqual([
+          { type: "text", text: "first" },
+          { type: "text", text: "first" },
+          { type: "text", text: "later" },
+          { type: "text", text: "retry" },
+        ]),
+      );
+      expect(onError).toHaveBeenLastCalledWith(undefined);
+      expect(result.current.adapter!.items).toEqual([]);
+    } finally {
+      logged.mockRestore();
+    }
+  });
+
+  it.each([true, false])(
+    "keeps the replacement queue until idle (intermediate idle: %s)",
+    async (intermediateIdle) => {
+      let finish!: () => void;
+      const firstRun = new Promise<void>((resolve) => {
+        finish = resolve;
+      });
+      const send = vi.fn(async (_message: AppendMessage) => {});
+      send.mockReturnValueOnce(firstRun);
+      const { result, rerender } = renderHook(
+        ({ isRunning }) =>
+          useMessageQueue({
+            enabled: true,
+            isRunning,
+            isSendDisabled: false,
+            send,
+            cancel: async () => {},
+          }),
+        { initialProps: { isRunning: false } },
+      );
+      await act(async () => result.current.adapter!.enqueue(message("first")));
+      rerender({ isRunning: true });
+      act(() => result.current.adapter!.steer(message("discarded")));
+      act(() => result.current.clear());
+      if (intermediateIdle) rerender({ isRunning: false });
+      rerender({ isRunning: true });
+      act(() => result.current.adapter!.enqueue(message("after replacement")));
+
+      await act(async () => {
+        finish();
+        await firstRun;
+      });
+      expect(send).toHaveBeenCalledOnce();
+      expect(result.current.adapter!.items.map((item) => item.prompt)).toEqual([
+        "after replacement",
+      ]);
+
+      rerender({ isRunning: false });
+      await waitFor(() => expect(send).toHaveBeenCalledTimes(2));
+      expect(send).toHaveBeenLastCalledWith(message("after replacement"));
+    },
+  );
+
+  it("preserves pending messages while disabled and resumes when enabled", async () => {
+    const send = vi.fn(async (_message: AppendMessage) => {});
+    const { result, rerender } = renderHook(
+      ({ enabled, isRunning }) =>
+        useMessageQueue({
+          enabled,
+          isRunning,
+          isSendDisabled: false,
+          send,
+          cancel: async () => {},
+        }),
+      { initialProps: { enabled: true, isRunning: true } },
+    );
+
+    act(() => result.current.adapter!.enqueue(message("pending")));
+    rerender({ enabled: false, isRunning: false });
+    expect(result.current.adapter).toBeUndefined();
+    expect(send).not.toHaveBeenCalled();
+
+    rerender({ enabled: true, isRunning: false });
+    await waitFor(() =>
+      expect(send).toHaveBeenCalledExactlyOnceWith(message("pending")),
+    );
+  });
+
+  it.each(["disable", "clear", "unmount"])(
+    "%s prevents a waiting steer from dispatching",
+    async (action) => {
+      let finish!: () => void;
+      const firstRun = new Promise<void>((resolve) => {
+        finish = resolve;
+      });
+      const send = vi.fn(async (_message: AppendMessage) => {});
+      send.mockReturnValueOnce(firstRun);
+      const { result, rerender, unmount } = renderHook(
+        ({ enabled, isRunning }) =>
+          useMessageQueue({
+            enabled,
+            isRunning,
+            isSendDisabled: false,
+            send,
+            cancel: async () => {},
+          }),
+        { initialProps: { enabled: true, isRunning: false } },
+      );
+
+      act(() => result.current.adapter!.enqueue(message("first")));
+      await waitFor(() => expect(send).toHaveBeenCalledOnce());
+      rerender({ enabled: true, isRunning: true });
+      act(() => result.current.adapter!.steer(message("second")));
+      if (action === "unmount") unmount();
+      else {
+        if (action === "clear") act(() => result.current.clear());
+        rerender({ enabled: action !== "disable", isRunning: false });
+      }
+      await act(async () => {
+        finish();
+        await firstRun;
+      });
+      expect(send).toHaveBeenCalledOnce();
+
+      if (action === "disable") {
+        rerender({ enabled: true, isRunning: false });
+        await waitFor(() => expect(send).toHaveBeenCalledTimes(2));
+        expect(send).toHaveBeenLastCalledWith(message("second"));
+      } else if (action === "clear") {
+        act(() => result.current.adapter!.enqueue(message("third")));
+        await waitFor(() => expect(send).toHaveBeenCalledTimes(2));
+        expect(send).toHaveBeenLastCalledWith(message("third"));
+      }
+    },
+  );
+
+  it("does not dispatch a waiting steer after unmount", async () => {
+    let finish!: () => void;
+    const firstRun = new Promise<void>((resolve) => {
+      finish = resolve;
+    });
+    const send = vi.fn(async (_message: AppendMessage) => {});
+    send.mockReturnValueOnce(firstRun);
+    const { result, rerender, unmount } = renderHook(
+      ({ isRunning }) =>
+        useMessageQueue({
+          enabled: true,
+          isRunning,
+          isSendDisabled: false,
+          send,
+          cancel: async () => {},
+        }),
+      { initialProps: { isRunning: false } },
+    );
+    await act(async () => result.current.adapter!.enqueue(message("first")));
+    expect(send).toHaveBeenCalledOnce();
+    rerender({ isRunning: true });
+    act(() => result.current.adapter!.steer(message("second")));
+    unmount();
+    await act(async () => {
+      finish();
+      await firstRun;
+    });
+    expect(send).toHaveBeenCalledOnce();
+  });
+});

package/src/runtime/useMessageQueue.ts

@@ -0,0 +1,189 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useInsertionEffect,
+  useRef,
+  useSyncExternalStore,
+} from "@ulearning/ai-tap";
+import {
+  createMessageQueue,
+  type AppendMessage,
+  type MessageQueueController,
+} from "@ulearning/ai-core";
+
+const subscribeNoop = () => () => {};
+const getNoItems = () => undefined;
+
+export const useMessageQueue = ({
+  enabled,
+  isRunning,
+  isSendDisabled,
+  send,
+  cancel,
+  onError,
+}: {
+  enabled: boolean;
+  isRunning: boolean;
+  isSendDisabled: boolean;
+  send: (message: AppendMessage) => Promise<void>;
+  cancel: () => Promise<void>;
+  onError?: ((error: Error | undefined) => void) | undefined;
+}) => {
+  const sendRef = useRef(send);
+  const cancelRef = useRef(cancel);
+  const onErrorRef = useRef(onError);
+  const heldRef = useRef(!enabled || isSendDisabled);
+  const runningRef = useRef(isRunning);
+  useInsertionEffect(() => {
+    sendRef.current = send;
+    cancelRef.current = cancel;
+    onErrorRef.current = onError;
+    heldRef.current = !enabled || isSendDisabled;
+    runningRef.current = isRunning;
+  });
+
+  const cancelsRef = useRef(0);
+  const cancelRun = useCallback(() => {
+    cancelsRef.current++;
+    return cancelRef.current();
+  }, []);
+
+  const reportedRef = useRef<{
+    controller: MessageQueueController | null;
+    busy: boolean;
+  }>({ controller: null, busy: isRunning });
+  const busyEdgesRef = useRef(0);
+  const idleWaitersRef = useRef<(() => void)[]>([]);
+  const lastDispatchRef = useRef<Promise<void>>(Promise.resolve());
+  const mountedRef = useRef(true);
+  const generationRef = useRef(0);
+
+  const queueRef = useRef<MessageQueueController | null>(null);
+  if (enabled && !queueRef.current) {
+    const controller = createMessageQueue({
+      run: (message) => {
+        const previous = lastDispatchRef.current;
+        const cancels = cancelsRef.current;
+        const generation = generationRef.current;
+        const busyEdgesAtDispatch = busyEdgesRef.current;
+        const dispatch = (async () => {
+          await previous;
+          let settledCancels = cancels;
+          while (true) {
+            if (!mountedRef.current || generation !== generationRef.current) {
+              if (
+                mountedRef.current &&
+                (!runningRef.current ||
+                  busyEdgesAtDispatch === busyEdgesRef.current)
+              ) {
+                controller.notifyIdle();
+              }
+              return;
+            }
+            if (
+              heldRef.current ||
+              runningRef.current ||
+              reportedRef.current.busy
+            ) {
+              await new Promise<void>((resolve) => {
+                idleWaitersRef.current.push(resolve);
+              });
+              continue;
+            }
+            if (settledCancels !== cancelsRef.current) {
+              settledCancels = cancelsRef.current;
+              await new Promise((resolve) => setTimeout(resolve));
+              continue;
+            }
+            break;
+          }
+          const overtaken = settledCancels !== cancels;
+          const busyEdges = busyEdgesRef.current;
+          onErrorRef.current?.(undefined);
+          try {
+            if (overtaken) {
+              const error = new Error("Queued send cancelled before dispatch");
+              error.name = "AbortError";
+              throw error;
+            }
+            await sendRef.current(message);
+          } catch (error) {
+            if (mountedRef.current && generation === generationRef.current) {
+              onErrorRef.current?.(
+                error instanceof Error ? error : new Error(String(error)),
+              );
+            }
+            throw error;
+          }
+          if (busyEdgesRef.current === busyEdges && !runningRef.current) {
+            controller.notifyIdle();
+          }
+        })();
+        lastDispatchRef.current = dispatch.catch(() => {});
+        return dispatch;
+      },
+    });
+    queueRef.current = controller;
+  }
+  const controller = queueRef.current;
+
+  useSyncExternalStore(
+    controller?.subscribe ?? subscribeNoop,
+    () => controller?.adapter.items,
+    getNoItems,
+  );
+  useSyncExternalStore(
+    controller?.subscribe ?? subscribeNoop,
+    () => controller?.adapter.steerItems,
+    getNoItems,
+  );
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      controller?.hold();
+      const waiters = idleWaitersRef.current;
+      idleWaitersRef.current = [];
+      for (const resolve of waiters) resolve();
+    };
+  }, [controller]);
+
+  useEffect(() => {
+    if (!controller) return;
+    if (!enabled || isSendDisabled) controller.hold();
+    else controller.release();
+  }, [controller, enabled, isSendDisabled]);
+
+  useEffect(() => {
+    const reported = reportedRef.current;
+    if (reported.controller !== controller || reported.busy !== isRunning) {
+      reportedRef.current = { controller, busy: isRunning };
+      if (isRunning) {
+        busyEdgesRef.current++;
+        controller?.notifyBusy();
+      } else {
+        controller?.notifyIdle();
+      }
+    }
+    if (!enabled || isSendDisabled || isRunning) return;
+    const waiters = idleWaitersRef.current;
+    idleWaitersRef.current = [];
+    for (const resolve of waiters) resolve();
+  }, [controller, enabled, isRunning, isSendDisabled]);
+
+  return {
+    adapter: enabled ? controller?.adapter : undefined,
+    cancel: cancelRun,
+    clear: () => {
+      onErrorRef.current?.(undefined);
+      generationRef.current++;
+      controller?.clear();
+      const waiters = idleWaitersRef.current;
+      idleWaitersRef.current = [];
+      for (const resolve of waiters) resolve();
+    },
+  };
+};

package/src/runtime/useResourceCleanup.ts

@@ -0,0 +1,58 @@
+import { useEffect, useRef } from "@ulearning/ai-tap";
+import { useAssistantClientDestroySignal } from "@ulearning/ai-store/internal";
+
+export const useResourceCleanup = (
+  enabled: boolean,
+  cleanup: () => void,
+  hostDestroySignal?: AbortSignal,
+) => {
+  const destroySignal = useAssistantClientDestroySignal();
+  const cleanupRef = useRef(cleanup);
+  const enabledRef = useRef(enabled);
+  const registrationRef = useRef<{
+    destroySignal: AbortSignal | undefined;
+    hostDestroySignal: AbortSignal | undefined;
+    controller: AbortController;
+  } | null>(null);
+
+  useEffect(() => {
+    cleanupRef.current = cleanup;
+    enabledRef.current = enabled;
+  });
+
+  useEffect(() => {
+    if (!enabled || (!destroySignal && !hostDestroySignal)) return undefined;
+    const current = registrationRef.current;
+    if (
+      current !== null &&
+      current.destroySignal === destroySignal &&
+      current.hostDestroySignal === hostDestroySignal
+    ) {
+      return undefined;
+    }
+    current?.controller.abort();
+
+    const registration = new AbortController();
+    registrationRef.current = {
+      destroySignal,
+      hostDestroySignal,
+      controller: registration,
+    };
+    const run = () => {
+      if (registration.signal.aborted) return;
+      registration.abort();
+      if (enabledRef.current) cleanupRef.current();
+    };
+    if (destroySignal?.aborted || hostDestroySignal?.aborted) {
+      run();
+      return undefined;
+    }
+    const options = { once: true, signal: registration.signal };
+    destroySignal?.addEventListener("abort", run, options);
+    hostDestroySignal?.addEventListener("abort", run, options);
+
+    // The listeners must survive standalone soft unmounts so a later
+    // permanent destroy still cleans up the retained resource state.
+    return undefined;
+  }, [destroySignal, enabled, hostDestroySignal]);
+};

package/src/runtime/useStreamingTiming.test.tsx

@@ -0,0 +1,96 @@
+// @vitest-environment jsdom
+
+import { cleanup, renderHook } from "./__tests__/tap";
+import type { UIMessage } from "ai";
+import { afterEach, expect, it, vi } from "vitest";
+import { aiSdkStreamingTimingAccessors } from "./useStreamingTiming";
+import { useStreamingTimingValue } from "@ulearning/ai-core/vue/internal";
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+const answer: UIMessage = {
+  id: "a1",
+  role: "assistant",
+  parts: [{ type: "text", text: "Previous answer" }],
+};
+
+it("times file output added to an existing answer without new text", () => {
+  vi.useFakeTimers();
+  const { result, rerender } = renderHook(
+    ({ messages, isRunning }) =>
+      useStreamingTimingValue(
+        messages,
+        isRunning,
+        aiSdkStreamingTimingAccessors,
+      ),
+    { initialProps: { messages: [answer], isRunning: false } },
+  );
+  vi.setSystemTime(1000);
+  rerender({ messages: [answer], isRunning: true });
+  vi.setSystemTime(1500);
+  rerender({
+    messages: [
+      {
+        ...answer,
+        parts: [
+          ...answer.parts,
+          {
+            type: "file",
+            mediaType: "image/png",
+            url: "https://example.com/image.png",
+          },
+        ],
+      },
+    ],
+    isRunning: false,
+  });
+  expect(result.current.a1).toMatchObject({
+    streamStartTime: 1000,
+    totalStreamTime: 500,
+    toolCallCount: 0,
+  });
+});
+
+it("leaves equivalent history without timing after an empty run", () => {
+  const { result, rerender } = renderHook(
+    ({ messages, isRunning }) =>
+      useStreamingTimingValue(
+        messages,
+        isRunning,
+        aiSdkStreamingTimingAccessors,
+      ),
+    { initialProps: { messages: [answer], isRunning: false } },
+  );
+  rerender({ messages: [structuredClone(answer)], isRunning: true });
+  rerender({ messages: [structuredClone(answer)], isRunning: false });
+  expect(result.current).toEqual({});
+});
+
+it("leaves older history untimed when regeneration drops the latest answer", () => {
+  const question: UIMessage = {
+    id: "u2",
+    role: "user",
+    parts: [{ type: "text", text: "Next question" }],
+  };
+  const secondAnswer: UIMessage = { ...answer, id: "a2" };
+  const { result, rerender } = renderHook(
+    ({ messages, isRunning }) =>
+      useStreamingTimingValue(
+        messages,
+        isRunning,
+        aiSdkStreamingTimingAccessors,
+      ),
+    {
+      initialProps: {
+        messages: [answer, question, secondAnswer],
+        isRunning: false,
+      },
+    },
+  );
+  rerender({ messages: [answer, question], isRunning: true });
+  rerender({ messages: [answer, question], isRunning: false });
+  expect(result.current).toEqual({});
+});