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

package/src/runtime/__tests__/controlled-transport.ts

@@ -0,0 +1,70 @@
+import type { ChatTransport, UIMessage, UIMessageChunk } from "ai";
+import { useAui, type AssistantClient } from "@ulearning/ai-store";
+import { defineComponent } from "vue";
+import { flushTapSync } from "@ulearning/ai-tap";
+
+export const createControlledTransport = () => {
+  let controller!: ReadableStreamDefaultController<UIMessageChunk>;
+  const transport: ChatTransport<UIMessage> = {
+    sendMessages: async () =>
+      new ReadableStream<UIMessageChunk>({
+        start(c) {
+          controller = c;
+        },
+      }),
+    reconnectToStream: async () => null,
+  };
+  return {
+    transport,
+    emit: (...chunks: UIMessageChunk[]) => {
+      for (const chunk of chunks) controller.enqueue(chunk);
+    },
+    close: () => controller.close(),
+  };
+};
+
+export const createCancellableTransport = () => {
+  let cancelCount = 0;
+  let controller!: ReadableStreamDefaultController<UIMessageChunk>;
+  const transport: ChatTransport<UIMessage> = {
+    sendMessages: async () =>
+      new ReadableStream<UIMessageChunk>({
+        start(c) {
+          controller = c;
+        },
+        cancel() {
+          cancelCount++;
+        },
+      }),
+    reconnectToStream: async () => null,
+  };
+  return {
+    transport,
+    getCancelCount: () => cancelCount,
+    emit: (...chunks: UIMessageChunk[]) => {
+      for (const chunk of chunks) controller.enqueue(chunk);
+    },
+    close: () => controller.close(),
+  };
+};
+
+export const nextTask = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+export const createStreamHarness = () => {
+  let aui: AssistantClient | undefined;
+  const Probe = defineComponent({
+    setup() {
+      aui = useAui();
+      return () => null;
+    },
+  });
+  return {
+    Probe,
+    send: () => {
+      flushTapSync(() => aui!.composer.setText("keep streaming"));
+      flushTapSync(() => aui!.composer.send());
+    },
+    isRunning: () => aui?.thread.getState().isRunning === true,
+    client: () => aui!,
+  };
+};

package/src/runtime/__tests__/tap.ts

@@ -0,0 +1,80 @@
+import { createTapRoot, flushTapSync, useState } from "@ulearning/ai-tap";
+import { afterEach, vi } from "vitest";
+import { Chat } from "@ai-sdk/vue";
+import type { ChatInit, UIMessage } from "ai";
+import { useChatSnapshot } from "../useChatSnapshot";
+
+const roots = new Set<{ unmount(): void }>();
+const refresh = new Set<() => void>();
+export const cleanup = () => {
+  for (const root of roots) root.unmount();
+  roots.clear();
+  refresh.clear();
+};
+afterEach(cleanup);
+export const waitFor = vi.waitFor;
+export function act<T>(action: () => Promise<T>): Promise<T>;
+export function act<T>(action: () => T): T;
+export function act(action: () => unknown): unknown {
+  const result = flushTapSync(action);
+  if (result instanceof Promise) {
+    // An async resource action schedules outside flushTapSync's callback.
+    // Render the fixtures' current inputs after settlement before exposing results.
+    const commit = () =>
+      flushTapSync(() => {
+        for (const read of refresh) read();
+      });
+    return result.then(
+      (value) => {
+        commit();
+        return value;
+      },
+      (error) => {
+        commit();
+        throw error;
+      },
+    );
+  }
+  return result;
+}
+
+/** Real Vue Chat state retained by a resource fixture, not a framework hook alias. */
+export function useTestChat<M extends UIMessage = UIMessage>(
+  options: ChatInit<M> & { chat?: Chat<M>; throttle?: number },
+) {
+  const [chat] = useState(() => options.chat ?? new Chat<M>(options));
+  return useChatSnapshot(chat, options.throttle);
+}
+
+/** Executes resource hooks on their actual host, preserving retained cells on updates. */
+export function renderHook<T, P = undefined>(
+  read: (props: P) => T,
+  options?: { initialProps: P },
+) {
+  let update!: (value: { props: P }) => void;
+  let props = options?.initialProps as P;
+  const root = createTapRoot(function useTestResource() {
+    const [input, setInput] = useState({ props });
+    update = setInput;
+    return read(input.props);
+  });
+  roots.add(root);
+  const commit = () => update({ props });
+  refresh.add(commit);
+  return {
+    result: {
+      get current() {
+        return root.getValue();
+      },
+    },
+    rerender(next: P = props) {
+      props = next;
+      flushTapSync(() => update({ props }));
+    },
+    unmount() {
+      root.unmount();
+      roots.delete(root);
+      refresh.delete(commit);
+    },
+  };
+}

