@assistant-ui/core 0.3.16 → 0.3.18

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,
@@ -12,6 +13,8 @@ import type { RemoteThreadListOptions } from "../../runtimes/remote-thread-list/
 import type { AssistantRuntimeCore } from "../../runtime/interfaces/assistant-runtime-core";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import { RemoteThreadListThreadListRuntimeCore } from "./RemoteThreadListThreadListRuntimeCore";
+import { WritableSubscribable } from "../../subscribable/subscribable";
+import { useSubscribable } from "../../store/runtime-clients/useSubscribable";
 import { useAui } from "@assistant-ui/store";
 
 class RemoteThreadListRuntimeCore
@@ -37,25 +40,73 @@ 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]);
 };
 
 export const useRemoteThreadListRuntime = (
   options: RemoteThreadListOptions,
 ): AssistantRuntime => {
-  const runtimeHookRef = useRef(options.runtimeHook);
-  runtimeHookRef.current = options.runtimeHook;
+  const [runtimeHookStore] = useState(
+    () => new WritableSubscribable(options.runtimeHook),
+  );
+  useEffect(() => {
+    runtimeHookStore.setState(options.runtimeHook);
+  }, [runtimeHookStore, options.runtimeHook]);
 
   const initialThreadIdRef = useRef(options.initialThreadId);
 
-  const stableRuntimeHook = useCallback(() => {
-    return runtimeHookRef.current();
-  }, []);
+  // Thread resources subscribe to the store rather than reading a ref, so a
+  // hook published at commit reaches exactly the resources that use it and an
+  // abandoned render publishes nothing. The store pins its server snapshot to
+  // the constructor value for hydration, which tap reads on any never-mounted
+  // fiber, so the live state serves as the server snapshot here.
+  const stableRuntimeHook = useCallback(
+    function useCommittedRuntimeHook() {
+      return useSubscribable({
+        subscribe: runtimeHookStore.subscribe,
+        getState: runtimeHookStore.getState,
+        getServerSnapshot: runtimeHookStore.getState,
+      })();
+    },
+    [runtimeHookStore],
+  );
 
   const onThreadIdChange = useEffectEvent((threadId: string | undefined) => {
     options.onThreadIdChange?.(threadId);
@@ -91,7 +142,7 @@ export const useRemoteThreadListRuntime = (
 
     // If allowNesting is true and already inside a thread list context,
     // just call the runtimeHook directly (no-op behavior)
-    return stableRuntimeHook();
+    return options.runtimeHook();
   }
 
   const runtime = useRemoteThreadListRuntimeImpl(stableOptions);

package/src/react/types/MessagePartComponentTypes.ts

@@ -83,10 +83,14 @@ export type ToolCallMessagePartProps<
     /**
      * Responds to a server-side tool approval gate. Only valid while
      * `approval` is set on the part, `approval.approved === undefined`, and
-     * no `approval.resolution` is recorded. Accepts a boolean decision or the
-     * id of one of `approval.options`; option kinds resolve to the boolean.
+     * no `approval.resolution` is recorded. Accepts a boolean decision, the
+     * id of one of `approval.options` (option kinds resolve to the boolean),
+     * or a free-form answer when the request accepts one.
+     *
+     * Resolves once the runtime has accepted the response, and rejects when
+     * it could not be recorded, so the controls can stay retryable.
      */
-    respondToApproval: (response: ToolApprovalResponse) => void;
+    respondToApproval: (response: ToolApprovalResponse) => Promise<void>;
   };
 
 /** Component used to render a tool-call message part. */

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

@@ -1,5 +1,6 @@
 import type { ToolCallMessagePartComponent } from "../MessagePartComponentTypes";
 import type { Unsubscribe } from "../../..";
+import type { ToolCallText } from "../../../model-context/tool-call-text";
 
 export type McpAppResourceOutput = {
   readonly render: ToolCallMessagePartComponent;
@@ -12,6 +13,7 @@ export type McpAppResourceOutput = {
  */
 type ToolRegistration = {
   readonly render: ToolCallMessagePartComponent;
+  readonly renderText?: ToolCallText<any, any, unknown> | undefined;
   /** Whether this UI renders standalone, outside the chain-of-thought trace. */
   readonly standalone: boolean;
 };

package/src/runtime/api/message-part-runtime.ts

@@ -28,7 +28,7 @@ type MessagePartSnapshotBinding = SubscribableWithState<
 export type MessagePartRuntime = {
   addToolResult(result: any | ToolResponse<any>): void;
   resumeToolCall(payload: unknown): void;
-  respondToToolApproval(response: ToolApprovalResponse): void;
+  respondToToolApproval(response: ToolApprovalResponse): Promise<void>;
 
   readonly path: MessagePartRuntimePath;
   getState(): MessagePartState;
@@ -113,7 +113,7 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
     });
   }
 
-  public respondToToolApproval(response: ToolApprovalResponse) {
+  public respondToToolApproval(response: ToolApprovalResponse): Promise<void> {
     const state = this.contentBinding.getState();
     if (!state) throw new Error("Message part is not available");
 
@@ -131,7 +131,7 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
 
     if (!this.threadApi) throw new Error("Thread API is not available");
 
-    this.threadApi
+    return this.threadApi
       .getState()
       .respondToToolApproval(
         resolveToolApprovalResponse(state.approval, response),

package/src/runtime/api/message-runtime.test.ts

@@ -11,6 +11,7 @@ import {
   type MessageStateBinding,
 } from "./message-runtime";
 import { toMessagePartStatus } from "../../utils/normalizePartStatus";
+import { convertExternalMessageChunk } from "../utils/external-message-conversion";
 
 const messagePath = {
   ref: "threads.main.messages[0]",
@@ -256,6 +257,80 @@ describe("toMessagePartStatus", () => {
 });
 
 describe("MessageRuntimeImpl paths", () => {
+  it.each([undefined, ""])(
+    "looks up separate tool calls with ID %s without breaking provider result matching",
+    (toolCallId) => {
+      const id = toolCallId === undefined ? {} : { toolCallId };
+      const converted = convertExternalMessageChunk(
+        {
+          inputs: [{}],
+          outputs: [
+            {
+              role: "assistant",
+              content: [
+                { type: "tool-call", ...id, toolName: "weather", args: {} },
+                { type: "tool-call", ...id, toolName: "search", args: {} },
+                {
+                  type: "tool-call",
+                  toolCallId: "provider-call",
+                  toolName: "calendar",
+                  args: { day: "Monday" },
+                },
+              ],
+            },
+            {
+              role: "assistant",
+              content: [
+                {
+                  type: "tool-call",
+                  toolCallId: "provider-call",
+                  toolName: "calendar",
+                  args: { day: "Tuesday" },
+                },
+              ],
+            },
+            {
+              role: "tool",
+              toolCallId: "provider-call",
+              toolName: "calendar",
+              result: "Meeting at noon",
+            },
+          ],
+        },
+        0,
+        1,
+        false,
+        undefined,
+      );
+      const runtime = new MessageRuntimeImpl(
+        {
+          ...messageBinding,
+          getState: () => ({ ...message, ...converted }),
+        },
+        threadBinding,
+      );
+      const calls = converted.content.filter(
+        (part) => part.type === "tool-call",
+      );
+
+      expect(
+        calls.map((call) =>
+          runtime.getMessagePartByToolCallId(call.toolCallId).getState(),
+        ),
+      ).toMatchObject([
+        { type: "tool-call", toolName: "weather" },
+        { type: "tool-call", toolName: "search" },
+        {
+          type: "tool-call",
+          toolCallId: "provider-call",
+          toolName: "calendar",
+          args: { day: "Tuesday" },
+          result: "Meeting at noon",
+        },
+      ]);
+    },
+  );
+
   it("appends nested selectors to the message path", () => {
     const runtime = new MessageRuntimeImpl(messageBinding, threadBinding);
 

package/src/runtime/api/thread-list-item-runtime.ts

@@ -30,12 +30,17 @@ import type { ThreadListItemStatus } from "../interfaces/thread-list-runtime-cor
 
 export type { ThreadListItemState, ThreadListItemStatus };
 
+export type ThreadListItemGenerateTitleOptions = {
+  /** Marks a generation started by the automatic title trigger. */
+  automatic?: boolean;
+};
+
 export type ThreadListItemRuntime = {
   readonly path: ThreadListItemRuntimePath;
   getState(): ThreadListItemState;
 
   initialize(): Promise<{ remoteId: string; externalId: string | undefined }>;
-  generateTitle(): Promise<void>;
+  generateTitle(options?: ThreadListItemGenerateTitleOptions): Promise<void>;
 
   switchTo(options?: { unarchive?: boolean }): Promise<void>;
   rename(newTitle: string): Promise<void>;
@@ -147,9 +152,11 @@ export class ThreadListItemRuntimeImpl implements ThreadListItemRuntime {
     return this._threadListBinding.initialize(state.id);
   }
 
-  public generateTitle(): Promise<void> {
+  public generateTitle(
+    options?: ThreadListItemGenerateTitleOptions,
+  ): Promise<void> {
     const state = this._core.getState();
-    return this._threadListBinding.generateTitle(state.id);
+    return this._threadListBinding.generateTitle(state.id, options);
   }
 
   public unstable_on<E extends ThreadListItemEventType>(

package/src/runtime/api/thread-list-runtime.ts

@@ -7,11 +7,15 @@ import {
   SKIP_UPDATE,
   ShallowMemoizeSubject,
 } from "../../subscribable/subscribable";
-import type { ThreadListRuntimeCore } from "../interfaces/thread-list-runtime-core";
+import type {
+  ThreadListRuntimeCore,
+  ThreadListRuntimeEvent,
+} from "../interfaces/thread-list-runtime-core";
 import {
   type ThreadListItemRuntime,
   ThreadListItemRuntimeImpl,
   type ThreadListItemState,
+  type ThreadListItemStateBinding,
 } from "./thread-list-item-runtime";
 import {
   type ThreadListItemRuntimeBinding,
@@ -21,6 +25,7 @@ import {
 } from "./thread-runtime";
 
 const RESOLVED_PROMISE = Promise.resolve();
+const NOOP_UNSUBSCRIBE = () => {};
 
 export type ThreadListState = {
   readonly mainThreadId: string;
@@ -28,6 +33,8 @@ export type ThreadListState = {
   readonly threadIds: readonly string[];
   readonly archivedThreadIds: readonly string[];
   readonly isLoading: boolean;
+  /** The error thrown by the most recent thread list load that failed, cleared when a later load starts. */
+  readonly loadError: unknown;
   readonly isLoadingMore: boolean;
   readonly hasMore: boolean;
   readonly threadItems: Readonly<
@@ -57,6 +64,16 @@ export type ThreadListRuntime = {
   ): Promise<void>;
   switchToNewThread(): Promise<void>;
 
+  /**
+   * Observes lifecycle events on every thread this list keeps alive, so an
+   * event that fires while its thread is not selected stays observable. Thread
+   * lists that mount only the main thread never emit; their main thread's
+   * runtime is observed directly.
+   */
+  unstable_subscribeThreadEvents(
+    callback: (event: ThreadListRuntimeEvent) => void,
+  ): Unsubscribe;
+
   getLoadThreadsPromise(): Promise<void>;
   reload(): Promise<void>;
   /**
@@ -83,6 +100,7 @@ const getThreadListState = (
     threadIds: threadList.threadIds,
     archivedThreadIds: threadList.archivedThreadIds,
     isLoading: threadList.isLoading,
+    loadError: threadList.loadError,
     isLoadingMore: threadList.isLoadingMore ?? false,
     hasMore: threadList.hasMore ?? false,
     threadItems: threadList.threadItems,
@@ -171,6 +189,8 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
   protected __internal_bindMethods() {
     this.switchToThread = this.switchToThread.bind(this);
     this.switchToNewThread = this.switchToNewThread.bind(this);
+    this.unstable_subscribeThreadEvents =
+      this.unstable_subscribeThreadEvents.bind(this);
     this.getLoadThreadsPromise = this.getLoadThreadsPromise.bind(this);
     this.reload = this.reload.bind(this);
     this.reloadMainThread = this.reloadMainThread.bind(this);
@@ -194,6 +214,14 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
     return this._core.switchToNewThread();
   }
 
+  public unstable_subscribeThreadEvents(
+    callback: (event: ThreadListRuntimeEvent) => void,
+  ): Unsubscribe {
+    return (
+      this._core.unstable_subscribeThreadEvents?.(callback) ?? NOOP_UNSUBSCRIBE
+    );
+  }
+
   public getLoadThreadsPromise(): Promise<void> {
     return this._core.getLoadThreadsPromise();
   }
@@ -226,6 +254,21 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
     return this._mainThreadListItemRuntime;
   }
 
+  private _createItemStateBinding(
+    threadId: string,
+  ): ThreadListItemStateBinding {
+    return new ShallowMemoizeSubject({
+      path: {
+        ref: `threadItems[threadId=${threadId}]`,
+        threadSelector: { type: "threadId", threadId },
+      },
+      getState: () => {
+        return getThreadListItemState(this._core, threadId);
+      },
+      subscribe: (callback) => this._core.subscribe(callback),
+    });
+  }
+
   public getById(threadId: string) {
     return new this._runtimeFactory(
       new NestedSubscriptionSubject({
@@ -236,7 +279,7 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
         getState: () => this._core.getThreadRuntimeCore(threadId),
         subscribe: (callback) => this._core.subscribe(callback),
       }),
-      this.mainItem,
+      this._createItemStateBinding(threadId),
     );
   }
 
@@ -277,16 +320,7 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
 
   public getItemById(threadId: string) {
     return new ThreadListItemRuntimeImpl(
-      new ShallowMemoizeSubject({
-        path: {
-          ref: `threadItems[threadId=${threadId}]`,
-          threadSelector: { type: "threadId", threadId },
-        },
-        getState: () => {
-          return getThreadListItemState(this._core, threadId);
-        },
-        subscribe: (callback) => this._core.subscribe(callback),
-      }),
+      this._createItemStateBinding(threadId),
       this._core,
     );
   }

package/src/runtime/api/thread-runtime.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from "vitest";
+import { LocalRuntimeCore } from "../../runtimes/local/local-runtime-core";
+import { ExternalStoreRuntimeCore } from "../../runtimes/external-store/external-store-runtime-core";
+import { AssistantRuntimeImpl } from "./assistant-runtime";
+
+describe("ThreadRuntime.append", () => {
+  it.each([
+    { parent: { parentId: null }, expectedParent: null, visible: ["new"] },
+    {
+      parent: {},
+      expectedParent: "tail",
+      visible: ["root", "tail", "new"],
+    },
+    {
+      parent: { parentId: "root" },
+      expectedParent: "root",
+      visible: ["root", "new"],
+    },
+  ])(
+    "selects the branch under $expectedParent",
+    ({ parent, expectedParent, visible }) => {
+      const core = new LocalRuntimeCore(
+        { adapters: { chatModel: { run: async () => ({ content: [] }) } } },
+        [
+          { id: "root", role: "user", content: "root" },
+          { id: "tail", role: "assistant", content: "tail" },
+        ],
+      );
+      const thread = new AssistantRuntimeImpl(core).thread;
+
+      thread.append({
+        ...parent,
+        content: [{ type: "text", text: "new" }],
+        startRun: false,
+      });
+
+      expect(
+        thread.getState().messages.map((message) => message.content),
+      ).toEqual(visible.map((text) => [{ type: "text", text }]));
+      expect(thread.export().messages.at(-1)?.parentId).toBe(expectedParent);
+    },
+  );
+});
+
+describe("ThreadRuntime.append with an external store", () => {
+  it("routes an explicit root parent to onEdit instead of onNew", async () => {
+    const onNew = vi.fn(async () => {});
+    const onEdit = vi.fn(async () => {});
+    const core = new ExternalStoreRuntimeCore({
+      messages: [
+        {
+          id: "old",
+          role: "user",
+          content: [{ type: "text", text: "old" }],
+          createdAt: new Date(0),
+          attachments: [],
+          metadata: { custom: {} },
+        },
+      ],
+      onNew,
+      onEdit,
+    });
+    const thread = new AssistantRuntimeImpl(core).thread;
+
+    thread.append({
+      parentId: null,
+      content: [{ type: "text", text: "new root" }],
+      startRun: false,
+    });
+
+    await vi.waitFor(() =>
+      expect(onEdit).toHaveBeenCalledExactlyOnceWith(
+        expect.objectContaining({ parentId: null }),
+      ),
+    );
+    expect(onNew).not.toHaveBeenCalled();
+  });
+});

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

@@ -77,6 +77,10 @@ const toStartRunConfig = (message: CreateStartRunConfig): StartRunConfig => {
 export type CreateAppendMessage =
   | string
   | {
+      /**
+       * An omitted value or `undefined` selects the current tail.
+       * `null` selects a root branch.
+       */
       parentId?: string | null | undefined;
       sourceId?: string | null | undefined;
       role?: AppendMessage["role"] | undefined;
@@ -107,7 +111,10 @@ const toAppendMessage = (
 
   return {
     createdAt: message.createdAt ?? new Date(),
-    parentId: message.parentId ?? messages.at(-1)?.id ?? null,
+    parentId:
+      message.parentId === undefined
+        ? (messages.at(-1)?.id ?? null)
+        : message.parentId,
     sourceId: message.sourceId ?? null,
     role: message.role ?? "user",
     content: message.content,