@copilotkit/react-core 0.0.0-feat-dynamic-copilotcloud-qa-20250117190454

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

@@ -0,0 +1,289 @@
+/**
+ * Example usage of useCopilotAction with complex parameters:
+ *
+ * @example
+ * useCopilotAction({
+ *   name: "myAction",
+ *   parameters: [
+ *     { name: "arg1", type: "string", enum: ["option1", "option2", "option3"], required: false },
+ *     { name: "arg2", type: "number" },
+ *     {
+ *       name: "arg3",
+ *       type: "object",
+ *       attributes: [
+ *         { name: "nestedArg1", type: "boolean" },
+ *         { name: "xyz", required: false },
+ *       ],
+ *     },
+ *     { name: "arg4", type: "number[]" },
+ *   ],
+ *   handler: ({ arg1, arg2, arg3, arg4 }) => {
+ *     const x = arg3.nestedArg1;
+ *     const z = arg3.xyz;
+ *     console.log(arg1, arg2, arg3);
+ *   },
+ * });
+ *
+ * @example
+ * // Simple action without parameters
+ * useCopilotAction({
+ *   name: "myAction",
+ *   handler: () => {
+ *     console.log("No parameters provided.");
+ *   },
+ * });
+ *
+ * @example
+ * // Interactive action with UI rendering and response handling
+ * useCopilotAction({
+ *   name: "handleMeeting",
+ *   description: "Handle a meeting by booking or canceling",
+ *   parameters: [
+ *     {
+ *       name: "meeting",
+ *       type: "string",
+ *       description: "The meeting to handle",
+ *       required: true,
+ *     },
+ *     {
+ *       name: "date",
+ *       type: "string",
+ *       description: "The date of the meeting",
+ *       required: true,
+ *     },
+ *     {
+ *       name: "title",
+ *       type: "string",
+ *       description: "The title of the meeting",
+ *       required: true,
+ *     },
+ *   ],
+ *   renderAndWaitForResponse: ({ args, respond, status }) => {
+ *     const { meeting, date, title } = args;
+ *     return (
+ *       <MeetingConfirmationDialog
+ *         meeting={meeting}
+ *         date={date}
+ *         title={title}
+ *         onConfirm={() => respond('meeting confirmed')}
+ *         onCancel={() => respond('meeting canceled')}
+ *       />
+ *     );
+ *   },
+ * });
+ *
+ * @example
+ * // Catch all action allows you to render actions that are not defined in the frontend
+ * useCopilotAction({
+ *   name: "*",
+ *   render: ({ name, args, status, result, handler, respond }) => {
+ *     return <div>Rendering action: {name}</div>;
+ *   },
+ * });
+ */
+
+/**
+ * <img src="/images/use-copilot-action/useCopilotAction.gif" width="500" />
+ * `useCopilotAction` is a React hook that you can use in your application to provide
+ * custom actions that can be called by the AI. Essentially, it allows the Copilot to
+ * execute these actions contextually during a chat, based on the user's interactions
+ * and needs.
+ *
+ * Here's how it works:
+ *
+ * Use `useCopilotAction` to set up actions that the Copilot can call. To provide
+ * more context to the Copilot, you can provide it with a `description` (for example to explain
+ * what the action does, under which conditions it can be called, etc.).
+ *
+ * Then you define the parameters of the action, which can be simple, e.g. primitives like strings or numbers,
+ * or complex, e.g. objects or arrays.
+ *
+ * Finally, you provide a `handler` function that receives the parameters and returns a result.
+ * CopilotKit takes care of automatically inferring the parameter types, so you get type safety
+ * and autocompletion for free.
+ *
+ * To render a custom UI for the action, you can provide a `render()` function. This function
+ * lets you render a custom component or return a string to display.
+ *
+ * ## Usage
+ *
+ * ### Simple Usage
+ *
+ * ```tsx
+ * useCopilotAction({
+ *   name: "sayHello",
+ *   description: "Say hello to someone.",
+ *   parameters: [
+ *     {
+ *       name: "name",
+ *       type: "string",
+ *       description: "name of the person to say greet",
+ *     },
+ *   ],
+ *   handler: async ({ name }) => {
+ *     alert(`Hello, ${name}!`);
+ *   },
+ * });
+ * ```
+ *
+ * ## Generative UI
+ *
+ * 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";
+
+// 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[] | [] = []>(
+  action: FrontendAction<T> | CatchAllFrontendAction,
+  dependencies?: any[],
+): void {
+  const { setAction, removeAction, actions, chatComponentsCache } = useCopilotContext();
+  const idRef = useRef<string>(randomId());
+  const renderAndWaitRef = useRef<RenderAndWaitForResponse | null>(null);
+
+  // clone the action to avoid mutating the original object
+  action = { ...action };
+
+  // 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)
+  ) {
+    const renderAndWait = action.renderAndWait || action.renderAndWaitForResponse;
+    // remove the renderAndWait function from the action
+    action.renderAndWait = undefined;
+    action.renderAndWaitForResponse = undefined;
+    // add a handler that will be called when the action is executed
+    action.handler = useAsyncCallback(async () => {
+      // 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! };
+      // then we await the promise (it will be resolved in the original renderAndWait function)
+      return await promise;
+    }, []) as any;
+
+    // add a render function that will be called when the action is rendered
+    action.render = ((props: ActionRenderProps<T>): React.ReactElement => {
+      // Specifically for renderAndWaitForResponse the executing state is set too early, causing a race condition
+      // To fit it: we will wait for the handler to be ready
+      let status = props.status;
+      if (props.status === "executing" && !renderAndWaitRef.current) {
+        status = "inProgress";
+      }
+      // Create type safe waitProps based on whether T extends empty array or not
+      const waitProps = {
+        status,
+        args: props.args,
+        result: props.result,
+        handler: status === "executing" ? renderAndWaitRef.current!.resolve : undefined,
+        respond: status === "executing" ? 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;
+      };
+
+      // 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(() => {
+    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);
+    };
+  }, [
+    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 || []),
+  ]);
+}
+
+function isFrontendAction<T extends Parameter[]>(
+  action: FrontendAction<T> | CatchAllFrontendAction,
+): action is FrontendAction<T> {
+  return action.name !== "*";
+}
+
+interface RenderAndWaitForResponse {
+  promise: Promise<any>;
+  resolve: (result: any) => void;
+  reject: (error: any) => void;
+}

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

@@ -0,0 +1,60 @@
+import { Parameter } from "@copilotkit/shared";
+import { Fragment, useCallback, useRef } from "react";
+import { useCopilotContext } from "../context/copilot-context";
+import { FrontendAction, ActionRenderProps } from "../types/frontend-action";
+import { useCopilotAction } from "./use-copilot-action";
+import React from "react";
+
+export function useCopilotAuthenticatedAction<T extends Parameter[]>(
+  action: FrontendAction<T>,
+  dependencies?: any[],
+): void {
+  const { authConfig, authStates, setAuthStates } = useCopilotContext();
+  const pendingActionRef = useRef<ActionRenderProps<Parameter[]> | null>(null);
+
+  const executeAction = useCallback(
+    (props: ActionRenderProps<Parameter[]>) => {
+      if (typeof action.render === "function") {
+        return action.render(props);
+      }
+      return action.render || React.createElement(Fragment);
+    },
+    [action],
+  );
+
+  const wrappedRender = useCallback(
+    (props: ActionRenderProps<Parameter[]>): string | React.ReactElement => {
+      const isAuthenticated = Object.values(authStates || {}).some(
+        (state) => state.status === "authenticated",
+      );
+
+      if (!isAuthenticated) {
+        // Store action details for later execution
+        pendingActionRef.current = props;
+
+        return authConfig?.SignInComponent
+          ? React.createElement(authConfig.SignInComponent, {
+              onSignInComplete: (authState) => {
+                setAuthStates?.((prev) => ({ ...prev, [action.name]: authState }));
+                if (pendingActionRef.current) {
+                  executeAction(pendingActionRef.current);
+                  pendingActionRef.current = null;
+                }
+              },
+            })
+          : React.createElement(Fragment);
+      }
+
+      return executeAction(props);
+    },
+    [action, authStates, setAuthStates],
+  );
+
+  useCopilotAction(
+    {
+      ...action,
+      render: wrappedRender,
+    } as FrontendAction<T>,
+    dependencies,
+  );
+}

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

@@ -0,0 +1,304 @@
+/**
+ * `useCopilotChat` is a React hook that lets you directly interact with the
+ * Copilot instance. Use to implement a fully custom UI (headless UI) or to
+ * programmatically interact with the Copilot instance managed by the default
+ * UI.
+ *
+ * ## Usage
+ *
+ * ### Simple Usage
+ *
+ * ```tsx
+ * import { useCopilotChat } from "@copilotkit/react-core";
+ * import { Role, TextMessage } from "@copilotkit/runtime-client-gql";
+ *
+ * export function YourComponent() {
+ *   const { appendMessage } = useCopilotChat();
+ *
+ *   appendMessage(
+ *     new TextMessage({
+ *       content: "Hello World",
+ *       role: Role.User,
+ *     }),
+ *   );
+ *
+ *   // optionally, you can append a message without running chat completion
+ *   appendMessage(yourMessage, { followUp: false });
+ * }
+ * ```
+ *
+ * `useCopilotChat` returns an object with the following properties:
+ *
+ * ```tsx
+ * const {
+ *   visibleMessages, // An array of messages that are currently visible in the chat.
+ *   appendMessage, // A function to append a message to the chat.
+ *   setMessages, // A function to set the messages in the chat.
+ *   deleteMessage, // A function to delete a message from the chat.
+ *   reloadMessages, // A function to reload the messages from the API.
+ *   stopGeneration, // A function to stop the generation of the next message.
+ *   isLoading, // A boolean indicating if the chat is loading.
+ * } = useCopilotChat();
+ * ```
+ */
+import { useRef, useEffect, useCallback } from "react";
+import { AgentSession, useCopilotContext } from "../context/copilot-context";
+import { Message, Role, TextMessage } from "@copilotkit/runtime-client-gql";
+import { SystemMessageFunction } from "../types";
+import { useChat, AppendMessageOptions } from "./use-chat";
+import { defaultCopilotContextCategories } from "../components";
+import { CoAgentStateRenderHandlerArguments } from "@copilotkit/shared";
+import { useCopilotMessagesContext } from "../context";
+import { useAsyncCallback } from "../components/error-boundary/error-utils";
+
+export interface UseCopilotChatOptions {
+  /**
+   * A unique identifier for the chat. If not provided, a random one will be
+   * generated. When provided, the `useChat` hook with the same `id` will
+   * have shared states across components.
+   */
+  id?: string;
+
+  /**
+   * HTTP headers to be sent with the API request.
+   */
+  headers?: Record<string, string> | Headers;
+  /**
+   * System messages of the chat. Defaults to an empty array.
+   */
+  initialMessages?: Message[];
+
+  /**
+   * A function to generate the system message. Defaults to `defaultSystemMessage`.
+   */
+  makeSystemMessage?: SystemMessageFunction;
+}
+
+export interface UseCopilotChatReturn {
+  visibleMessages: Message[];
+  appendMessage: (message: Message, options?: AppendMessageOptions) => Promise<void>;
+  setMessages: (messages: Message[]) => void;
+  deleteMessage: (messageId: string) => void;
+  reloadMessages: () => Promise<void>;
+  stopGeneration: () => void;
+  reset: () => void;
+  isLoading: boolean;
+  runChatCompletion: () => Promise<Message[]>;
+}
+
+export function useCopilotChat({
+  makeSystemMessage,
+  ...options
+}: UseCopilotChatOptions = {}): UseCopilotChatReturn {
+  const {
+    getContextString,
+    getFunctionCallHandler,
+    copilotApiConfig,
+    isLoading,
+    setIsLoading,
+    chatInstructions,
+    actions,
+    coagentStatesRef,
+    setCoagentStatesWithRef,
+    coAgentStateRenders,
+    agentSession,
+    setAgentSession,
+    forwardedParameters,
+    agentLock,
+    threadId,
+    setThreadId,
+    runId,
+    setRunId,
+    chatAbortControllerRef,
+  } = useCopilotContext();
+  const { messages, setMessages } = useCopilotMessagesContext();
+
+  // We need to ensure that makeSystemMessageCallback always uses the latest
+  // useCopilotReadable data.
+  const latestGetContextString = useUpdatedRef(getContextString);
+  const deleteMessage = useCallback(
+    (messageId: string) => {
+      setMessages((prev) => prev.filter((message) => message.id !== messageId));
+    },
+    [setMessages],
+  );
+
+  const makeSystemMessageCallback = useCallback(() => {
+    const systemMessageMaker = makeSystemMessage || defaultSystemMessage;
+    // this always gets the latest context string
+    const contextString = latestGetContextString.current([], defaultCopilotContextCategories); // TODO: make the context categories configurable
+
+    return new TextMessage({
+      content: systemMessageMaker(contextString, chatInstructions),
+      role: Role.System,
+    });
+  }, [getContextString, makeSystemMessage, chatInstructions]);
+
+  const onCoAgentStateRender = useAsyncCallback(
+    async (args: CoAgentStateRenderHandlerArguments) => {
+      const { name, nodeName, state } = args;
+      let action = Object.values(coAgentStateRenders).find(
+        (action) => action.name === name && action.nodeName === nodeName,
+      );
+      if (!action) {
+        action = Object.values(coAgentStateRenders).find(
+          (action) => action.name === name && !action.nodeName,
+        );
+      }
+      if (action) {
+        await action.handler?.({ state, nodeName });
+      }
+    },
+    [coAgentStateRenders],
+  );
+
+  const { append, reload, stop, runChatCompletion } = useChat({
+    ...options,
+    actions: Object.values(actions),
+    copilotConfig: copilotApiConfig,
+    initialMessages: options.initialMessages || [],
+    onFunctionCall: getFunctionCallHandler(),
+    onCoAgentStateRender,
+    messages,
+    setMessages,
+    makeSystemMessageCallback,
+    isLoading,
+    setIsLoading,
+    coagentStatesRef,
+    setCoagentStatesWithRef,
+    agentSession,
+    setAgentSession,
+    forwardedParameters,
+    threadId,
+    setThreadId,
+    runId,
+    setRunId,
+    chatAbortControllerRef,
+    agentLock,
+  });
+
+  // this is a workaround born out of a bug that Athena incessantly ran into.
+  // We could not find the origin of the bug, however, it was clear that an outdated version of the append function was being used somehow --
+  // it referenced the old state of the messages array, and not the latest one.
+  //
+  // We want to make copilotkit as abuse-proof as possible, so we are adding this workaround to ensure that the latest version of the append function is always used.
+  //
+  // How does this work?
+  // we store the relevant function in a ref that is always up-to-date, and then we use that ref in the callback.
+  const latestAppend = useUpdatedRef(append);
+  const latestAppendFunc = useAsyncCallback(
+    async (message: Message, options?: AppendMessageOptions) => {
+      return await latestAppend.current(message, options);
+    },
+    [latestAppend],
+  );
+
+  const latestReload = useUpdatedRef(reload);
+  const latestReloadFunc = useAsyncCallback(async () => {
+    return await latestReload.current();
+  }, [latestReload]);
+
+  const latestStop = useUpdatedRef(stop);
+  const latestStopFunc = useCallback(() => {
+    return latestStop.current();
+  }, [latestStop]);
+
+  const latestDelete = useUpdatedRef(deleteMessage);
+  const latestDeleteFunc = useCallback(
+    (messageId: string) => {
+      return latestDelete.current(messageId);
+    },
+    [latestDelete],
+  );
+
+  const latestSetMessages = useUpdatedRef(setMessages);
+  const latestSetMessagesFunc = useCallback(
+    (messages: Message[]) => {
+      return latestSetMessages.current(messages);
+    },
+    [latestSetMessages],
+  );
+
+  const latestRunChatCompletion = useUpdatedRef(runChatCompletion);
+  const latestRunChatCompletionFunc = useAsyncCallback(async () => {
+    return await latestRunChatCompletion.current!();
+  }, [latestRunChatCompletion]);
+
+  const reset = useCallback(() => {
+    latestStopFunc();
+    setMessages([]);
+    setThreadId(null);
+    setRunId(null);
+    setCoagentStatesWithRef({});
+    let initialAgentSession: AgentSession | null = null;
+    if (agentLock) {
+      initialAgentSession = {
+        agentName: agentLock,
+      };
+    }
+    setAgentSession(initialAgentSession);
+  }, [
+    latestStopFunc,
+    setMessages,
+    setThreadId,
+    setCoagentStatesWithRef,
+    setAgentSession,
+    agentLock,
+  ]);
+
+  const latestReset = useUpdatedRef(reset);
+  const latestResetFunc = useCallback(() => {
+    return latestReset.current();
+  }, [latestReset]);
+
+  return {
+    visibleMessages: messages,
+    appendMessage: latestAppendFunc,
+    setMessages: latestSetMessagesFunc,
+    reloadMessages: latestReloadFunc,
+    stopGeneration: latestStopFunc,
+    reset: latestResetFunc,
+    deleteMessage: latestDeleteFunc,
+    runChatCompletion: latestRunChatCompletionFunc,
+    isLoading,
+  };
+}
+
+// store `value` in a ref and update
+// it whenever it changes.
+function useUpdatedRef<T>(value: T) {
+  const ref = useRef(value);
+
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+
+  return ref;
+}
+
+export function defaultSystemMessage(
+  contextString: string,
+  additionalInstructions?: string,
+): string {
+  return (
+    `
+Please act as an efficient, competent, conscientious, and industrious professional assistant.
+
+Help the user achieve their goals, and you do so in a way that is as efficient as possible, without unnecessary fluff, but also without sacrificing professionalism.
+Always be polite and respectful, and prefer brevity over verbosity.
+
+The user has provided you with the following context:
+\`\`\`
+${contextString}
+\`\`\`
+
+They have also provided you with functions you can call to initiate actions on their behalf, or functions you can call to receive more information.
+
+Please assist them as best you can.
+
+You can ask them for clarifying questions if needed, but don't be annoying about it. If you can reasonably 'fill in the blanks' yourself, do so.
+
+If you would like to call a function, call it without saying anything else.
+` + (additionalInstructions ? `\n\n${additionalInstructions}` : "")
+  );
+}