package/src/runtime/__tests__/vue.ts

@@ -0,0 +1,46 @@
+import {
+  createApp,
+  defineComponent,
+  nextTick,
+  shallowRef,
+  type App,
+  type VNode,
+} from "vue";
+import { afterEach, vi } from "vitest";
+import { flushTapSync } from "@ulearning/ai-tap";
+
+const apps = new Map<App, HTMLElement>();
+export function cleanup() {
+  for (const [app, container] of apps) {
+    app.unmount();
+    container.remove();
+  }
+  apps.clear();
+}
+afterEach(cleanup);
+export const waitFor = vi.waitFor;
+export async function act<T>(action: () => T) {
+  const value = await flushTapSync(action);
+  await nextTick();
+  return value;
+}
+export function render(node: VNode) {
+  const source = shallowRef(node);
+  const container = document.createElement("div");
+  document.body.append(container);
+  const app = createApp(defineComponent({ setup: () => () => source.value }));
+  apps.set(app, container);
+  app.mount(container);
+  return {
+    container,
+    async rerender(next: VNode) {
+      source.value = next;
+      await nextTick();
+    },
+    unmount() {
+      app.unmount();
+      apps.delete(app);
+      container.remove();
+    },
+  };
+}

package/src/runtime/getResumableAdapter.ts

@@ -0,0 +1,16 @@
+import type { UIMessage } from "ai";
+import type { ChatTransport } from "ai";
+import { AssistantChatTransport } from "../transport/AssistantChatTransport";
+import type { AssistantChatResumableOptions } from "../transport/resumable";
+
+export const getResumableAdapter = <UI_MESSAGE extends UIMessage>(
+  transport: ChatTransport<UI_MESSAGE>,
+): AssistantChatResumableOptions | undefined => {
+  if (transport instanceof AssistantChatTransport) {
+    return transport.getResumableAdapter();
+  }
+  const candidate = (transport as { getResumableAdapter?: () => unknown })
+    .getResumableAdapter;
+  if (typeof candidate !== "function") return undefined;
+  return candidate.call(transport) as AssistantChatResumableOptions | undefined;
+};

package/src/runtime/toolHistoryCodec.test.ts

