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

package/src/runtime/AISDKChat.artifacts.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+import { flushTapSync } from "@ulearning/ai-tap";
+import { AuiConfig, createAssistantClient } from "@ulearning/ai-store/client";
+import { AISDKChat } from "./AISDKChat";
+import { createControlledTransport } from "./__tests__/controlled-transport";
+
+// Runs the streaming round trip against the compiled dist entry (aliased in
+// vitest.artifacts.config.ts), exercising the public runtime artifact.
+describe("AISDKChat compiled output", () => {
+  it("streams a chat round trip through the compiled entry", async () => {
+    const { transport, emit, close } = createControlledTransport();
+    const handle = createAssistantClient(
+      AuiConfig({ threads: AISDKChat({ transport }) }),
+    );
+    try {
+      handle.subscribe(() => {});
+      const aui = handle.getClient();
+
+      flushTapSync(() => aui.composer.setText("hi"));
+      flushTapSync(() => aui.composer.send());
+
+      await vi.waitFor(() => {
+        expect(aui.thread.getState().isRunning).toBe(true);
+      });
+
+      emit(
+        { type: "start" },
+        { type: "text-start", id: "t1" },
+        { type: "text-delta", id: "t1", delta: "hello " },
+        { type: "text-delta", id: "t1", delta: "world" },
+        { type: "text-end", id: "t1" },
+        { type: "finish" },
+      );
+      close();
+
+      await vi.waitFor(() => {
+        const state = aui.thread.getState();
+        expect(state.isRunning).toBe(false);
+        expect(state.messages).toHaveLength(2);
+        expect(state.messages.at(-1)?.content).toContainEqual(
+          expect.objectContaining({ type: "text", text: "hello world" }),
+        );
+      });
+    } finally {
+      handle.destroy();
+    }
+  });
+});

package/src/runtime/AISDKChat.integration.test.tsx

