@assistant-ui/core 0.3.12 → 0.3.14

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

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+
+import { StrictMode } from "react";
+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";
+
+describe("useExternalStoreRuntime lifecycle", () => {
+  it("keeps dispatching appends after StrictMode's simulated remount", async () => {
+    const onNew = vi.fn(async () => {});
+    const capture: { runtime: AssistantRuntime | null } = { runtime: null };
+    const App = () => {
+      const runtime = useExternalStoreRuntime({ messages: [], onNew });
+      capture.runtime = runtime;
+      return null;
+    };
+    render(
+      <StrictMode>
+        <App />
+      </StrictMode>,
+    );
+    expect(capture.runtime).not.toBeNull();
+
+    await act(async () => {
+      await capture.runtime!.thread.append({
+        role: "user",
+        content: [{ type: "text", text: "hello" }],
+      });
+    });
+
+    expect(onNew).toHaveBeenCalledTimes(1);
+  });
+
+  it("dispatches an append before unmount", async () => {
+    let resolveInitialization!: () => void;
+    const initialization = new Promise<void>((resolve) => {
+      resolveInitialization = resolve;
+    });
+    const onNew = vi.fn(async () => {});
+    const capture: { runtime: AssistantRuntime | null } = { runtime: null };
+    const App = () => {
+      const runtime = useExternalStoreRuntime({ messages: [], onNew });
+      capture.runtime = runtime;
+      return null;
+    };
+    const view = render(<App />);
+    expect(capture.runtime).not.toBeNull();
+    const core = (
+      capture.runtime!.thread as unknown as {
+        __internal_threadBinding: {
+          getState(): {
+            __internal_setGetInitializePromise(
+              getPromise: () => Promise<unknown> | undefined,
+            ): void;
+            append(message: unknown): Promise<void>;
+          };
+        };
+      }
+    ).__internal_threadBinding.getState();
+    core.__internal_setGetInitializePromise(() => initialization);
+
+    const appendPromise = core.append({
+      parentId: null,
+      sourceId: null,
+      runConfig: {},
+      role: "user",
+      content: [{ type: "text", text: "hello" }],
+      attachments: [],
+      metadata: { custom: {} },
+      createdAt: new Date(0),
+    });
+    await Promise.resolve();
+
+    expect(onNew).toHaveBeenCalledTimes(1);
+
+    view.unmount();
+    resolveInitialization();
+
+    await appendPromise;
+    expect(onNew).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,124 @@
+// @vitest-environment jsdom
+
+import { StrictMode } from "react";
+import { cleanup, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  AuiConfig,
+  useAui,
+  useAuiState,
+  type AssistantClient,
+} from "@assistant-ui/store";
+import type { ThreadSuggestion } from "../../runtime/interfaces/thread-runtime-core";
+import { Suggestions } from "../../store/clients/suggestions";
+import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
+import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
+
+let aui!: AssistantClient;
+let scopeSuggestions!: readonly { prompt: string }[];
+
+const Consumer = () => {
+  aui = useAui();
+  scopeSuggestions = useAuiState((s) => s.suggestions.suggestions);
+  return null;
+};
+
+const App = ({
+  suggestions,
+  config,
+  strict,
+}: {
+  suggestions?: ThreadSuggestion[];
+  config?: AuiConfig;
+  strict?: boolean;
+}) => {
+  const runtime = useExternalStoreRuntime({
+    messages: [],
+    onNew: async () => {},
+    ...(suggestions && { suggestions }),
+  });
+  const tree = (
+    <AssistantRuntimeProvider runtime={runtime} config={config}>
+      <Consumer />
+    </AssistantRuntimeProvider>
+  );
+  return strict ? <StrictMode>{tree}</StrictMode> : tree;
+};
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("useExternalStoreRuntime suggestions scope", () => {
+  it("exposes runtime suggestions on the suggestions scope", () => {
+    render(
+      <App
+        suggestions={[
+          { title: "Weather", label: "in SF", prompt: "What's the weather?" },
+          { prompt: "Help" },
+        ]}
+      />,
+    );
+
+    expect(scopeSuggestions).toEqual([
+      { title: "Weather", label: "in SF", prompt: "What's the weather?" },
+      { title: "Help", label: "", prompt: "Help" },
+    ]);
+    expect(aui.suggestions.suggestion({ index: 0 }).getState()).toEqual({
+      title: "Weather",
+      label: "in SF",
+      prompt: "What's the weather?",
+    });
+    expect(aui.suggestions.suggestion({ index: 1 }).getState()).toEqual({
+      title: "Help",
+      label: "",
+      prompt: "Help",
+    });
+    expect(aui.thread.getState().suggestions).toEqual([
+      { title: "Weather", label: "in SF", prompt: "What's the weather?" },
+      { prompt: "Help" },
+    ]);
+  });
+
+  it("exposes runtime suggestions under StrictMode", () => {
+    render(<App strict suggestions={[{ prompt: "Tell me a joke" }]} />);
+
+    expect(scopeSuggestions).toEqual([
+      { title: "Tell me a joke", label: "", prompt: "Tell me a joke" },
+    ]);
+  });
+
+  it("reports an empty scope without runtime suggestions", () => {
+    render(<App />);
+
+    expect(scopeSuggestions).toEqual([]);
+  });
+
+  it("follows runtime suggestion updates", async () => {
+    const view = render(<App suggestions={[{ prompt: "First" }]} />);
+    expect(scopeSuggestions).toEqual([
+      { title: "First", label: "", prompt: "First" },
+    ]);
+
+    view.rerender(<App suggestions={[{ prompt: "Second" }]} />);
+    await waitFor(() => {
+      expect(scopeSuggestions).toEqual([
+        { title: "Second", label: "", prompt: "Second" },
+      ]);
+    });
+  });
+
+  it("prefers config-provided suggestions over runtime suggestions", () => {
+    render(
+      <App
+        suggestions={[{ prompt: "Runtime" }]}
+        config={AuiConfig({ suggestions: Suggestions(["Static"]) })}
+      />,
+    );
+
+    expect(scopeSuggestions).toEqual([
+      { title: "Static", label: "", prompt: "Static" },
+    ]);
+    expect(aui.thread.getState().suggestions).toEqual([{ prompt: "Runtime" }]);
+  });
+});

package/src/react/runtimes/useExternalStoreRuntime.ts

@@ -5,6 +5,7 @@ import { ExternalStoreRuntimeCore } from "../../runtimes/internal";
 import type { ExternalStoreAdapter } from "../../runtimes/external-store/external-store-adapter";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import { AssistantRuntimeImpl } from "../../runtime/internal";
+import { invalidateThreadRuntime } from "../../runtime/utils/thread-runtime-lifecycle";
 import { useRuntimeAdapters } from "./RuntimeAdapterProvider";
 
 export const useExternalStoreRuntime = <T>(
@@ -12,6 +13,12 @@ export const useExternalStoreRuntime = <T>(
 ): AssistantRuntime => {
   const [runtime] = useState(() => new ExternalStoreRuntimeCore(store));
 
+  useEffect(() => {
+    return () => {
+      invalidateThreadRuntime(runtime.threads.getMainThreadRuntimeCore());
+    };
+  }, [runtime]);
+
   useEffect(() => {
     runtime.setAdapter(store);
   });

package/src/react/runtimes/useExternalStoreSharedOptions.ts

@@ -16,7 +16,9 @@ export const useExternalStoreSharedOptions = (
         unstable_capabilities,
         suggestions,
       }) satisfies {
-        [K in keyof Required<ExternalStoreSharedOptions>]: ExternalStoreSharedOptions[K];
+        [
+          K in keyof Required<ExternalStoreSharedOptions>
+        ]: ExternalStoreSharedOptions[K];
       },
     [isDisabled, isSendDisabled, unstable_capabilities, suggestions],
   );

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

@@ -1,9 +1,10 @@
 // @vitest-environment jsdom
 
-import { render, waitFor } from "@testing-library/react";
-import { StrictMode } from "react";
+import { act, render, waitFor } from "@testing-library/react";
+import { type FC, StrictMode } 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";
@@ -17,13 +18,49 @@ const makeCloud = () =>
     threads: {
       list: vi.fn().mockResolvedValue({ threads: [] }),
     },
+    files: {
+      generatePresignedUploadUrl: vi.fn().mockResolvedValue({
+        signedUrl: "https://storage.example/upload",
+        publicUrl: "https://cdn.example/file.txt",
+      }),
+    },
   }) as unknown as AssistantCloud;
 
 afterEach(() => {
+  vi.unstubAllGlobals();
   vi.restoreAllMocks();
 });
 
 describe("useLocalRuntime", () => {
+  it("surfaces the live thread after mount without user input", async () => {
+    const auiRef: { current: ReturnType<typeof useAui> | null } = {
+      current: null,
+    };
+    const loadingRef = { current: true };
+    const Capture: FC = () => {
+      auiRef.current = useAui();
+      loadingRef.current = useAuiState((s) => s.thread.isLoading);
+      return null;
+    };
+
+    const App = () => {
+      const runtime = useLocalRuntime(chatModel, {
+        unstable_enableMessageQueue: true,
+      });
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <Capture />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<App />);
+    await waitFor(() => {
+      expect(loadingRef.current).toBe(false);
+      expect(auiRef.current!.thread.getState().capabilities.queue).toBe(true);
+    });
+  });
+
   it("keeps the Cloud thread list loaded across unrelated rerenders", async () => {
     const firstCloud = makeCloud();
     const secondCloud = makeCloud();
@@ -59,6 +96,47 @@ describe("useLocalRuntime", () => {
     expect(firstCloud.threads.list).toHaveBeenCalledOnce();
   });
 
+  it("uses the current Cloud client for attachment uploads", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+    const firstCloud = makeCloud();
+    const secondCloud = makeCloud();
+    let addAttachment: ((file: File) => Promise<void>) | undefined;
+    let getAttachmentStatus: (() => unknown) | undefined;
+
+    const App = ({ cloud }: { cloud: AssistantCloud }) => {
+      const runtime = useLocalRuntime(chatModel, { cloud });
+      addAttachment = (file) => runtime.thread.composer.addAttachment(file);
+      getAttachmentStatus = () =>
+        runtime.thread.composer.getState().attachments[0]?.status;
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <div />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    const { rerender } = render(<App cloud={firstCloud} />);
+
+    await waitFor(() => {
+      expect(firstCloud.threads.list).toHaveBeenCalledOnce();
+    });
+
+    rerender(<App cloud={secondCloud} />);
+
+    await act(async () => {
+      await addAttachment!(
+        new File(["hello"], "notes.txt", { type: "text/plain" }),
+      );
+    });
+
+    expect(firstCloud.files.generatePresignedUploadUrl).not.toHaveBeenCalled();
+    expect(secondCloud.files.generatePresignedUploadUrl).toHaveBeenCalledOnce();
+    expect(getAttachmentStatus!()).toEqual({
+      type: "requires-action",
+      reason: "composer-send",
+    });
+  });
+
   it("handles rejected history loads", async () => {
     const error = new Error("history unavailable");
     const consoleError = vi
@@ -92,8 +170,56 @@ describe("useLocalRuntime", () => {
       );
     });
 
+    const loadsAfterMount = history.load.mock.calls.length;
+    const errorsAfterMount = consoleError.mock.calls.length;
+    expect(loadsAfterMount).toBeGreaterThan(0);
     rerender(renderApp());
-    expect(history.load).toHaveBeenCalledTimes(1);
-    expect(consoleError).toHaveBeenCalledTimes(1);
+    expect(history.load).toHaveBeenCalledTimes(loadsAfterMount);
+    expect(consoleError).toHaveBeenCalledTimes(errorsAfterMount);
+  });
+
+  it("exposes composer.canCancel while a run started after initial messages is in flight", async () => {
+    const hangingModel: ChatModelAdapter = {
+      async *run({ abortSignal }) {
+        await new Promise<void>((resolve) => {
+          if (abortSignal.aborted) {
+            resolve();
+            return;
+          }
+          abortSignal.addEventListener("abort", () => resolve(), {
+            once: true,
+          });
+        });
+      },
+    };
+    let runtime: ReturnType<typeof useLocalRuntime> | null = null;
+    const App = () => {
+      runtime = useLocalRuntime(hangingModel, {
+        initialMessages: [
+          {
+            role: "assistant",
+            content: [{ type: "text", text: "Hello" }],
+            status: { type: "complete", reason: "stop" },
+          },
+        ],
+      });
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <div />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<App />);
+    act(() => {
+      runtime!.thread.append("Run");
+    });
+    await waitFor(() => {
+      expect(runtime!.thread.getState().isRunning).toBe(true);
+      expect(runtime!.thread.composer.getState().canCancel).toBe(true);
+    });
+    act(() => {
+      runtime!.thread.cancelRun();
+    });
   });
 });

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

@@ -0,0 +1,62 @@
+// @vitest-environment jsdom
+
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { useStableRuntimeAdapters } from "./useRuntimeAdapters";
+import type { RuntimeAdapters } from "../../runtimes/remote-thread-list/types";
+import type { ThreadHistoryAdapter } from "../../adapters/thread-history";
+
+const makeHistory = (): ThreadHistoryAdapter => ({
+  load: async () => ({ messages: [] }),
+  append: async () => {},
+});
+
+describe("useStableRuntimeAdapters", () => {
+  it("keeps the previous bag when a fresh literal is shallow-equal", () => {
+    const history = makeHistory();
+    const { result, rerender } = renderHook(
+      ({ adapters }: { adapters: RuntimeAdapters | null }) =>
+        useStableRuntimeAdapters(adapters),
+      { initialProps: { adapters: { history } } },
+    );
+    const first = result.current;
+
+    rerender({ adapters: { history } });
+
+    expect(result.current).toBe(first);
+  });
+
+  it("adopts the new bag when a field changes", () => {
+    const first = makeHistory();
+    const second = makeHistory();
+    const { result, rerender } = renderHook(
+      ({ adapters }: { adapters: RuntimeAdapters | null }) =>
+        useStableRuntimeAdapters(adapters),
+      { initialProps: { adapters: { history: first } } },
+    );
+
+    rerender({ adapters: { history: second } });
+
+    expect(result.current?.history).toBe(second);
+  });
+
+  it("moves between null and a bag", () => {
+    const history = makeHistory();
+    const { result, rerender } = renderHook(
+      ({ adapters }: { adapters: RuntimeAdapters | null }) =>
+        useStableRuntimeAdapters(adapters),
+      { initialProps: { adapters: null as RuntimeAdapters | null } },
+    );
+    expect(result.current).toBeNull();
+
+    rerender({ adapters: { history } });
+    expect(result.current?.history).toBe(history);
+
+    rerender({ adapters: null });
+    expect(result.current).toBeNull();
+
+    rerender({ adapters: {} });
+    expect(result.current).not.toBeNull();
+    expect(result.current).toEqual({});
+  });
+});

package/src/react/runtimes/useRuntimeAdapters.ts

@@ -0,0 +1,28 @@
+import { createContext, useContext } from "react";
+import { useContextProvider } from "@assistant-ui/tap";
+import { useShallowStable } from "@assistant-ui/store/internal";
+import type { RuntimeAdapters } from "../../runtimes/remote-thread-list/types";
+
+const RuntimeAdaptersContext = createContext<RuntimeAdapters | null>(null);
+
+export const useRuntimeAdaptersProvider = <T>(
+  adapters: RuntimeAdapters | null,
+  fn: () => T,
+): T => useContextProvider(RuntimeAdaptersContext, adapters, fn);
+
+export const useRuntimeAdapters = () => {
+  return useContext(RuntimeAdaptersContext);
+};
+
+const NO_ADAPTERS: RuntimeAdapters = {};
+
+// Both adapter faces absorb a fresh but shallow-equal bag from
+// `unstable_useAdapters`, so a per-render literal does not churn the context.
+export const useStableRuntimeAdapters = (
+  adapters: RuntimeAdapters | null | undefined,
+): RuntimeAdapters | null => {
+  const stable = useShallowStable(adapters ?? NO_ADAPTERS);
+  return adapters == null ? null : stable;
+};
+
+export { RuntimeAdaptersContext };

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

@@ -42,6 +42,11 @@ export type {
 };
 
 type BaseComposerState = {
+  /**
+   * Whether the composer can cancel the current run. `true` when the runtime
+   * supports cancel and a run is in flight, not merely when cancel is a
+   * capability.
+   */
   readonly canCancel: boolean;
   readonly canSend: boolean;
   readonly isEditing: boolean;

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

@@ -114,6 +114,7 @@ export type ThreadListRuntimeCoreBinding = ThreadListRuntimeCore;
 
 export class ThreadListRuntimeImpl implements ThreadListRuntime {
   private _getState;
+  private _stateBinding: LazyMemoizeSubject<ThreadListState, object>;
   private _core: ThreadListRuntimeCoreBinding;
   private _runtimeFactory: new (
     binding: ThreadRuntimeCoreBinding,
@@ -136,6 +137,7 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
     });
 
     this._getState = stateBinding.getState.bind(stateBinding);
+    this._stateBinding = stateBinding;
 
     this._mainThreadListItemRuntime = new ThreadListItemRuntimeImpl(
       new ShallowMemoizeSubject({
@@ -213,7 +215,7 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
   }
 
   public subscribe(callback: () => void): Unsubscribe {
-    return this._core.subscribe(callback);
+    return this._stateBinding.subscribe(callback);
   }
 
   private _mainThreadListItemRuntime;

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

@@ -34,6 +34,7 @@ import type {
 import type { ThreadListItemState } from "./bindings";
 import type { AppendMessage, ThreadMessage } from "../../types/message";
 import type { Unsubscribe } from "../../types/unsubscribe";
+import { isMessageNotSentError } from "../../types/error";
 import type { RunConfig } from "../../types/message";
 import { EventSubscriptionSubject } from "../../subscribable/subscribable";
 import { symbolInnerMessage } from "../utils/external-store-message";
@@ -198,7 +199,7 @@ export type ThreadState = {
  * reports it directly; the rest fall back to the trailing assistant message.
  */
 export const getThreadRuntimeCoreIsRunning = (
-  runtime: ThreadRuntimeCore,
+  runtime: Pick<ThreadRuntimeCore, "isRunning" | "messages">,
 ): boolean => {
   if (runtime.isRunning !== undefined) return runtime.isRunning;
   const lastMessage = runtime.messages.at(-1);
@@ -293,6 +294,13 @@ export type ThreadRuntime = {
 
   subscribe(callback: () => void): Unsubscribe;
   cancelRun(): void;
+  /**
+   * Notifies the runtime that the adapter discarded its backing session.
+   * Clears session-scoped tool-invocation state without run-cancel side
+   * effects such as composer draft restoration. Internal API for
+   * external-store adapter authors.
+   */
+  unstable_notifySessionReset(): void;
   getModelContext(): ModelContext;
 
   export(): ExportedMessageRepository;
@@ -338,6 +346,10 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
   private readonly _threadBinding: ThreadRuntimeCoreBinding & {
     getStateState(): ThreadState;
   };
+  private readonly _stateBinding: ShallowMemoizeSubject<
+    ThreadState,
+    ThreadRuntimePath
+  >;
 
   constructor(
     threadBinding: ThreadRuntimeCoreBinding,
@@ -360,6 +372,7 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
       },
     });
 
+    this._stateBinding = stateBinding;
     this._threadBinding = {
       path: threadBinding.path,
       getState: () => threadBinding.getState(),
@@ -391,6 +404,8 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     this.exportExternalState = this.exportExternalState.bind(this);
     this.startRun = this.startRun.bind(this);
     this.cancelRun = this.cancelRun.bind(this);
+    this.unstable_notifySessionReset =
+      this.unstable_notifySessionReset.bind(this);
     this.stopSpeaking = this.stopSpeaking.bind(this);
     this.connectVoice = this.connectVoice.bind(this);
     this.disconnectVoice = this.disconnectVoice.bind(this);
@@ -416,11 +431,17 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
   }
 
   public append(message: CreateAppendMessage) {
-    this._threadBinding
+    const task = this._threadBinding
       .getState()
       .append(
         toAppendMessage(this._threadBinding.getState().messages, message),
       );
+    // An undispatched send is reported to the composer, so it is a control
+    // signal rather than a failure to surface; every other rejection keeps
+    // reaching the host untouched.
+    void Promise.resolve(task).catch((error) => {
+      if (!isMessageNotSentError(error)) throw error;
+    });
   }
 
   public deleteMessage(messageId: string) {
@@ -428,7 +449,7 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
   }
 
   public subscribe(callback: () => void) {
-    return this._threadBinding.subscribe(callback);
+    return this._stateBinding.subscribe(callback);
   }
 
   public getModelContext() {
@@ -455,6 +476,10 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     this._threadBinding.getState().cancelRun();
   }
 
+  public unstable_notifySessionReset() {
+    this._threadBinding.getState().unstable_notifySessionReset();
+  }
+
   public stopSpeaking() {
     return this._threadBinding.getState().stopSpeaking();
   }