@assistant-ui/core 0.3.13 → 0.3.14

package/src/store/clients/suggestions.ts

@@ -72,8 +72,8 @@ const useThreadSuggestions = (
   const state = useMemo<SuggestionsState>(
     () => ({
       suggestions: suggestions.map((s) => ({
-        title: s.prompt,
-        label: "",
+        title: s.title ?? s.prompt,
+        label: s.label ?? "",
         prompt: s.prompt,
       })),
     }),

package/src/store/clients/thread-selection-events.ts

@@ -0,0 +1,21 @@
+import { useEffect, useRef } from "react";
+import { useAssistantEmit } from "@assistant-ui/store/client";
+
+/**
+ * Emits `threads.selectionChanged` whenever the main thread selection changes.
+ * Does not emit for the initially selected thread on mount. Every `threads`
+ * client whose selection can change calls this with its current main thread id.
+ */
+export const useThreadSelectionEvents = (mainThreadId: string) => {
+  const emit = useAssistantEmit();
+  const previousMainThreadIdRef = useRef(mainThreadId);
+  useEffect(() => {
+    const previousThreadId = previousMainThreadIdRef.current;
+    if (previousThreadId === mainThreadId) return;
+    previousMainThreadIdRef.current = mainThreadId;
+    emit("threads.selectionChanged", {
+      threadId: mainThreadId,
+      previousThreadId,
+    });
+  }, [mainThreadId, emit]);
+};

package/src/store/env.ts

@@ -0,0 +1,11 @@
+// Bundlers replace the process.env.NODE_ENV literal statically (Vite, webpack,
+// Metro); the try covers hosts where no process binding exists at runtime.
+export const isDevelopment = (() => {
+  try {
+    return (
+      process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test"
+    );
+  } catch {
+    return false;
+  }
+})();

package/src/store/index.ts

@@ -5,6 +5,7 @@
 export type {
   ThreadsState,
   ThreadsMethods,
+  ThreadsEvents,
   ThreadsClientSchema,
 } from "./scopes/threads";
 export type {
@@ -79,7 +80,19 @@ export type {
 } from "./scopes/chain-of-thought";
 
 // runtime wiring
-export { RuntimeAdapter } from "../react/RuntimeAdapter";
+export {
+  RuntimeAdapter,
+  runtimeAdapterTransformScopes,
+} from "../react/RuntimeAdapter";
+export {
+  InMemoryThreadList,
+  inMemoryThreadListTransformScopes,
+  type InMemoryThreadListProps,
+} from "../react/client/InMemoryThreadList";
+export {
+  RemoteThreadList,
+  type RemoteThreadListProps,
+} from "../react/client/RemoteThreadList";
 export {
   useExternalMessageConverter,
   convertExternalMessages,

package/src/store/internal.ts

@@ -6,3 +6,16 @@ export { ThreadClient } from "./runtime-clients/thread-runtime-client";
 export { ThreadListItemClient } from "./runtime-clients/thread-list-item-runtime-client";
 export { ThreadListClient } from "./runtime-clients/thread-list-runtime-client";
 export { baseRuntimeAdapterTransformScopes } from "./clients/runtime-adapter";
+export {
+  actionBarCopyDisabled,
+  actionBarEditDisabled,
+  actionBarReloadDisabled,
+  branchPickerNextDisabled,
+  branchPickerPreviousDisabled,
+  composerCancelDisabled,
+  composerInputDisabled,
+  composerSendDisabled,
+  suggestionTriggerDisabled,
+} from "./primitive-predicates";
+export { isDevelopment } from "./env";
+export { useThreadSelectionEvents } from "./clients/thread-selection-events";

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

@@ -4,6 +4,7 @@ import type { ClientOutput } from "@assistant-ui/store";
 import { useAssistantEmit } from "@assistant-ui/store/client";
 import type { ThreadListItemRuntime } from "../../runtime/api/thread-list-item-runtime";
 import { useSubscribable } from "./useSubscribable";
+import { handleThreadListAction } from "./handle-thread-list-action";
 
 const useThreadListItemClient = ({
   runtime,
@@ -39,13 +40,20 @@ const useThreadListItemClient = ({
 
   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/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/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

@@ -145,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 };
   /**

package/src/store/scopes/threads.ts

@@ -35,6 +35,20 @@ export type ThreadsMethods = {
   __internal_getAssistantRuntime?(): AssistantRuntime;
 };
 
+export type ThreadsEvents = {
+  /**
+   * The main thread selection changed. Fires once per switch with the newly
+   * selected thread and the thread that was selected before. Does not fire
+   * for the initially selected thread on mount. Runtimes that resolve a
+   * deep-linked `threadId`/`initialThreadId` after mount (such as
+   * `useRemoteThreadListRuntime`) start on a placeholder new thread, so the
+   * deep link's resolution fires this event with the placeholder as
+   * `previousThreadId`.
+   */
+  "threads.selectionChanged": { threadId: string; previousThreadId: string };
+};
+
 export type ThreadsClientSchema = {
   methods: ThreadsMethods;
+  events: ThreadsEvents;
 };