@@ -0,0 +1,148 @@
+import { flushTapSync } from "@ulearning/ai-tap";
+// @vitest-environment jsdom
+
+import {
+  defineComponent,
+  h,
+  KeepAlive,
+  nextTick,
+  onMounted,
+  shallowRef,
+  type Component,
+} from "vue";
+import { act, render, waitFor } from "./__tests__/vue";
+import { AuiConfig, AuiProvider, useAui } from "@ulearning/ai-store";
+import type { ChatTransport, UIMessage } from "ai";
+import { describe, expect, it, vi } from "vitest";
+import { AISDKChat } from "./AISDKChat";
+import {
+  createCancellableTransport,
+  createStreamHarness,
+} from "./__tests__/controlled-transport";
+
+// Native retained-scope lifecycle checks replace React's development replay.
+// Deactivation must preserve the running transport; permanent release aborts once.
+const mountRetained = (Owner: Component) => {
+  const visible = shallowRef(true);
+  const view = render(
+    h(
+      defineComponent({
+        setup: () => () =>
+          h(KeepAlive, null, {
+            default: () => (visible.value ? h(Owner) : null),
+          }),
+      }),
+    ),
+  );
+  return { ...view, visible };
+};
+
+const LegacyProvider = defineComponent(
+  (props: { transport: ChatTransport<UIMessage> }, { slots }) => {
+    const aui = useAui(() =>
+      AuiConfig({ threads: AISDKChat({ transport: props.transport }) }),
+    );
+    return () => h(AuiProvider, { value: aui }, slots);
+  },
+  { props: ["transport"] },
+);
+
+for (const legacy of [false, true]) {
+  describe(
+    legacy
+      ? "AISDKChat legacy useAui host integration"
+      : "AISDKChat Vue integration",
+    () => {
+      it("aborts the in-flight transport after a real unmount", async () => {
+        const { transport, getCancelCount } = createCancellableTransport();
+        const { Probe, send, isRunning } = createStreamHarness();
+        const Owner = defineComponent({
+          setup: () => () =>
+            legacy
+              ? h(LegacyProvider, { transport }, { default: () => h(Probe) })
+              : h(
+                  AuiProvider,
+                  { config: AuiConfig({ threads: AISDKChat({ transport }) }) },
+                  { default: () => h(Probe) },
+                ),
+        });
+        const view = mountRetained(Owner);
+        await act(async () => send());
+        await waitFor(() => expect(isRunning()).toBe(true));
+        view.visible.value = false;
+        await nextTick();
+        expect(getCancelCount()).toBe(0);
+        view.visible.value = true;
+        await nextTick();
+        expect(isRunning()).toBe(true);
+        expect(getCancelCount()).toBe(0);
+        view.unmount();
+        await waitFor(() => expect(getCancelCount()).toBe(1));
+      });
+    },
+  );
+}
+
+describe("replacement transports", () => {
+  it("routes sends through a replacement transport", async () => {
+    const emptyStream = () =>
+      new ReadableStream({ start: (controller) => controller.close() });
+    const sendA = vi.fn(async () => emptyStream());
+    const sendB = vi.fn(async () => emptyStream());
+    const transportA: ChatTransport<UIMessage> = {
+      sendMessages: sendA,
+      reconnectToStream: vi.fn(),
+    };
+    const transportB: ChatTransport<UIMessage> = {
+      sendMessages: sendB,
+      reconnectToStream: vi.fn(),
+    };
+    let initialClient: ReturnType<typeof useAui> | undefined;
+    let currentClient: ReturnType<typeof useAui> | undefined;
+    const CaptureClient = defineComponent({
+      setup() {
+        const aui = useAui();
+        initialClient ??= aui;
+        currentClient = aui;
+        return () => null;
+      },
+    });
+    const SendOnLayout = defineComponent({
+      setup() {
+        const aui = useAui();
+        onMounted(() => {
+          flushTapSync(() => {
+            aui.composer.setText("hello");
+            aui.composer.send();
+          });
+        });
+        return () => null;
+      },
+    });
+    const App = defineComponent(
+      (props: { transport: ChatTransport<UIMessage>; send?: boolean }) => () =>
+        h(
+          AuiProvider,
+          {
+            config: AuiConfig({
+              threads: AISDKChat({ transport: props.transport }),
+            }),
+          },
+          {
+            default: () => [
+              h(CaptureClient),
+              props.send ? h(SendOnLayout) : null,
+            ],
+          },
+        ),
+      { props: ["transport", "send"] },
+    );
+
+    const view = render(h(App, { transport: transportA }));
+    await view.rerender(h(App, { transport: transportB, send: true }));
+
+    await waitFor(() => expect(sendB).toHaveBeenCalledOnce());
+    expect(sendA).not.toHaveBeenCalled();
+    expect(currentClient).toBe(initialClient);
+  });
+});

package/src/runtime/AISDKChat.test.ts

