@assistant-ui/core 0.3.12 → 0.3.14

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

@@ -14,6 +14,12 @@ import {
 } from "assistant-cloud";
 import { auiV0Decode, auiV0Encode } from "./auiV0";
 import { type AssistantClient, getClientId, useAui } from "@assistant-ui/store";
+import type { ThreadListItemMethods } from "../../../store/scopes/thread-list-item";
+
+type CloudThreadListItem = Pick<
+  ThreadListItemMethods,
+  "getState" | "initialize"
+>;
 
 const globalPersistence = new WeakMap<
   getClientId.ClientId,
@@ -36,8 +42,10 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
     return this.getAui();
   }
 
-  private get _persistence(): CloudMessagePersistence {
-    const key = getClientId(this.aui.threadListItem);
+  private getPersistence(
+    threadListItem: CloudThreadListItem = this.aui.threadListItem,
+  ): CloudMessagePersistence {
+    const key = getClientId(threadListItem);
     if (!globalPersistence.has(key)) {
       globalPersistence.set(
         key,
@@ -47,24 +55,57 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
     return globalPersistence.get(key)!;
   }
 
+  private get _persistence(): CloudMessagePersistence {
+    return this.getPersistence();
+  }
+
+  private tryGetKeyedThreadListItem(): CloudThreadListItem | undefined {
+    const live = this.aui.threadListItem;
+    if (!live.source) return undefined;
+    const id = live.getState().id;
+    if (id === undefined) return undefined;
+    return this.aui.threads.item({ id });
+  }
+
   withFormat<TMessage, TStorageFormat extends Record<string, unknown>>(
     formatAdapter: MessageFormatAdapter<TMessage, TStorageFormat>,
   ): GenericThreadHistoryAdapter<TMessage> {
     const adapter = this;
-    const formatted = createFormattedPersistence(
-      this._persistence,
-      formatAdapter,
-    );
+    let threadListItem: CloudThreadListItem | undefined;
+    const pinCurrent = () => {
+      const next = adapter.tryGetKeyedThreadListItem();
+      if (next) threadListItem = next;
+      return threadListItem;
+    };
+    const resolvePinned = () => threadListItem ?? pinCurrent();
+    const getFormatted = () =>
+      createFormattedPersistence(adapter._persistence, formatAdapter);
+    const getTargetFormatted = (item: CloudThreadListItem) =>
+      createFormattedPersistence(adapter.getPersistence(item), formatAdapter);
     return {
-      // Note: callers must also call reportTelemetry() for run tracking
+      pin() {
+        pinCurrent();
+      },
       async append(item: MessageFormatItem<TMessage>) {
-        const { remoteId } = await adapter.aui.threadListItem.initialize();
-        await formatted.append(remoteId, item);
+        const pinned = resolvePinned();
+        if (!pinned) {
+          throw new Error(
+            "Cannot persist cloud history without a thread list item.",
+          );
+        }
+        const remoteId =
+          pinned.getState().remoteId ?? (await pinned.initialize()).remoteId;
+        await getTargetFormatted(pinned).append(remoteId, item);
       },
       async update(item: MessageFormatItem<TMessage>, localMessageId: string) {
-        const remoteId = adapter.aui.threadListItem.getState().remoteId;
-        if (!remoteId) return;
-        await formatted.update?.(remoteId, item, localMessageId);
+        const pinned = resolvePinned();
+        const remoteId = pinned?.getState().remoteId;
+        if (!remoteId || !pinned) return;
+        await getTargetFormatted(pinned).update?.(
+          remoteId,
+          item,
+          localMessageId,
+        );
       },
       async delete() {
         throw new Error(
@@ -85,12 +126,15 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
           formatAdapter.format,
           encodedRunMessages,
           options,
+          resolvePinned(),
         );
       },
       async load(): Promise<MessageFormatRepository<TMessage>> {
-        const remoteId = adapter.aui.threadListItem.getState().remoteId;
+        pinCurrent();
+        const live = adapter.aui.threadListItem;
+        const remoteId = live.source ? live.getState().remoteId : undefined;
         if (!remoteId) return { messages: [] };
-        return formatted.load(remoteId);
+        return getFormatted().load(remoteId);
       },
     };
   }
@@ -153,10 +197,12 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
       durationMs?: number;
       stepTimestamps?: StepTimestamp[];
     },
+    threadListItem?: CloudThreadListItem,
   ) {
     if (!this.cloudRef.current.telemetry.enabled) return;
 
-    const remoteId = this.aui.threadListItem.getState().remoteId;
+    const remoteId = (threadListItem ?? this.aui.threadListItem).getState()
+      .remoteId;
     if (!remoteId) return;
 
     const extracted = extractRunTelemetry(format, runMessages);

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

@@ -19,10 +19,12 @@ const guessAttachmentType = (
 export class CloudFileAttachmentAdapter implements AttachmentAdapter {
   public accept = "*";
 
-  private cloud: AssistantCloud;
+  private getCloud: () => AssistantCloud;
 
-  constructor(cloud: AssistantCloud) {
-    this.cloud = cloud;
+  constructor(cloud: AssistantCloud);
+  constructor(getCloud: () => AssistantCloud);
+  constructor(cloud: AssistantCloud | (() => AssistantCloud)) {
+    this.getCloud = typeof cloud === "function" ? cloud : () => cloud;
   }
 
   private uploadedUrls = new Map<string, string>();
@@ -46,7 +48,7 @@ export class CloudFileAttachmentAdapter implements AttachmentAdapter {
 
     try {
       const { signedUrl, publicUrl } =
-        await this.cloud.files.generatePresignedUploadUrl({
+        await this.getCloud().files.generatePresignedUploadUrl({
           filename: file.name,
         });
       const res = await fetch(signedUrl, {

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

@@ -79,6 +79,11 @@ type AuiV0MessagePart =
       readonly mimeType: string;
       readonly filename?: string;
       readonly sourceType?: "url" | "id";
+    }
+  | {
+      readonly type: "data";
+      readonly name: string;
+      readonly data: ReadonlyJSONValue;
     };
 
 type AuiV0AttachmentPart =
@@ -296,8 +301,19 @@ export function auiV0Encode(message: ThreadMessage): AuiV0Message {
             ...(part.sourceType ? { sourceType: part.sourceType } : undefined),
           };
 
+        case "data": {
+          if (!isJSONValue(part.data)) {
+            console.warn(`data part is not JSON! ${JSON.stringify(part)}`);
+          }
+          return {
+            type: "data",
+            name: part.name,
+            data: part.data as ReadonlyJSONValue,
+          };
+        }
+
         default: {
-          const unhandledType: "audio" | "data" | "generative-ui" = type;
+          const unhandledType: "audio" | "generative-ui" = type;
           throw new Error(
             `Message part type not supported by aui/v0: ${unhandledType}`,
           );

package/src/react/runtimes/cloud/useCloudThreadListAdapter.tsx

@@ -3,16 +3,21 @@ declare const process: { env: Record<string, string | undefined> };
 import {
   type FC,
   type PropsWithChildren,
+  type RefObject,
   useCallback,
   useEffect,
   useMemo,
   useRef,
+  useState,
 } from "react";
 import { AssistantCloud } from "assistant-cloud";
 import type { RemoteThreadListAdapter } from "../../../runtimes/remote-thread-list/types";
 import { InMemoryThreadListAdapter } from "../../../runtimes/remote-thread-list/adapter/in-memory";
 import { useAssistantCloudThreadHistoryAdapter } from "./AssistantCloudThreadHistoryAdapter";
-import { RuntimeAdapterProvider } from "../RuntimeAdapterProvider";
+import {
+  RuntimeAdapterProvider,
+  type RuntimeAdapters,
+} from "../RuntimeAdapterProvider";
 import { CloudFileAttachmentAdapter } from "./CloudFileAttachmentAdapter";
 import { isRecord } from "../../../utils/json/is-json";
 
@@ -39,6 +44,29 @@ const autoCloud = baseUrl
 
 const CLOUD_THREAD_PAGE_SIZE = 20;
 
+const useCloudThreadListAdapters = (
+  adapterRef: RefObject<CloudThreadListAdapterOptions>,
+): RuntimeAdapters => {
+  const history = useAssistantCloudThreadHistoryAdapter({
+    get current() {
+      return adapterRef.current.cloud ?? autoCloud!;
+    },
+  });
+  const [attachments] = useState(
+    () =>
+      new CloudFileAttachmentAdapter(
+        () => adapterRef.current.cloud ?? autoCloud!,
+      ),
+  );
+  return useMemo(
+    () => ({
+      history,
+      attachments,
+    }),
+    [history, attachments],
+  );
+};
+
 export const useCloudThreadListAdapter = (
   adapter: CloudThreadListAdapterOptions,
 ): RemoteThreadListAdapter => {
@@ -47,27 +75,13 @@ export const useCloudThreadListAdapter = (
     adapterRef.current = adapter;
   }, [adapter]);
 
+  const unstable_useAdapters = useCallback(function useCloudAdapters() {
+    return useCloudThreadListAdapters(adapterRef);
+  }, []);
+
   const unstable_Provider = useCallback<FC<PropsWithChildren>>(
     function Provider({ children }) {
-      const history = useAssistantCloudThreadHistoryAdapter({
-        get current() {
-          return adapterRef.current.cloud ?? autoCloud!;
-        },
-      });
-      const cloudInstance = adapterRef.current.cloud ?? autoCloud!;
-      const attachments = useMemo(
-        () => new CloudFileAttachmentAdapter(cloudInstance),
-        [cloudInstance],
-      );
-
-      const adapters = useMemo(
-        () => ({
-          history,
-          attachments,
-        }),
-        [history, attachments],
-      );
-
+      const adapters = useCloudThreadListAdapters(adapterRef);
       return (
         <RuntimeAdapterProvider adapters={adapters}>
           {children}
@@ -175,6 +189,7 @@ export const useCloudThreadListAdapter = (
       },
 
       unstable_Provider,
+      unstable_useAdapters,
     };
-  }, [cloud, unstable_Provider]);
+  }, [cloud, unstable_Provider, unstable_useAdapters]);
 };

package/src/react/runtimes/cloud/useCloudThreadListRuntime.test.tsx

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+
+import { renderHook } from "@testing-library/react";
+import type { AssistantCloud } from "assistant-cloud";
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantRuntime } from "../../../runtime/api/assistant-runtime";
+import { useCloudThreadListRuntime } from "./useCloudThreadListRuntime";
+
+const mocks = vi.hoisted(() => ({
+  useCloudThreadListAdapter: vi.fn(),
+  useRemoteThreadListRuntime: vi.fn(),
+}));
+
+vi.mock("./useCloudThreadListAdapter", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./useCloudThreadListAdapter")>()),
+  useCloudThreadListAdapter: mocks.useCloudThreadListAdapter,
+}));
+
+vi.mock("../useRemoteThreadListRuntime", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../useRemoteThreadListRuntime")>()),
+  useRemoteThreadListRuntime: mocks.useRemoteThreadListRuntime,
+}));
+
+describe("useCloudThreadListRuntime", () => {
+  it("forwards cloud options to the adapter and nests the runtime hook", () => {
+    const cloud = { threads: {} } as AssistantCloud;
+    const runtimeHook = () => ({}) as AssistantRuntime;
+    const create = vi.fn();
+    const del = vi.fn();
+    const adapter = { list: vi.fn() };
+    const runtime = { kind: "runtime" };
+    mocks.useCloudThreadListAdapter.mockReturnValue(adapter);
+    mocks.useRemoteThreadListRuntime.mockReturnValue(runtime);
+
+    const { result } = renderHook(() =>
+      useCloudThreadListRuntime({
+        cloud,
+        runtimeHook,
+        create,
+        delete: del,
+      }),
+    );
+
+    expect(mocks.useCloudThreadListAdapter).toHaveBeenCalledWith({
+      cloud,
+      create,
+      delete: del,
+    });
+    expect(mocks.useRemoteThreadListRuntime).toHaveBeenCalledWith({
+      runtimeHook,
+      adapter,
+      allowNesting: true,
+    });
+    expect(result.current).toBe(runtime);
+  });
+});

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

@@ -0,0 +1,31 @@
+"use client";
+
+import type { AssistantCloud } from "assistant-cloud";
+import type { AssistantRuntime } from "../../../runtime/api/assistant-runtime";
+import { useRemoteThreadListRuntime } from "../useRemoteThreadListRuntime";
+import { useCloudThreadListAdapter } from "./useCloudThreadListAdapter";
+
+type ThreadData = {
+  externalId: string;
+};
+
+type CloudThreadListAdapter = {
+  cloud: AssistantCloud;
+
+  runtimeHook: () => AssistantRuntime;
+
+  create?(): Promise<ThreadData>;
+  delete?(threadId: string): Promise<void>;
+};
+
+export function useCloudThreadListRuntime({
+  runtimeHook,
+  ...adapterOptions
+}: CloudThreadListAdapter) {
+  const adapter = useCloudThreadListAdapter(adapterOptions);
+  return useRemoteThreadListRuntime({
+    runtimeHook,
+    adapter,
+    allowNesting: true,
+  });
+}

package/src/react/runtimes/external-message-converter.test.ts

@@ -344,6 +344,149 @@ describe("convertExternalMessages", () => {
     });
   });
 
+  describe("metadata merging across joined messages", () => {
+    it("keeps the final assistant message's metadata after a tool call", () => {
+      const messages = [
+        {
+          id: "a1",
+          role: "assistant" as const,
+          content: [
+            {
+              type: "tool-call" as const,
+              toolCallId: "t1",
+              toolName: "search",
+              args: {},
+            },
+          ],
+        },
+        {
+          role: "tool" as const,
+          toolCallId: "t1",
+          toolName: "search",
+          result: { ok: true },
+        },
+        {
+          id: "a2",
+          role: "assistant" as const,
+          content: [{ type: "text" as const, text: "final answer" }],
+          metadata: {
+            unstable_annotations: [{ note: "final" }],
+            steps: [{ usage: { promptTokens: 1, completionTokens: 2 } }],
+          },
+        },
+      ];
+
+      const callback: useExternalMessageConverter.Callback<
+        (typeof messages)[number]
+      > = (msg) => msg as useExternalMessageConverter.Message;
+
+      const result = convertExternalMessages(messages, callback, false, {});
+
+      expect(result).toHaveLength(1);
+      const metadata = result[0]!.metadata as any;
+      expect(metadata.unstable_annotations).toEqual([{ note: "final" }]);
+      expect(metadata.steps).toEqual([
+        { usage: { promptTokens: 1, completionTokens: 2 } },
+      ]);
+    });
+
+    it("accumulates annotations and data from every joined assistant message", () => {
+      const messages = [
+        {
+          id: "a1",
+          role: "assistant" as const,
+          content: [{ type: "text" as const, text: "first" }],
+          metadata: {
+            unstable_annotations: [{ a: 1 }],
+            unstable_data: [{ d: 1 }],
+          },
+        },
+        {
+          id: "a2",
+          role: "assistant" as const,
+          content: [{ type: "text" as const, text: "second" }],
+          metadata: {
+            unstable_annotations: [{ a: 2 }],
+            unstable_data: [{ d: 2 }],
+          },
+        },
+      ];
+
+      const callback: useExternalMessageConverter.Callback<
+        (typeof messages)[number]
+      > = (msg) => msg as useExternalMessageConverter.Message;
+
+      const result = convertExternalMessages(messages, callback, false, {});
+
+      expect(result).toHaveLength(1);
+      const metadata = result[0]!.metadata as any;
+      expect(metadata.unstable_annotations).toEqual([{ a: 1 }, { a: 2 }]);
+      expect(metadata.unstable_data).toEqual([{ d: 1 }, { d: 2 }]);
+    });
+
+    it("keeps the last joined output's timing, dropping earlier timing", () => {
+      const messages = [
+        {
+          id: "a1",
+          role: "assistant" as const,
+          content: [{ type: "text" as const, text: "first" }],
+          metadata: {
+            timing: { streamStartTime: 1 },
+          },
+        },
+        {
+          id: "a2",
+          role: "assistant" as const,
+          content: [{ type: "text" as const, text: "second" }],
+          metadata: {
+            timing: { streamStartTime: 2 },
+          },
+        },
+      ];
+
+      const callback: useExternalMessageConverter.Callback<
+        (typeof messages)[number]
+      > = (msg) => msg as useExternalMessageConverter.Message;
+
+      const result = convertExternalMessages(messages, callback, false, {});
+
+      expect(result).toHaveLength(1);
+      const metadata = result[0]!.metadata as any;
+      expect(metadata.timing).toEqual({ streamStartTime: 2 });
+    });
+
+    it("merges custom across joined outputs, with later keys overwriting earlier ones", () => {
+      const messages = [
+        {
+          id: "a1",
+          role: "assistant" as const,
+          content: [{ type: "text" as const, text: "first" }],
+          metadata: {
+            custom: { author: "agent-a", branch: "main" },
+          },
+        },
+        {
+          id: "a2",
+          role: "assistant" as const,
+          content: [{ type: "text" as const, text: "second" }],
+          metadata: {
+            custom: { author: "agent-b" },
+          },
+        },
+      ];
+
+      const callback: useExternalMessageConverter.Callback<
+        (typeof messages)[number]
+      > = (msg) => msg as useExternalMessageConverter.Message;
+
+      const result = convertExternalMessages(messages, callback, false, {});
+
+      expect(result).toHaveLength(1);
+      const metadata = result[0]!.metadata as any;
+      expect(metadata.custom).toEqual({ author: "agent-b", branch: "main" });
+    });
+  });
+
   describe("invalid converter output", () => {
     it("throws a descriptive error when the callback returns undefined", () => {
       const messages = [{ id: "m1", type: "remove" }];

package/src/react/runtimes/external-message-converter.ts

@@ -200,52 +200,52 @@ const joinExternalMessages = (
                 ...output.attachments,
               ];
             }
+          }
 
-            if (output.metadata) {
-              assistantMessage.metadata ??= {};
-              if (output.metadata.unstable_state !== undefined) {
-                assistantMessage.metadata.unstable_state =
-                  output.metadata.unstable_state;
-              }
-              if (output.metadata.unstable_annotations) {
-                assistantMessage.metadata.unstable_annotations = [
-                  ...(assistantMessage.metadata.unstable_annotations ?? []),
-                  ...output.metadata.unstable_annotations,
-                ];
-              }
-              if (output.metadata.unstable_data) {
-                assistantMessage.metadata.unstable_data = [
-                  ...(assistantMessage.metadata.unstable_data ?? []),
-                  ...output.metadata.unstable_data,
-                ];
-              }
-              if (output.metadata.steps) {
-                assistantMessage.metadata.steps = [
-                  ...(assistantMessage.metadata.steps ?? []),
-                  ...output.metadata.steps,
-                ];
-              }
-              if (output.metadata.custom) {
-                assistantMessage.metadata.custom = {
-                  ...(assistantMessage.metadata.custom ?? {}),
-                  ...output.metadata.custom,
-                };
-              }
+          if (output.metadata) {
+            assistantMessage.metadata ??= {};
+            if (output.metadata.unstable_state !== undefined) {
+              assistantMessage.metadata.unstable_state =
+                output.metadata.unstable_state;
+            }
+            if (output.metadata.unstable_annotations) {
+              assistantMessage.metadata.unstable_annotations = [
+                ...(assistantMessage.metadata.unstable_annotations ?? []),
+                ...output.metadata.unstable_annotations,
+              ];
+            }
+            if (output.metadata.unstable_data) {
+              assistantMessage.metadata.unstable_data = [
+                ...(assistantMessage.metadata.unstable_data ?? []),
+                ...output.metadata.unstable_data,
+              ];
+            }
+            if (output.metadata.steps) {
+              assistantMessage.metadata.steps = [
+                ...(assistantMessage.metadata.steps ?? []),
+                ...output.metadata.steps,
+              ];
+            }
+            if (output.metadata.custom) {
+              assistantMessage.metadata.custom = {
+                ...(assistantMessage.metadata.custom ?? {}),
+                ...output.metadata.custom,
+              };
+            }
 
-              if (output.metadata.timing) {
-                assistantMessage.metadata.timing = output.metadata.timing;
-              }
+            if (output.metadata.timing) {
+              assistantMessage.metadata.timing = output.metadata.timing;
+            }
 
-              if (output.metadata.submittedFeedback) {
-                assistantMessage.metadata.submittedFeedback =
-                  output.metadata.submittedFeedback;
-              }
+            if (output.metadata.submittedFeedback) {
+              assistantMessage.metadata.submittedFeedback =
+                output.metadata.submittedFeedback;
+            }
 
-              if (output.metadata.isOptimistic) {
-                assistantMessage.metadata.isOptimistic = true;
-              }
+            if (output.metadata.isOptimistic) {
+              assistantMessage.metadata.isOptimistic = true;
             }
-            // TODO keep this in sync
+            // TODO keep this in sync with ThreadMessageLike["metadata"] / fromThreadMessageLike
           }
 
           // Add content parts, merging reasoning parts with same parentId

package/src/react/runtimes/remote-thread-hook-on-tap.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import {
+  createTapRoot,
+  resource,
+  useResources,
+  withKey,
+} from "@assistant-ui/tap";
+import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+
+const EMPTY_MESSAGES: readonly never[] = [];
+
+const useTestThreadRuntime = () =>
+  useExternalStoreRuntime({
+    messages: EMPTY_MESSAGES,
+    isRunning: false,
+    onNew: async () => {},
+  });
+
+const TestThread = resource(useTestThreadRuntime);
+
+describe("runtimeHook hosted under one tap root", () => {
+  it("starts N independent threads as keyed resources", () => {
+    const ids = ["a", "b", "c"] as const;
+    const root = createTapRoot(function RemoteThreadListHost() {
+      return useResources(ids.map((id) => withKey(id, TestThread(), [id])));
+    });
+
+    try {
+      const runtimes = root.getValue();
+      expect(runtimes).toHaveLength(3);
+      for (const runtime of runtimes) {
+        expect(runtime.thread.getState().messages).toEqual([]);
+        expect(runtime.thread.getState().isRunning).toBe(false);
+      }
+      expect(new Set(runtimes).size).toBe(3);
+    } finally {
+      root.unmount();
+    }
+  });
+
+  it("keeps a sibling resource after another key is removed", () => {
+    let ids = ["first", "second"];
+    const root = createTapRoot(function RemoteThreadListHost() {
+      return useResources(ids.map((id) => withKey(id, TestThread(), [id])));
+    });
+
+    try {
+      const [kept] = root.getValue() as [AssistantRuntime, AssistantRuntime];
+      ids = ["first"];
+      root.getValue();
+      expect(root.getValue()[0]).toBe(kept);
+      expect(kept.thread.getState().messages).toEqual([]);
+    } finally {
+      root.unmount();
+    }
+  });
+});