@copilotkit/react-core 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

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

@@ -0,0 +1,236 @@
+/**
+ * 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="https://cdn.copilotkit.ai/docs/copilotkit/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 { 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,
+) {
+  if (action.name === "*") {
+    return {
+      type: "render" as const,
+      action: action as UseRenderToolCallArgs<T>,
+    };
+  }
+
+  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;
+    }
+
+    return {
+      type: "hitl" as const,
+      action: { ...action, render } as UseHumanInTheLoopArgs<T>,
+    };
+  }
+
+  if ("available" in action) {
+    if (action.available === "enabled" || action.available === "remote") {
+      return {
+        type: "frontend" as const,
+        action: action as UseFrontendToolArgs<T>,
+      };
+    }
+    if (action.available === "frontend" || action.available === "disabled") {
+      return {
+        type: "render" as const,
+        action: action as UseRenderToolCallArgs<T>,
+      };
+    }
+  }
+
+  if ("handler" in action) {
+    return {
+      type: "frontend" as const,
+      action: action as UseFrontendToolArgs<T>,
+    };
+  }
+
+  throw new Error("Invalid action configuration");
+}
+
+/**
+ * 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,
+  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");
+  }
+
+  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-additional-instructions.ts

@@ -0,0 +1,85 @@
+/**
+ * `useCopilotAdditionalInstructions` is a React hook that provides additional instructions
+ * to the Copilot.
+ *
+ * ## Usage
+ *
+ * ### Simple Usage
+ *
+ * In its most basic usage, useCopilotAdditionalInstructions accepts a single string argument
+ * representing the instructions to be added to the Copilot.
+ *
+ * ```tsx
+ * import { useCopilotAdditionalInstructions } from "@copilotkit/react-core";
+ *
+ * export function MyComponent() {
+ *   useCopilotAdditionalInstructions({
+ *     instructions: "Do not answer questions about the weather.",
+ *   });
+ * }
+ * ```
+ *
+ * ### Conditional Usage
+ *
+ * You can also conditionally add instructions based on the state of your app.
+ *
+ * ```tsx
+ * import { useCopilotAdditionalInstructions } from "@copilotkit/react-core";
+ *
+ * export function MyComponent() {
+ *   const [showInstructions, setShowInstructions] = useState(false);
+ *
+ *   useCopilotAdditionalInstructions({
+ *     available: showInstructions ? "enabled" : "disabled",
+ *     instructions: "Do not answer questions about the weather.",
+ *   });
+ * }
+ * ```
+ */
+import { useEffect } from "react";
+import { useCopilotContext } from "../context/copilot-context";
+
+/**
+ * Options for the useCopilotAdditionalInstructions hook.
+ */
+export interface UseCopilotAdditionalInstructionsOptions {
+  /**
+   * The instructions to be added to the Copilot. Will be added to the instructions like so:
+   *
+   * ```txt
+   * You are a helpful assistant.
+   * Additionally, follow these instructions:
+   * - Do not answer questions about the weather.
+   * - Do not answer questions about the stock market.
+   * ```
+   */
+  instructions: string;
+
+  /**
+   * Whether the instructions are available to the Copilot.
+   */
+  available?: "enabled" | "disabled";
+}
+
+/**
+ * Adds the given instructions to the Copilot context.
+ */
+export function useCopilotAdditionalInstructions(
+  { instructions, available = "enabled" }: UseCopilotAdditionalInstructionsOptions,
+  dependencies?: any[],
+) {
+  const { setAdditionalInstructions } = useCopilotContext();
+
+  useEffect(() => {
+    if (available === "disabled") return;
+
+    setAdditionalInstructions((prevInstructions) => [...(prevInstructions || []), instructions]);
+
+    return () => {
+      setAdditionalInstructions(
+        (prevInstructions) =>
+          prevInstructions?.filter((instruction) => instruction !== instructions) || [],
+      );
+    };
+  }, [available, instructions, setAdditionalInstructions, ...(dependencies || [])]);
+}

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

@@ -0,0 +1,70 @@
+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";
+
+/**
+ * Hook to create an authenticated action that requires user sign-in before execution.
+ *
+ * @remarks
+ * This feature is only available when using CopilotKit's hosted cloud service.
+ * To use this feature, sign up at https://cloud.copilotkit.ai to get your publicApiKey.
+ *
+ * @param action - The frontend action to be wrapped with authentication
+ * @param dependencies - Optional array of dependencies that will trigger recreation of the action when changed
+ */
+export function useCopilotAuthenticatedAction_c<T extends Parameter[]>(
+  action: FrontendAction<T>,
+  dependencies?: any[],
+): void {
+  const { authConfig_c, authStates_c, setAuthStates_c } = 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_c || {}).some(
+        (state) => state.status === "authenticated",
+      );
+
+      if (!isAuthenticated) {
+        // Store action details for later execution
+        pendingActionRef.current = props;
+
+        return authConfig_c?.SignInComponent
+          ? React.createElement(authConfig_c.SignInComponent, {
+              onSignInComplete: (authState) => {
+                setAuthStates_c?.((prev) => ({ ...prev, [action.name]: authState }));
+                if (pendingActionRef.current) {
+                  executeAction(pendingActionRef.current);
+                  pendingActionRef.current = null;
+                }
+              },
+            })
+          : React.createElement(Fragment);
+      }
+
+      return executeAction(props);
+    },
+    [action, authStates_c, setAuthStates_c],
+  );
+
+  useCopilotAction(
+    {
+      ...action,
+      render: wrappedRender,
+    } as FrontendAction<T>,
+    dependencies,
+  );
+}

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

