@assistant-ui/core 0.3.12 → 0.3.14

package/src/store/primitive-predicates.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from "vitest";
+import {
+  actionBarCopyDisabled,
+  actionBarEditDisabled,
+  actionBarReloadDisabled,
+  branchPickerNextDisabled,
+  branchPickerPreviousDisabled,
+  composerCancelDisabled,
+  composerInputDisabled,
+  composerSendDisabled,
+  suggestionTriggerDisabled,
+} from "./primitive-predicates";
+
+const state = (partial: Record<string, unknown>) => partial as never;
+
+describe("primitive predicates", () => {
+  it("composerSendDisabled requires canSend and either an idle thread or a queue", () => {
+    const composer = { canSend: true };
+    expect(
+      composerSendDisabled(
+        state({
+          composer,
+          thread: { isRunning: false, capabilities: { queue: false } },
+        }),
+      ),
+    ).toBe(false);
+    expect(
+      composerSendDisabled(
+        state({
+          composer,
+          thread: { isRunning: true, capabilities: { queue: true } },
+        }),
+      ),
+    ).toBe(false);
+    expect(
+      composerSendDisabled(
+        state({
+          composer,
+          thread: { isRunning: true, capabilities: { queue: false } },
+        }),
+      ),
+    ).toBe(true);
+    expect(
+      composerSendDisabled(
+        state({
+          composer: { canSend: false },
+          thread: { isRunning: false, capabilities: { queue: false } },
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("actionBarReloadDisabled rejects user messages and busy threads", () => {
+    const thread = { isRunning: false, isDisabled: false };
+    expect(
+      actionBarReloadDisabled(
+        state({ thread, message: { role: "assistant" } }),
+      ),
+    ).toBe(false);
+    expect(
+      actionBarReloadDisabled(state({ thread, message: { role: "user" } })),
+    ).toBe(true);
+    expect(
+      actionBarReloadDisabled(
+        state({
+          thread: { ...thread, isRunning: true },
+          message: { role: "assistant" },
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("actionBarCopyDisabled requires settled content with non-empty text", () => {
+    expect(
+      actionBarCopyDisabled(
+        state({
+          message: {
+            role: "assistant",
+            status: { type: "complete" },
+            parts: [{ type: "text", text: "hi" }],
+          },
+        }),
+      ),
+    ).toBe(false);
+    expect(
+      actionBarCopyDisabled(
+        state({
+          message: {
+            role: "assistant",
+            status: { type: "running" },
+            parts: [{ type: "text", text: "hi" }],
+          },
+        }),
+      ),
+    ).toBe(true);
+    expect(
+      actionBarCopyDisabled(
+        state({
+          message: {
+            role: "user",
+            status: undefined,
+            parts: [{ type: "text", text: "" }],
+          },
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("branch picker predicates respect bounds and run capabilities", () => {
+    const thread = {
+      isRunning: false,
+      capabilities: { switchBranchDuringRun: false },
+    };
+    const message = { branchNumber: 2, branchCount: 3 };
+    expect(branchPickerPreviousDisabled(state({ thread, message }))).toBe(
+      false,
+    );
+    expect(branchPickerNextDisabled(state({ thread, message }))).toBe(false);
+    expect(
+      branchPickerPreviousDisabled(
+        state({ thread, message: { ...message, branchNumber: 1 } }),
+      ),
+    ).toBe(true);
+    expect(
+      branchPickerNextDisabled(
+        state({ thread, message: { ...message, branchNumber: 3 } }),
+      ),
+    ).toBe(true);
+    expect(
+      branchPickerNextDisabled(
+        state({ thread: { ...thread, isRunning: true }, message }),
+      ),
+    ).toBe(true);
+  });
+
+  it("suggestionTriggerDisabled gates on send only for queueless runs", () => {
+    const thread = {
+      isDisabled: false,
+      isRunning: true,
+      capabilities: { queue: false },
+    };
+    expect(suggestionTriggerDisabled(state({ thread }), false)).toBe(false);
+    expect(suggestionTriggerDisabled(state({ thread }), true)).toBe(true);
+    expect(
+      suggestionTriggerDisabled(
+        state({ thread: { ...thread, capabilities: { queue: true } } }),
+        true,
+      ),
+    ).toBe(false);
+  });
+  it("composerCancelDisabled, composerInputDisabled, and actionBarEditDisabled mirror their fields", () => {
+    expect(
+      composerCancelDisabled(state({ composer: { canCancel: true } })),
+    ).toBe(false);
+    expect(
+      composerCancelDisabled(state({ composer: { canCancel: false } })),
+    ).toBe(true);
+
+    const enabledThread = { isDisabled: false };
+    expect(
+      composerInputDisabled(state({ thread: enabledThread, composer: {} })),
+    ).toBe(false);
+    expect(
+      composerInputDisabled(
+        state({
+          thread: enabledThread,
+          composer: { dictation: { inputDisabled: true } },
+        }),
+      ),
+    ).toBe(true);
+    expect(
+      composerInputDisabled(
+        state({ thread: { isDisabled: true }, composer: {} }),
+      ),
+    ).toBe(true);
+
+    expect(
+      actionBarEditDisabled(state({ composer: { isEditing: false } })),
+    ).toBe(false);
+    expect(
+      actionBarEditDisabled(state({ composer: { isEditing: true } })),
+    ).toBe(true);
+  });
+});

package/src/store/primitive-predicates.ts

@@ -0,0 +1,43 @@
+import type { AssistantState } from "@assistant-ui/store";
+
+/**
+ * Disabled predicates shared by every binding's primitive layer. Each binding
+ * consumes these as state selectors so the disabled semantics of a primitive
+ * cannot drift between frameworks.
+ */
+
+export const composerSendDisabled = (s: AssistantState): boolean =>
+  !s.composer.canSend || (s.thread.isRunning && !s.thread.capabilities.queue);
+
+export const composerCancelDisabled = (s: AssistantState): boolean =>
+  !s.composer.canCancel;
+
+export const composerInputDisabled = (s: AssistantState): boolean =>
+  s.thread.isDisabled || s.composer.dictation?.inputDisabled === true;
+
+export const actionBarEditDisabled = (s: AssistantState): boolean =>
+  s.composer.isEditing;
+
+export const actionBarReloadDisabled = (s: AssistantState): boolean =>
+  s.thread.isRunning || s.thread.isDisabled || s.message.role !== "assistant";
+
+export const actionBarCopyDisabled = (s: AssistantState): boolean =>
+  !(
+    (s.message.role !== "assistant" || s.message.status?.type !== "running") &&
+    s.message.parts.some((part) => part.type === "text" && part.text.length > 0)
+  );
+
+export const branchPickerPreviousDisabled = (s: AssistantState): boolean =>
+  s.message.branchNumber <= 1 ||
+  (s.thread.isRunning && !s.thread.capabilities.switchBranchDuringRun);
+
+export const branchPickerNextDisabled = (s: AssistantState): boolean =>
+  s.message.branchNumber >= s.message.branchCount ||
+  (s.thread.isRunning && !s.thread.capabilities.switchBranchDuringRun);
+
+export const suggestionTriggerDisabled = (
+  s: AssistantState,
+  send: boolean,
+): boolean =>
+  s.thread.isDisabled ||
+  (send && s.thread.isRunning && !s.thread.capabilities.queue);

package/src/store/runtime-clients/attachment-runtime-client.test.ts

@@ -0,0 +1,41 @@
+import { createTapRoot, useResource } from "@assistant-ui/tap";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AttachmentRuntime } from "../../runtime/api/attachment-runtime";
+import { AttachmentRuntimeClient } from "./attachment-runtime-client";
+
+describe("AttachmentRuntimeClient", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("reports attachment removal failures", async () => {
+    const error = new Error("storage unavailable");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const state = {
+      id: "attachment-1",
+      type: "file",
+      name: "notes.txt",
+      status: { type: "complete" },
+      content: [],
+      source: "thread-composer",
+    };
+    const runtime = {
+      getState: () => state,
+      subscribe: () => () => {},
+      remove: () => Promise.reject(error),
+    } as unknown as AttachmentRuntime;
+    const root = createTapRoot(function AttachmentClientRoot() {
+      return useResource(AttachmentRuntimeClient({ runtime }));
+    });
+
+    await expect(root.getValue().remove()).rejects.toBe(error);
+
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] attachment remove failed:",
+      error,
+    );
+    root.unmount();
+  });
+});

package/src/store/runtime-clients/attachment-runtime-client.ts

@@ -1,6 +1,7 @@
 import { resource } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import type { AttachmentRuntime } from "../../runtime/api/attachment-runtime";
+import { handleRuntimeAction } from "./handle-runtime-action";
 import { useSubscribable } from "./useSubscribable";
 
 const useAttachmentRuntimeClient = ({
@@ -12,7 +13,7 @@ const useAttachmentRuntimeClient = ({
 
   return {
     getState: () => state,
-    remove: runtime.remove,
+    remove: () => handleRuntimeAction("attachment remove", runtime.remove),
     __internal_getRuntime: () => runtime,
   };
 };

package/src/store/runtime-clients/handle-runtime-action.ts

@@ -0,0 +1,11 @@
+export const handleRuntimeAction = (
+  label: string,
+  execute: () => Promise<void>,
+): Promise<void> => {
+  const task = execute();
+
+  void task.catch((error: unknown) => {
+    console.error(`[assistant-ui] ${label} failed:`, error);
+  });
+  return task;
+};

package/src/store/runtime-clients/handle-thread-list-action.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { handleThreadListAction } from "./handle-thread-list-action";
+
+describe("handleThreadListAction", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("reports a rejected task", async () => {
+    const error = new Error("unavailable");
+    const task = Promise.reject(error);
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    const result = handleThreadListAction("delete", () => task);
+
+    expect(result).toBe(task);
+    await expect(result).rejects.toBe(error);
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] thread list delete failed:",
+      error,
+    );
+  });
+
+  it("preserves synchronous failures", () => {
+    const error = new Error("invalid thread");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    expect(() =>
+      handleThreadListAction("switch", () => {
+        throw error;
+      }),
+    ).toThrow(error);
+    expect(consoleError).not.toHaveBeenCalled();
+  });
+
+  it("does not leak an ignored action as an unhandled rejection", async () => {
+    const error = new Error("delete failed");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const rejections: unknown[] = [];
+    const onUnhandledRejection = (reason: unknown) => {
+      rejections.push(reason);
+    };
+    const priorListeners = process.listeners("unhandledRejection");
+    process.removeAllListeners("unhandledRejection");
+    process.on("unhandledRejection", onUnhandledRejection);
+
+    try {
+      handleThreadListAction("delete", () => Promise.reject(error));
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    } finally {
+      process.removeListener("unhandledRejection", onUnhandledRejection);
+      for (const listener of priorListeners) {
+        process.on("unhandledRejection", listener);
+      }
+    }
+
+    expect(rejections).toEqual([]);
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] thread list delete failed:",
+      error,
+    );
+  });
+});

package/src/store/runtime-clients/handle-thread-list-action.ts

@@ -0,0 +1,6 @@
+import { handleRuntimeAction } from "./handle-runtime-action";
+
+export const handleThreadListAction = (
+  action: string,
+  execute: () => Promise<void>,
+): Promise<void> => handleRuntimeAction(`thread list ${action}`, execute);

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

@@ -1,13 +1,10 @@
-import type { Unsubscribe } from "../../types/unsubscribe";
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { resource } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import { useAssistantEmit } from "@assistant-ui/store/client";
-import type {
-  ThreadListItemEventType,
-  ThreadListItemRuntime,
-} from "../../runtime/api/thread-list-item-runtime";
+import type { ThreadListItemRuntime } from "../../runtime/api/thread-list-item-runtime";
 import { useSubscribable } from "./useSubscribable";
+import { handleThreadListAction } from "./handle-thread-list-action";
 
 const useThreadListItemClient = ({
   runtime,
@@ -28,39 +25,35 @@ const useThreadListItemClient = ({
   }, [runtimeState, mainThreadIsRunning]);
   const emit = useAssistantEmit();
 
-  // Bind thread list item events to event manager
+  // Emitted after the flush that rebinds the derived scopes; the runtime's own
+  // synchronous notification would be delivered against the pre-switch binding.
+  const { isMain, id: threadId } = runtimeState;
+  const selectionRef = useRef({ isMain, threadId });
   useEffect(() => {
-    const unsubscribers: Unsubscribe[] = [];
-
-    // Subscribe to thread list item events
-    const threadListItemEvents: ThreadListItemEventType[] = [
-      "switchedTo",
-      "switchedAway",
-    ];
-
-    for (const event of threadListItemEvents) {
-      const unsubscribe = runtime.unstable_on(event, () => {
-        emit(`threadListItem.${event}`, {
-          threadId: runtime.getState()!.id,
-        });
-      });
-      unsubscribers.push(unsubscribe);
-    }
-
-    return () => {
-      for (const unsub of unsubscribers) unsub();
-    };
-  }, [runtime, emit]);
+    const previous = selectionRef.current;
+    if (previous.isMain === isMain && previous.threadId === threadId) return;
+    selectionRef.current = { isMain, threadId };
+    emit(isMain ? "threadListItem.switchedTo" : "threadListItem.switchedAway", {
+      threadId,
+    });
+  }, [isMain, threadId, emit]);
 
   return {
     getState: () => state,
-    switchTo: runtime.switchTo,
-    rename: runtime.rename,
-    updateCustom: runtime.updateCustom,
-    archive: runtime.archive,
-    unarchive: runtime.unarchive,
-    delete: runtime.delete,
-    generateTitle: runtime.generateTitle,
+    switchTo: (options) =>
+      handleThreadListAction("switch", () => runtime.switchTo(options)),
+    rename: (newTitle) =>
+      handleThreadListAction("rename", () => runtime.rename(newTitle)),
+    updateCustom: (custom) =>
+      handleThreadListAction("update custom metadata", () =>
+        runtime.updateCustom(custom),
+      ),
+    archive: () => handleThreadListAction("archive", () => runtime.archive()),
+    unarchive: () =>
+      handleThreadListAction("unarchive", () => runtime.unarchive()),
+    delete: () => handleThreadListAction("delete", () => runtime.delete()),
+    generateTitle: () =>
+      handleThreadListAction("generate title", () => runtime.generateTitle()),
     initialize: runtime.initialize,
     detach: runtime.detach,
     __internal_getRuntime: () => runtime,

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

@@ -2,12 +2,14 @@ import { 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 { useThreadSelectionEvents } from "../clients/thread-selection-events";
 import type { ThreadListRuntime } from "../../runtime/api/thread-list-runtime";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import { useSubscribable } from "./useSubscribable";
 import { ThreadListItemClient } from "./thread-list-item-runtime-client";
 import { ThreadClient } from "./thread-runtime-client";
 import type { ThreadsState } from "../scopes/threads";
+import { handleThreadListAction } from "./handle-thread-list-action";
 
 const useThreadListItemClientById = ({
   runtime,
@@ -40,6 +42,7 @@ const useThreadListClient = ({
   __internal_assistantRuntime: AssistantRuntime;
 }): ClientOutput<"threads"> => {
   const runtimeState = useSubscribable(runtime);
+  useThreadSelectionEvents(runtimeState.mainThreadId);
 
   const main = useClientResource(
     ThreadClient({
@@ -93,12 +96,12 @@ const useThreadListClient = ({
         : state.threadIds[index]!;
       return threadItems.get({ key: id });
     },
-    switchToThread: async (threadId, options) => {
-      await runtime.switchToThread(threadId, options);
-    },
-    switchToNewThread: async () => {
-      await runtime.switchToNewThread();
-    },
+    switchToThread: (threadId, options) =>
+      handleThreadListAction("switch", () =>
+        runtime.switchToThread(threadId, options),
+      ),
+    switchToNewThread: () =>
+      handleThreadListAction("create", () => runtime.switchToNewThread()),
     getLoadThreadsPromise: () => runtime.getLoadThreadsPromise(),
     reload: () => runtime.reload(),
     reloadMainThread: () => runtime.reloadMainThread(),

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

@@ -12,6 +12,7 @@ import {
 } from "@assistant-ui/store/client";
 import { ComposerClient } from "./composer-runtime-client";
 import { MessageClient } from "./message-runtime-client";
+import { ThreadSuggestions } from "../clients/suggestions";
 import { useSubscribable } from "./useSubscribable";
 import type { ThreadState } from "../scopes/thread";
 
@@ -78,6 +79,9 @@ const useThreadClient = ({
       threadIdRef,
     }),
   );
+  const suggestions = useClientResource(
+    ThreadSuggestions(runtimeState.suggestions),
+  );
   const messages = useClientLookup(
     runtimeState.messages.map((m) =>
       withKey(m.id, MessageClientById({ runtime, id: m.id, threadIdRef }), [
@@ -109,6 +113,7 @@ const useThreadClient = ({
   return {
     getState: () => state,
     composer: () => composer.methods,
+    suggestions: () => suggestions.methods,
     append: runtime.append,
     deleteMessage: runtime.deleteMessage,
     startRun: runtime.startRun,

package/src/store/scopes/composer.ts

@@ -27,6 +27,11 @@ export type ComposerState = {
   readonly attachments: readonly Attachment[];
   readonly runConfig: RunConfig;
   readonly isEditing: boolean;
+  /**
+   * 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;
   /**
    * Whether the composer is currently willing to send. `true` when the
@@ -104,13 +109,13 @@ export type ComposerMeta = {
 
 export type ComposerEvents = {
   /**
-   * @deprecated State-derivable. Observe composer `text` clearing via
-   * `useAuiState` instead. Kept for backward compatibility.
+   * The user sent the composer contents. `messageId` is set when the send
+   * came from an edit composer.
    */
   "composer.send": { threadId: string; messageId?: string };
   /**
-   * @deprecated State-derivable. Observe composer `attachments` via
-   * `useAuiState` instead. Kept for backward compatibility.
+   * An attachment was added to the composer. `messageId` is set when the
+   * attachment was added to an edit composer.
    */
   "composer.attachmentAdd": { threadId: string; messageId?: string };
   "composer.attachmentAddError": {

package/src/store/scopes/suggestions.ts

@@ -15,6 +15,12 @@ export type SuggestionsMethods = {
   suggestion(query: { index: number }): SuggestionMethods;
 };
 
+export type SuggestionsMeta = {
+  source: "thread";
+  query: Record<string, never>;
+};
+
 export type SuggestionsClientSchema = {
   methods: SuggestionsMethods;
+  meta: SuggestionsMeta;
 };

package/src/store/scopes/thread-list-item.ts

@@ -42,15 +42,16 @@ export type ThreadListItemMeta = {
 
 export type ThreadListItemEvents = {
   /**
-   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
-   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
-   * compatibility.
+   * @deprecated Use `threads.selectionChanged` instead; its `threadId` is the
+   * newly selected thread. Inside a per-item `threadListItem` scope, filter by
+   * `threadId === threadListItem.id` to reproduce the per-item delivery. Kept
+   * for backward compatibility.
    */
   "threadListItem.switchedTo": { threadId: string };
   /**
-   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
-   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
-   * compatibility.
+   * @deprecated Use `threads.selectionChanged` instead; its
+   * `previousThreadId` is the thread that was switched away from. Kept for
+   * backward compatibility.
    */
   "threadListItem.switchedAway": { threadId: string };
 };

package/src/store/scopes/thread.ts

@@ -17,6 +17,7 @@ import type {
 import type { ModelContext } from "../../model-context/types";
 import type { MessageMethods, MessageState } from "./message";
 import type { ComposerMethods, ComposerState } from "./composer";
+import type { SuggestionsMethods } from "./suggestions";
 
 export type ThreadState = {
   /**
@@ -71,6 +72,10 @@ export type ThreadMethods = {
    * The thread composer runtime.
    */
   composer(): ComposerMethods;
+  /**
+   * The suggestions shown for this thread.
+   */
+  suggestions(): SuggestionsMethods;
   /**
    * Append a new message to the thread.
    *
@@ -100,6 +105,18 @@ export type ThreadMethods = {
    */
   resumeRun(config: CreateResumeRunConfig): void;
   cancelRun(): void;
+  /**
+   * Re-fetch this thread's state from its backing store, in place: the tap
+   * thread's refetch hook, which `threads.reloadMainThread()` prefers and
+   * whose rejection it propagates. `capabilities.refetchThread` is the
+   * portable feature-detection signal; a legacy-bridged thread reports it
+   * there while routing the refetch through its runtime, not this method.
+   * The method-shorthand optionality is load-bearing: an explicit
+   * `| undefined` stops `ThreadMethods` satisfying `ClientMethods` and
+   * collapses the client schema, which only a workspace-level app typecheck
+   * surfaces.
+   */
+  unstable_refetchThread?(): Promise<void>;
   getModelContext(): ModelContext;
   export(): ExportedMessageRepository;
   import(repository: ExportedMessageRepository): void;
@@ -128,19 +145,20 @@ export type ThreadMeta = {
 
 export type ThreadEvents = {
   /**
-   * @deprecated State-derivable. Observe `isRunning` flipping to `true` via
-   * `useAuiState` instead. Kept for backward compatibility.
+   * A run started on this thread. Also observable as `isRunning` flipping to
+   * `true` in thread state.
    */
   "thread.runStart": { threadId: string };
   /**
-   * @deprecated State-derivable. Observe `isRunning` flipping to `false` via
-   * `useAuiState` instead. Kept for backward compatibility.
+   * A run on this thread ended, whether it completed, errored, or was
+   * cancelled. Also observable as `isRunning` flipping to `false` in thread
+   * state.
    */
   "thread.runEnd": { threadId: string };
   /**
-   * @deprecated State-derivable. This event fires before the first message is
-   * added; observe `messages` becoming non-empty via `useAuiState` instead of
-   * reading state inside this event handler. Kept for backward compatibility.
+   * The thread transitioned from new to initialized. Fires before the first
+   * message is added, so read thread state via `useAuiState` rather than
+   * inside this event handler.
    */
   "thread.initialize": { threadId: string };
   /**