@@ -0,0 +1,241 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { flushTapSync } from "@ulearning/ai-tap";
+import { AuiConfig, createAssistantClient } from "@ulearning/ai-store/client";
+import { AISDKChat } from "./AISDKChat";
+import {
+  createCancellableTransport,
+  createControlledTransport,
+} from "./__tests__/controlled-transport";
+
+describe("AISDKChat as a standalone client config entry", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("streams a chat round trip without React", async () => {
+    const { transport, emit, close } = createControlledTransport();
+    const handle = createAssistantClient(
+      AuiConfig({ threads: AISDKChat({ transport }) }),
+    );
+    try {
+      handle.subscribe(() => {});
+      const aui = handle.getClient();
+
+      expect(aui.thread.getState().messages).toHaveLength(0);
+
+      flushTapSync(() => aui.composer.setText("hi"));
+      flushTapSync(() => aui.composer.send());
+
+      await vi.waitFor(() => {
+        const state = aui.thread.getState();
+        expect(state.isRunning).toBe(true);
+        expect(state.messages[0]).toMatchObject({ role: "user" });
+      });
+
+      emit(
+        { type: "start" },
+        { type: "text-start", id: "t1" },
+        { type: "text-delta", id: "t1", delta: "hello " },
+      );
+      await vi.waitFor(() => {
+        const last = aui.thread.getState().messages.at(-1);
+        expect(last?.role).toBe("assistant");
+        expect(last?.content).toContainEqual(
+          expect.objectContaining({ type: "text", text: "hello " }),
+        );
+      });
+
+      emit(
+        { type: "text-delta", id: "t1", delta: "world" },
+        { type: "text-end", id: "t1" },
+        { type: "finish" },
+      );
+      close();
+
+      await vi.waitFor(() => {
+        const state = aui.thread.getState();
+        expect(state.isRunning).toBe(false);
+        expect(state.messages).toHaveLength(2);
+        expect(state.messages.at(-1)?.content).toContainEqual(
+          expect.objectContaining({ type: "text", text: "hello world" }),
+        );
+      });
+    } finally {
+      handle.destroy();
+    }
+  });
+
+  it("stops an in-flight chat when its client is destroyed", async () => {
+    const { transport, getCancelCount } = createCancellableTransport();
+    const handle = createAssistantClient(
+      AuiConfig({ threads: AISDKChat({ transport }) }),
+    );
+    handle.subscribe(() => {});
+    const aui = handle.getClient();
+
+    try {
+      flushTapSync(() => aui.composer.setText("stop me"));
+      flushTapSync(() => aui.composer.send());
+      await vi.waitFor(() => {
+        expect(aui.thread.getState().isRunning).toBe(true);
+      });
+    } finally {
+      handle.destroy();
+    }
+
+    await vi.waitFor(() => {
+      expect(getCancelCount()).toBe(1);
+    });
+  });
+
+  it("stops a soft-unmounted chat on later client destruction", async () => {
+    const { transport, getCancelCount } = createCancellableTransport();
+    const handle = createAssistantClient(
+      AuiConfig({ threads: AISDKChat({ transport }) }),
+    );
+    const release = handle.subscribe(() => {});
+    const aui = handle.getClient();
+
+    flushTapSync(() => aui.composer.setText("keep streaming"));
+    flushTapSync(() => aui.composer.send());
+    await vi.waitFor(() => {
+      expect(aui.thread.getState().isRunning).toBe(true);
+    });
+
+    release();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(getCancelCount()).toBe(0);
+
+    handle.destroy();
+    await vi.waitFor(() => {
+      expect(getCancelCount()).toBe(1);
+    });
+  });
+
+  it("holds a send made during a run with unstable_enableMessageQueue", async () => {
+    const { transport, emit, close } = createControlledTransport();
+    const sendMessages = vi.spyOn(transport, "sendMessages");
+    const handle = createAssistantClient(
+      AuiConfig({
+        threads: AISDKChat({ transport, unstable_enableMessageQueue: true }),
+      }),
+    );
+    try {
+      handle.subscribe(() => {});
+      const aui = handle.getClient();
+      const queued = () =>
+        aui.composer.getState().queue.map((item) => item.prompt);
+
+      flushTapSync(() => aui.composer.setText("first"));
+      flushTapSync(() => aui.composer.send());
+      await vi.waitFor(() => {
+        expect(aui.thread.getState().isRunning).toBe(true);
+      });
+      expect(aui.thread.getState().capabilities.queue).toBe(true);
+
+      flushTapSync(() => aui.composer.setText("second"));
+      flushTapSync(() => aui.composer.send({ steer: false }));
+      await vi.waitFor(() => {
+        expect(queued()).toEqual(["second"]);
+      });
+      expect(sendMessages).toHaveBeenCalledTimes(1);
+
+      emit(
+        { type: "start" },
+        { type: "text-start", id: "t1" },
+        { type: "text-delta", id: "t1", delta: "one" },
+        { type: "text-end", id: "t1" },
+        { type: "finish" },
+      );
+      close();
+
+      await vi.waitFor(() => {
+        expect(sendMessages).toHaveBeenCalledTimes(2);
+      });
+      expect(
+        sendMessages.mock.calls[1]![0].messages.at(-1)?.parts,
+      ).toContainEqual(expect.objectContaining({ text: "second" }));
+      expect(queued()).toEqual([]);
+    } finally {
+      handle.destroy();
+    }
+  });
+
+  it("installs the RuntimeAdapter scope defaults", () => {
+    const { transport } = createControlledTransport();
+    const handle = createAssistantClient(
+      AuiConfig({ threads: AISDKChat({ transport }) }),
+    );
+    try {
+      handle.subscribe(() => {});
+      const aui = handle.getClient();
+
+      expect(aui.threads.getState().mainThreadId).toBeDefined();
+      expect(aui.tools.getState()).toBeDefined();
+      expect(aui.dataRenderers.getState()).toBeDefined();
+      expect(aui.thread.getState().isRunning).toBe(false);
+    } finally {
+      handle.destroy();
+    }
+  });
+
+  it("mounts with the default transport when no options are given", () => {
+    const handle = createAssistantClient(AuiConfig({ threads: AISDKChat({}) }));
+    try {
+      handle.subscribe(() => {});
+      const aui = handle.getClient();
+
+      expect(aui.thread.getState().messages).toHaveLength(0);
+      expect(aui.thread.getState().isRunning).toBe(false);
+    } finally {
+      handle.destroy();
+    }
+  });
+
+  it("sends through the default AssistantChatTransport with the generated id", async () => {
+    const sse = [
+      { type: "start" },
+      { type: "text-start", id: "t1" },
+      { type: "text-delta", id: "t1", delta: "ok" },
+      { type: "text-end", id: "t1" },
+      { type: "finish" },
+    ]
+      .map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`)
+      .join("");
+    const fetchMock = vi.fn<
+      (input: RequestInfo | URL, init: RequestInit) => Promise<Response>
+    >(
+      async () =>
+        new Response(sse, {
+          headers: { "content-type": "text/event-stream" },
+        }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const handle = createAssistantClient(
+      AuiConfig({ threads: AISDKChat({ id: "test-thread-1" }) }),
+    );
+    try {
+      handle.subscribe(() => {});
+      const aui = handle.getClient();
+
+      flushTapSync(() => aui.composer.setText("hi"));
+      flushTapSync(() => aui.composer.send());
+
+      await vi.waitFor(() => {
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const state = aui.thread.getState();
+        expect(state.isRunning).toBe(false);
+        expect(state.messages).toHaveLength(2);
+      });
+
+      const [url, init] = fetchMock.mock.calls[0]!;
+      expect(String(url)).toContain("/api/chat");
+      const body = JSON.parse(init.body as string);
+      expect(body.id).toBe("test-thread-1");
+      expect(body.messages).toHaveLength(1);
+    } finally {
+      handle.destroy();
+    }
+  });
+});

package/src/runtime/AISDKChat.ts

@@ -0,0 +1,43 @@
+"use client";
+
+import { resource, useResource } from "@ulearning/ai-tap";
+import { useState } from "@ulearning/ai-tap";
+import { generateId } from "ai";
+import type { UIMessage } from "ai";
+import {
+  RuntimeAdapter,
+  runtimeAdapterTransformScopes,
+} from "@ulearning/ai-core/store";
+import { attachTransformScopes } from "@ulearning/ai-store/client";
+import { useChatThread, type ChatThreadOptions } from "./useChatThread";
+
+export type AISDKChatOptions<UI_MESSAGE extends UIMessage = UIMessage> =
+  ChatThreadOptions<UI_MESSAGE>;
+
+const useAISDKChat = <UI_MESSAGE extends UIMessage = UIMessage>(
+  options?: AISDKChatOptions<UI_MESSAGE>,
+) => {
+  const [id] = useState(() => options?.id ?? generateId());
+  const [threadListItem] = useState(() => ({
+    initialize: async () => ({ remoteId: id, externalId: undefined }),
+  }));
+  const runtime = useChatThread(options, {
+    id,
+    isMainThread: true,
+    getThreadListItem: () => threadListItem,
+    stopOnClientDestroy: true,
+  });
+  return useResource(RuntimeAdapter(runtime));
+};
+
+/**
+ * `AuiConfig` entry that runs the AI SDK chat as the `threads` scope. Hosts the
+ * same orchestration as `useChatRuntime` inside the client's own resource tree,
+ * so it works with any `AssistantClient` host, React or not. Single thread; the
+ * multi-thread surface is {@link AISDKThreads}. The chat
+ * id is captured when the entry mounts, so a later `id` change in the options
+ * has no effect.
+ */
+export const AISDKChat = resource(useAISDKChat);
+
+attachTransformScopes(useAISDKChat, runtimeAdapterTransformScopes);