@copilotkit/react-core 1.10.0-next.3 → 1.10.0-next.5

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

@@ -4,14 +4,26 @@
  * programmatically interact with the Copilot instance managed by the default
  * UI.
  *
+ * **Requires a publicApiKey** - Sign up for free at https://cloud.copilotkit.ai/
+ * to get your API key with generous usage limits.
+ *
  * ## Usage
  *
  * ### Simple Usage
  *
  * ```tsx
+ * import { CopilotKit } from "@copilotkit/react-core";
  * import { useCopilotChat } from "@copilotkit/react-core";
  * import { Role, TextMessage } from "@copilotkit/runtime-client-gql";
  *
+ * export function App() {
+ *   return (
+ *     <CopilotKit publicApiKey="your-public-api-key">
+ *       <YourComponent />
+ *     </CopilotKit>
+ *   );
+ * }
+ *
  * export function YourComponent() {
  *   const { appendMessage } = useCopilotChat();
  *
@@ -30,8 +42,17 @@
  * ### Working with Suggestions
  *
  * ```tsx
+ * import { CopilotKit } from "@copilotkit/react-core";
  * import { useCopilotChat, useCopilotChatSuggestions } from "@copilotkit/react-core";
  *
+ * export function App() {
+ *   return (
+ *     <CopilotKit publicApiKey="your-public-api-key">
+ *       <YourComponent />
+ *     </CopilotKit>
+ *   );
+ * }
+ *
  * export function YourComponent() {
  *   const {
  *     suggestions,
@@ -80,440 +101,78 @@
  * } = useCopilotChat();
  * ```
  */
-import { useRef, useEffect, useCallback, useState, useMemo } from "react";
-import { AgentSession, useCopilotContext, CopilotContextParams } from "../context/copilot-context";
-import { useCopilotMessagesContext, CopilotMessagesContextParams } from "../context";
-import { SystemMessageFunction } from "../types";
-import { useChat, AppendMessageOptions } from "./use-chat";
-import { defaultCopilotContextCategories } from "../components";
-import { CoAgentStateRenderHandlerArguments } from "@copilotkit/shared";
-import { useAsyncCallback } from "../components/error-boundary/error-utils";
-import { reloadSuggestions as generateSuggestions } from "../utils";
-import type { SuggestionItem } from "../utils";
-
-import { Message } from "@copilotkit/shared";
-import { Role as gqlRole, TextMessage, aguiToGQL, gqlToAGUI } from "@copilotkit/runtime-client-gql";
-import { useLangGraphInterruptRender } from "./use-langgraph-interrupt-render";
-
-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;
-
-  /**
-   * Initial messages to populate the chat with.
-   */
-  initialMessages?: Message[];
-
-  /**
-   * A function to generate the system message. Defaults to `defaultSystemMessage`.
-   */
-  makeSystemMessage?: SystemMessageFunction;
-}
-
-export interface MCPServerConfig {
-  endpoint: string;
-  apiKey?: string;
-}
-
-export interface UseCopilotChatReturn {
-  /** Array of messages currently visible in the chat interface */
-  visibleMessages: Message[];
-
-  /** Send a new message to the chat */
-  appendMessage: (message: Message, options?: AppendMessageOptions) => Promise<void>;
-
-  /** Replace all messages in the chat */
-  setMessages: (messages: Message[]) => void;
-
-  /** Remove a specific message by ID */
-  deleteMessage: (messageId: string) => void;
-
-  /** Regenerate the response for a specific message */
-  reloadMessages: (messageId: string) => Promise<void>;
-
-  /** Stop the current message generation */
-  stopGeneration: () => void;
-
-  /** Clear all messages and reset chat state */
-  reset: () => void;
-
-  /** Whether the chat is currently generating a response */
-  isLoading: boolean;
-
-  /** Manually trigger chat completion (advanced usage) */
-  runChatCompletion: () => Promise<Message[]>;
-
-  /** MCP (Model Context Protocol) server configurations */
-  mcpServers: MCPServerConfig[];
-
-  /** Update MCP server configurations */
-  setMcpServers: (mcpServers: MCPServerConfig[]) => void;
-
-  /**
-   * Current suggestions array
-   * Use this to read the current suggestions or in conjunction with setSuggestions for manual control
-   */
-  suggestions: SuggestionItem[];
-
-  /**
-   * Manually set suggestions
-   * Useful for manual mode or custom suggestion workflows
-   */
-  setSuggestions: (suggestions: SuggestionItem[]) => void;
-
-  /**
-   * Trigger AI-powered suggestion generation
-   * Uses configurations from useCopilotChatSuggestions hooks
-   * Respects global debouncing - only one generation can run at a time
-   */
-  generateSuggestions: () => Promise<void>;
-
-  /**
-   * Clear all current suggestions
-   * Also resets suggestion generation state
-   */
-  resetSuggestions: () => void;
-
-  /** Whether suggestions are currently being generated */
-  isLoadingSuggestions: boolean;
-
-  /** Interrupt content for human-in-the-loop workflows */
-  interrupt: string | React.ReactElement | null;
-}
-
-let globalSuggestionPromise: Promise<void> | null = null;
-
-export function useCopilotChat(options: UseCopilotChatOptions = {}): UseCopilotChatReturn {
-  const makeSystemMessage = options.makeSystemMessage ?? defaultSystemMessage;
-  const {
-    getContextString,
-    getFunctionCallHandler,
-    copilotApiConfig,
-    isLoading,
-    setIsLoading,
-    chatInstructions,
-    actions,
-    coagentStatesRef,
-    setCoagentStatesWithRef,
-    coAgentStateRenders,
-    agentSession,
-    setAgentSession,
-    forwardedParameters,
-    agentLock,
-    threadId,
-    setThreadId,
-    runId,
-    setRunId,
-    chatAbortControllerRef,
-    extensions,
-    setExtensions,
-    langGraphInterruptAction,
-    setLangGraphInterruptAction,
-    chatSuggestionConfiguration,
-    suggestions,
-    setSuggestions,
-    runtimeClient,
-  } = useCopilotContext();
-  const { messages, setMessages } = useCopilotMessagesContext();
-
-  // Simple state for MCP servers (keep for interface compatibility)
-  const [mcpServers, setLocalMcpServers] = useState<MCPServerConfig[]>([]);
-
-  // Basic suggestion state for programmatic control
-  const suggestionsAbortControllerRef = useRef<AbortController | null>(null);
-  const isLoadingSuggestionsRef = useRef<boolean>(false);
-
-  const abortSuggestions = useCallback(
-    (clear: boolean = true) => {
-      suggestionsAbortControllerRef.current?.abort("suggestions aborted by user");
-      suggestionsAbortControllerRef.current = null;
-      if (clear) {
-        setSuggestions([]);
-      }
-    },
-    [setSuggestions],
-  );
-
-  // Memoize context with stable dependencies only
-  const stableContext = useMemo(() => {
-    return {
-      actions,
-      copilotApiConfig,
-      chatSuggestionConfiguration,
-      messages,
-      setMessages,
-      getContextString,
-      runtimeClient,
-    };
-  }, [
-    JSON.stringify(Object.keys(actions)),
-    copilotApiConfig.chatApiEndpoint,
-    messages.length,
-    Object.keys(chatSuggestionConfiguration).length,
-  ]);
-
-  // Programmatic suggestion generation function
-  const generateSuggestionsFunc = useCallback(async () => {
-    // If a global suggestion is running, ignore this call
-    if (globalSuggestionPromise) {
-      return globalSuggestionPromise;
-    }
-
-    globalSuggestionPromise = (async () => {
-      try {
-        abortSuggestions();
-        isLoadingSuggestionsRef.current = true;
-        suggestionsAbortControllerRef.current = new AbortController();
-
-        setSuggestions([]);
-
-        await generateSuggestions(
-          stableContext as CopilotContextParams & CopilotMessagesContextParams,
-          chatSuggestionConfiguration,
-          setSuggestions,
-          suggestionsAbortControllerRef,
-        );
-      } catch (error) {
-        // Re-throw to allow caller to handle the error
-        throw error;
-      } finally {
-        isLoadingSuggestionsRef.current = false;
-        globalSuggestionPromise = null;
-      }
-    })();
-
-    return globalSuggestionPromise;
-  }, [stableContext, chatSuggestionConfiguration, setSuggestions, abortSuggestions]);
-
-  const resetSuggestions = useCallback(() => {
-    setSuggestions([]);
-  }, [setSuggestions]);
-
-  // MCP servers logic
+import { useEffect } from "react";
+import { useCopilotContext } from "../context/copilot-context";
+
+import {
+  useCopilotChat as useCopilotChatInternal,
+  defaultSystemMessage,
+  UseCopilotChatOptions,
+  UseCopilotChatReturn,
+  MCPServerConfig,
+} from "./use-copilot-chat_internal";
+import {
+  ErrorVisibility,
+  Severity,
+  CopilotKitError,
+  CopilotKitErrorCode,
+  styledConsole,
+} from "@copilotkit/shared";
+
+// Non-functional fallback implementation
+const createNonFunctionalReturn = (): UseCopilotChatReturn => ({
+  visibleMessages: [],
+  appendMessage: async () => {},
+  setMessages: () => {},
+  deleteMessage: () => {},
+  reloadMessages: async () => {},
+  stopGeneration: () => {},
+  reset: () => {},
+  isLoading: false,
+  runChatCompletion: async () => [],
+  mcpServers: [],
+  setMcpServers: () => {},
+  suggestions: [],
+  setSuggestions: () => {},
+  generateSuggestions: async () => {},
+  resetSuggestions: () => {},
+  isLoadingSuggestions: false,
+  interrupt: null,
+});
+function useCopilotChat(options: UseCopilotChatOptions = {}): UseCopilotChatReturn {
+  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 (mcpServers.length > 0) {
-      const serversCopy = [...mcpServers];
-      copilotApiConfig.mcpServers = serversCopy;
-      if (!copilotApiConfig.properties) {
-        copilotApiConfig.properties = {};
-      }
-      copilotApiConfig.properties.mcpServers = serversCopy;
-    }
-  }, [mcpServers, copilotApiConfig]);
-
-  const setMcpServers = useCallback((servers: MCPServerConfig[]) => {
-    setLocalMcpServers(servers);
-  }, []);
-
-  // Move these function declarations above the useChat call
-  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 (!hasPublicApiKey) {
+      setBannerError(
+        new CopilotKitError({
+          message: "As of v1.10.0, useCopilotChat requires a publicApiKey to function.",
+          code: CopilotKitErrorCode.MISSING_PUBLIC_API_KEY_ERROR,
+          severity: Severity.CRITICAL,
+          visibility: ErrorVisibility.BANNER,
+        }),
       );
-      if (!action) {
-        action = Object.values(coAgentStateRenders).find(
-          (action) => action.name === name && !action.nodeName,
-        );
-      }
-      if (action) {
-        await action.handler?.({ state, nodeName });
-      }
-    },
-    [coAgentStateRenders],
-  );
-
-  const makeSystemMessageCallback = useCallback(() => {
-    const systemMessageMaker = makeSystemMessage || defaultSystemMessage;
-    // this always gets the latest context string
-    const contextString = getContextString([], defaultCopilotContextCategories); // TODO: make the context categories configurable
-
-    return new TextMessage({
-      content: systemMessageMaker(contextString, chatInstructions),
-      role: gqlRole.System,
-    });
-  }, [getContextString, makeSystemMessage, chatInstructions]);
-
-  const deleteMessage = useCallback(
-    (messageId: string) => {
-      setMessages((prev) => prev.filter((message) => message.id !== messageId));
-    },
-    [setMessages],
-  );
-
-  // Get chat helpers with updated config
-  const { append, reload, stop, runChatCompletion } = useChat({
-    ...options,
-    actions: Object.values(actions),
-    copilotConfig: copilotApiConfig,
-    initialMessages: aguiToGQL(options.initialMessages || []),
-    onFunctionCall: getFunctionCallHandler(),
-    onCoAgentStateRender,
-    messages,
-    setMessages,
-    makeSystemMessageCallback,
-    isLoading,
-    setIsLoading,
-    coagentStatesRef,
-    setCoagentStatesWithRef,
-    agentSession,
-    setAgentSession,
-    forwardedParameters,
-    threadId,
-    setThreadId,
-    runId,
-    setRunId,
-    chatAbortControllerRef,
-    agentLock,
-    extensions,
-    setExtensions,
-    langGraphInterruptAction,
-    setLangGraphInterruptAction,
-  });
-
-  const latestAppend = useUpdatedRef(append);
-  const latestAppendFunc = useAsyncCallback(
-    async (message: Message, options?: AppendMessageOptions) => {
-      abortSuggestions(options?.clearSuggestions);
-      return await latestAppend.current(aguiToGQL([message])[0], options);
-    },
-    [latestAppend],
-  );
-
-  const latestReload = useUpdatedRef(reload);
-  const latestReloadFunc = useAsyncCallback(
-    async (messageId: string) => {
-      return await latestReload.current(messageId);
-    },
-    [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(aguiToGQL(messages));
-    },
-    [latestSetMessages],
-  );
-
-  const latestRunChatCompletion = useUpdatedRef(runChatCompletion);
-  const latestRunChatCompletionFunc = useAsyncCallback(async () => {
-    return await latestRunChatCompletion.current!();
-  }, [latestRunChatCompletion]);
-
-  const reset = useCallback(() => {
-    latestStopFunc();
-    setMessages([]);
-    setRunId(null);
-    setCoagentStatesWithRef({});
-    let initialAgentSession: AgentSession | null = null;
-    if (agentLock) {
-      initialAgentSession = {
-        agentName: agentLock,
-      };
+      styledConsole.logCopilotKitPlatformMessage();
+    } else {
+      setBannerError(null); // Clear banner when API key is provided
     }
-    setAgentSession(initialAgentSession);
-    // Reset suggestions when chat is reset
-    resetSuggestions();
-  }, [
-    latestStopFunc,
-    setMessages,
-    setThreadId,
-    setCoagentStatesWithRef,
-    setAgentSession,
-    agentLock,
-    resetSuggestions,
-  ]);
-
-  const latestReset = useUpdatedRef(reset);
-  const latestResetFunc = useCallback(() => {
-    return latestReset.current();
-  }, [latestReset]);
-
-  const interrupt = useLangGraphInterruptRender();
-
-  return {
-    visibleMessages: gqlToAGUI(messages, actions, coAgentStateRenders),
-    appendMessage: latestAppendFunc,
-    setMessages: latestSetMessagesFunc,
-    reloadMessages: latestReloadFunc,
-    stopGeneration: latestStopFunc,
-    reset: latestResetFunc,
-    deleteMessage: latestDeleteFunc,
-    runChatCompletion: latestRunChatCompletionFunc,
-    isLoading,
-    mcpServers,
-    setMcpServers,
-    suggestions,
-    setSuggestions,
-    generateSuggestions: generateSuggestionsFunc,
-    resetSuggestions,
-    isLoadingSuggestions: isLoadingSuggestionsRef.current,
-    interrupt,
-  };
-}
+  }, [hasPublicApiKey]); // Removed setBannerError dependency
 
-// store `value` in a ref and update
-// it whenever it changes.
-function useUpdatedRef<T>(value: T) {
-  const ref = useRef(value);
+  // Return internal result if publicApiKey is available, otherwise return fallback
+  if (hasPublicApiKey) {
+    return internalResult;
+  }
 
-  useEffect(() => {
-    ref.current = value;
-  }, [value]);
-
-  return ref;
+  // Return non-functional fallback when no publicApiKey
+  return createNonFunctionalReturn();
 }
 
-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.
-In case of a function error:
-- If this error stems from incorrect function parameters or syntax, you may retry with corrected arguments.
-- If the error's source is unclear or seems unrelated to your input, do not attempt further retries.
-` + (additionalInstructions ? `\n\n${additionalInstructions}` : "")
-  );
-}
+export { defaultSystemMessage, useCopilotChat };
+export type { UseCopilotChatOptions, UseCopilotChatReturn, MCPServerConfig };