@copilotkit/react-core 1.10.7-next.0 → 1.50.0-beta.0

package/src/hooks/use-copilot-action.ts

@@ -130,218 +130,107 @@
  *
  * This hooks enables you to dynamically generate UI elements and render them in the copilot chat. For more information, check out the [Generative UI](/guides/generative-ui) page.
  */
-import { Parameter, randomId } from "@copilotkit/shared";
-import { createElement, Fragment, useEffect, useRef } from "react";
-import { useCopilotContext } from "../context/copilot-context";
-import { useAsyncCallback } from "../components/error-boundary/error-utils";
-import {
-  ActionRenderProps,
-  ActionRenderPropsNoArgsWait,
-  ActionRenderPropsWait,
-  CatchAllFrontendAction,
-  FrontendAction,
-} from "../types/frontend-action";
-import { useToast } from "../components/toast/toast-provider";
-
-// We implement useCopilotAction dependency handling so that
-// the developer has the option to not provide any dependencies.
-// In this case, we assume they want to update the handler on each rerender.
-// To avoid getting stuck in an infinite loop, we update the handler directly,
-// skipping React state updates.
-// This is ok in this case, because the handler is not part of any UI that
-// needs to be updated.
-// useCallback, useMemo or other memoization techniques are not suitable here,
-// because they will cause a infinite rerender loop.
-export function useCopilotAction<const T extends Parameter[] | [] = []>(
+import { useEffect, useRef, useState } from "react";
+import { Parameter } from "@copilotkit/shared";
+import { CatchAllFrontendAction, FrontendAction } from "../types/frontend-action";
+import { useFrontendTool, UseFrontendToolArgs } from "./use-frontend-tool";
+import { useRenderToolCall, UseRenderToolCallArgs } from "./use-render-tool-call";
+import { useHumanInTheLoop, UseHumanInTheLoopArgs } from "./use-human-in-the-loop";
+import { useCopilotContext } from "../context";
+
+// Helper to determine which component and action config to use
+function getActionConfig<const T extends Parameter[] | [] = []>(
   action: FrontendAction<T> | CatchAllFrontendAction,
-  dependencies?: any[],
-): void {
-  const { setAction, removeAction, actions, chatComponentsCache } = useCopilotContext();
-  const idRef = useRef<string>(randomId());
-  const renderAndWaitRef = useRef<RenderAndWaitForResponse | null>(null);
-  const activatingMessageIdRef = useRef<string | null>(null);
-  const { addToast } = useToast();
-
-  // clone the action to avoid mutating the original object
-  action = { ...action };
-
-  // const { currentlyActivatingHitlActionMessageIdRef } = useCopilotContext() as any; // <-- REMOVE THIS FOR NOW
+) {
+  if (action.name === "*") {
+    return {
+      type: "render" as const,
+      action: action as UseRenderToolCallArgs<T>,
+    };
+  }
 
-  // If the developer provides a renderAndWaitForResponse function, we transform the action
-  // to use a promise internally, so that we can treat it like a normal action.
-  if (
-    // renderAndWaitForResponse is not available for catch all actions
-    isFrontendAction(action) &&
-    // check if renderAndWaitForResponse is set
-    (action.renderAndWait || action.renderAndWaitForResponse)
-  ) {
-    (action as any)._isRenderAndWait = true; // Internal flag to identify this action type later
-    const renderAndWait = action.renderAndWait || action.renderAndWaitForResponse;
-    // remove the renderAndWait function from the action
-    action.renderAndWait = undefined;
-    action.renderAndWaitForResponse = undefined;
+  if ("renderAndWaitForResponse" in action || "renderAndWait" in action) {
+    let render = action.render;
+    if (!render && "renderAndWaitForResponse" in action) {
+      // @ts-expect-error -- renderAndWaitForResponse is deprecated, but we need to support it for backwards compatibility
+      render = action.renderAndWaitForResponse;
+    }
+    if (!render && "renderAndWait" in action) {
+      // @ts-expect-error -- renderAndWait is deprecated, but we need to support it for backwards compatibility
+      render = action.renderAndWait;
+    }
 
-    // Add a method for use-chat.ts to set the activating message ID.
-    // This helps correlate the action instance with the message being processed by use-chat.
-    (action as any)._setActivatingMessageId = (id: string | null) => {
-      activatingMessageIdRef.current = id;
+    return {
+      type: "hitl" as const,
+      action: { ...action, render } as UseHumanInTheLoopArgs<T>,
     };
+  }
 
-    // add a handler that will be called when the action is executed
-    action.handler = useAsyncCallback(async () => {
-      const currentActivatingId = activatingMessageIdRef.current;
-      // we create a new promise when the handler is called
-      let resolve: (result: any) => void;
-      let reject: (error: any) => void;
-      const promise = new Promise<any>((resolvePromise, rejectPromise) => {
-        resolve = resolvePromise;
-        reject = rejectPromise;
-      });
-      renderAndWaitRef.current = {
-        promise,
-        resolve: resolve!,
-        reject: reject!,
-        messageId: currentActivatingId,
+  if ("available" in action) {
+    if (action.available === "enabled" || action.available === "remote") {
+      return {
+        type: "frontend" as const,
+        action: action as UseFrontendToolArgs<T>,
       };
-      // then we await the promise (it will be resolved in the original renderAndWait function)
-      const result = await promise;
-      return result;
-    }, []) as any;
-
-    // add a render function that will be called when the action is rendered
-    action.render = ((props: ActionRenderProps<T> & { messageId?: string }): React.ReactElement => {
-      const currentRenderMessageId = props.messageId;
-      // For renderAndWaitForResponse, the 'executing' state might be set by use-chat before
-      // this specific action instance's handler (and thus its promise) is ready.
-      // This logic adjusts the status to 'inProgress' if the current render
-      // isn't for the actively processing HITL action, preventing premature interaction.
-      let status = props.status;
-      if (props.status === "executing") {
-        if (!renderAndWaitRef.current || !renderAndWaitRef.current.promise) {
-          status = "inProgress";
-        } else if (
-          renderAndWaitRef.current.messageId !== currentRenderMessageId &&
-          activatingMessageIdRef.current !== currentRenderMessageId
-        ) {
-          status = "inProgress";
-        }
-        // If conditions met, status remains 'executing'
-      }
-      // Create type safe waitProps based on whether T extends empty array or not
-      const waitProps = {
-        status,
-        args: props.args,
-        result: props.result,
-        // handler and respond should only be provided if this is the truly active instance
-        // and its promise infrastructure is ready.
-        handler:
-          status === "executing" &&
-          renderAndWaitRef.current &&
-          renderAndWaitRef.current.messageId === currentRenderMessageId
-            ? renderAndWaitRef.current!.resolve
-            : undefined,
-        respond:
-          status === "executing" &&
-          renderAndWaitRef.current &&
-          renderAndWaitRef.current.messageId === currentRenderMessageId
-            ? renderAndWaitRef.current!.resolve
-            : undefined,
-      } as T extends [] ? ActionRenderPropsNoArgsWait<T> : ActionRenderPropsWait<T>;
-
-      // Type guard to check if renderAndWait is for no args case
-      const isNoArgsRenderWait = (
-        _fn:
-          | ((props: ActionRenderPropsNoArgsWait<T>) => React.ReactElement)
-          | ((props: ActionRenderPropsWait<T>) => React.ReactElement),
-      ): _fn is (props: ActionRenderPropsNoArgsWait<T>) => React.ReactElement => {
-        return action.parameters?.length === 0;
+    }
+    if (action.available === "frontend" || action.available === "disabled") {
+      return {
+        type: "render" as const,
+        action: action as UseRenderToolCallArgs<T>,
       };
-
-      // Safely call renderAndWait with correct props type
-      if (renderAndWait) {
-        if (isNoArgsRenderWait(renderAndWait)) {
-          return renderAndWait(waitProps as ActionRenderPropsNoArgsWait<T>);
-        } else {
-          return renderAndWait(waitProps as ActionRenderPropsWait<T>);
-        }
-      }
-
-      // Return empty Fragment instead of null
-      return createElement(Fragment);
-    }) as any;
-  }
-
-  // If the developer doesn't provide dependencies, we assume they want to
-  // update handler and render function when the action object changes.
-  // This ensures that any captured variables in the handler are up to date.
-  if (dependencies === undefined) {
-    if (actions[idRef.current]) {
-      // catch all actions don't have a handler
-      if (isFrontendAction(action)) {
-        actions[idRef.current].handler = action.handler as any;
-      }
-      if (typeof action.render === "function") {
-        if (chatComponentsCache.current !== null) {
-          // TODO: using as any here because the type definitions are getting to tricky
-          // not wasting time on this now - we know the types are compatible
-          chatComponentsCache.current.actions[action.name] = action.render as any;
-        }
-      }
     }
   }
 
-  useEffect(() => {
-    const hasDuplicate = Object.values(actions).some(
-      (otherAction) => otherAction.name === action.name && otherAction !== actions[idRef.current],
-    );
-
-    if (hasDuplicate) {
-      addToast({
-        type: "warning",
-        message: `Found an already registered action with name ${action.name}.`,
-        id: `dup-action-${action.name}`,
-      });
-    }
-  }, [actions]);
-
-  useEffect(() => {
-    setAction(idRef.current, action as any);
-    if (chatComponentsCache.current !== null && action.render !== undefined) {
-      // see comment about type safety above
-      chatComponentsCache.current.actions[action.name] = action.render as any;
-    }
-    return () => {
-      // NOTE: For now, we don't remove the chatComponentsCache entry when the action is removed.
-      // This is because we currently don't have access to the messages array in CopilotContext.
-      // UPDATE: We now have access, we should remove the entry if not referenced by any message.
-      removeAction(idRef.current);
+  if ("handler" in action) {
+    return {
+      type: "frontend" as const,
+      action: action as UseFrontendToolArgs<T>,
     };
-  }, [
-    setAction,
-    removeAction,
-    isFrontendAction(action) ? action.description : undefined,
-    action.name,
-    isFrontendAction(action) ? action.disabled : undefined,
-    isFrontendAction(action) ? action.available : undefined,
-    // This should be faster than deep equality checking
-    // In addition, all major JS engines guarantee the order of object keys
-    JSON.stringify(isFrontendAction(action) ? action.parameters : []),
-    // include render only if it's a string
-    typeof action.render === "string" ? action.render : undefined,
-    // dependencies set by the developer
-    ...(dependencies || []),
-  ]);
+  }
+
+  throw new Error("Invalid action configuration");
 }
 
-function isFrontendAction<T extends Parameter[]>(
+/**
+ * useCopilotAction is a legacy hook maintained for backwards compatibility.
+ *
+ * To avoid violating React's Rules of Hooks (which prohibit conditional hook calls),
+ * we use a registration pattern:
+ * 1. This hook registers the action configuration with the CopilotContext
+ * 2. A renderer component in CopilotKit actually renders the appropriate hook wrapper
+ * 3. React properly manages hook state since components are rendered, not conditionally called
+ *
+ * This allows action types to change between renders without corrupting React's hook state.
+ */
+export function useCopilotAction<const T extends Parameter[] | [] = []>(
   action: FrontendAction<T> | CatchAllFrontendAction,
-): action is FrontendAction<T> {
-  return action.name !== "*";
-}
+  dependencies?: any[],
+): void {
+  const [initialActionConfig] = useState(getActionConfig(action));
+  const currentActionConfig = getActionConfig(action);
+
+  /**
+   * Calling hooks conditionally violates React's Rules of Hooks. This rule exists because
+   * React maintains the call stack for hooks like useEffect or useState, and conditionally
+   * calling a hook would result in inconsistent call stacks between renders.
+   *
+   * Unfortunately, useCopilotAction _has_ to conditionally call a hook based on the
+   * supplied parameters. In order to avoid breaking React's call stack tracking, while
+   * breaking the Rule of Hooks, we use a ref to store the initial action configuration
+   * and throw an error if the _configuration_ changes such that we would call a different hook.
+   */
+  if (initialActionConfig.type !== currentActionConfig.type) {
+    throw new Error("Action configuration changed between renders");
+  }
 
-interface RenderAndWaitForResponse {
-  promise: Promise<any>;
-  resolve: (result: any) => void;
-  reject: (error: any) => void;
-  messageId: string | null;
+  switch (currentActionConfig.type) {
+    case "render":
+      return useRenderToolCall(currentActionConfig.action, dependencies);
+    case "hitl":
+      return useHumanInTheLoop(currentActionConfig.action, dependencies);
+    case "frontend":
+      return useFrontendTool(currentActionConfig.action, dependencies);
+    default:
+      throw new Error("Invalid action configuration");
+  }
 }

package/src/hooks/use-copilot-chat-headless_c.ts

@@ -161,7 +161,7 @@
 import { useEffect } from "react";
 import { useCopilotContext } from "../context/copilot-context";
 import {
-  useCopilotChat as useCopilotChatInternal,
+  useCopilotChatInternal,
   defaultSystemMessage,
   UseCopilotChatOptions as UseCopilotChatOptions_c,
   UseCopilotChatReturn as UseCopilotChatReturn_c,
@@ -188,6 +188,7 @@ const createNonFunctionalReturn = (): UseCopilotChatReturn_c => ({
   stopGeneration: () => {},
   reset: () => {},
   isLoading: false,
+  isAvailable: false,
   runChatCompletion: async () => [],
   mcpServers: [],
   setMcpServers: () => {},

package/src/hooks/use-copilot-chat.ts

@@ -75,7 +75,7 @@
 
 import {
   UseCopilotChatOptions,
-  useCopilotChat as useCopilotChatInternal,
+  useCopilotChatInternal,
   UseCopilotChatReturn as UseCopilotChatReturnInternal,
 } from "./use-copilot-chat_internal";
 
@@ -100,6 +100,7 @@ export type UseCopilotChatReturn = Omit<
  *
  * **Open Source Friendly** - Works without requiring a `publicApiKey`.
  */
+// TODO: Do we need this? If so, does it work properly? test.
 export function useCopilotChat(options: UseCopilotChatOptions = {}): UseCopilotChatReturn {
   const {
     visibleMessages,
@@ -108,6 +109,7 @@ export function useCopilotChat(options: UseCopilotChatOptions = {}): UseCopilotC
     stopGeneration,
     reset,
     isLoading,
+    isAvailable,
     runChatCompletion,
     mcpServers,
     setMcpServers,
@@ -120,6 +122,7 @@ export function useCopilotChat(options: UseCopilotChatOptions = {}): UseCopilotC
     stopGeneration,
     reset,
     isLoading,
+    isAvailable,
     runChatCompletion,
     mcpServers,
     setMcpServers,