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

package/src/components/copilot-provider/copilot-messages.tsx

@@ -0,0 +1,274 @@
+/**
+ * An internal context to separate the messages state (which is constantly changing) from the rest of CopilotKit context
+ */
+
+import {
+  ReactNode,
+  useEffect,
+  useState,
+  useRef,
+  useCallback,
+  useMemo,
+  createContext,
+  useContext,
+} from "react";
+import { CopilotMessagesContext } from "../../context/copilot-messages-context";
+import {
+  loadMessagesFromJsonRepresentation,
+  Message,
+  GraphQLError,
+} from "@copilotkit/runtime-client-gql";
+import { useCopilotContext } from "../../context/copilot-context";
+import { useToast } from "../toast/toast-provider";
+import { shouldShowDevConsole } from "../../utils/dev-console";
+import {
+  ErrorVisibility,
+  CopilotKitApiDiscoveryError,
+  CopilotKitRemoteEndpointDiscoveryError,
+  CopilotKitAgentDiscoveryError,
+  CopilotKitError,
+  CopilotKitErrorCode,
+} from "@copilotkit/shared";
+import { Suggestion } from "@copilotkitnext/core";
+
+// Helper to determine if error should show as banner based on visibility and legacy patterns
+function shouldShowAsBanner(gqlError: GraphQLError): boolean {
+  const extensions = gqlError.extensions;
+  if (!extensions) return false;
+
+  // Priority 1: Check error code for discovery errors (these should always be banners)
+  const code = extensions.code as CopilotKitErrorCode;
+  if (
+    code === CopilotKitErrorCode.AGENT_NOT_FOUND ||
+    code === CopilotKitErrorCode.API_NOT_FOUND ||
+    code === CopilotKitErrorCode.REMOTE_ENDPOINT_NOT_FOUND ||
+    code === CopilotKitErrorCode.CONFIGURATION_ERROR ||
+    code === CopilotKitErrorCode.MISSING_PUBLIC_API_KEY_ERROR ||
+    code === CopilotKitErrorCode.UPGRADE_REQUIRED_ERROR
+  ) {
+    return true;
+  }
+
+  // Priority 2: Check banner visibility
+  if (extensions.visibility === ErrorVisibility.BANNER) {
+    return true;
+  }
+
+  // Priority 3: Check for critical errors that should be banners regardless of formal classification
+  const errorMessage = gqlError.message.toLowerCase();
+  if (
+    errorMessage.includes("api key") ||
+    errorMessage.includes("401") ||
+    errorMessage.includes("unauthorized") ||
+    errorMessage.includes("authentication") ||
+    errorMessage.includes("incorrect api key")
+  ) {
+    return true;
+  }
+
+  // Priority 4: Legacy stack trace detection for discovery errors
+  const originalError = extensions.originalError as any;
+  if (originalError?.stack) {
+    return (
+      originalError.stack.includes("CopilotApiDiscoveryError") ||
+      originalError.stack.includes("CopilotKitRemoteEndpointDiscoveryError") ||
+      originalError.stack.includes("CopilotKitAgentDiscoveryError")
+    );
+  }
+
+  return false;
+}
+
+/**
+ * MessagesTap is used to mitigate performance issues when we only need
+ * a snapshot of the messages, not a continuously updating stream of messages.
+ */
+
+export type MessagesTap = {
+  getMessagesFromTap: () => Message[];
+  updateTapMessages: (messages: Message[]) => void;
+};
+
+const MessagesTapContext = createContext<MessagesTap | null>(null);
+
+export function useMessagesTap() {
+  const tap = useContext(MessagesTapContext);
+  if (!tap) throw new Error("useMessagesTap must be used inside <MessagesTapProvider>");
+  return tap;
+}
+
+export function MessagesTapProvider({ children }: { children: React.ReactNode }) {
+  const messagesRef = useRef<Message[]>([]);
+
+  const tapRef = useRef<MessagesTap>({
+    getMessagesFromTap: () => messagesRef.current,
+    updateTapMessages: (messages: Message[]) => {
+      messagesRef.current = messages;
+    },
+  });
+
+  return (
+    <MessagesTapContext.Provider value={tapRef.current}>{children}</MessagesTapContext.Provider>
+  );
+}
+
+/**
+ * CopilotKit messages context.
+ */
+
+export function CopilotMessages({ children }: { children: ReactNode }) {
+  const [messages, setMessages] = useState<Message[]>([]);
+  const lastLoadedThreadId = useRef<string>(undefined!);
+  const lastLoadedAgentName = useRef<string>(undefined!);
+  const lastLoadedMessages = useRef<string>(undefined!);
+
+  const { updateTapMessages } = useMessagesTap();
+
+  const { threadId, agentSession, showDevConsole, onError, copilotApiConfig } = useCopilotContext();
+  const { setBannerError } = useToast();
+
+  // Helper function to trace UI errors (similar to useCopilotRuntimeClient)
+  const traceUIError = useCallback(
+    async (error: CopilotKitError, originalError?: any) => {
+      // Just check if onError and publicApiKey are defined
+      if (!onError || !copilotApiConfig.publicApiKey) return;
+
+      try {
+        const traceEvent = {
+          type: "error" as const,
+          timestamp: Date.now(),
+          context: {
+            source: "ui" as const,
+            request: {
+              operation: "loadAgentState",
+              url: copilotApiConfig.chatApiEndpoint,
+              startTime: Date.now(),
+            },
+            technical: {
+              environment: "browser",
+              userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+              stackTrace: originalError instanceof Error ? originalError.stack : undefined,
+            },
+          },
+          error,
+        };
+        await onError(traceEvent);
+      } catch (traceError) {
+        console.error("Error in CopilotMessages onError handler:", traceError);
+      }
+    },
+    [onError, copilotApiConfig.publicApiKey, copilotApiConfig.chatApiEndpoint],
+  );
+
+  const createStructuredError = (gqlError: GraphQLError): CopilotKitError | null => {
+    const extensions = gqlError.extensions;
+    const originalError = extensions?.originalError as any;
+
+    // Priority: Check stack trace for discovery errors first
+    if (originalError?.stack) {
+      if (originalError.stack.includes("CopilotApiDiscoveryError")) {
+        return new CopilotKitApiDiscoveryError({ message: originalError.message });
+      }
+      if (originalError.stack.includes("CopilotKitRemoteEndpointDiscoveryError")) {
+        return new CopilotKitRemoteEndpointDiscoveryError({ message: originalError.message });
+      }
+      if (originalError.stack.includes("CopilotKitAgentDiscoveryError")) {
+        return new CopilotKitAgentDiscoveryError({
+          agentName: "",
+          availableAgents: [],
+        });
+      }
+    }
+
+    // Fallback: Use the formal error code if available
+    const message = originalError?.message || gqlError.message;
+    const code = extensions?.code as CopilotKitErrorCode;
+
+    if (code) {
+      return new CopilotKitError({ message, code });
+    }
+
+    return null;
+  };
+
+  const handleGraphQLErrors = useCallback(
+    (error: any) => {
+      if (error.graphQLErrors?.length) {
+        const graphQLErrors = error.graphQLErrors as GraphQLError[];
+
+        // Route all errors to banners for consistent UI
+        const routeError = (gqlError: GraphQLError) => {
+          const extensions = gqlError.extensions;
+          const visibility = extensions?.visibility as ErrorVisibility;
+          const isDev = shouldShowDevConsole(showDevConsole);
+
+          if (!isDev) {
+            console.error("CopilotKit Error (hidden in production):", gqlError.message);
+            return;
+          }
+
+          // Silent errors - just log
+          if (visibility === ErrorVisibility.SILENT) {
+            console.error("CopilotKit Silent Error:", gqlError.message);
+            return;
+          }
+
+          // All other errors (including DEV_ONLY) show as banners for consistency
+          const ckError = createStructuredError(gqlError);
+          if (ckError) {
+            setBannerError(ckError);
+            // Trace the structured error
+            traceUIError(ckError, gqlError);
+          } else {
+            // Fallback: create a generic error for unstructured GraphQL errors
+            const fallbackError = new CopilotKitError({
+              message: gqlError.message,
+              code: CopilotKitErrorCode.UNKNOWN,
+            });
+            setBannerError(fallbackError);
+            // Trace the fallback error
+            traceUIError(fallbackError, gqlError);
+          }
+        };
+
+        // Process all errors as banners
+        graphQLErrors.forEach(routeError);
+      } else {
+        const isDev = shouldShowDevConsole(showDevConsole);
+        if (!isDev) {
+          console.error("CopilotKit Error (hidden in production):", error);
+        } else {
+          // Route non-GraphQL errors to banner as well
+          const fallbackError = new CopilotKitError({
+            message: error?.message || String(error),
+            code: CopilotKitErrorCode.UNKNOWN,
+          });
+          setBannerError(fallbackError);
+          // Trace the non-GraphQL error
+          traceUIError(fallbackError, error);
+        }
+      }
+    },
+    [setBannerError, showDevConsole, traceUIError],
+  );
+
+  useEffect(() => {
+    updateTapMessages(messages);
+  }, [messages, updateTapMessages]);
+
+  const memoizedChildren = useMemo(() => children, [children]);
+  const [suggestions, setSuggestions] = useState<Suggestion[]>([]);
+
+  return (
+    <CopilotMessagesContext.Provider
+      value={{
+        messages,
+        setMessages,
+        suggestions,
+        setSuggestions,
+      }}
+    >
+      {memoizedChildren}
+    </CopilotMessagesContext.Provider>
+  );
+}

