@assistant-ui/core 0.3.19 → 0.3.21

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

@@ -1,13 +1,15 @@
 // @vitest-environment jsdom
 
 import { act, render, waitFor } from "@testing-library/react";
-import { type FC, StrictMode } from "react";
+import { Activity, type FC, StrictMode, useEffect } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { AssistantCloud } from "assistant-cloud";
 import { useAui, useAuiState } from "@assistant-ui/store";
 import type { ChatModelAdapter } from "../../runtime/utils/chat-model-adapter";
 import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
 import { useLocalRuntime } from "./useLocalRuntime";
+import type { RealtimeVoiceAdapter } from "../../adapters/voice";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 
 const chatModel: ChatModelAdapter = {
   run: async () => ({ content: [] }),
@@ -32,6 +34,148 @@ afterEach(() => {
 });
 
 describe("useLocalRuntime", () => {
+  const createVoiceApp = () => {
+    const disconnect = vi.fn();
+    let emitTranscript!: (item: RealtimeVoiceAdapter.TranscriptItem) => void;
+    const session: RealtimeVoiceAdapter.Session = {
+      status: { type: "running" },
+      isMuted: false,
+      disconnect,
+      mute: vi.fn(),
+      unmute: vi.fn(),
+      onStatusChange: () => () => {},
+      onTranscript: (callback) => {
+        emitTranscript = callback;
+        return () => {};
+      },
+      onModeChange: () => () => {},
+      onVolumeChange: () => () => {},
+    };
+    const capture: { runtime: AssistantRuntime | null } = { runtime: null };
+    let connected = false;
+    const App = () => {
+      const runtime = useLocalRuntime(chatModel, {
+        adapters: { voice: { connect: () => session } },
+      });
+      capture.runtime = runtime;
+      useEffect(() => {
+        if (connected) return;
+        connected = true;
+        runtime.thread.connectVoice();
+      }, [runtime]);
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <div />
+        </AssistantRuntimeProvider>
+      );
+    };
+    return {
+      App,
+      capture,
+      disconnect,
+      emitTranscript: (item: RealtimeVoiceAdapter.TranscriptItem) =>
+        emitTranscript(item),
+    };
+  };
+
+  it("keeps voice connected through StrictMode replay and disconnects on unmount", async () => {
+    const { App, disconnect } = createVoiceApp();
+
+    const view = render(
+      <StrictMode>
+        <App />
+      </StrictMode>,
+    );
+    await act(async () => Promise.resolve());
+    expect(disconnect).not.toHaveBeenCalled();
+
+    view.unmount();
+    await act(async () => Promise.resolve());
+    expect(disconnect).toHaveBeenCalledOnce();
+  });
+
+  it("keeps voice and the thread through Activity hide and reveal", async () => {
+    const { App, capture, disconnect, emitTranscript } = createVoiceApp();
+    const renderApp = (mode: "visible" | "hidden") => (
+      <Activity mode={mode}>
+        <App />
+      </Activity>
+    );
+
+    const view = render(renderApp("visible"));
+    await act(async () => Promise.resolve());
+    view.rerender(renderApp("hidden"));
+    await act(async () => Promise.resolve());
+    view.rerender(renderApp("visible"));
+    await act(async () => Promise.resolve());
+
+    expect(disconnect).not.toHaveBeenCalled();
+    expect(capture.runtime!.thread.getState().voice).toBeDefined();
+
+    act(() =>
+      emitTranscript({ role: "user", text: "after reveal", isFinal: true }),
+    );
+    expect(capture.runtime!.thread.getState().messages).toHaveLength(1);
+
+    view.unmount();
+    await act(async () => Promise.resolve());
+    expect(disconnect).toHaveBeenCalledOnce();
+  });
+
+  it("passes the remote id of a fresh Cloud thread to its first run", async () => {
+    const cloud = {
+      registerSdk: vi.fn(),
+      telemetry: { enabled: false },
+      threads: {
+        list: vi.fn().mockResolvedValue({ threads: [] }),
+        create: vi.fn().mockResolvedValue({ thread_id: "remote-thread" }),
+        messages: {
+          list: vi.fn().mockResolvedValue({ messages: [] }),
+          create: vi.fn().mockResolvedValue({ message_id: "message-1" }),
+          update: vi.fn().mockResolvedValue(undefined),
+        },
+      },
+      runs: {
+        stream: vi.fn().mockResolvedValue(
+          new ReadableStream({
+            start(controller) {
+              controller.close();
+            },
+          }),
+        ),
+      },
+    } as unknown as AssistantCloud;
+    const threadIds: (string | undefined)[] = [];
+    const run: ChatModelAdapter = {
+      run: async ({ unstable_threadId }) => {
+        threadIds.push(unstable_threadId);
+        return { content: [] };
+      },
+    };
+    let runtime: ReturnType<typeof useLocalRuntime> | null = null;
+    const App = () => {
+      runtime = useLocalRuntime(run, { cloud });
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <div />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<App />);
+    await waitFor(() => {
+      expect(runtime!.threads.mainItem.getState().id).toBeDefined();
+    });
+
+    await runtime!.thread.append("hello");
+
+    await waitFor(() => {
+      expect(threadIds).toHaveLength(1);
+    });
+    expect(cloud.threads.create).toHaveBeenCalledTimes(1);
+    expect(threadIds).toEqual(["remote-thread"]);
+  });
+
   it("enables feedback for Cloud threads", async () => {
     const cloud = makeCloud();
     let runtime: ReturnType<typeof useLocalRuntime> | null = null;

package/src/react/runtimes/useLocalRuntime.ts

@@ -6,7 +6,7 @@ import type {
 } from "../../index";
 import type { LocalRuntimeOptionsBase } from "../../runtimes/local/local-runtime-options";
 import { AssistantRuntimeImpl, LocalRuntimeCore } from "../../internal";
-import { useAuiState } from "@assistant-ui/store";
+import { useAui } from "@assistant-ui/store";
 import { useRemoteThreadListRuntime } from "./useRemoteThreadListRuntime";
 import { useCloudThreadListAdapter } from "./cloud/useCloudThreadListAdapter";
 import { useRuntimeAdapters } from "./RuntimeAdapterProvider";
@@ -34,15 +34,18 @@ const useLocalThreadRuntime = (
 
   const [runtime] = useState(() => new LocalRuntimeCore(opt, initialMessages));
 
-  const threadIdRef = useRef<string | undefined>(undefined);
+  const aui = useAui();
   const historyLoadPromiseRef = useRef<Promise<void> | undefined>(undefined);
-  threadIdRef.current = useAuiState((s) => s.threadListItem.remoteId);
 
+  // A run reads the id in the microtask after the initialization barrier,
+  // before the store has flushed the remote id into React state.
   useEffect(() => {
     runtime.threads
       .getMainThreadRuntimeCore()
-      .__internal_setGetThreadId(() => threadIdRef.current);
-  }, [runtime]);
+      .__internal_setGetThreadId(
+        () => aui.threadListItem.__internal_getRuntime?.().getState().remoteId,
+      );
+  }, [aui, runtime]);
 
   useEffect(() => {
     return () => {

package/src/react/runtimes/useRemoteThreadListRuntime.concurrent.test.tsx

@@ -1,10 +1,18 @@
 // @vitest-environment jsdom
 
 import { act, render } from "@testing-library/react";
-import { startTransition, Suspense, type ReactNode } from "react";
+import {
+  startTransition,
+  Suspense,
+  useInsertionEffect,
+  useLayoutEffect,
+  useRef,
+  type ReactNode,
+} from "react";
+import { createRoot } from "react-dom/client";
 import { describe, expect, it, vi } from "vitest";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
-import type { AppendMessage } from "../../types/message";
+import type { AppendMessage, ThreadMessage } from "../../types/message";
 import { makeAdapter } from "../../tests/remote-thread-list-test-helpers";
 import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
 import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
@@ -51,7 +59,7 @@ const createHarness = ({ stableHook = false } = {}) => {
   // variant is the only way to exercise an unchanged published hook.
   const useHoistedThreadRuntime = () => {
     renderThreadRuntime();
-    return useExternalStoreRuntime({
+    return useExternalStoreRuntime<ThreadMessage>({
       messages: EMPTY_MESSAGES,
       onNew: onNewA,
     });
@@ -68,7 +76,10 @@ const createHarness = ({ stableHook = false } = {}) => {
       ? useHoistedThreadRuntime
       : () => {
           renderThreadRuntime();
-          return useExternalStoreRuntime({ messages: EMPTY_MESSAGES, onNew });
+          return useExternalStoreRuntime<ThreadMessage>({
+            messages: EMPTY_MESSAGES,
+            onNew,
+          });
         };
     const runtime = useRemoteThreadListRuntime({
       adapter,
@@ -214,3 +225,72 @@ describe("useRemoteThreadListRuntime concurrent options", () => {
     expect(onNewA).not.toHaveBeenCalled();
   });
 });
+
+describe("useRemoteThreadListRuntime commit phase", () => {
+  const LayoutProbe = ({
+    onLayout,
+  }: {
+    onLayout: (() => void) | undefined;
+  }) => {
+    useLayoutEffect(() => {
+      onLayout?.();
+    }, [onLayout]);
+    return null;
+  };
+
+  it("hands a hosted hook its committed options before a yielded commit settles work", async () => {
+    // A render past the scheduler's 5 ms frame budget yields before passive
+    // effects, and act would drain them first, so this renders outside act.
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", false);
+    try {
+      const adapter = makeAdapter();
+      const settled: string[] = [];
+      let readLabel: (() => string) | undefined;
+      const App = ({
+        label,
+        renderMs,
+        onLayout,
+      }: {
+        label: string;
+        renderMs: number;
+        onLayout?: () => void;
+      }) => {
+        const runtime = useRemoteThreadListRuntime({
+          adapter,
+          runtimeHook: function useLabelThreadRuntime() {
+            const labelRef = useRef(label);
+            useInsertionEffect(() => {
+              labelRef.current = label;
+              readLabel = () => labelRef.current;
+            });
+            return useExternalStoreRuntime<ThreadMessage>({
+              messages: EMPTY_MESSAGES,
+              onNew: async () => {},
+            });
+          },
+        });
+        const renderEnd = performance.now() + renderMs;
+        while (performance.now() < renderEnd) {}
+        return (
+          <AssistantRuntimeProvider runtime={runtime}>
+            <LayoutProbe onLayout={onLayout} />
+          </AssistantRuntimeProvider>
+        );
+      };
+      const settleInMicrotask = () => {
+        queueMicrotask(() => settled.push(readLabel!()));
+      };
+
+      const root = createRoot(document.createElement("div"));
+      root.render(<App label="A" renderMs={0} />);
+      await vi.waitFor(() => expect(readLabel?.()).toBe("A"));
+      root.render(<App label="B" renderMs={30} onLayout={settleInMicrotask} />);
+      await vi.waitFor(() => expect(settled).toHaveLength(1));
+      root.unmount();
+
+      expect(settled).toEqual(["B"]);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});

package/src/react/runtimes/useRemoteThreadListRuntime.ts

@@ -2,6 +2,7 @@ import {
   useState,
   useEffect,
   useInsertionEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useCallback,
@@ -86,7 +87,10 @@ export const useRemoteThreadListRuntime = (
   const [runtimeHookStore] = useState(
     () => new WritableSubscribable(options.runtimeHook),
   );
-  useEffect(() => {
+  // The layout phase re-renders hosted threads before this commit yields. An
+  // insertion effect cannot notify subscribers, so descendant layout effects
+  // of the same commit still see the previous hook.
+  useLayoutEffect(() => {
     runtimeHookStore.setState(options.runtimeHook);
   }, [runtimeHookStore, options.runtimeHook]);
 

package/src/react/types/MessagePartComponentTypes.ts

@@ -12,6 +12,7 @@ import type {
   ToolApprovalResponse,
   ToolCallMessagePart,
   Unstable_AudioMessagePart,
+  Unstable_ToolInteractionInput,
   QuoteInfo,
 } from "../..";
 import type { MessagePartState } from "../..";
@@ -91,6 +92,15 @@ export type ToolCallMessagePartProps<
      * it could not be recorded, so the controls can stay retryable.
      */
     respondToApproval: (response: ToolApprovalResponse) => Promise<void>;
+    /**
+     * Records what the user did in this call's UI on the part, so a stored
+     * conversation keeps it. Resolves once recorded, and rejects when the
+     * payload is not plain JSON, is over the size limit, or the runtime
+     * cannot record interactions; the user's action itself is unaffected.
+     */
+    unstable_recordInteraction?:
+      | ((input: Unstable_ToolInteractionInput) => Promise<void>)
+      | undefined;
   };
 
 /** Component used to render a tool-call message part. */

package/src/react/types/scopes/interactables.ts

@@ -59,6 +59,9 @@ export type Unstable_InteractablePersistenceAdapter = {
    * Restores previously saved state. Called when the adapter is attached;
    * loaded state seeds app-scoped interactables that have not been locally
    * edited yet (a local edit always wins over a slow load).
+   *
+   * A different adapter instance represents a different persistence scope.
+   * Switching adapters resets app-scoped state before loading the replacement.
    */
   load?():
     | Unstable_InteractablePersistedState

package/src/runtime/api/attachment-runtime.ts

@@ -17,25 +17,30 @@ type EditComposerAttachmentState = Attachment & {
   readonly source: "edit-composer";
 };
 
-export type AttachmentState =
+export type AttachmentRuntimeState =
   | ThreadComposerAttachmentState
   | EditComposerAttachmentState
   | MessageAttachmentState;
 
+/**
+ * @deprecated Use `AttachmentRuntimeState`. From `@assistant-ui/react` 0.16, `AttachmentState` names the attachment state read through `useAuiState`.
+ */
+export type AttachmentState = AttachmentRuntimeState;
+
 type AttachmentSnapshotBinding<Source extends AttachmentRuntimeSource> =
   SubscribableWithState<
-    AttachmentState & { source: Source },
+    AttachmentRuntimeState & { source: Source },
     AttachmentRuntimePath & { attachmentSource: Source }
   >;
 
-type AttachmentRuntimeSource = AttachmentState["source"];
+type AttachmentRuntimeSource = AttachmentRuntimeState["source"];
 
 export type AttachmentRuntime<
   TSource extends AttachmentRuntimeSource = AttachmentRuntimeSource,
 > = {
   readonly path: AttachmentRuntimePath & { attachmentSource: TSource };
   readonly source: TSource;
-  getState(): AttachmentState & { source: TSource };
+  getState(): AttachmentRuntimeState & { source: TSource };
   remove(): Promise<void>;
   subscribe(callback: () => void): Unsubscribe;
 };
@@ -62,7 +67,7 @@ export abstract class AttachmentRuntimeImpl<
     this.subscribe = this.subscribe.bind(this);
   }
 
-  public getState(): AttachmentState & { source: Source } {
+  public getState(): AttachmentRuntimeState & { source: Source } {
     return this._core.getState();
   }
 

package/src/runtime/api/bindings.ts

@@ -35,7 +35,7 @@ export type MessageStateBinding = SubscribableWithState<
   MessageRuntimePath
 >;
 
-export type ThreadListItemState = {
+export type ThreadListItemRuntimeState = {
   readonly isMain: boolean;
   /**
    * Whether this thread has a run in progress, including a run that continues
@@ -50,3 +50,8 @@ export type ThreadListItemState = {
   readonly lastMessageAt?: Date | undefined;
   readonly custom?: Record<string, unknown> | undefined;
 };
+
+/**
+ * @deprecated Use `ThreadListItemRuntimeState`. From `@assistant-ui/react` 0.16, `ThreadListItemState` names the thread list item state read through `useAuiState`.
+ */
+export type ThreadListItemState = ThreadListItemRuntimeState;

package/src/runtime/api/composer-runtime.ts

@@ -16,6 +16,7 @@ import {
 import type {
   ComposerRuntimeEventCallback,
   ComposerRuntimeEventType,
+  ComposerSubmission,
   DictationState,
   EditComposerRuntimeCore,
   SendOptions,
@@ -30,7 +31,7 @@ import type { ComposerRuntimePath } from "./paths";
 
 import {
   type AttachmentRuntime,
-  type AttachmentState,
+  type AttachmentRuntimeState,
   EditComposerAttachmentRuntimeImpl,
   ThreadComposerAttachmentRuntimeImpl,
 } from "./attachment-runtime";
@@ -73,6 +74,19 @@ type BaseComposerState = {
 
   /** Messages waiting to be processed. Empty unless the `queue` capability is set. */
   readonly queue: readonly QueueItemState[];
+
+  /**
+   * The message this composer sent while its attachments are prepared.
+   * Undefined once the runtime has taken it.
+   */
+  readonly submission?: ComposerSubmission | undefined;
+
+  /**
+   * Messages this composer handed to the runtime that the thread does not
+   * show yet, oldest first. The thread keeps rendering each one until the
+   * runtime shows the message it became.
+   */
+  readonly inTransit?: readonly ComposerSubmission[] | undefined;
 };
 
 export type ThreadComposerState = BaseComposerState & {
@@ -85,7 +99,12 @@ export type EditComposerState = BaseComposerState & {
   readonly sourceId: string | null;
 };
 
-export type ComposerState = ThreadComposerState | EditComposerState;
+export type ComposerRuntimeState = ThreadComposerState | EditComposerState;
+
+/**
+ * @deprecated Use `ComposerRuntimeState`. From `@assistant-ui/react` 0.16, `ComposerState` names the composer state read through `useAuiState`.
+ */
+export type ComposerState = ComposerRuntimeState;
 
 const EMPTY_ARRAY = Object.freeze([]);
 const EMPTY_OBJECT = Object.freeze({});
@@ -108,6 +127,8 @@ const getThreadComposerState = (
     dictation: runtime?.dictation,
     quote: runtime?.quote,
     queue: runtime?.queue ?? EMPTY_ARRAY,
+    submission: runtime?.submission,
+    inTransit: runtime?.inTransit ?? EMPTY_ARRAY,
 
     value: runtime?.text ?? "",
   });
@@ -132,6 +153,8 @@ const getEditComposerState = (
     dictation: runtime?.dictation,
     quote: runtime?.quote,
     queue: runtime?.queue ?? EMPTY_ARRAY,
+    submission: runtime?.submission,
+    inTransit: runtime?.inTransit ?? EMPTY_ARRAY,
 
     parentId: runtime?.parentId ?? null,
     sourceId: runtime?.sourceId ?? null,
@@ -147,7 +170,7 @@ export type ComposerRuntime = {
   /**
    * Get the current state of the composer. Includes any data that has been added to the composer.
    */
-  getState(): ComposerState;
+  getState(): ComposerRuntimeState;
 
   /**
    * Add an attachment to the composer. Accepts either a standard File object
@@ -287,7 +310,7 @@ export abstract class ComposerRuntimeImpl implements ComposerRuntime {
     this.unstable_on = this.unstable_on.bind(this);
   }
 
-  public abstract getState(): ComposerState;
+  public abstract getState(): ComposerRuntimeState;
 
   public setText(text: string) {
     const core = this._core.getState();
@@ -464,7 +487,7 @@ export class ThreadComposerRuntimeImpl
           return {
             ...attachment,
             source: "thread-composer",
-          } satisfies AttachmentState & { source: "thread-composer" };
+          } satisfies AttachmentRuntimeState & { source: "thread-composer" };
         },
         subscribe: (callback) => this._core.subscribe(callback),
       }),
@@ -552,7 +575,7 @@ export class EditComposerRuntimeImpl
           return {
             ...attachment,
             source: "edit-composer",
-          } satisfies AttachmentState & { source: "edit-composer" };
+          } satisfies AttachmentRuntimeState & { source: "edit-composer" };
         },
         subscribe: (callback) => this._core.subscribe(callback),
       }),