@@ -0,0 +1,187 @@
+import type {
+  RespondToToolApprovalOptions,
+  ThreadMessage,
+  Unstable_ToolInteractionLog,
+} from "@ulearning/ai-core";
+import { describe, expect, it } from "vitest";
+import {
+  addToolData,
+  collectToolApprovalResponses,
+  collectToolArtifacts,
+  collectToolInteractions,
+  restoreToolData,
+} from "./toolHistoryCodec";
+
+describe("tool history codec", () => {
+  it("round trips artifacts, interactions, and approval responses", () => {
+    const log: Unstable_ToolInteractionLog = {
+      entries: [{ type: "action", occurredAt: 1, payload: { refresh: true } }],
+    };
+    const response: RespondToToolApprovalOptions = {
+      approvalId: "approval-1",
+      approved: true,
+      answers: { scope: { optionIds: ["tests"] } },
+      reason: "Approved",
+    };
+    const threadMessage: ThreadMessage = {
+      id: "assistant-1",
+      role: "assistant",
+      content: [
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "weather",
+          args: {},
+          argsText: "{}",
+          result: undefined,
+          isError: false,
+          approval: { id: "approval-1" },
+        },
+      ],
+      createdAt: new Date(),
+      status: { type: "complete", reason: "stop" },
+      metadata: {
+        unstable_state: null,
+        unstable_annotations: [],
+        unstable_data: [],
+        steps: [],
+        custom: {},
+      },
+    };
+    const innerMessage = {
+      id: "inner-1",
+      parts: [{ toolCallId: "call-1", approval: { id: "approval-1" } }],
+      metadata: { custom: "kept" },
+    };
+    const artifacts = new Map<string, unknown>([
+      ["call-1", { preview: "sunny" }],
+      ["unrelated", "ignored"],
+    ]);
+    const interactions = new Map<string, Unstable_ToolInteractionLog>([
+      ["call-1", log],
+      ["unrelated", log],
+    ]);
+    const responses = new Map<string, RespondToToolApprovalOptions>([
+      ["approval-1", response],
+      ["unrelated", response],
+    ]);
+
+    const encoded = addToolData(
+      innerMessage,
+      collectToolArtifacts(threadMessage, artifacts),
+      collectToolInteractions(threadMessage, interactions),
+      collectToolApprovalResponses(threadMessage, responses),
+    );
+
+    expect(encoded).toEqual({
+      ...innerMessage,
+      metadata: {
+        custom: "kept",
+        __aui_toolArtifacts: { "call-1": { preview: "sunny" } },
+        __aui_toolInteractions: { "call-1": log },
+        __aui_toolApprovalResponses: {
+          "approval-1": {
+            approved: true,
+            answers: response.answers,
+            reason: "Approved",
+          },
+        },
+      },
+    });
+    expect(innerMessage.metadata).toEqual({ custom: "kept" });
+
+    const restoredArtifacts = new Map<string, unknown>();
+    const restoredInteractions = new Map<string, Unstable_ToolInteractionLog>();
+    const restoredResponses = new Map<string, RespondToToolApprovalOptions>();
+    expect(
+      restoreToolData(
+        encoded,
+        restoredArtifacts,
+        restoredInteractions,
+        restoredResponses,
+      ),
+    ).toEqual(innerMessage);
+    expect(restoredArtifacts).toEqual(
+      new Map([["call-1", { preview: "sunny" }]]),
+    );
+    expect(restoredInteractions).toEqual(new Map([["call-1", log]]));
+    expect(restoredResponses).toEqual(new Map([["approval-1", response]]));
+  });
+
+  it("leaves messages without tool metadata unchanged", () => {
+    const message = {
+      parts: [{ toolCallId: "call-1" }],
+      metadata: { custom: 1 },
+    };
+    expect(addToolData(message, undefined, undefined, undefined)).toBe(message);
+    expect(restoreToolData(message, new Map(), new Map(), new Map())).toBe(
+      message,
+    );
+    expect(
+      restoreToolData({ parts: [] }, new Map(), new Map(), new Map()),
+    ).toEqual({ parts: [] });
+  });
+
+  it("keeps live artifacts for matching calls while restoring other stored artifacts", () => {
+    const artifacts = new Map<string, unknown>([
+      ["call-live", { preview: "new" }],
+    ]);
+    restoreToolData(
+      {
+        metadata: {
+          __aui_toolArtifacts: {
+            "call-live": { preview: "stale" },
+            "call-stored": { preview: "earlier" },
+          },
+        },
+      },
+      artifacts,
+      undefined,
+      undefined,
+    );
+
+    expect(artifacts).toEqual(
+      new Map([
+        ["call-live", { preview: "new" }],
+        ["call-stored", { preview: "earlier" }],
+      ]),
+    );
+  });
+
+  it("ignores non-object messages and malformed metadata values", () => {
+    expect(
+      addToolData(null, { "call-1": "artifact" }, undefined, undefined),
+    ).toBeNull();
+    const invalidParts = { parts: "invalid" };
+    expect(
+      addToolData(invalidParts, { "call-1": "artifact" }, undefined, undefined),
+    ).toBe(invalidParts);
+    expect(restoreToolData(42, new Map(), new Map(), new Map())).toBe(42);
+    const invalidMetadata = { parts: [], metadata: "invalid" };
+    expect(
+      restoreToolData(invalidMetadata, new Map(), new Map(), new Map()),
+    ).toBe(invalidMetadata);
+
+    const artifacts = new Map<string, unknown>();
+    const interactions = new Map<string, Unstable_ToolInteractionLog>();
+    const responses = new Map<string, RespondToToolApprovalOptions>();
+    expect(
+      restoreToolData(
+        {
+          metadata: {
+            custom: "kept",
+            __aui_toolArtifacts: "invalid",
+            __aui_toolInteractions: 1,
+            __aui_toolApprovalResponses: [],
+          },
+        },
+        artifacts,
+        interactions,
+        responses,
+      ),
+    ).toEqual({ metadata: { custom: "kept" } });
+    expect(artifacts.size).toBe(0);
+    expect(interactions.size).toBe(0);
+    expect(responses.size).toBe(0);
+  });
+});

package/src/runtime/toolHistoryCodec.ts

