@assistant-ui/eve 0.0.18 → 0.0.20

package/src/useEveAgentRuntime.fast-refresh.test.tsx

@@ -0,0 +1,342 @@
+// @vitest-environment jsdom
+
+import { act, type ReactNode } from "react";
+import type { AssistantCloud } from "assistant-cloud";
+import { afterAll, afterEach, expect, it, vi } from "vitest";
+import type { EveCloudSessions } from "./eveCloudSessions";
+
+const { mockUseEveAgent, directRuntimeHook, sessionInstances } = vi.hoisted(
+  () => ({
+    mockUseEveAgent: vi.fn(),
+    directRuntimeHook: { current: false },
+    sessionInstances: [] as unknown[],
+  }),
+);
+
+vi.mock("eve/react", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("eve/react")>()),
+  useEveAgent: mockUseEveAgent,
+}));
+
+vi.mock("@assistant-ui/store", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@assistant-ui/store")>();
+  return {
+    ...original,
+    useAui: () => {
+      const aui = original.useAui();
+      if (!directRuntimeHook.current) return aui;
+      return new Proxy(aui, {
+        get(target, key) {
+          if (key !== "threadListItem") return Reflect.get(target, key);
+          return new Proxy(target.threadListItem, {
+            get(item, itemKey) {
+              if (itemKey !== "getState") return Reflect.get(item, itemKey);
+              return () => ({ ...item.getState(), status: "new" });
+            },
+          });
+        },
+      });
+    },
+  };
+});
+
+vi.mock("@assistant-ui/core/react", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("@assistant-ui/core/react")>();
+  return {
+    ...original,
+    useRemoteThreadListRuntime: (
+      options: Parameters<typeof original.useRemoteThreadListRuntime>[0],
+    ) =>
+      directRuntimeHook.current
+        ? options.runtimeHook()
+        : original.useRemoteThreadListRuntime(options),
+  };
+});
+
+vi.mock("./eveCloudSessions", async (importOriginal) => {
+  const original = await importOriginal<typeof import("./eveCloudSessions")>();
+  return {
+    ...original,
+    createEveCloudSessions: () => {
+      const sessions = original.createEveCloudSessions();
+      sessionInstances.push(sessions);
+      return sessions;
+    },
+  };
+});
+
+type Family = { current: unknown };
+type RendererInternals = {
+  setRefreshHandler: (resolve: (type: unknown) => Family | undefined) => void;
+  scheduleRefresh: (
+    root: unknown,
+    update: { staleFamilies: Set<Family>; updatedFamilies: Set<Family> },
+  ) => void;
+};
+
+let renderer: RendererInternals | undefined;
+const fiberRoots = new Set<unknown>();
+vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+vi.stubGlobal("__REACT_DEVTOOLS_GLOBAL_HOOK__", {
+  supportsFiber: true,
+  inject: (internals: RendererInternals) => {
+    renderer = internals;
+    return 1;
+  },
+  onScheduleFiberRoot: () => {},
+  onCommitFiberRoot: (_id: number, root: unknown) => fiberRoots.add(root),
+  onCommitFiberUnmount: () => {},
+});
+const { cleanup, render, waitFor } = await import("@testing-library/react");
+const { AssistantRuntimeProvider } = await import("@assistant-ui/core/react");
+const { useEveAgentRuntime } = await import("./useEveAgentRuntime");
+const { useEveReset } = await import("./hooks");
+const { useAui } = await import("@assistant-ui/store");
+
+afterEach(() => {
+  cleanup();
+  mockUseEveAgent.mockReset();
+  directRuntimeHook.current = false;
+  sessionInstances.length = 0;
+  renderer!.setRefreshHandler(() => undefined);
+  fiberRoots.clear();
+});
+afterAll(() => vi.unstubAllGlobals());
+
+const refresh = async (Before: unknown, After: unknown) => {
+  const family: Family = { current: After };
+  renderer!.setRefreshHandler((type) =>
+    type === Before || type === After ? family : undefined,
+  );
+  await act(async () => {
+    for (const root of fiberRoots) {
+      renderer!.scheduleRefresh(root, {
+        staleFamilies: new Set(),
+        updatedFamilies: new Set([family]),
+      });
+    }
+  });
+  await act(async () => {});
+};
+
+const makeAgent = (send: (content: string) => Promise<void>) => ({
+  data: {
+    messages: [
+      { id: "u1", role: "user", parts: [{ type: "text", text: "earlier" }] },
+      {
+        id: "a1",
+        role: "assistant",
+        parts: [{ type: "text", text: "earlier answer" }],
+      },
+    ],
+  },
+  error: undefined,
+  events: [],
+  session: undefined,
+  status: "ready",
+  send: vi.fn(send),
+  respond: vi.fn(async () => {}),
+  cancel: vi.fn(async () => ({ status: "no_active_turn" })),
+  reset: vi.fn(),
+  resume: vi.fn(async () => {}),
+});
+
+it("dispatches an Eve send queued behind a turn after Fast Refresh", async () => {
+  let releaseFirst!: () => void;
+  const agent = makeAgent(
+    vi
+      .fn()
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            releaseFirst = resolve;
+          }),
+      )
+      .mockResolvedValue(undefined),
+  );
+  mockUseEveAgent.mockReturnValue(agent);
+  let runtime!: ReturnType<typeof useEveAgentRuntime>;
+  let rendered = "";
+  const Before = () => {
+    rendered = "before";
+    runtime = useEveAgentRuntime();
+    return null;
+  };
+  const After = () => {
+    rendered = "after";
+    runtime = useEveAgentRuntime();
+    return null;
+  };
+  const view = render(<Before />);
+
+  await act(async () => runtime.thread.append("first"));
+  await waitFor(() => expect(agent.send).toHaveBeenCalledTimes(1));
+  await act(async () => runtime.thread.append("queued"));
+  expect(agent.send).toHaveBeenCalledTimes(1);
+
+  await refresh(Before, After);
+  expect(rendered).toBe("after");
+  await act(async () => releaseFirst());
+  await waitFor(() => expect(agent.send).toHaveBeenCalledTimes(2));
+  expect(agent.send).toHaveBeenNthCalledWith(2, "queued", undefined);
+  view.unmount();
+});
+
+it("abandons an Eve send still queued when the runtime unmounts", async () => {
+  let releaseFirst!: () => void;
+  const agent = makeAgent(
+    vi
+      .fn()
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            releaseFirst = resolve;
+          }),
+      )
+      .mockResolvedValue(undefined),
+  );
+  mockUseEveAgent.mockReturnValue(agent);
+  let runtime!: ReturnType<typeof useEveAgentRuntime>;
+  const Host = () => {
+    runtime = useEveAgentRuntime();
+    return null;
+  };
+  const view = render(<Host />);
+  await act(async () => runtime.thread.append("first"));
+  await waitFor(() => expect(agent.send).toHaveBeenCalledTimes(1));
+  await act(async () => runtime.thread.append("queued"));
+
+  view.unmount();
+  await act(async () => {});
+  await act(async () => releaseFirst());
+  expect(agent.send).toHaveBeenCalledTimes(1);
+});
+
+const makeCloud = () => {
+  const create = vi.fn(async () => ({ thread_id: "cloud-1" }));
+  const cloud = {
+    threads: {
+      list: vi.fn(async () => ({ threads: [] })),
+      create,
+      update: vi.fn(async () => {}),
+      delete: vi.fn(async () => {}),
+      get: vi.fn(),
+      messages: {
+        list: vi.fn(async () => ({ messages: [] })),
+        create: vi.fn(async () => ({ message_id: "cloud-message" })),
+        update: vi.fn(async () => {}),
+      },
+    },
+    events: { track: vi.fn() },
+    telemetry: { enabled: false },
+    runs: { report: vi.fn(async () => {}) },
+    registerSdk: vi.fn(),
+  } as unknown as AssistantCloud;
+  return { cloud, create };
+};
+
+it("resolves a pending first Eve session after Fast Refresh", async () => {
+  const { cloud, create } = makeCloud();
+  let onSessionChange:
+    | ((session: { sessionId: string; streamIndex: number }) => void)
+    | undefined;
+  const agent = makeAgent(async () => {});
+  agent.data.messages = [];
+  mockUseEveAgent.mockImplementation((options) => {
+    onSessionChange = options.onSessionChange;
+    return agent;
+  });
+  let runtime!: ReturnType<typeof useEveAgentRuntime>;
+  let rendered = "";
+  const Probe = () => {
+    useEveReset();
+    return null;
+  };
+  const Before = () => {
+    rendered = "before";
+    runtime = useEveAgentRuntime({ cloud });
+    return (
+      <AssistantRuntimeProvider runtime={runtime}>
+        <Probe />
+      </AssistantRuntimeProvider>
+    );
+  };
+  const After = () => {
+    rendered = "after";
+    runtime = useEveAgentRuntime({ cloud });
+    return (
+      <AssistantRuntimeProvider runtime={runtime}>
+        <Probe />
+      </AssistantRuntimeProvider>
+    );
+  };
+  const view = render(<Before />);
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+  await act(async () => runtime.thread.append("first"));
+  await waitFor(() => expect(agent.send).toHaveBeenCalledTimes(1));
+  expect(create).not.toHaveBeenCalled();
+
+  await refresh(Before, After);
+  expect(rendered).toBe("after");
+  expect(create).not.toHaveBeenCalled();
+  act(() => onSessionChange?.({ sessionId: "session-1", streamIndex: 0 }));
+  await waitFor(() =>
+    expect(create).toHaveBeenCalledWith({
+      last_message_at: expect.any(Date),
+      external_id: "session-1",
+      upsert: true,
+    }),
+  );
+  view.unmount();
+});
+
+it("keeps a first Eve session wait alive when a nested runtimeHook refreshes", async () => {
+  directRuntimeHook.current = true;
+  const { cloud } = makeCloud();
+  const agent = makeAgent(async () => {});
+  let onSessionChange:
+    | ((session: { sessionId: string; streamIndex: number }) => void)
+    | undefined;
+  mockUseEveAgent.mockImplementation((options) => {
+    onSessionChange = options.onSessionChange;
+    return agent;
+  });
+  let threadId = "";
+  let rendered = "";
+  const Before = () => {
+    rendered = "before";
+    threadId = useAui().threadListItem.getState().id;
+    useEveAgentRuntime({ cloud });
+    return null;
+  };
+  const After = () => {
+    rendered = "after";
+    threadId = useAui().threadListItem.getState().id;
+    useEveAgentRuntime({ cloud });
+    return null;
+  };
+  const Host = ({ children }: { children: ReactNode }) => {
+    const runtime = useEveAgentRuntime();
+    return (
+      <AssistantRuntimeProvider runtime={runtime}>
+        {children}
+      </AssistantRuntimeProvider>
+    );
+  };
+  const view = render(
+    <Host>
+      <Before />
+    </Host>,
+  );
+  const sessions = sessionInstances[0] as EveCloudSessions;
+  const waiting = sessions.wait(threadId);
+
+  await refresh(Before, After);
+  expect(rendered).toBe("after");
+  act(() => onSessionChange?.({ sessionId: "session-1", streamIndex: 0 }));
+  await expect(waiting).resolves.toBe("session-1");
+  view.unmount();
+});

