@assistant-ui/core 0.3.15 → 0.3.17

package/src/store/clients/suggestions.test.ts

@@ -0,0 +1,185 @@
+import { useState } from "react";
+import { createTapRoot, flushTapSync, useResource } from "@assistant-ui/tap";
+import { describe, expect, it } from "vitest";
+import type { ThreadSuggestion } from "../../runtime/interfaces/thread-runtime-core";
+import {
+  Suggestions,
+  ThreadSuggestions,
+  type SuggestionConfig,
+} from "./suggestions";
+
+describe("Suggestions", () => {
+  it("keeps equal inline string suggestions stable across owner renders", () => {
+    let rerender!: () => void;
+    const root = createTapRoot(function SuggestionsRoot() {
+      const [, setTick] = useState(0);
+      rerender = () => setTick((tick) => tick + 1);
+      return useResource(Suggestions(["account-a", "account-b"]));
+    });
+
+    try {
+      const firstState = root.getValue().getState();
+      const firstSuggestion = root
+        .getValue()
+        .suggestion({ index: 0 })
+        .getState();
+
+      flushTapSync(rerender);
+
+      expect(root.getValue().getState()).toBe(firstState);
+      expect(root.getValue().suggestion({ index: 0 }).getState()).toBe(
+        firstSuggestion,
+      );
+    } finally {
+      root.unmount();
+    }
+  });
+
+  it("keeps equal inline object suggestions stable across owner renders", () => {
+    let rerender!: () => void;
+    const root = createTapRoot(function SuggestionsRoot() {
+      const [, setTick] = useState(0);
+      rerender = () => setTick((tick) => tick + 1);
+      return useResource(
+        Suggestions([{ title: "Title", label: "Label", prompt: "Prompt" }]),
+      );
+    });
+
+    try {
+      const firstState = root.getValue().getState();
+      const firstSuggestion = root
+        .getValue()
+        .suggestion({ index: 0 })
+        .getState();
+
+      flushTapSync(rerender);
+
+      expect(root.getValue().getState()).toBe(firstState);
+      expect(root.getValue().suggestion({ index: 0 }).getState()).toBe(
+        firstSuggestion,
+      );
+    } finally {
+      root.unmount();
+    }
+  });
+
+  it("updates when the configured suggestions change", () => {
+    let setSuggestions!: (suggestions: SuggestionConfig[]) => void;
+    const root = createTapRoot(function SuggestionsRoot() {
+      const [suggestions, setValue] = useState<SuggestionConfig[]>([
+        "account-a",
+      ]);
+      setSuggestions = setValue;
+      return useResource(Suggestions(suggestions));
+    });
+
+    try {
+      expect(root.getValue().getState().suggestions[0]?.prompt).toBe(
+        "account-a",
+      );
+
+      flushTapSync(() => setSuggestions(["account-b"]));
+
+      expect(root.getValue().getState().suggestions[0]?.prompt).toBe(
+        "account-b",
+      );
+    } finally {
+      root.unmount();
+    }
+  });
+
+  it("reuses unchanged suggestion state when one entry changes", () => {
+    let setSuggestions!: (suggestions: SuggestionConfig[]) => void;
+    const root = createTapRoot(function SuggestionsRoot() {
+      const [suggestions, setValue] = useState<SuggestionConfig[]>([
+        { title: "Title A", label: "Label A", prompt: "Prompt A" },
+        { title: "Title B", label: "Label B", prompt: "Prompt B" },
+      ]);
+      setSuggestions = setValue;
+      return useResource(Suggestions(suggestions));
+    });
+
+    try {
+      const firstState = root.getValue().getState();
+      const unchangedSuggestion = root
+        .getValue()
+        .suggestion({ index: 1 })
+        .getState();
+
+      flushTapSync(() =>
+        setSuggestions([
+          { title: "Changed", label: "Label A", prompt: "Prompt A" },
+          { title: "Title B", label: "Label B", prompt: "Prompt B" },
+        ]),
+      );
+
+      expect(root.getValue().getState()).not.toBe(firstState);
+      expect(root.getValue().getState().suggestions[0]?.title).toBe("Changed");
+      expect(root.getValue().suggestion({ index: 1 }).getState()).toBe(
+        unchangedSuggestion,
+      );
+    } finally {
+      root.unmount();
+    }
+  });
+});
+
+describe("ThreadSuggestions", () => {
+  it("keeps equal runtime suggestions stable across owner renders", () => {
+    let rerender!: () => void;
+    const root = createTapRoot(function ThreadSuggestionsRoot() {
+      const [, setTick] = useState(0);
+      rerender = () => setTick((tick) => tick + 1);
+      return useResource(ThreadSuggestions([{ prompt: "Prompt" }]));
+    });
+
+    try {
+      const firstState = root.getValue().getState();
+      const firstSuggestion = root
+        .getValue()
+        .suggestion({ index: 0 })
+        .getState();
+
+      flushTapSync(rerender);
+
+      expect(root.getValue().getState()).toBe(firstState);
+      expect(root.getValue().suggestion({ index: 0 }).getState()).toBe(
+        firstSuggestion,
+      );
+    } finally {
+      root.unmount();
+    }
+  });
+
+  it("reuses unchanged suggestion state when one entry changes", () => {
+    let setSuggestions!: (suggestions: ThreadSuggestion[]) => void;
+    const root = createTapRoot(function ThreadSuggestionsRoot() {
+      const [suggestions, setValue] = useState<ThreadSuggestion[]>([
+        { prompt: "Prompt A" },
+        { prompt: "Prompt B" },
+      ]);
+      setSuggestions = setValue;
+      return useResource(ThreadSuggestions(suggestions));
+    });
+
+    try {
+      const firstState = root.getValue().getState();
+      const unchangedSuggestion = root
+        .getValue()
+        .suggestion({ index: 1 })
+        .getState();
+
+      flushTapSync(() =>
+        setSuggestions([{ prompt: "Changed" }, { prompt: "Prompt B" }]),
+      );
+
+      expect(root.getValue().getState()).not.toBe(firstState);
+      expect(root.getValue().getState().suggestions[0]?.prompt).toBe("Changed");
+      expect(root.getValue().suggestion({ index: 1 }).getState()).toBe(
+        unchangedSuggestion,
+      );
+    } finally {
+      root.unmount();
+    }
+  });
+});