@@ -0,0 +1,258 @@
+/**
+ * `useCopilotChatHeadless_c` is for building fully custom UI (headless UI) implementations.
+ *
+ * <Callout title="This is a premium-only feature">
+ * Sign up for free on [Copilot Cloud](https://cloud.copilotkit.ai) to get your public license key or read more about <a href="/premium/overview">premium features</a>.
+ *
+ * Usage is generous, **free** to get started, and works with **either self-hosted or Copilot Cloud** environments.
+ * </Callout>
+ *
+ * ## Key Features
+ *
+ * - **Fully headless**: Build your own fully custom UI's for your agentic applications.
+ * - **Advanced Suggestions**: Direct access to suggestions array with full control
+ * - **Interrupt Handling**: Support for advanced interrupt functionality
+ * - **MCP Server Support**: Model Context Protocol server configurations
+ * - **Chat Controls**: Complete set of chat management functions
+ * - **Loading States**: Comprehensive loading state management
+ *
+ *
+ * ## Usage
+ *
+ * ### Basic Setup
+ *
+ * ```tsx
+ * import { CopilotKit } from "@copilotkit/react-core";
+ * import { useCopilotChatHeadless_c } from "@copilotkit/react-core";
+ *
+ * export function App() {
+ *   return (
+ *     <CopilotKit publicApiKey="your-free-public-license-key">
+ *       <YourComponent />
+ *     </CopilotKit>
+ *   );
+ * }
+ *
+ * export function YourComponent() {
+ *   const { messages, sendMessage, isLoading } = useCopilotChatHeadless_c();
+ *
+ *   const handleSendMessage = async () => {
+ *     await sendMessage({
+ *       id: "123",
+ *       role: "user",
+ *       content: "Hello World",
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {messages.map(msg => <div key={msg.id}>{msg.content}</div>)}
+ *       <button onClick={handleSendMessage} disabled={isLoading}>
+ *         Send Message
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * ### Working with Suggestions
+ *
+ * ```tsx
+ * import { useCopilotChatHeadless_c, useCopilotChatSuggestions } from "@copilotkit/react-core";
+ *
+ * export function SuggestionExample() {
+ *   const {
+ *     suggestions,
+ *     setSuggestions,
+ *     generateSuggestions,
+ *     isLoadingSuggestions
+ *   } = useCopilotChatHeadless_c();
+ *
+ *   // Configure AI suggestion generation
+ *   useCopilotChatSuggestions({
+ *     instructions: "Suggest helpful actions based on the current context",
+ *     maxSuggestions: 3
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {suggestions.map(suggestion => (
+ *         <button key={suggestion.title}>{suggestion.title}</button>
+ *       ))}
+ *       <button onClick={generateSuggestions} disabled={isLoadingSuggestions}>
+ *         Generate Suggestions
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * ## Return Values
+ * The following properties are returned from the hook:
+ *
+ * <PropertyReference name="messages" type="Message[]">
+ * The messages currently in the chat in AG-UI format
+ * </PropertyReference>
+ *
+ * <PropertyReference name="sendMessage" type="(message: Message, options?) => Promise<void>">
+ * Send a new message to the chat and trigger AI response
+ * </PropertyReference>
+ *
+ * <PropertyReference name="setMessages" type="(messages: Message[] | DeprecatedGqlMessage[]) => void">
+ * Replace all messages in the chat with new array
+ * </PropertyReference>
+ *
+ * <PropertyReference name="deleteMessage" type="(messageId: string) => void">
+ * Remove a specific message by ID from the chat
+ * </PropertyReference>
+ *
+ * <PropertyReference name="reloadMessages" type="(messageId: string) => Promise<void>">
+ * Regenerate the response for a specific message by ID
+ * </PropertyReference>
+ *
+ * <PropertyReference name="stopGeneration" type="() => void">
+ * Stop the current message generation process
+ * </PropertyReference>
+ *
+ * <PropertyReference name="reset" type="() => void">
+ * Clear all messages and reset chat state completely
+ * </PropertyReference>
+ *
+ * <PropertyReference name="isLoading" type="boolean">
+ * Whether the chat is currently generating a response
+ * </PropertyReference>
+ *
+ * <PropertyReference name="runChatCompletion" type="() => Promise<Message[]>">
+ * Manually trigger chat completion for advanced usage
+ * </PropertyReference>
+ *
+ * <PropertyReference name="mcpServers" type="MCPServerConfig[]">
+ * Array of Model Context Protocol server configurations
+ * </PropertyReference>
+ *
+ * <PropertyReference name="setMcpServers" type="(servers: MCPServerConfig[]) => void">
+ * Update MCP server configurations for enhanced context
+ * </PropertyReference>
+ *
+ * <PropertyReference name="suggestions" type="SuggestionItem[]">
+ * Current suggestions array for reading or manual control
+ * </PropertyReference>
+ *
+ * <PropertyReference name="setSuggestions" type="(suggestions: SuggestionItem[]) => void">
+ * Manually set suggestions for custom workflows
+ * </PropertyReference>
+ *
+ * <PropertyReference name="generateSuggestions" type="() => Promise<void>">
+ * Trigger AI-powered suggestion generation using configured settings
+ * </PropertyReference>
+ *
+ * <PropertyReference name="resetSuggestions" type="() => void">
+ * Clear all current suggestions and reset generation state
+ * </PropertyReference>
+ *
+ * <PropertyReference name="isLoadingSuggestions" type="boolean">
+ * Whether suggestions are currently being generated
+ * </PropertyReference>
+ *
+ * <PropertyReference name="interrupt" type="string | React.ReactElement | null">
+ * Interrupt content for human-in-the-loop workflows
+ * </PropertyReference>
+ */
+import { useEffect } from "react";
+import { useCopilotContext } from "../context/copilot-context";
+import {
+  useCopilotChatInternal,
+  defaultSystemMessage,
+  UseCopilotChatOptions as UseCopilotChatOptions_c,
+  UseCopilotChatReturn as UseCopilotChatReturn_c,
+  MCPServerConfig,
+} from "./use-copilot-chat_internal";
+
+import {
+  ErrorVisibility,
+  Severity,
+  CopilotKitError,
+  CopilotKitErrorCode,
+  styledConsole,
+} from "@copilotkit/shared";
+
+// Non-functional fallback implementation
+const createNonFunctionalReturn = (): UseCopilotChatReturn_c => ({
+  visibleMessages: [],
+  messages: [],
+  sendMessage: async () => {},
+  appendMessage: async () => {},
+  setMessages: () => {},
+  deleteMessage: () => {},
+  reloadMessages: async () => {},
+  stopGeneration: () => {},
+  reset: () => {},
+  isLoading: false,
+  isAvailable: false,
+  runChatCompletion: async () => [],
+  mcpServers: [],
+  setMcpServers: () => {},
+  suggestions: [],
+  setSuggestions: () => {},
+  generateSuggestions: async () => {},
+  resetSuggestions: () => {},
+  isLoadingSuggestions: false,
+  interrupt: null,
+});
+/**
+ * Enterprise React hook that provides complete chat functionality for fully custom UI implementations.
+ * Includes all advanced features like direct message access, suggestions array, interrupt handling, and MCP support.
+ *
+ * **Requires a publicApiKey** - Sign up for free at https://cloud.copilotkit.ai/
+ *
+ * @param options - Configuration options for the chat
+ * @returns Complete chat interface with all enterprise features
+ *
+ * @example
+ * ```tsx
+ * const { messages, sendMessage, suggestions, interrupt } = useCopilotChatHeadless_c();
+ * ```
+ */
+function useCopilotChatHeadless_c(options: UseCopilotChatOptions_c = {}): UseCopilotChatReturn_c {
+  const { copilotApiConfig, setBannerError } = useCopilotContext();
+
+  // Check if publicApiKey is available
+  const hasPublicApiKey = Boolean(copilotApiConfig.publicApiKey);
+
+  // Always call the internal hook (follows rules of hooks)
+  const internalResult = useCopilotChatInternal(options);
+
+  // Set banner error when no public API key is provided
+  useEffect(() => {
+    if (!hasPublicApiKey) {
+      setBannerError(
+        new CopilotKitError({
+          message:
+            // add link to documentation here
+            "You're using useCopilotChatHeadless_c, a premium-only feature, which offers extensive headless chat capabilities. To continue, you'll need to provide a free public license key.",
+          code: CopilotKitErrorCode.MISSING_PUBLIC_API_KEY_ERROR,
+          severity: Severity.WARNING,
+          visibility: ErrorVisibility.BANNER,
+        }),
+      );
+      styledConsole.logCopilotKitPlatformMessage();
+    } else {
+      setBannerError(null); // Clear banner when API key is provided
+    }
+  }, [hasPublicApiKey]); // Removed setBannerError dependency
+
+  // Return internal result if publicApiKey is available, otherwise return fallback
+  if (hasPublicApiKey) {
+    return internalResult;
+  }
+
+  // Return non-functional fallback when no publicApiKey
+  return createNonFunctionalReturn();
+}
+
+export { defaultSystemMessage, useCopilotChatHeadless_c };
+export type { UseCopilotChatOptions_c, UseCopilotChatReturn_c, MCPServerConfig };
+
+const noKeyWarning = () => {
+  styledConsole.logCopilotKitPlatformMessage();
+};