feat: useAssistantActions (#337)

.changeset/eleven-crews-cross.md

@@ -0,0 +1,6 @@
+---
+"@assistant-ui/react-ai-sdk": patch
+"@assistant-ui/react": patch
+---
+
+feat: useAssistantActions

apps/www/components/docs/parameters/context.tsx

@@ -1,5 +1,17 @@
 import { ParametersTableProps } from "../ParametersTable";
 
+export const AssistantActionsState: ParametersTableProps = {
+  type: "AssistantActionsState",
+  parameters: [
+    {
+      name: "switchToThread",
+      type: "(threadId: string | null) => void",
+      description: "Switch to a new thread.",
+      required: true,
+    },
+  ],
+};
+
 export const AssistantModelConfigState: ParametersTableProps = {
   type: "AssistantModelConfigState",
   parameters: [
@@ -101,6 +113,12 @@ export const AssistantToolUIsState: ParametersTableProps = {
 export const AssistantContextValue: ParametersTableProps = {
   type: "AssistantContextValue",
   parameters: [
+    {
+      name: "useAssistantActions",
+      type: "ReadonlyStore<AssistantActionsState>",
+      required: true,
+      description: "Provides functions to perform actions on the assistant.",
+    },
     {
       name: "useModelConfig",
       type: "ReadonlyStore<AssistantModelConfigState>",
@@ -215,7 +233,8 @@ export const ComposerState: ParametersTableProps = {
       name: "cancel",
       type: "() => boolean",
       required: true,
-      description: "A function to cancel the run. Returns true if the run was canceled.",
+      description:
+        "A function to cancel the run. Returns true if the run was canceled.",
     },
     {
       name: "focus",

apps/www/pages/reference/context.mdx

@@ -15,7 +15,8 @@ The context is split into four hierarchies:
 import { ParametersTable } from "@/components/docs";
 import { 
   AssistantContextValue, 
-  AssistantModelConfigState, 
+  AssistantActionsState,
+  AssistantModelConfigState,
   AssistantToolUIsState,
   ThreadState, 
   ThreadActionsState, 
@@ -43,6 +44,17 @@ const { useModelConfig, useToolUIs } = useAssistantContext();
 
 <ParametersTable {...AssistantContextValue} /> 
 
+#### `useAssistantActions`
+
+```tsx
+import { useAssistantActions } from "@assistant-ui/react";
+
+const switchToNewThread = useAssistantActions(m => m.switchToThread);
+const switchToNewThread = useAssistantActions.getState().switchToThread;
+```
+
+<ParametersTable {...AssistantActionsState} />
+
 ### `useModelConfig`
 
 ```tsx

packages/react-ai-sdk/src/rsc/VercelRSCRuntime.tsx

@@ -36,12 +36,14 @@ export class VercelRSCRuntime<
     return () => {};
   }
 
-  public newThread() {
-    this.thread = new VercelRSCThreadRuntime(this.thread.adapter);
-  }
+  public switchToThread(threadId: string | null) {
+    if (threadId) {
+      throw new Error(
+        "VercelRSCRuntime does not yet support switching threads",
+      );
+    }
 
-  public switchToThread() {
-    throw new Error("VercelRSCRuntime does not yet support switching threads");
+    this.thread = new VercelRSCThreadRuntime(this.thread.adapter);
   }
 }
 

packages/react-ai-sdk/src/ui/VercelAIRuntime.tsx

@@ -34,12 +34,12 @@ export class VercelAIRuntime extends BaseAssistantRuntime<VercelAIThreadRuntime>
     return () => {};
   }
 
-  public newThread() {
-    this.thread = new VercelAIThreadRuntime(this.thread.vercel);
-  }
+  public switchToThread(threadId: string | null) {
+    if (threadId) {
+      throw new Error("VercelAIRuntime does not yet support switching threads");
+    }
 
-  public switchToThread() {
-    throw new Error("VercelAIRuntime does not yet support switching threads");
+    this.thread = new VercelAIThreadRuntime(this.thread.vercel);
   }
 }
 

packages/react/src/context/providers/AssistantProvider.tsx

@@ -5,6 +5,7 @@ import { AssistantContext } from "../react/AssistantContext";
 import { makeAssistantModelConfigStore } from "../stores/AssistantModelConfig";
 import { makeAssistantToolUIsStore } from "../stores/AssistantToolUIs";
 import { ThreadProvider } from "./ThreadProvider";
+import { makeAssistantActionsStore } from "../stores/AssistantActions";
 
 type AssistantProviderProps = {
   runtime: AssistantRuntime;
@@ -21,8 +22,9 @@ export const AssistantProvider: FC<
   const [context] = useState(() => {
     const useModelConfig = makeAssistantModelConfigStore();
     const useToolUIs = makeAssistantToolUIsStore();
+    const useAssistantActions = makeAssistantActionsStore(runtimeRef);
 
-    return { useModelConfig, useToolUIs };
+    return { useModelConfig, useToolUIs, useAssistantActions };
   });
 
   const getModelCOnfig = context.useModelConfig((c) => c.getModelConfig);

packages/react/src/context/react/AssistantContext.ts

@@ -2,10 +2,12 @@ import { createContext, useContext } from "react";
 import type { AssistantModelConfigState } from "../stores/AssistantModelConfig";
 import type { AssistantToolUIsState } from "../stores/AssistantToolUIs";
 import { ReadonlyStore } from "../ReadonlyStore";
+import { AssistantActionsState } from "../stores/AssistantActions";
 
 export type AssistantContextValue = {
   useModelConfig: ReadonlyStore<AssistantModelConfigState>;
   useToolUIs: ReadonlyStore<AssistantToolUIsState>;
+  useAssistantActions: ReadonlyStore<AssistantActionsState>;
 };
 
 export const AssistantContext = createContext<AssistantContextValue | null>(

packages/react/src/context/stores/AssistantActions.tsx

@@ -0,0 +1,16 @@
+import { create } from "zustand";
+import { AssistantRuntime } from "../../runtime";
+import { MutableRefObject } from "react";
+
+export type AssistantActionsState = Readonly<{
+  switchToThread: (threadId: string | null) => void;
+}>;
+
+export const makeAssistantActionsStore = (
+  runtimeRef: MutableRefObject<AssistantRuntime>,
+) =>
+  create<AssistantActionsState>(() =>
+    Object.freeze({
+      switchToThread: () => runtimeRef.current.switchToThread(null),
+    }),
+  );

packages/react/src/context/stores/ThreadActions.ts

@@ -1,6 +1,7 @@
 import type { MutableRefObject } from "react";
 import { create } from "zustand";
 import type { AppendMessage } from "../../types/AssistantTypes";
+import { ThreadRuntime } from "../../runtime";
 
 export type ThreadActionsState = Readonly<{
   getBranches: (messageId: string) => readonly string[];
@@ -14,7 +15,7 @@ export type ThreadActionsState = Readonly<{
 }>;
 
 export const makeThreadActionStore = (
-  runtimeRef: MutableRefObject<ThreadActionsState>,
+  runtimeRef: MutableRefObject<ThreadRuntime>,
 ) => {
   return create<ThreadActionsState>(() =>
     Object.freeze({

packages/react/src/runtime/core/AssistantRuntime.tsx

@@ -3,8 +3,6 @@ import type { Unsubscribe } from "../../types/Unsubscribe";
 import type { ThreadRuntime } from "./ThreadRuntime";
 
 export type AssistantRuntime = ThreadRuntime & {
-  newThread: () => void;
-  switchToThread: (threadId: string) => void;
-
+  switchToThread: (threadId: string | null) => void;
   registerModelConfigProvider: (provider: ModelConfigProvider) => Unsubscribe;
 };

packages/react/src/runtime/core/BaseAssistantRuntime.tsx

@@ -12,8 +12,7 @@ export abstract class BaseAssistantRuntime<TThreadRuntime extends ThreadRuntime>
   public abstract registerModelConfigProvider(
     provider: ModelConfigProvider,
   ): Unsubscribe;
-  public abstract newThread(): void;
-  public abstract switchToThread(threadId: string): void;
+  public abstract switchToThread(threadId: string | null): void;
 
   public get messages() {
     return this.thread.messages;

packages/react/src/runtime/local/LocalRuntime.tsx

@@ -32,16 +32,16 @@ export class LocalRuntime extends BaseAssistantRuntime<LocalThreadRuntime> {
     return () => this._configProviders.delete(provider);
   }
 
-  public newThread() {
+  public switchToThread(threadId: string | null) {
+    if (threadId) {
+      throw new Error("LocalRuntime does not yet support switching threads");
+    }
+
     return (this.thread = new LocalThreadRuntime(
       this._configProviders,
       this.thread.adapter,
     ));
   }
-
-  public switchToThread() {
-    throw new Error("LocalRuntime does not yet support switching threads");
-  }
 }
 
 class LocalThreadRuntime implements ThreadRuntime {