package/src/store/clients/suggestions.ts

@@ -1,7 +1,8 @@
-import { useMemo, useState } from "react";
+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,28 +67,13 @@ const useSuggestionsClient = (
 const useStaticSuggestions = (
   suggestions?: SuggestionConfig[],
 ): ClientOutput<"suggestions"> => {
-  const [state] = useState<SuggestionsState>(() => {
-    const normalizedSuggestions = (suggestions ?? []).map((s) => {
-      if (typeof s === "string") {
-        return {
-          title: s,
-          label: "",
-          prompt: s,
-        };
-      }
-      return {
-        title: s.title,
-        label: s.label,
-        prompt: s.prompt,
-      };
-    });
-
-    return {
-      suggestions: normalizedSuggestions,
-    };
+  return useSuggestionsClient({
+    suggestions: (suggestions ?? []).map((s) =>
+      typeof s === "string"
+        ? { title: s, label: "", prompt: s }
+        : { title: s.title, label: s.label, prompt: s.prompt },
+    ),
   });
-
-  return useSuggestionsClient(state);
 };
 
 export const Suggestions = resource(useStaticSuggestions);
@@ -69,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/message.ts

@@ -19,7 +19,7 @@ export type MessageState = ThreadMessage & {
    * @example
    * ```ts
    * import { WebSpeechSynthesisAdapter } from "@assistant-ui/react";
-   * import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+   * import { useChatRuntime } from "@assistant-ui/ai-sdk";
    *
    * const runtime = useChatRuntime({
    *   adapters: {

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/store/scopes/queue-item.ts

@@ -1,14 +1,7 @@
-import type { FileMessagePart, TextMessagePart } from "../../types/message";
 import type { QueuePlacement } from "../../runtime/queue/external-thread-queue-adapter";
+import type { QueueItemState } from "../../runtime/queue/queue-item";
 
-export type QueueItemState = {
-  readonly id: string;
-  /** @deprecated Derive from the text parts of `parts` instead. Removal after 2026-11-05. */
-  readonly prompt: string;
-  readonly parts: readonly (FileMessagePart | TextMessagePart)[];
-};
-
-export const EMPTY_QUEUE_ITEMS: readonly QueueItemState[] = Object.freeze([]);
+export type { QueueItemState };
 
 export type QueueItemMethods = {
   getState(): QueueItemState;

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/MessageRepository.test.ts

@@ -576,6 +576,83 @@ describe("MessageRepository", () => {
     });
   });
 
+  describe("ExportedMessageRepository auto status", () => {
+    const pendingToolCall: ThreadMessageLike = {
+      id: "a1",
+      role: "assistant",
+      content: [
+        {
+          type: "tool-call",
+          toolCallId: "t1",
+          toolName: "search",
+          args: {},
+          argsText: "{}",
+          approval: { id: "a1" },
+        },
+      ],
+    };
+
+    it("fromArray reports requires-action for an unresolved approval", () => {
+      const result = ExportedMessageRepository.fromArray([pendingToolCall]);
+      expect(result.messages[0]!.message.status).toMatchObject({
+        type: "requires-action",
+        reason: "interrupt",
+      });
+    });
+
+    it("fromBranchableArray reports requires-action for an unresolved approval", () => {
+      const result = ExportedMessageRepository.fromBranchableArray([
+        { message: pendingToolCall, parentId: null },
+      ]);
+      expect(result.messages[0]!.message.status).toMatchObject({
+        type: "requires-action",
+        reason: "interrupt",
+      });
+    });
+
+    it("fromArray reports requires-action with reason tool-calls for a resultless tool call", () => {
+      const result = ExportedMessageRepository.fromArray([
+        {
+          ...pendingToolCall,
+          content: [
+            {
+              type: "tool-call",
+              toolCallId: "t1",
+              toolName: "search",
+              args: {},
+              argsText: "{}",
+            },
+          ],
+        },
+      ]);
+      expect(result.messages[0]!.message.status).toMatchObject({
+        type: "requires-action",
+        reason: "tool-calls",
+      });
+    });
+
+    it("keeps complete for a resolved tool call", () => {
+      const result = ExportedMessageRepository.fromArray([
+        {
+          ...pendingToolCall,
+          content: [
+            {
+              type: "tool-call",
+              toolCallId: "t1",
+              toolName: "search",
+              args: {},
+              argsText: "{}",
+              result: "ok",
+            },
+          ],
+        },
+      ]);
+      expect(result.messages[0]!.message.status).toMatchObject({
+        type: "complete",
+      });
+    });
+  });
+
   describe("ExportedMessageRepository.fromBranchableArray", () => {
     it("should create a branching tree structure", () => {
       const items = [