@assistant-ui/core 0.3.16 → 0.3.17

package/src/store/clients/suggestions.ts

@@ -2,6 +2,7 @@ import { useMemo } from "react";
 import { resource, withKey } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import { useClientLookup } from "@assistant-ui/store/client";
+import { shallowEqual } from "@assistant-ui/store/internal";
 import type { SuggestionsState } from "../scopes/suggestions";
 import type { SuggestionState } from "../scopes/suggestion";
 import type { ThreadSuggestion } from "../../runtime/interfaces/thread-runtime-core";
@@ -10,6 +11,31 @@ export type SuggestionConfig =
   | string
   | { title: string; label: string; prompt: string };
 
+const useStableSuggestionsState = (
+  next: SuggestionsState,
+): SuggestionsState => {
+  const cell = useMemo(() => ({}) as { state?: SuggestionsState }, []);
+  const previous = cell.state;
+
+  const suggestions = next.suggestions.map((suggestion, index) => {
+    const previousSuggestion = previous?.suggestions[index];
+    return previousSuggestion && shallowEqual(previousSuggestion, suggestion)
+      ? previousSuggestion
+      : suggestion;
+  });
+  const state =
+    previous &&
+    previous.suggestions.length === suggestions.length &&
+    suggestions.every(
+      (suggestion, index) => suggestion === previous.suggestions[index],
+    )
+      ? previous
+      : { suggestions };
+
+  cell.state = state;
+  return state;
+};
+
 const useSuggestionClient = (
   state: SuggestionState,
 ): ClientOutput<"suggestion"> => {
@@ -21,8 +47,9 @@ const useSuggestionClient = (
 const SuggestionClient = resource(useSuggestionClient);
 
 const useSuggestionsClient = (
-  state: SuggestionsState,
+  nextState: SuggestionsState,
 ): ClientOutput<"suggestions"> => {
+  const state = useStableSuggestionsState(nextState);
   const suggestionClients = useClientLookup(
     state.suggestions.map((suggestion, index) =>
       withKey(index, SuggestionClient(suggestion), [suggestion]),
@@ -40,27 +67,13 @@ const useSuggestionsClient = (
 const useStaticSuggestions = (
   suggestions?: SuggestionConfig[],
 ): ClientOutput<"suggestions"> => {
-  const state = useMemo<SuggestionsState>(
-    () => ({
-      suggestions: (suggestions ?? []).map((s) => {
-        if (typeof s === "string") {
-          return {
-            title: s,
-            label: "",
-            prompt: s,
-          };
-        }
-        return {
-          title: s.title,
-          label: s.label,
-          prompt: s.prompt,
-        };
-      }),
-    }),
-    [suggestions],
-  );
-
-  return useSuggestionsClient(state);
+  return useSuggestionsClient({
+    suggestions: (suggestions ?? []).map((s) =>
+      typeof s === "string"
+        ? { title: s, label: "", prompt: s }
+        : { title: s.title, label: s.label, prompt: s.prompt },
+    ),
+  });
 };
 
 export const Suggestions = resource(useStaticSuggestions);
@@ -68,18 +81,13 @@ export const Suggestions = resource(useStaticSuggestions);
 const useThreadSuggestions = (
   suggestions: readonly ThreadSuggestion[],
 ): ClientOutput<"suggestions"> => {
-  const state = useMemo<SuggestionsState>(
-    () => ({
-      suggestions: suggestions.map((s) => ({
-        title: s.title ?? s.prompt,
-        label: s.label ?? "",
-        prompt: s.prompt,
-      })),
-    }),
-    [suggestions],
-  );
-
-  return useSuggestionsClient(state);
+  return useSuggestionsClient({
+    suggestions: suggestions.map((s) => ({
+      title: s.title ?? s.prompt,
+      label: s.label ?? "",
+      prompt: s.prompt,
+    })),
+  });
 };
 
 export const ThreadSuggestions = resource(useThreadSuggestions);

package/src/store/index.ts

@@ -108,6 +108,10 @@ export {
   createRuntimeExtrasBrand,
   type RuntimeExtrasBrand,
 } from "../runtime/utils/runtime-extras-brand";
+export {
+  resolveToolCallText,
+  type ToolCallText,
+} from "../model-context/tool-call-text";
 export { defineToolkit } from "../react/model-context/define-toolkit";
 export {
   defineMcpToolkit,

package/src/store/internal.ts

@@ -15,7 +15,9 @@ export {
   composerCancelDisabled,
   composerInputDisabled,
   composerSendDisabled,
+  messageErrorText,
   suggestionTriggerDisabled,
+  threadListLoadMoreDisabled,
 } from "./primitive-predicates";
 export { isDevelopment } from "./env";
 export { useThreadSelectionEvents } from "./clients/thread-selection-events";

package/src/store/primitive-predicates.ts

@@ -1,3 +1,7 @@
+import type {
+  ReadonlyJSONArray,
+  ReadonlyJSONObject,
+} from "assistant-stream/utils";
 import type { AssistantState } from "@assistant-ui/store";
 
 /**
@@ -41,3 +45,34 @@ export const suggestionTriggerDisabled = (
 ): boolean =>
   s.thread.isDisabled ||
   (send && s.thread.isRunning && !s.thread.capabilities.queue);
+
+export const messageErrorText = (
+  s: AssistantState,
+):
+  | string
+  | number
+  | boolean
+  | ReadonlyJSONObject
+  | ReadonlyJSONArray
+  | undefined => {
+  if (
+    s.message.status?.type !== "incomplete" ||
+    s.message.status.reason !== "error"
+  ) {
+    return undefined;
+  }
+  const error = s.message.status.error;
+  if (typeof error === "string") return error;
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    typeof error.message === "string"
+  ) {
+    return error.message;
+  }
+  return error ?? "An error occurred";
+};
+
+export const threadListLoadMoreDisabled = (s: AssistantState): boolean =>
+  !s.threads.hasMore || s.threads.isLoading || s.threads.isLoadingMore;

package/src/store/runtime-clients/thread-list-runtime-client.ts

@@ -1,7 +1,11 @@
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import { useResource, withKey, resource } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
-import { useClientLookup, useClientResource } from "@assistant-ui/store/client";
+import {
+  useAssistantEmit,
+  useClientLookup,
+  useClientResource,
+} from "@assistant-ui/store/client";
 import { useThreadSelectionEvents } from "../clients/thread-selection-events";
 import type { ThreadListRuntime } from "../../runtime/api/thread-list-runtime";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
@@ -44,6 +48,16 @@ const useThreadListClient = ({
   const runtimeState = useSubscribable(runtime);
   useThreadSelectionEvents(runtimeState.mainThreadId);
 
+  const emit = useAssistantEmit();
+  useEffect(
+    () =>
+      runtime.unstable_subscribeThreadEvents(({ threadId, type }) => {
+        if (threadId === runtime.getState().mainThreadId) return;
+        emit(`thread.${type}`, { threadId });
+      }),
+    [runtime, emit],
+  );
+
   const main = useClientResource(
     ThreadClient({
       runtime: runtime.main,

package/src/store/runtime-clients/useSubscribable.ts

@@ -2,7 +2,13 @@ import { useSyncExternalStore } from "react";
 import type { SubscribableWithState } from "../../subscribable/subscribable";
 
 export const useSubscribable = <T>(
-  subscribable: Omit<SubscribableWithState<T, any>, "path">,
+  subscribable: Omit<SubscribableWithState<T, any>, "path"> & {
+    getServerSnapshot?: () => T;
+  },
 ) => {
-  return useSyncExternalStore(subscribable.subscribe, subscribable.getState);
+  return useSyncExternalStore(
+    subscribable.subscribe,
+    subscribable.getState,
+    subscribable.getServerSnapshot,
+  );
 };

package/src/store/scopes/part.ts

@@ -29,10 +29,13 @@ export type PartMethods = {
   resumeToolCall(payload: unknown): void;
   /**
    * Respond to a server-side tool approval gate. The approval id is read from
-   * the part. Accepts a boolean decision or the id of one of the approval's
-   * options.
+   * the part. Accepts a boolean decision, the id of one of the approval's
+   * options, or a free-form answer when the request asks for one.
+   *
+   * Resolves once the runtime has accepted the response, and rejects when it
+   * could not be recorded, so a renderer can leave its controls retryable.
    */
-  respondToToolApproval(response: ToolApprovalResponse): void;
+  respondToToolApproval(response: ToolApprovalResponse): Promise<void>;
   __internal_getRuntime?(): MessagePartRuntime;
 };
 

package/src/subscribable/subscribable.test.ts

@@ -32,6 +32,30 @@ const createBinding = (initialState: TestState) => {
   };
 };
 
+// Mirrors runtime bindings such as `getThreadListState`, which assemble a new
+// object on every read while the underlying values keep their identity.
+const createRebuildingBinding = (initialState: TestState) => {
+  let state = initialState;
+  const subscribers = new Set<() => void>();
+
+  const binding: SubscribableWithState<TestState, null> = {
+    path: null,
+    getState: () => ({ ...state }),
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      return () => subscribers.delete(callback);
+    },
+  };
+
+  return {
+    binding,
+    update(nextState: TestState) {
+      state = nextState;
+      for (const callback of subscribers) callback();
+    },
+  };
+};
+
 describe("ShallowMemoizeSubject", () => {
   it("notifies subscribers when a state key is removed", () => {
     const source = createBinding({
@@ -131,4 +155,30 @@ describe("LazyMemoizeSubject", () => {
     expect(subject.getState()).toEqual({ status: "ready" });
     reconnect();
   });
+
+  it("keeps one reference while unconnected and the state is unchanged", () => {
+    // A consumer that reads without subscribing (React's useSyncExternalStore
+    // calls getSnapshot outside the subscription) must not see a new object on
+    // every call: React compares snapshots with Object.is, so a fresh reference
+    // reads as a change and re-renders forever.
+    const source = createRebuildingBinding({ status: "ready" });
+    const subject = new LazyMemoizeSubject(source.binding);
+
+    const first = subject.getState();
+
+    expect(subject.getState()).toBe(first);
+    expect(subject.getState()).toBe(first);
+  });
+
+  it("returns a new reference once the unchanged state actually changes", () => {
+    const source = createRebuildingBinding({ status: "ready" });
+    const subject = new LazyMemoizeSubject(source.binding);
+
+    const first = subject.getState();
+    source.update({ status: "done" });
+
+    const second = subject.getState();
+    expect(second).not.toBe(first);
+    expect(second).toEqual({ status: "done" });
+  });
 });

package/src/subscribable/subscribable.ts

@@ -1,3 +1,4 @@
+import { shallowEqual } from "@assistant-ui/store/client";
 import type { Unsubscribe } from "../types/unsubscribe";
 import { notifyEventListeners } from "../utils/notify-event-listeners";
 
@@ -57,25 +58,10 @@ export const notifySubscribers = <TArgs extends unknown[]>(
   }
 };
 
-function shallowEqual<T extends object>(
-  objA: T | undefined,
-  objB: T | undefined,
-) {
-  if (objA === undefined && objB === undefined) return true;
-  if (objA === undefined) return false;
-  if (objB === undefined) return false;
-
-  const keysA = Object.keys(objA);
-  if (keysA.length !== Object.keys(objB).length) return false;
-
-  for (const key of keysA) {
-    const valueA = objA[key as keyof T];
-    const valueB = objB[key as keyof T];
-    if (!Object.is(valueA, valueB)) return false;
-  }
-
-  return true;
-}
+const shallowEqualOrUndefined = <T extends object>(
+  a: T | undefined,
+  b: T | undefined,
+) => (a === undefined || b === undefined ? a === b : shallowEqual(a, b));
 
 export class BaseSubscribable {
   private _subscribers = new Set<() => void>();
@@ -99,6 +85,32 @@ export class BaseSubscribable {
   }
 }
 
+export class WritableSubscribable<TState> extends BaseSubscribable {
+  private _state: TState;
+
+  constructor(state: TState) {
+    super();
+    this._state = state;
+    this.subscribe = this.subscribe.bind(this);
+    this.getState = this.getState.bind(this);
+    // Hydration has to agree with what the server rendered, so the server
+    // snapshot stays at the creation-time state rather than following writes.
+    this.getServerSnapshot = () => state;
+  }
+
+  public getState(): TState {
+    return this._state;
+  }
+
+  public getServerSnapshot: () => TState;
+
+  public setState(state: TState): void {
+    if (Object.is(state, this._state)) return;
+    this._state = state;
+    this._notifySubscribers();
+  }
+}
+
 // lazy connect/disconnect: only opens upstream subscription while it has subscribers
 export abstract class BaseSubject {
   private _subscriptions = new Set<(payload?: unknown) => void>();
@@ -168,7 +180,7 @@ export class ShallowMemoizeSubject<TState extends object, TPath>
   private _syncState() {
     const state = this.binding.getState();
     if (state === SKIP_UPDATE) return false;
-    if (shallowEqual(state, this._previousState)) return false;
+    if (shallowEqualOrUndefined(state, this._previousState)) return false;
     this._previousState = state;
     return true;
   }
@@ -209,7 +221,7 @@ export class LazyMemoizeSubject<TState extends object, TPath>
       if (
         newState !== SKIP_UPDATE &&
         (this._previousState === undefined ||
-          !shallowEqual(newState, this._previousState))
+          !shallowEqualOrUndefined(newState, this._previousState))
       ) {
         this._previousState = newState;
       }

package/src/tests/RemoteThreadListThreadListRuntimeCore-load-race.test.ts

@@ -36,6 +36,117 @@ describe("RemoteThreadListThreadListRuntimeCore load race", () => {
     expect(core.threadIds[0]).toBe(newId);
     expect(core.threadIds).toContain("t1");
   });
+
+  it("keeps one slot when the list reports the thread just initialized", async () => {
+    const listDeferred = deferred<ListResult>();
+    const adapter = makeAdapter({
+      list: vi.fn(() => listDeferred.promise),
+      initialize: vi.fn(async () => ({
+        remoteId: "remote-1",
+        externalId: "remote-1",
+      })),
+    });
+    const core = createCore(adapter);
+
+    const loadPromise = core.getLoadThreadsPromise();
+    await core.switchToNewThread();
+    const localId = core.newThreadId!;
+    await core.initialize(localId);
+
+    listDeferred.resolve({
+      threads: [
+        { status: "regular", remoteId: "remote-1", externalId: "remote-1" },
+      ],
+    });
+    await loadPromise;
+
+    expect(Object.keys(core.threadItems)).toEqual([localId]);
+    expect(core.threadIds).toEqual([localId]);
+    expect(core.getItemById("remote-1")?.id).toBe(localId);
+    expect(core.mainThreadId).toBe(localId);
+
+    await core.delete("remote-1");
+
+    expect(core.getItemById(localId)).toBeUndefined();
+    expect(core.getItemById("remote-1")).toBeUndefined();
+    expect(core.threadIds).toEqual([]);
+  });
+
+  it("collapses a slot the list minted while initialize was in flight", async () => {
+    const listDeferred = deferred<ListResult>();
+    const initializeDeferred = deferred<{
+      remoteId: string;
+      externalId: string;
+    }>();
+    const adapter = makeAdapter({
+      list: vi.fn(() => listDeferred.promise),
+      initialize: vi.fn(() => initializeDeferred.promise),
+    });
+    const core = createCore(adapter);
+
+    const loadPromise = core.getLoadThreadsPromise();
+    await core.switchToNewThread();
+    const localId = core.newThreadId!;
+    const initializePromise = core.initialize(localId);
+
+    listDeferred.resolve({
+      threads: [
+        { status: "regular", remoteId: "remote-1", externalId: "remote-1" },
+      ],
+    });
+    await loadPromise;
+
+    initializeDeferred.resolve({
+      remoteId: "remote-1",
+      externalId: "remote-1",
+    });
+    await initializePromise;
+
+    expect(Object.keys(core.threadItems)).toEqual([localId]);
+    expect(core.threadIds).toEqual([localId]);
+    expect(core.getItemById("remote-1")?.id).toBe(localId);
+
+    await core.delete("remote-1");
+
+    expect(core.getItemById(localId)).toBeUndefined();
+    expect(core.getItemById("remote-1")).toBeUndefined();
+    expect(core.threadIds).toEqual([]);
+  });
+
+  it("does not leave the collapsed slot in both lists when the race reported it archived", async () => {
+    const listDeferred = deferred<ListResult>();
+    const initializeDeferred = deferred<{
+      remoteId: string;
+      externalId: string;
+    }>();
+    const adapter = makeAdapter({
+      list: vi.fn(() => listDeferred.promise),
+      initialize: vi.fn(() => initializeDeferred.promise),
+    });
+    const core = createCore(adapter);
+
+    const loadPromise = core.getLoadThreadsPromise();
+    await core.switchToNewThread();
+    const localId = core.newThreadId!;
+    const initializePromise = core.initialize(localId);
+
+    listDeferred.resolve({
+      threads: [
+        { status: "archived", remoteId: "remote-1", externalId: "remote-1" },
+      ],
+    });
+    await loadPromise;
+
+    initializeDeferred.resolve({
+      remoteId: "remote-1",
+      externalId: "remote-1",
+    });
+    await initializePromise;
+
+    expect(Object.keys(core.threadItems)).toEqual([localId]);
+    expect(core.threadIds).toEqual([localId]);
+    expect(core.archivedThreadIds).toEqual([]);
+  });
 });
 
 describe("preserveMidLoadTransitions", () => {

package/src/tests/RemoteThreadListThreadListRuntimeCore-loadMore.test.ts

@@ -195,6 +195,30 @@ describe("RemoteThreadListThreadListRuntimeCore.loadMore", () => {
     expect(core.hasMore).toBe(false);
   });
 
+  it("clears loadingMore when the superseded request never settles", async () => {
+    const listFn = vi
+      .fn<ListFn>()
+      .mockResolvedValueOnce({
+        threads: [{ status: "regular", remoteId: "a", externalId: "a" }],
+        nextCursor: "c1",
+      })
+      .mockReturnValueOnce(new Promise<never>(() => {}))
+      .mockResolvedValueOnce({
+        threads: [
+          { status: "regular", remoteId: "fresh", externalId: "fresh" },
+        ],
+      });
+    const adapter = makeAdapter({ list: listFn });
+    const core = createCore(adapter);
+
+    await core.getLoadThreadsPromise();
+    void core.loadMore();
+    await core.reload();
+
+    expect(core.threadIds).toEqual(["fresh"]);
+    expect(core.isLoadingMore).toBe(false);
+  });
+
   it("releases the dedup handle after a rejection so retries can proceed", async () => {
     vi.spyOn(console, "error").mockImplementation(() => {});
     const listFn = vi
@@ -241,6 +265,60 @@ describe("RemoteThreadListThreadListRuntimeCore.loadMore", () => {
     expect(core.threadIds).toEqual(["a", "b"]);
   });
 
+  it("refreshes a thread repeated on a later page instead of dropping it", async () => {
+    const listFn = vi
+      .fn<ListFn>()
+      .mockResolvedValueOnce({
+        threads: [
+          { status: "regular", remoteId: "a", externalId: "a", title: "old" },
+        ],
+        nextCursor: "c1",
+      })
+      .mockResolvedValueOnce({
+        threads: [
+          {
+            status: "regular",
+            remoteId: "a",
+            externalId: "a",
+            title: "updated",
+          },
+          { status: "regular", remoteId: "b", externalId: "b", title: "New" },
+        ],
+      });
+    const core = createCore(makeAdapter({ list: listFn }));
+
+    await core.getLoadThreadsPromise();
+    await core.loadMore();
+
+    expect(core.threadIds).toEqual(["a", "b"]);
+    expect(core.getItemById("a")?.title).toBe("updated");
+  });
+
+  it("moves a thread whose status flips between pages", async () => {
+    const listFn = vi
+      .fn<ListFn>()
+      .mockResolvedValueOnce({
+        threads: [
+          { status: "regular", remoteId: "a", externalId: "a", title: "A" },
+          { status: "regular", remoteId: "b", externalId: "b", title: "B" },
+        ],
+        nextCursor: "c1",
+      })
+      .mockResolvedValueOnce({
+        threads: [
+          { status: "archived", remoteId: "a", externalId: "a", title: "A" },
+        ],
+      });
+    const core = createCore(makeAdapter({ list: listFn }));
+
+    await core.getLoadThreadsPromise();
+    await core.loadMore();
+
+    expect(core.threadIds).toEqual(["b"]);
+    expect(core.archivedThreadIds).toEqual(["a"]);
+    expect(core.getItemById("a")?.status).toBe("archived");
+  });
+
   it("__internal_setOptions clears cursor and dedup handles on adapter swap, then refetches via the new adapter", async () => {
     const firstAdapter = makeAdapter({
       list: vi.fn<ListFn>(async () => ({

package/src/tests/RemoteThreadListThreadListRuntimeCore-reload.test.ts

@@ -95,6 +95,58 @@ describe("RemoteThreadListThreadListRuntimeCore.reload", () => {
     expect(core.threadIds).not.toContain("stale");
   });
 
+  it("clears loading when the superseded request never settles", async () => {
+    const listFn = vi
+      .fn<() => Promise<RemoteThreadListResponse>>()
+      .mockReturnValueOnce(new Promise<never>(() => {}))
+      .mockResolvedValueOnce({
+        threads: [
+          {
+            status: "regular",
+            remoteId: "fresh",
+            externalId: "fresh",
+            title: "Fresh",
+          },
+        ],
+      });
+    const adapter = makeAdapter({ list: listFn });
+    const core = createCore(adapter);
+
+    void core.getLoadThreadsPromise();
+    await core.reload();
+
+    expect(core.threadIds).toEqual(["fresh"]);
+    expect(core.isLoading).toBe(false);
+  });
+
+  it("clears loading once the fresh list arrives, before the superseded request settles", async () => {
+    const first = deferred<RemoteThreadListResponse>();
+    const listFn = vi
+      .fn<() => Promise<RemoteThreadListResponse>>()
+      .mockReturnValueOnce(first.promise)
+      .mockResolvedValueOnce({
+        threads: [
+          {
+            status: "regular",
+            remoteId: "fresh",
+            externalId: "fresh",
+            title: "Fresh",
+          },
+        ],
+      });
+    const core = createCore(makeAdapter({ list: listFn }));
+
+    void core.getLoadThreadsPromise();
+    await core.reload();
+
+    expect(core.threadIds).toEqual(["fresh"]);
+    expect(core.isLoading).toBe(false);
+
+    first.resolve({ threads: [] });
+    await Promise.resolve();
+    expect(core.isLoading).toBe(false);
+  });
+
   it("recovers after a failed initial load", async () => {
     vi.spyOn(console, "error").mockImplementation(() => {});
     const listFn = vi