@assistant-ui/core 0.3.17 → 0.3.19

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

@@ -1,9 +1,94 @@
 import { describe, it, expect } from "vitest";
-import { convertExternalMessages } from "./external-message-converter";
+import {
+  convertExternalMessages,
+  createExternalMessageConversionCache,
+} from "./external-message-converter";
 import type { useExternalMessageConverter } from "./external-message-converter";
 import { isErrorMessageId } from "../../utils/id";
 
 describe("convertExternalMessages", () => {
+  it("keeps unchanged messages and rebuilds a replaced one with an opt-in cache", () => {
+    type Input = { id: string; role: "user" | "assistant"; text: string };
+    const metadata = {};
+    const cache = createExternalMessageConversionCache();
+    const callback: useExternalMessageConverter.Callback<Input> = (
+      message,
+    ) => ({
+      id: message.id,
+      role: message.role,
+      content: message.text,
+    });
+    const question: Input = { id: "question", role: "user", text: "hi" };
+    const answer: Input = { id: "answer", role: "assistant", text: "hel" };
+
+    const first = convertExternalMessages(
+      [question, answer],
+      callback,
+      true,
+      metadata,
+      cache,
+    );
+    const second = convertExternalMessages(
+      [question, { ...answer, text: "hello" }],
+      callback,
+      true,
+      metadata,
+      cache,
+    );
+
+    expect(second[0]).toBe(first[0]);
+    expect(second[1]).not.toBe(first[1]);
+    expect(second[1]?.content).toMatchObject([{ type: "text", text: "hello" }]);
+  });
+
+  it("invalidates cached messages when the callback or metadata changes", () => {
+    const input = { text: "nested" };
+    const cache = createExternalMessageConversionCache();
+    const withFormat =
+      (
+        format: (text: string) => string,
+      ): useExternalMessageConverter.Callback<typeof input> =>
+      (message, metadata) => ({
+        id: "nested",
+        role: "assistant",
+        content: format(message.text),
+        metadata: { timing: metadata.messageTiming?.["nested"] },
+      });
+    const callback = withFormat((text) => text);
+    const uppercaseCallback = withFormat((text) => text.toUpperCase());
+    const metadata = {};
+    const timing = { streamStartTime: 1, totalChunks: 1, toolCallCount: 0 };
+
+    const first = convertExternalMessages(
+      [input],
+      callback,
+      false,
+      metadata,
+      cache,
+    );
+    const second = convertExternalMessages(
+      [input],
+      uppercaseCallback,
+      false,
+      metadata,
+      cache,
+    );
+    const third = convertExternalMessages(
+      [input],
+      uppercaseCallback,
+      false,
+      { messageTiming: { nested: timing } },
+      cache,
+    );
+
+    expect(second[0]).not.toBe(first[0]);
+    expect(second[0]?.content).toMatchObject([
+      { type: "text", text: "NESTED" },
+    ]);
+    expect(third[0]).not.toBe(second[0]);
+    expect(third[0]?.metadata).toMatchObject({ timing });
+  });
+
   describe("reasoning part merging", () => {
     it("should merge reasoning parts with the same parentId", () => {
       const messages = [
@@ -205,6 +290,56 @@ describe("convertExternalMessages", () => {
       expect((toolCallParts[0] as any).argsText).toBe('{"query":"new"}');
     });
 
+    it("keeps a merged tool call in its original content position", () => {
+      const messages = [
+        {
+          role: "assistant" as const,
+          content: [
+            {
+              type: "tool-call" as const,
+              toolCallId: "tc1",
+              toolName: "search",
+              args: { query: "old" },
+            },
+            { type: "text" as const, text: "after tool" },
+          ],
+        },
+        {
+          role: "assistant" as const,
+          content: [
+            {
+              type: "tool-call" as const,
+              toolCallId: "tc1",
+              toolName: "search",
+              args: { query: "new" },
+            },
+          ],
+        },
+        {
+          role: "tool" as const,
+          toolCallId: "tc1",
+          result: "found",
+        },
+      ];
+
+      const result = convertExternalMessages(
+        messages,
+        (message) => message,
+        false,
+        {},
+      );
+
+      expect(result[0]!.content).toMatchObject([
+        {
+          type: "tool-call",
+          toolCallId: "tc1",
+          args: { query: "new" },
+          result: "found",
+        },
+        { type: "text", text: "after tool" },
+      ]);
+    });
+
     it("should ignore orphaned tool results without throwing", () => {
       const messages = [
         {

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

@@ -2,28 +2,29 @@
 
 import { useMemo, useState } from "react";
 import {
-  chunkExternalMessages,
-  completeExternalMessageConversion,
-  convertExternalMessageCallback,
-  convertExternalMessageChunk,
   convertExternalMessages as convertExternalMessagesInternal,
-  shallowArrayEqual,
+  createExternalMessageConversionCache as createExternalMessageConversionCacheInternal,
   type ExternalMessageConverterCallback,
-  type ExternalMessageConverterCallbackResult,
-  type ExternalMessageConverterChunk,
   type ExternalMessageConverterMessage,
   type ExternalMessageConverterMetadata,
+  type InternalExternalMessageConversionCache,
   type JoinStrategy,
 } from "../../runtime/utils/external-message-conversion";
 import { bindExternalStoreMessage } from "../../runtime/utils/external-store-message";
-import { ThreadMessageConverter } from "../../runtimes/external-store/thread-message-converter";
-import type { ThreadMessage } from "../../types/message";
-
-// Generatedness is tracked by identity, not by id shape: a caller-supplied id
-// that happens to match the generated pattern must never be rewritten.
-const generatedFallbackMessages = new WeakSet<object>();
 
 export type { JoinStrategy };
+export type ExternalMessageConversionCache = {
+  readonly __brand: unique symbol;
+};
+
+/**
+ * Creates a cache for plain external message conversion. Pass the same cache on every call for one message list, and a source message that has not changed since the previous call converts to the same `ThreadMessage` object.
+ *
+ * Entries are keyed by source message identity and rebuilt whenever `callback` or `metadata` is a different object than on the previous call, so keep both referentially stable.
+ */
+export const createExternalMessageConversionCache =
+  (): ExternalMessageConversionCache =>
+    createExternalMessageConversionCacheInternal() as unknown as ExternalMessageConversionCache;
 
 export namespace useExternalMessageConverter {
   export type Message = ExternalMessageConverterMessage;
@@ -31,17 +32,21 @@ export namespace useExternalMessageConverter {
   export type Callback<T> = ExternalMessageConverterCallback<T>;
 }
 
-export const convertExternalMessages: <T extends WeakKey>(
+export const convertExternalMessages = <T extends WeakKey>(
   messages: T[],
   callback: useExternalMessageConverter.Callback<T>,
   isRunning: boolean,
   metadata: useExternalMessageConverter.Metadata,
-) => ThreadMessage[] = convertExternalMessagesInternal;
-
-type CallbackCacheEntry<T> = ExternalMessageConverterCallbackResult<T> & {
-  metadata: useExternalMessageConverter.Metadata;
-  callback: useExternalMessageConverter.Callback<T>;
-};
+  cache?: ExternalMessageConversionCache,
+) =>
+  convertExternalMessagesInternal(
+    messages,
+    callback,
+    isRunning,
+    metadata,
+    undefined,
+    cache as unknown as InternalExternalMessageConversionCache<T> | undefined,
+  );
 
 export const useExternalMessageConverter = <T extends WeakKey>({
   callback,
@@ -56,89 +61,30 @@ export const useExternalMessageConverter = <T extends WeakKey>({
   joinStrategy?: JoinStrategy | undefined;
   metadata?: useExternalMessageConverter.Metadata | undefined;
 }) => {
-  // The caches live for the component lifetime; React Compiler hoists
-  // allocations without reactive dependencies out of useMemo, so re-creating
-  // them on dependency change would not survive compilation. Staleness is
-  // instead tracked per entry via the metadata/callback that produced it,
-  // keeping correctness independent of memoization (which React treats as
-  // droppable). A "use no memo" opt-out would restore the useMemo semantics
-  // but leave cache flushing coupled to memo firing.
-  const [caches] = useState(() => ({
-    callbackCache: new WeakMap<T, CallbackCacheEntry<T>>(),
-    chunkCache: new WeakMap<
-      ExternalMessageConverterMessage,
-      ExternalMessageConverterChunk<T>
-    >(),
-    converterCache: new ThreadMessageConverter(),
-  }));
+  // The cache lives for the component lifetime: React Compiler hoists allocations without reactive dependencies out of useMemo, so entries carry the callback and metadata that produced them instead of being flushed when those change.
+  const [cache] = useState(() =>
+    createExternalMessageConversionCacheInternal<T>(),
+  );
 
   const state = useMemo(
     () => ({
       metadata: metadata ?? {},
       callback,
-      ...caches,
     }),
-    [callback, metadata, caches],
+    [callback, metadata],
   );
 
   return useMemo(() => {
-    const callbackResults: ExternalMessageConverterCallbackResult<T>[] = [];
-    for (const message of messages) {
-      let result = state.callbackCache.get(message);
-      if (
-        !result ||
-        result.metadata !== state.metadata ||
-        result.callback !== state.callback
-      ) {
-        result = {
-          ...convertExternalMessageCallback(
-            message,
-            state.callback,
-            state.metadata,
-          ),
-          metadata: state.metadata,
-          callback: state.callback,
-        };
-        state.callbackCache.set(message, result);
-      }
-      callbackResults.push(result);
-    }
-
-    const chunks = chunkExternalMessages(callbackResults, joinStrategy).map(
-      (message) => {
-        const key = message.outputs[0];
-        if (!key) return message;
-
-        const cached = state.chunkCache.get(key);
-        if (cached && shallowArrayEqual(cached.outputs, message.outputs)) {
-          return cached;
-        }
-        state.chunkCache.set(key, message);
-        return message;
-      },
-    );
-
-    const threadMessages = state.converterCache.convertMessages(
-      chunks,
-      (cache, message, idx) =>
-        convertExternalMessageChunk(
-          message,
-          idx,
-          chunks.length,
-          isRunning,
-          state.metadata.error,
-          {
-            message: cache,
-            generatedFallbackMessages,
-          },
-          state.metadata.cancelledMessageIds,
-        ),
+    const threadMessages = convertExternalMessagesInternal(
+      messages,
+      state.callback,
+      isRunning,
+      state.metadata,
+      joinStrategy,
+      cache,
     );
 
     bindExternalStoreMessage(threadMessages, messages);
-    return completeExternalMessageConversion(
-      threadMessages,
-      state.metadata.error,
-    );
-  }, [state, messages, isRunning, joinStrategy]);
+    return threadMessages;
+  }, [state, messages, isRunning, joinStrategy, cache]);
 };

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

@@ -5,8 +5,49 @@ import { act, render } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+import type { ThreadMessage } from "../../types/message";
+import { RuntimeAdapterProvider } from "./RuntimeAdapterProvider";
+
+const userMessage: ThreadMessage = {
+  id: "user-1",
+  role: "user",
+  content: [{ type: "text", text: "hello" }],
+  attachments: [],
+  createdAt: new Date(0),
+  metadata: { custom: {} },
+};
 
 describe("useExternalStoreRuntime lifecycle", () => {
+  it("uses feedback supplied by the per-thread adapter context", () => {
+    const submit = vi.fn();
+    const capture: { runtime: AssistantRuntime | null } = { runtime: null };
+    const App = () => {
+      const runtime = useExternalStoreRuntime({
+        messages: [userMessage],
+        onNew: async () => {},
+      });
+      capture.runtime = runtime;
+      return null;
+    };
+
+    render(
+      <RuntimeAdapterProvider adapters={{ feedback: { submit } }}>
+        <App />
+      </RuntimeAdapterProvider>,
+    );
+
+    expect(capture.runtime!.thread.getState().capabilities.feedback).toBe(true);
+    act(() => {
+      capture
+        .runtime!.thread.getMessageById("user-1")
+        .submitFeedback({ type: "positive" });
+    });
+    expect(submit).toHaveBeenCalledWith({
+      message: expect.objectContaining({ id: "user-1" }),
+      type: "positive",
+    });
+  });
+
   it("keeps dispatching appends after StrictMode's simulated remount", async () => {
     const onNew = vi.fn(async () => {});
     const capture: { runtime: AssistantRuntime | null } = { runtime: null };

package/src/react/runtimes/useExternalStoreRuntime.ts

@@ -11,7 +11,15 @@ import { useRuntimeAdapters } from "./RuntimeAdapterProvider";
 export const useExternalStoreRuntime = <T>(
   store: ExternalStoreAdapter<T>,
 ): AssistantRuntime => {
-  const [runtime] = useState(() => new ExternalStoreRuntimeCore(store));
+  const { modelContext, feedback } = useRuntimeAdapters() ?? {};
+  const adaptedStore = useMemo(() => {
+    if (!feedback || store.adapters?.feedback) return store;
+    return {
+      ...store,
+      adapters: { ...store.adapters, feedback },
+    };
+  }, [feedback, store]);
+  const [runtime] = useState(() => new ExternalStoreRuntimeCore(adaptedStore));
 
   useEffect(() => {
     return () => {
@@ -20,11 +28,9 @@ export const useExternalStoreRuntime = <T>(
   }, [runtime]);
 
   useEffect(() => {
-    runtime.setAdapter(store);
+    runtime.setAdapter(adaptedStore);
   });
 
-  const { modelContext } = useRuntimeAdapters() ?? {};
-
   useEffect(() => {
     if (!modelContext) return undefined;
     return runtime.registerModelContextProvider(modelContext);

package/src/react/runtimes/useLocalRuntime.test.tsx

@@ -32,6 +32,26 @@ afterEach(() => {
 });
 
 describe("useLocalRuntime", () => {
+  it("enables feedback for Cloud threads", async () => {
+    const cloud = makeCloud();
+    let runtime: ReturnType<typeof useLocalRuntime> | null = null;
+    const App = () => {
+      runtime = useLocalRuntime(chatModel, { cloud });
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <div />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<App />);
+
+    await waitFor(() => {
+      expect(cloud.threads.list).toHaveBeenCalledTimes(2);
+      expect(runtime!.thread.getState().capabilities.feedback).toBe(true);
+    });
+  });
+
   it("surfaces the live thread after mount without user input", async () => {
     const auiRef: { current: ReturnType<typeof useAui> | null } = {
       current: null,

package/src/react/runtimes/useRemoteThreadListRuntime.load-error.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+import { makeAdapter } from "../../tests/remote-thread-list-test-helpers";
+import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
+import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
+import { useRemoteThreadListRuntime } from "./useRemoteThreadListRuntime";
+
+const EMPTY_MESSAGES: readonly never[] = [];
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe("useRemoteThreadListRuntime load recovery", () => {
+  it("reloads once when the browser comes online after a failed load", async () => {
+    const error = new Error("offline");
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const list = vi
+      .fn()
+      .mockRejectedValueOnce(error)
+      .mockResolvedValueOnce({ threads: [] });
+    const adapter = makeAdapter({ list });
+    const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+    const useThreadRuntime = () =>
+      useExternalStoreRuntime({
+        messages: EMPTY_MESSAGES,
+        onNew: async () => {},
+      } as never);
+
+    const App = () => {
+      const runtime = useRemoteThreadListRuntime({
+        adapter,
+        runtimeHook: useThreadRuntime,
+      });
+      runtimeRef.current = runtime;
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          {null}
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<App />);
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(runtimeRef.current!.threads.getState().loadError).toBe(error),
+    );
+
+    act(() => window.dispatchEvent(new Event("online")));
+
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(2));
+    await act(async () => {});
+    expect(list).toHaveBeenCalledTimes(2);
+    expect(runtimeRef.current!.threads.getState().loadError).toBeUndefined();
+  });
+
+  it("reloads once when the page becomes visible after a failed load", async () => {
+    const error = new Error("offline");
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(document, "visibilityState", "get").mockReturnValue("visible");
+    const list = vi
+      .fn()
+      .mockRejectedValueOnce(error)
+      .mockResolvedValueOnce({ threads: [] });
+    const adapter = makeAdapter({ list });
+    const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+    const useThreadRuntime = () =>
+      useExternalStoreRuntime({
+        messages: EMPTY_MESSAGES,
+        onNew: async () => {},
+      } as never);
+
+    const App = () => {
+      const runtime = useRemoteThreadListRuntime({
+        adapter,
+        runtimeHook: useThreadRuntime,
+      });
+      runtimeRef.current = runtime;
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          {null}
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<App />);
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(runtimeRef.current!.threads.getState().loadError).toBe(error),
+    );
+
+    act(() => document.dispatchEvent(new Event("visibilitychange")));
+
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(2));
+    await waitFor(() =>
+      expect(runtimeRef.current!.threads.getState().loadError).toBeUndefined(),
+    );
+
+    act(() => document.dispatchEvent(new Event("visibilitychange")));
+    await act(async () => {});
+
+    expect(list).toHaveBeenCalledTimes(2);
+  });
+});

package/src/react/runtimes/useRemoteThreadListRuntime.ts

@@ -1,6 +1,7 @@
 import {
   useState,
   useEffect,
+  useInsertionEffect,
   useMemo,
   useRef,
   useCallback,
@@ -39,11 +40,43 @@ const useRemoteThreadListRuntimeImpl = (
   options: RemoteThreadListOptions,
 ): AssistantRuntime => {
   const [runtime] = useState(() => new RemoteThreadListRuntimeCore(options));
+
+  // Insertion-effect cleanup runs only when React deletes the fiber, so a
+  // hidden <Activity> or a re-suspended boundary keeps the threads alive; the
+  // disposal is deferred to a microtask because it notifies subscribers and
+  // React forbids scheduling updates from an insertion effect.
+  useInsertionEffect(
+    () => () => queueMicrotask(() => runtime.threads.__internal_dispose()),
+    [runtime],
+  );
+
   useEffect(() => {
     runtime.threads.__internal_setOptions(options);
     runtime.threads.__internal_load();
   }, [runtime, options]);
 
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+
+    const reloadAfterError = () => {
+      if (runtime.threads.loadError !== undefined) {
+        void runtime.threads.reload();
+      }
+    };
+    const reloadAfterVisible = () => {
+      if (document.visibilityState === "visible") reloadAfterError();
+    };
+
+    window.addEventListener("online", reloadAfterError);
+    document.addEventListener("visibilitychange", reloadAfterVisible);
+    return () => {
+      window.removeEventListener("online", reloadAfterError);
+      document.removeEventListener("visibilitychange", reloadAfterVisible);
+    };
+  }, [runtime]);
+
   return useMemo(() => new AssistantRuntimeImpl(runtime), [runtime]);
 };
 
@@ -76,7 +109,7 @@ export const useRemoteThreadListRuntime = (
   );
 
   const onThreadIdChange = useEffectEvent((threadId: string | undefined) => {
-    options.onThreadIdChange?.(threadId);
+    return options.onThreadIdChange?.(threadId);
   });
 
   const stableOptions = useMemo<RemoteThreadListOptions>(

package/src/react/utils/groupParts.ts

@@ -47,8 +47,13 @@ export const GROUPBY_MEMO_KEY: unique symbol = Symbol.for(
  *   `display: "standalone"`). Resolving the registry-driven cases reads the
  *   {@link GroupByContext} passed to the `groupBy` function. Takes precedence
  *   over the `"tool-call"` entry.
+ *
+ * A `"tool-call:<name>"` entry matches tool calls by tool name and takes precedence over the plain `"tool-call"` entry, while `"standalone-tool-call"` still wins first.
  */
-type GroupPartType = PartState["type"] | "standalone-tool-call";
+type GroupPartType =
+  | PartState["type"]
+  | "standalone-tool-call"
+  | `tool-call:${string}`;
 
 /**
  * Build a `groupBy` from a `part.type → group-key path` lookup.
@@ -63,11 +68,14 @@ type GroupPartType = PartState["type"] | "standalone-tool-call";
  * {@link GroupByContext} that `<MessagePrimitive.GroupedParts>` passes to the
  * `groupBy` function — the helper needs nothing threaded into it.
  *
+ * A `"tool-call:<name>"` entry matches tool calls by tool name and takes precedence over the plain `"tool-call"` entry, while `"standalone-tool-call"` still wins first.
+ *
  * @example
  * ```tsx
  * <MessagePrimitive.GroupedParts
  *   groupBy={groupPartByType({
  *     reasoning: ["group-thought", "group-reasoning"],
+ *     "tool-call:task": ["group-subagents"],
  *     "tool-call": ["group-thought", "group-tool"],
  *     "standalone-tool-call": [],
  *   })}
@@ -91,6 +99,9 @@ export const groupPartByType = <TKey extends `group-${string}`>(
       if (isStandalone && lookup["standalone-tool-call"] !== undefined) {
         return lookup["standalone-tool-call"]!;
       }
+      const toolCallPath = lookup[`tool-call:${part.toolName}`];
+      if (toolCallPath !== undefined) return toolCallPath;
+      return lookup["tool-call"] ?? [];
     }
     return lookup[part.type] ?? [];
   }) as ((part: PartState, context?: GroupByContext) => readonly TKey[]) & {

package/src/react/utils/useJSONEqual.ts

@@ -1,6 +1,15 @@
 import { useRef } from "react";
+import type { ReadonlyJSONValue } from "assistant-stream/utils";
 import { isJSONValueEqual } from "../../utils/json/is-json-equal";
 
+export function useJSONEqualValue<T extends ReadonlyJSONValue>(value: T): T {
+  const prev = useRef(value);
+  if (prev.current !== value && !isJSONValueEqual(prev.current, value)) {
+    prev.current = value;
+  }
+  return prev.current;
+}
+
 /**
  * Like `useShallow`, but with JSON deep-equality. Use when a selector derives an
  * equal-but-fresh value on every store update — e.g. folding over

package/src/react/utils/useJSONSchemaDependency.ts

@@ -0,0 +1,22 @@
+import { useMemo } from "react";
+import { toJSONSchema } from "assistant-stream";
+import type { ReadonlyJSONValue } from "assistant-stream/utils";
+import { isJSONValue } from "../../utils/json/is-json";
+import type { Unstable_InteractableStateSchema } from "../types/scopes/interactables";
+import { useJSONEqualValue } from "./useJSONEqual";
+
+export function useJSONSchemaDependency(
+  schema: Unstable_InteractableStateSchema,
+): ReadonlyJSONValue {
+  const normalizedSchema = useMemo(() => {
+    try {
+      const jsonSchema = toJSONSchema(schema);
+      return isJSONValue(jsonSchema) ? jsonSchema : null;
+    } catch {
+      // Opaque schemas share one fallback so rebuilt instances do not churn registration.
+      return null;
+    }
+  }, [schema]);
+
+  return useJSONEqualValue(normalizedSchema);
+}