package/src/useEveAgentRuntime.ts

@@ -24,9 +24,14 @@ import {
   type ToolExecutionStatus,
 } from "@assistant-ui/core";
 import {
+  useCloudThreadListAdapter,
   useExternalStoreRuntime,
+  useRemoteThreadListRuntime,
   useRuntimeAdapters,
 } from "@assistant-ui/core/react";
+import { useReplaySafeEffect } from "@assistant-ui/store/internal";
+import { useAui } from "@assistant-ui/store";
+import type { AssistantCloud } from "assistant-cloud";
 import {
   useEveAgent,
   type EveMessageData,
@@ -43,7 +48,12 @@ import {
   collectTurnTimestamps,
   createTurnTimestampCache,
 } from "./deriveCreatedAt";
+import {
+  createEveCloudSessions,
+  type EveCloudSessions,
+} from "./eveCloudSessions";
 import { eveExtras } from "./eveExtras";
+import { EVE_SDK } from "./sdkIdentity";
 
 const USER_STAGED_STATUS = {
   type: "complete",
@@ -125,10 +135,9 @@ const toEveSendOptions = (
     ? { clientContext: runConfig.custom as EveClientContext }
     : undefined;
 
-export type UseEveAgentRuntimeOptions = Omit<
-  UseEveAgentOptions<EveMessageData>,
-  "reducer"
-> &
+type EveAgentOptions = Omit<UseEveAgentOptions<EveMessageData>, "reducer">;
+
+export type UseEveAgentRuntimeOptions = EveAgentOptions &
   ExternalStoreSharedOptions & {
     readonly adapters?:
       | {
@@ -139,18 +148,44 @@ export type UseEveAgentRuntimeOptions = Omit<
           readonly feedback?: FeedbackAdapter | undefined;
         }
       | undefined;
+    /**
+     * Backs the thread list with Assistant Cloud. Each cloud thread keeps one Eve session as its external id, saved once the thread's first turn creates the session, and opening a thread resumes it, so `session`, `initialSession`, `initialEvents`, and `resume` are not used. Pass it from the first render: adding or removing it later throws, so remount the runtime, for example with a `key`, to switch.
+     */
+    readonly cloud?: AssistantCloud | undefined;
   };
 
-/**
- * Connects Eve's `useEveAgent` hook to assistant-ui's runtime contract.
- *
- * The runtime renders Eve messages, forwards new user messages to the Eve
- * session, supports cancellation, and maps Eve input requests to assistant-ui
- * tool approval UI.
- */
-export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
+type EveCloudThread = {
+  readonly sessions: EveCloudSessions;
+  readonly id: string;
+  readonly isNew: boolean;
+  readonly sessionId: string | undefined;
+};
+
+const withCloudThreadSession = (
+  {
+    initialEvents: _initialEvents,
+    initialSession: _initialSession,
+    resume: _resume,
+    session: _session,
+    ...options
+  }: EveAgentOptions,
+  sessionId: string | undefined,
+): EveAgentOptions =>
+  sessionId === undefined
+    ? options
+    : {
+        ...options,
+        initialSession: { sessionId, streamIndex: 0 },
+        resume: true,
+      };
+
+const useEveThreadRuntime = (
+  options: UseEveAgentRuntimeOptions,
+  cloudSessions: EveCloudSessions | undefined,
+) => {
   const {
     adapters,
+    cloud: _cloud,
     isDisabled: _isDisabled,
     isSendDisabled: _isSendDisabled,
     suggestions: _suggestions,
@@ -162,10 +197,33 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
     ? true
     : never;
 
+  const aui = useAui();
+  const [cloudThread] = useState((): EveCloudThread | undefined => {
+    if (!cloudSessions) return undefined;
+    const { id, status, externalId } = aui.threadListItem.getState();
+    return {
+      sessions: cloudSessions,
+      id,
+      isNew: status === "new",
+      sessionId: externalId,
+    };
+  });
+  const [resumesOnMount] = useState(() =>
+    cloudThread
+      ? cloudThread.sessionId !== undefined
+      : agentOptions.resume === true,
+  );
+  const isSessionless =
+    cloudThread !== undefined &&
+    !cloudThread.isNew &&
+    cloudThread.sessionId === undefined;
+
   const { onError, onEvent, onFinish, onSessionChange } = agentOptions;
   const lastFinishStatusRef = useRef<UseEveAgentStatus | null>(null);
   const agent = useEveAgent({
-    ...agentOptions,
+    ...(cloudThread
+      ? withCloudThreadSession(agentOptions, cloudThread.sessionId)
+      : agentOptions),
     ...(onError
       ? {
           onError: (error) =>
@@ -182,17 +240,34 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
       lastFinishStatusRef.current = snapshot.status;
       invokeEveLifecycleCallback("onFinish", onFinish, snapshot);
     },
-    ...(onSessionChange
+    ...(onSessionChange || cloudThread?.isNew
       ? {
-          onSessionChange: (session) =>
+          onSessionChange: (session) => {
+            if (cloudThread?.isNew && session === undefined) {
+              cloudThread.sessions.reject(
+                cloudThread.id,
+                new Error("The eve turn ended before it created a session."),
+              );
+            } else if (cloudThread?.isNew && session !== undefined) {
+              cloudThread.sessions.resolve(cloudThread.id, session.sessionId);
+              // A first message staged without a run leaves the thread unsaved, so the run that creates the session saves it.
+              if (aui.threadListItem.getState().status === "new")
+                aui.threadListItem.initialize().catch(() => {});
+            }
             invokeEveLifecycleCallback(
               "onSessionChange",
               onSessionChange,
               session,
-            ),
+            );
+          },
         }
       : {}),
   });
+  if (cloudThread && !("resume" in agent)) {
+    throw new Error(
+      "useEveAgentRuntime needs eve 0.44.1 or later for `cloud`, because opening a cloud thread resumes its session.",
+    );
+  }
   const runtimeAdapters = useRuntimeAdapters();
   const [toolStatuses, setToolStatuses] = useState<
     Record<string, ToolExecutionStatus>
@@ -279,19 +354,22 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
     null,
   );
 
-  const enqueueSend = (
-    dispatch: () => Promise<void>,
-    epochRef: { current: number } = sendEpochRef,
-  ) => {
-    const epoch = epochRef.current;
-    const next = sendChainRef.current.then(() => {
-      if (!isMountedRef.current) throw sendAbandonedError;
-      if (epoch !== epochRef.current) throw sendCancelledError;
-      return dispatch();
-    });
-    sendChainRef.current = next.catch(() => {});
-    return next;
-  };
+  const enqueueSend = useCallback(
+    (
+      dispatch: () => Promise<void>,
+      epochRef: { current: number } = sendEpochRef,
+    ) => {
+      const epoch = epochRef.current;
+      const next = sendChainRef.current.then(() => {
+        if (!isMountedRef.current) throw sendAbandonedError;
+        if (epoch !== epochRef.current) throw sendCancelledError;
+        return dispatch();
+      });
+      sendChainRef.current = next.catch(() => {});
+      return next;
+    },
+    [],
+  );
 
   // The store outlives the component (useEveAgent holds it in a ref with no
   // cleanup), so queued sends must not fire server turns after unmount. The
@@ -301,10 +379,45 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
     isMountedRef.current = true;
     return () => {
       isMountedRef.current = false;
-      sendEpochRef.current += 1;
     };
   }, []);
 
+  // A replay (Fast Refresh, StrictMode) must not cancel the sends queued behind the active turn.
+  useReplaySafeEffect(
+    () => () => {
+      sendEpochRef.current += 1;
+    },
+    [],
+  );
+
+  // A replay rides the send chain because `resume()` rejects during a turn and upstream refuses sends while it runs; the reset counter keeps a cancel from dropping a refetch, and the hook's own replay on mount joins this one since upstream shares concurrent `resume()` calls.
+  const enqueueResume = useCallback(
+    () =>
+      enqueueSend(async () => {
+        const live = agentRef.current;
+        if (live.session === undefined || !("resume" in live)) return;
+        await live.resume();
+      }, resetEpochRef),
+    [enqueueSend],
+  );
+
+  useEffect(() => {
+    if (!resumesOnMount) return;
+    // StrictMode's second setup queues the replay again, so only the setup that survives queues it.
+    let active = true;
+    queueMicrotask(() => {
+      if (active) enqueueResume().catch(() => {});
+    });
+    return () => {
+      active = false;
+    };
+  }, [enqueueResume, resumesOnMount]);
+
+  useReplaySafeEffect(() => {
+    if (!cloudThread?.isNew) return;
+    return () => cloudThread.sessions.release(cloudThread.id);
+  }, [cloudThread]);
+
   useEffect(() => {
     if (stagedInputsRef.current.size === 0) return;
     const baseIds = new Set(convertedMessages.map((message) => message.id));
@@ -347,6 +460,11 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
   };
 
   const reset = useCallback(() => {
+    // A cloud thread keeps the session its external id names, so a fresh session starts a new thread and leaves this one in the list.
+    if (cloudThread) {
+      aui.threads.switchToNewThread();
+      return;
+    }
     runtimeRef.current?.thread.unstable_notifySessionReset();
     // Sends parked behind an active turn captured the pre-reset epoch, so the
     // epoch has to advance before the session is torn down or they dispatch
@@ -359,7 +477,7 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
     stagedInputsRef.current.clear();
     setToolStatuses({});
     agent.reset();
-  }, [agent]);
+  }, [agent, aui, cloudThread]);
 
   const extras = useMemo(
     () =>
@@ -376,6 +494,7 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
     ...pickExternalStoreSharedOptions(options),
     messages,
     isRunning: providerIsRunning,
+    isLoading: agent.status === "resuming",
     extras,
     unstable_enableToolInvocations: true,
     setToolStatuses,
@@ -387,7 +506,17 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
       feedback: adapters?.feedback,
     },
     onNew: async (message) => {
+      if (isSessionless)
+        throw new MessageNotSentError(
+          "This thread has no eve session to send to.",
+        );
       if (!(message.startRun ?? message.role === "user")) {
+        // Saving a new cloud thread waits for its first session, which a staged message never creates.
+        if (cloudThread?.isNew)
+          cloudThread.sessions.reject(
+            cloudThread.id,
+            new Error("The thread's first message was staged without a run."),
+          );
         stageUserMessage(message);
         return;
       }
@@ -474,20 +603,7 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
     ...("resume" in agent
       ? {
           onRefetchThread: () =>
-            // `resume()` rejects during a turn, so the replay rides the send
-            // chain like every other dispatch and runs once the turn parks; a
-            // cancel of that turn does not drop it, or the caller would be told
-            // the thread was refetched when it was not. Upstream shares one
-            // replay across concurrent `resume()` calls, so a refetch
-            // dispatched while `resume: true` is replaying on mount joins that
-            // read instead of taking a fresh one. The session is read at
-            // dispatch time because nothing durable exists before the first
-            // send lands.
-            enqueueSend(async () => {
-              const live = agentRef.current;
-              if (live.session === undefined) return;
-              await live.resume();
-            }, resetEpochRef).catch((error) => {
+            enqueueResume().catch((error) => {
               if (isDroppedSend(error)) return;
               throw error;
             }),
@@ -514,3 +630,45 @@ export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
 
   return runtime;
 };
+
+const useEveCloudRuntime = (
+  cloud: AssistantCloud,
+  options: UseEveAgentRuntimeOptions,
+) => {
+  const [sessions] = useState(createEveCloudSessions);
+  const adapter = useCloudThreadListAdapter({
+    cloud,
+    sdk: EVE_SDK,
+    upsert: true,
+    create: async (threadId) => ({ externalId: await sessions.wait(threadId) }),
+  });
+  return useRemoteThreadListRuntime({
+    adapter,
+    allowNesting: true,
+    runtimeHook: function RuntimeHook() {
+      return useEveThreadRuntime(options, sessions);
+    },
+  });
+};
+
+/**
+ * Connects Eve's `useEveAgent` hook to assistant-ui's runtime contract.
+ *
+ * The runtime renders Eve messages, forwards new user messages to the Eve
+ * session, supports cancellation, and maps Eve input requests to assistant-ui
+ * tool approval UI.
+ */
+export const useEveAgentRuntime = (options: UseEveAgentRuntimeOptions = {}) => {
+  const [hasCloud] = useState(options.cloud !== undefined);
+  if ((options.cloud !== undefined) !== hasCloud) {
+    throw new Error(
+      "useEveAgentRuntime cannot add or remove `cloud` after it mounts; remount it, for example with a `key`, to switch.",
+    );
+  }
+  if (!options.cloud) {
+    // oxlint-disable-next-line react-hooks/rules-of-hooks -- `cloud` stays set or unset for the runtime's lifetime, so every render takes the same branch
+    return useEveThreadRuntime(options, undefined);
+  }
+  // oxlint-disable-next-line react-hooks/rules-of-hooks -- `cloud` stays set or unset for the runtime's lifetime, so every render takes the same branch
+  return useEveCloudRuntime(options.cloud, options);
+};