package/src/components/copilot-provider/copilotkit-props.tsx

@@ -0,0 +1,169 @@
+import { ForwardedParametersInput } from "@copilotkit/runtime-client-gql";
+import { ReactNode } from "react";
+import { AuthState } from "../../context/copilot-context";
+import { CopilotErrorHandler } from "@copilotkit/shared";
+import { CopilotKitProviderProps } from "@copilotkitnext/react";
+/**
+ * Props for CopilotKit.
+ */
+
+/**
+ * We shouldn't need this `Omit` here, but using it because `CopilotKitProps`
+ * and `CopilotKitProviderProps` have non-identical `children` types
+ *
+ * TODO: Remove this `Omit` once this is resolved.
+ */
+export interface CopilotKitProps extends Omit<CopilotKitProviderProps, "children"> {
+  /**
+   * Your Copilot Cloud API key.
+   *
+   * Don't have it yet? Go to https://cloud.copilotkit.ai and get one for free.
+   */
+  publicApiKey?: string;
+
+  /**
+   * Your public license key for accessing premium CopilotKit features.
+   *
+   * Don't have it yet? Go to https://cloud.copilotkit.ai and get one for free.
+   */
+  publicLicenseKey?: string;
+
+  /**
+   * Restrict input to a specific topic.
+   * @deprecated Use `guardrails_c` instead to control input restrictions
+   */
+  cloudRestrictToTopic?: {
+    validTopics?: string[];
+    invalidTopics?: string[];
+  };
+
+  /**
+   * Restrict input to specific topics using guardrails.
+   * @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. The feature allows restricting chat conversations to specific topics.
+   */
+  guardrails_c?: {
+    validTopics?: string[];
+    invalidTopics?: string[];
+  };
+
+  /**
+   * The endpoint for the Copilot Runtime instance. [Click here for more information](/concepts/copilot-runtime).
+   */
+  runtimeUrl?: string;
+
+  /**
+   * The endpoint for the Copilot transcribe audio service.
+   */
+  transcribeAudioUrl?: string;
+
+  /**
+   * The endpoint for the Copilot text to speech service.
+   */
+  textToSpeechUrl?: string;
+
+  /**
+   * Additional headers to be sent with the request.
+   *
+   * For example:
+   * ```json
+   * {
+   *   "Authorization": "Bearer X"
+   * }
+   * ```
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * The children to be rendered within the CopilotKit.
+   */
+  children: ReactNode;
+
+  /**
+   * Custom properties to be sent with the request.
+   * Can include threadMetadata for thread creation and authorization for LangGraph Platform authentication.
+   * For example:
+   * ```js
+   * {
+   *   'user_id': 'users_id',
+   *   'authorization': 'your-auth-token', // For LangGraph Platform authentication
+   *   threadMetadata: {
+   *     'account_id': '123',
+   *     'user_type': 'premium'
+   *   }
+   * }
+   * ```
+   *
+   * **Note**: The `authorization` property is automatically forwarded to LangGraph agents. See the [LangGraph Agent Authentication Guide](/coagents/shared/guides/langgraph-platform-authentication) for details.
+   */
+  properties?: Record<string, any>;
+
+  /**
+   * Indicates whether the user agent should send or receive cookies from the other domain
+   * in the case of cross-origin requests.
+   */
+  credentials?: RequestCredentials;
+
+  /**
+   * Whether to show the dev console.
+   *
+   * Set to `true` to show error banners and toasts, `false` to hide all error UI.
+   * Defaults to `false` for production safety.
+   */
+  showDevConsole?: boolean;
+
+  /**
+   * The name of the agent to use.
+   */
+  agent?: string;
+
+  /**
+   * The forwarded parameters to use for the task.
+   */
+  forwardedParameters?: Pick<ForwardedParametersInput, "temperature">;
+
+  /**
+   * The auth config to use for the CopilotKit.
+   * @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. The feature allows restricting chat conversations to specific topics.
+   */
+  authConfig_c?: {
+    SignInComponent: React.ComponentType<{
+      onSignInComplete: (authState: AuthState) => void;
+    }>;
+  };
+
+  /**
+   * The thread id to use for the CopilotKit.
+   */
+  threadId?: string;
+
+  /**
+   * Optional error handler for comprehensive debugging and observability.
+   *
+   * **Requires publicApiKey**: Error handling only works when publicApiKey is provided.
+   * This is a premium Copilot Cloud feature.
+   *
+   * @param errorEvent - Structured error event with rich debugging context
+   *
+   * @example
+   * ```typescript
+   * <CopilotKit
+   *   publicApiKey="ck_pub_your_key"
+   *   onError={(errorEvent) => {
+   *     debugDashboard.capture(errorEvent);
+   *   }}
+   * >
+   * ```
+   */
+  onError?: CopilotErrorHandler;
+
+  /**
+   * Enable or disable the CopilotKit Inspector, letting you inspect AG-UI events,
+   * view agent messages, check agent state, and visualize agent context. Defaults
+   * to enabled.
+   */
+  enableInspector?: boolean;
+}