@@ -0,0 +1,245 @@
+import type {
+  RespondToToolApprovalOptions,
+  ThreadMessage,
+  Unstable_ToolInteractionLog,
+} from "@ulearning/ai-core";
+import {
+  appendToolInteraction,
+  isJSONValueEqual,
+  isRecord,
+  readToolInteractionLog,
+} from "@ulearning/ai-core/internal";
+import { normalizeToolApprovalAnswers } from "../converters/toolApprovalAnswers";
+
+const TOOL_ARTIFACTS_METADATA_KEY = "__aui_toolArtifacts";
+const TOOL_INTERACTIONS_METADATA_KEY = "__aui_toolInteractions";
+const TOOL_APPROVAL_RESPONSES_METADATA_KEY = "__aui_toolApprovalResponses";
+
+export type StoredToolApprovalResponse = Omit<
+  RespondToToolApprovalOptions,
+  "approvalId"
+>;
+
+const mergeInteractionLogs = (
+  stored: Unstable_ToolInteractionLog,
+  current: Unstable_ToolInteractionLog | undefined,
+): Unstable_ToolInteractionLog => {
+  const incoming = readToolInteractionLog(current);
+  if (!incoming) return stored;
+  const omitted = Math.max(stored.omitted ?? 0, incoming.omitted ?? 0);
+  let merged: Unstable_ToolInteractionLog = {
+    entries: stored.entries,
+    ...(omitted ? { omitted } : undefined),
+  };
+  for (const entry of incoming.entries) {
+    if (
+      merged.entries.some(
+        (existing) =>
+          existing.type === entry.type &&
+          existing.occurredAt === entry.occurredAt &&
+          isJSONValueEqual(existing.payload, entry.payload),
+      )
+    ) {
+      continue;
+    }
+    merged = appendToolInteraction(merged, entry);
+  }
+  return merged;
+};
+
+export const collectToolArtifacts = (
+  message: ThreadMessage,
+  toolArtifacts: ReadonlyMap<string, unknown> | undefined,
+) => {
+  if (!toolArtifacts) return undefined;
+  const entries = message.content.flatMap((part) => {
+    if (part.type !== "tool-call") return [];
+    const artifact = toolArtifacts.get(part.toolCallId);
+    return artifact === undefined ? [] : [[part.toolCallId, artifact] as const];
+  });
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+};
+
+export const collectToolInteractions = (
+  message: ThreadMessage,
+  toolInteractions:
+    | ReadonlyMap<string, Unstable_ToolInteractionLog>
+    | undefined,
+) => {
+  if (!toolInteractions) return undefined;
+  const entries = message.content.flatMap((part) => {
+    if (part.type !== "tool-call") return [];
+    const interactions = toolInteractions.get(part.toolCallId);
+    return interactions === undefined
+      ? []
+      : [[part.toolCallId, interactions] as const];
+  });
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+};
+
+export const collectToolApprovalResponses = (
+  message: ThreadMessage,
+  toolApprovalResponses:
+    | ReadonlyMap<string, RespondToToolApprovalOptions>
+    | undefined,
+) => {
+  if (!toolApprovalResponses) return undefined;
+  const entries = message.content.flatMap((part) => {
+    if (part.type !== "tool-call" || !part.approval) return [];
+    const response = toolApprovalResponses.get(part.approval.id);
+    if (!response) return [];
+    return [
+      [
+        part.approval.id,
+        {
+          approved: response.approved,
+          ...(response.optionId != null && { optionId: response.optionId }),
+          ...(response.text != null && { text: response.text }),
+          ...(response.answers != null && { answers: response.answers }),
+          ...(response.reason != null && { reason: response.reason }),
+        },
+      ] as const,
+    ];
+  });
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+};
+
+export const addToolData = <TMessage>(
+  message: TMessage,
+  toolArtifacts: Record<string, unknown> | undefined,
+  toolInteractions: Record<string, Unstable_ToolInteractionLog> | undefined,
+  toolApprovalResponses: Record<string, StoredToolApprovalResponse> | undefined,
+): TMessage => {
+  if (
+    (!toolArtifacts && !toolInteractions && !toolApprovalResponses) ||
+    !isRecord(message) ||
+    !Array.isArray(message.parts)
+  )
+    return message;
+  const toolCallIds = message.parts.flatMap((part) => {
+    if (!isRecord(part) || typeof part.toolCallId !== "string") return [];
+    return [part.toolCallId];
+  });
+  const artifacts = toolArtifacts
+    ? Object.fromEntries(
+        toolCallIds.flatMap((toolCallId) =>
+          Object.hasOwn(toolArtifacts, toolCallId)
+            ? [[toolCallId, toolArtifacts[toolCallId]] as const]
+            : [],
+        ),
+      )
+    : undefined;
+  const interactions = toolInteractions
+    ? Object.fromEntries(
+        toolCallIds.flatMap((toolCallId) =>
+          Object.hasOwn(toolInteractions, toolCallId)
+            ? [[toolCallId, toolInteractions[toolCallId]] as const]
+            : [],
+        ),
+      )
+    : undefined;
+  const approvalIds = message.parts.flatMap((part) => {
+    if (!isRecord(part) || !isRecord(part.approval)) return [];
+    const approvalId = part.approval.id;
+    return typeof approvalId === "string" ? [approvalId] : [];
+  });
+  const approvalResponses = toolApprovalResponses
+    ? Object.fromEntries(
+        approvalIds.flatMap((approvalId) =>
+          Object.hasOwn(toolApprovalResponses, approvalId)
+            ? [[approvalId, toolApprovalResponses[approvalId]] as const]
+            : [],
+        ),
+      )
+    : undefined;
+  const hasArtifacts = !!artifacts && Object.keys(artifacts).length > 0;
+  const hasInteractions =
+    !!interactions && Object.keys(interactions).length > 0;
+  const hasApprovalResponses =
+    !!approvalResponses && Object.keys(approvalResponses).length > 0;
+  if (!hasArtifacts && !hasInteractions && !hasApprovalResponses)
+    return message;
+  const metadata = isRecord(message.metadata) ? message.metadata : {};
+  return {
+    ...message,
+    metadata: {
+      ...metadata,
+      ...(hasArtifacts && { [TOOL_ARTIFACTS_METADATA_KEY]: artifacts }),
+      ...(hasInteractions && {
+        [TOOL_INTERACTIONS_METADATA_KEY]: interactions,
+      }),
+      ...(hasApprovalResponses && {
+        [TOOL_APPROVAL_RESPONSES_METADATA_KEY]: approvalResponses,
+      }),
+    },
+  } as TMessage;
+};
+
+export const restoreToolData = <TMessage>(
+  message: TMessage,
+  toolArtifacts: Map<string, unknown> | undefined,
+  toolInteractions: Map<string, Unstable_ToolInteractionLog> | undefined,
+  toolApprovalResponses: Map<string, RespondToToolApprovalOptions> | undefined,
+): TMessage => {
+  if (!isRecord(message) || !isRecord(message.metadata)) return message;
+  const metadata = message.metadata;
+  const hasArtifacts = Object.hasOwn(metadata, TOOL_ARTIFACTS_METADATA_KEY);
+  const hasInteractions = Object.hasOwn(
+    metadata,
+    TOOL_INTERACTIONS_METADATA_KEY,
+  );
+  const hasApprovalResponses = Object.hasOwn(
+    metadata,
+    TOOL_APPROVAL_RESPONSES_METADATA_KEY,
+  );
+  if (!hasArtifacts && !hasInteractions && !hasApprovalResponses)
+    return message;
+  const artifacts = metadata[TOOL_ARTIFACTS_METADATA_KEY];
+  if (toolArtifacts && isRecord(artifacts)) {
+    for (const [toolCallId, artifact] of Object.entries(artifacts)) {
+      if (!toolArtifacts.has(toolCallId))
+        toolArtifacts.set(toolCallId, artifact);
+    }
+  }
+  const interactions = metadata[TOOL_INTERACTIONS_METADATA_KEY];
+  if (toolInteractions && isRecord(interactions)) {
+    for (const [toolCallId, value] of Object.entries(interactions)) {
+      const log = readToolInteractionLog(value);
+      if (log) {
+        toolInteractions.set(
+          toolCallId,
+          mergeInteractionLogs(log, toolInteractions.get(toolCallId)),
+        );
+      }
+    }
+  }
+  const approvalResponses = metadata[TOOL_APPROVAL_RESPONSES_METADATA_KEY];
+  if (toolApprovalResponses && isRecord(approvalResponses)) {
+    for (const [approvalId, value] of Object.entries(approvalResponses)) {
+      if (!isRecord(value) || typeof value.approved !== "boolean") continue;
+      const answers = normalizeToolApprovalAnswers(value.answers);
+      toolApprovalResponses.set(approvalId, {
+        approvalId,
+        approved: value.approved,
+        ...(typeof value.optionId === "string" && {
+          optionId: value.optionId,
+        }),
+        ...(typeof value.text === "string" && { text: value.text }),
+        ...(answers && Object.keys(answers).length > 0 && { answers }),
+        ...(typeof value.reason === "string" && { reason: value.reason }),
+      });
+    }
+  }
+  const {
+    [TOOL_ARTIFACTS_METADATA_KEY]: _,
+    [TOOL_INTERACTIONS_METADATA_KEY]: __,
+    [TOOL_APPROVAL_RESPONSES_METADATA_KEY]: ___,
+    ...restMetadata
+  } = metadata;
+  const { metadata: _metadata, ...restMessage } = message;
+  return (
+    Object.keys(restMetadata).length === 0
+      ? restMessage
+      : { ...restMessage, metadata: restMetadata }
+  ) as TMessage;
+};