@copilotkit/react-core 1.55.3 → 1.56.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/react-core",
-  "version": "1.55.3",
+  "version": "1.56.1",
   "private": false,
   "keywords": [
     "ai",
@@ -73,11 +73,11 @@
     "untruncate-json": "^0.0.1",
     "use-stick-to-bottom": "^1.1.1",
     "zod-to-json-schema": "^3.24.5",
-    "@copilotkit/core": "1.55.3",
-    "@copilotkit/runtime-client-gql": "1.55.3",
-    "@copilotkit/web-inspector": "1.55.3",
-    "@copilotkit/shared": "1.55.3",
-    "@copilotkit/a2ui-renderer": "1.55.3"
+    "@copilotkit/runtime-client-gql": "1.56.1",
+    "@copilotkit/core": "1.56.1",
+    "@copilotkit/shared": "1.56.1",
+    "@copilotkit/web-inspector": "1.56.1",
+    "@copilotkit/a2ui-renderer": "1.56.1"
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4.1.11",

package/src/components/CopilotListeners.tsx

@@ -60,16 +60,27 @@ const usePredictStateSubscription = (agent?: AbstractAgent) => {
   }, [agent, getSubscriber]);
 };
 
-export function CopilotListeners() {
-  const { copilotkit } = useCopilotKit();
+function CopilotListenersAgentSubscription() {
   const existingConfig = useCopilotChatConfiguration();
   const resolvedAgentId = existingConfig?.agentId;
-  const { setBannerError } = useToast();
 
   const { agent } = useAgent({ agentId: resolvedAgentId });
 
   usePredictStateSubscription(agent);
 
+  return null;
+}
+
+export function CopilotListeners() {
+  const { copilotkit } = useCopilotKit();
+  const { setBannerError } = useToast();
+
+  // Only render the agent subscription when agents are registered or a runtime
+  // is configured. Without this guard, useAgent() throws when the agents map is
+  // empty and no runtimeUrl is set (#3249).
+  const hasAgents = Object.keys(copilotkit.agents ?? {}).length > 0;
+  const hasRuntime = copilotkit.runtimeUrl !== undefined;
+
   useEffect(() => {
     const subscriber: CopilotKitCoreSubscriber = {
       onError: ({ error, code, context }) => {
@@ -122,5 +133,5 @@ export function CopilotListeners() {
     };
   }, [copilotkit?.subscribe]);
 
-  return null;
+  return hasAgents || hasRuntime ? <CopilotListenersAgentSubscription /> : null;
 }

package/src/components/__tests__/CopilotListeners.test.tsx

@@ -0,0 +1,38 @@
+import React from "react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render } from "@testing-library/react";
+import { CopilotListeners } from "../CopilotListeners";
+import { CopilotKitProvider } from "../../v2/providers/CopilotKitProvider";
+import { CopilotChatConfigurationProvider } from "../../v2/providers/CopilotChatConfigurationProvider";
+import { ToastProvider } from "../toast/toast-provider";
+
+/**
+ * Regression test for #3249: CopilotListeners throws when no agents registered.
+ *
+ * When CopilotKitProvider has no agents registered (empty agents map) and no
+ * runtimeUrl, useAgent() inside CopilotListeners throws. The component should
+ * handle this gracefully and render null without crashing.
+ */
+describe("CopilotListeners (#3249)", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  it("does not throw when no agents are registered", () => {
+    // No agents, no runtimeUrl - should not crash
+    expect(() => {
+      render(
+        <ToastProvider enabled={false}>
+          <CopilotKitProvider>
+            <CopilotChatConfigurationProvider
+              agentId="default"
+              threadId="test-thread"
+            >
+              <CopilotListeners />
+            </CopilotChatConfigurationProvider>
+          </CopilotKitProvider>
+        </ToastProvider>,
+      );
+    }).not.toThrow();
+  });
+});

package/src/components/copilot-provider/__tests__/error-visibility-prod.test.tsx

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest";
+import { ErrorVisibility } from "@copilotkit/shared";
+import { getErrorSuppression } from "../copilot-messages";
+
+/**
+ * Regression tests for #2431: error visibility when showDevConsole=false.
+ *
+ * The bug: `routeError` returned early for ALL errors when `isDev` was false,
+ * suppressing TOAST and BANNER errors that should always reach the user.
+ *
+ * The fix: only SILENT and DEV_ONLY errors are suppressed in production;
+ * TOAST, BANNER, and untagged errors are always surfaced.
+ */
+describe("getErrorSuppression — error visibility routing (#2431)", () => {
+  // --- Production (isDev = false) ---
+
+  it("surfaces TOAST errors in production", () => {
+    expect(getErrorSuppression(ErrorVisibility.TOAST, false)).toBeNull();
+  });
+
+  it("surfaces BANNER errors in production", () => {
+    expect(getErrorSuppression(ErrorVisibility.BANNER, false)).toBeNull();
+  });
+
+  it("suppresses DEV_ONLY errors in production", () => {
+    expect(getErrorSuppression(ErrorVisibility.DEV_ONLY, false)).not.toBeNull();
+  });
+
+  it("suppresses SILENT errors in production", () => {
+    expect(getErrorSuppression(ErrorVisibility.SILENT, false)).not.toBeNull();
+  });
+
+  it("surfaces errors with no visibility tag in production", () => {
+    expect(getErrorSuppression(undefined, false)).toBeNull();
+  });
+
+  // --- Development (isDev = true) ---
+
+  it("surfaces TOAST errors in development", () => {
+    expect(getErrorSuppression(ErrorVisibility.TOAST, true)).toBeNull();
+  });
+
+  it("surfaces BANNER errors in development", () => {
+    expect(getErrorSuppression(ErrorVisibility.BANNER, true)).toBeNull();
+  });
+
+  it("surfaces DEV_ONLY errors in development", () => {
+    expect(getErrorSuppression(ErrorVisibility.DEV_ONLY, true)).toBeNull();
+  });
+
+  it("suppresses SILENT errors in development", () => {
+    expect(getErrorSuppression(ErrorVisibility.SILENT, true)).not.toBeNull();
+  });
+
+  it("surfaces errors with no visibility tag in development", () => {
+    expect(getErrorSuppression(undefined, true)).toBeNull();
+  });
+
+  // --- Log prefix strings ---
+
+  it("returns a 'Silent Error' prefix for SILENT visibility", () => {
+    const prefix = getErrorSuppression(ErrorVisibility.SILENT, false);
+    expect(prefix).toContain("Silent");
+  });
+
+  it("returns a 'hidden in production' prefix for DEV_ONLY visibility", () => {
+    const prefix = getErrorSuppression(ErrorVisibility.DEV_ONLY, false);
+    expect(prefix).toContain("hidden in production");
+  });
+});

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

@@ -31,6 +31,33 @@ import {
 } from "@copilotkit/shared";
 import { Suggestion } from "@copilotkit/core";
 
+/**
+ * Determine whether a GraphQL error should be suppressed based on its visibility
+ * and whether the dev console is active.
+ *
+ * Returns `null` when the error should be surfaced to the UI, or a log prefix
+ * string when the error should be suppressed (logged to console only).
+ *
+ * Exported for unit testing.
+ */
+export function getErrorSuppression(
+  visibility: ErrorVisibility | undefined,
+  isDev: boolean,
+): string | null {
+  // Silent errors are always suppressed
+  if (visibility === ErrorVisibility.SILENT) {
+    return "CopilotKit Silent Error:";
+  }
+
+  // DEV_ONLY errors are suppressed in production
+  if (!isDev && visibility === ErrorVisibility.DEV_ONLY) {
+    return "CopilotKit Error (hidden in production):";
+  }
+
+  // All other visibilities (TOAST, BANNER, undefined) are always surfaced
+  return null;
+}
+
 // Helper to determine if error should show as banner based on visibility and legacy patterns
 function shouldShowAsBanner(gqlError: GraphQLError): boolean {
   const extensions = gqlError.extensions;
@@ -224,20 +251,13 @@ export function CopilotMessages({ children }: { children: ReactNode }) {
           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);
+          const suppression = getErrorSuppression(visibility, isDev);
+          if (suppression) {
+            console.error(suppression, gqlError.message);
             return;
           }
 
+          // TOAST and BANNER errors are always surfaced, even in production
           // All other errors (including DEV_ONLY) show as banners for consistency
           const ckError = createStructuredError(gqlError);
           if (ckError) {
@@ -259,19 +279,14 @@ export function CopilotMessages({ children }: { children: ReactNode }) {
         // 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);
-        }
+        // Non-GraphQL errors are always surfaced to the user
+        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],

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

@@ -1,7 +1,7 @@
 import { ForwardedParametersInput } from "@copilotkit/runtime-client-gql";
 import { ReactNode } from "react";
 import { AuthState } from "../../context/copilot-context";
-import { CopilotErrorHandler } from "@copilotkit/shared";
+import { CopilotErrorHandler, DebugConfig } from "@copilotkit/shared";
 import { CopilotKitProviderProps } from "../../v2";
 /**
  * Props for CopilotKit.
@@ -68,15 +68,19 @@ export interface CopilotKitProps extends Omit<
 
   /**
    * Additional headers to be sent with the request.
+   * Can be a static object or a function that returns headers dynamically
+   * (useful for refreshing auth tokens).
    *
    * For example:
-   * ```json
-   * {
-   *   "Authorization": "Bearer X"
-   * }
+   * ```tsx
+   * // Static headers
+   * headers={{ "Authorization": "Bearer X" }}
+   *
+   * // Dynamic headers (re-evaluated on each render)
+   * headers={() => ({ "Authorization": `Bearer ${getToken()}` })}
    * ```
    */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | (() => Record<string, string>);
 
   /**
    * The children to be rendered within the CopilotKit.
@@ -191,4 +195,20 @@ export interface CopilotKitProps extends Omit<
    * to enabled.
    */
   enableInspector?: boolean;
+
+  /**
+   * Enable debug logging. On the server (`CopilotRuntime`), this enables
+   * structured Pino logging of the AG-UI event pipeline. On the client,
+   * this configuration is forwarded to the AG-UI transport layer
+   * (`transformChunks`) for transport-level debug output.
+   *
+   * Pass `true` for full output, or an object for granular control:
+   *
+   * ```tsx
+   * <CopilotKit debug={true} runtimeUrl="...">
+   *   {children}
+   * </CopilotKit>
+   * ```
+   */
+  debug?: DebugConfig;
 }

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

@@ -311,7 +311,10 @@ export function CopilotKitInternal(cpkProps: CopilotKitProps) {
       publicApiKey: publicApiKey,
       ...(cloud ? { cloud } : {}),
       chatApiEndpoint: chatApiEndpoint,
-      headers: props.headers || {},
+      headers:
+        typeof props.headers === "function"
+          ? props.headers()
+          : props.headers || {},
       properties: props.properties || {},
       transcribeAudioUrl: props.transcribeAudioUrl,
       textToSpeechUrl: props.textToSpeechUrl,

package/src/v2/components/chat/CopilotChatAssistantMessage.tsx

@@ -22,6 +22,7 @@ import {
 import { useKatexStyles } from "../../hooks/useKatexStyles";
 import { WithSlots, renderSlot } from "../../lib/slots";
 import { Streamdown } from "streamdown";
+import { copyToClipboard } from "@copilotkit/shared";
 import CopilotChatToolCallsView from "./CopilotChatToolCallsView";
 
 export type CopilotChatAssistantMessageProps = WithSlots<
@@ -86,12 +87,9 @@ export function CopilotChatAssistantMessage({
     {
       onClick: async () => {
         if (message.content) {
-          try {
-            await navigator.clipboard.writeText(message.content);
-          } catch (err) {
-            console.error("Failed to copy message:", err);
-          }
+          return await copyToClipboard(message.content);
         }
+        return false;
       },
     },
   );
@@ -100,7 +98,7 @@ export function CopilotChatAssistantMessage({
     thumbsUpButton,
     CopilotChatAssistantMessage.ThumbsUpButton,
     {
-      onClick: onThumbsUp,
+      onClick: onThumbsUp ? () => onThumbsUp(message) : undefined,
     },
   );
 
@@ -108,7 +106,7 @@ export function CopilotChatAssistantMessage({
     thumbsDownButton,
     CopilotChatAssistantMessage.ThumbsDownButton,
     {
-      onClick: onThumbsDown,
+      onClick: onThumbsDown ? () => onThumbsDown(message) : undefined,
     },
   );
 
@@ -116,7 +114,7 @@ export function CopilotChatAssistantMessage({
     readAloudButton,
     CopilotChatAssistantMessage.ReadAloudButton,
     {
-      onClick: onReadAloud,
+      onClick: onReadAloud ? () => onReadAloud(message) : undefined,
     },
   );
 
@@ -124,7 +122,7 @@ export function CopilotChatAssistantMessage({
     regenerateButton,
     CopilotChatAssistantMessage.RegenerateButton,
     {
-      onClick: onRegenerate,
+      onClick: onRegenerate ? () => onRegenerate(message) : undefined,
     },
   );
 
@@ -275,18 +273,23 @@ export namespace CopilotChatAssistantMessage {
       };
     }, []);
 
-    const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
-      setCopied(true);
-      if (timerRef.current !== null) {
-        clearTimeout(timerRef.current);
+    const handleClick = async (event: React.MouseEvent<HTMLButtonElement>) => {
+      let success = false;
+      if (onClick) {
+        // onClick may return a boolean indicating copy success
+        const result = await Promise.resolve(onClick(event));
+        success = result === true;
       }
-      timerRef.current = setTimeout(() => {
-        timerRef.current = null;
-        setCopied(false);
-      }, 2000);
 
-      if (onClick) {
-        onClick(event);
+      if (success) {
+        setCopied(true);
+        if (timerRef.current !== null) {
+          clearTimeout(timerRef.current);
+        }
+        timerRef.current = setTimeout(() => {
+          timerRef.current = null;
+          setCopied(false);
+        }, 2000);
       }
     };
 

package/src/v2/components/chat/CopilotChatInput.tsx

@@ -384,6 +384,12 @@ export function CopilotChatInput({
   );
 
   const handleKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    // Skip key handling during IME composition (e.g. CJK input).
+    // The compositionend event will fire separately when composition ends.
+    if (e.nativeEvent.isComposing || e.keyCode === 229) {
+      return;
+    }
+
     if (commandQuery !== null && mode === "input") {
       if (e.key === "ArrowDown") {
         if (filteredCommands.length > 0) {
@@ -455,10 +461,12 @@ export function CopilotChatInput({
 
     onSubmitMessage(trimmed);
 
+    // Always clear the input after sending, including controlled mode.
+    // In controlled mode, onChange("") notifies the parent to reset its state.
     if (!isControlled) {
       setInternalValue("");
-      onChange?.("");
     }
+    onChange?.("");
 
     if (inputRef.current) {
       inputRef.current.focus();
@@ -470,6 +478,12 @@ export function CopilotChatInput({
     value: resolvedValue,
     onChange: handleChange,
     onKeyDown: handleKeyDown,
+    onCompositionStart: () => {
+      isComposingRef.current = true;
+    },
+    onCompositionEnd: () => {
+      isComposingRef.current = false;
+    },
     autoFocus: autoFocus,
     className: twMerge(
       "cpk:w-full cpk:py-3",
@@ -612,9 +626,14 @@ export function CopilotChatInput({
     }
   };
 
+  // Track whether an IME composition is active so we can avoid
+  // resetting textarea.value during measurement (which would break
+  // the composition session).
+  const isComposingRef = useRef(false);
+
   const ensureMeasurements = useCallback(() => {
     const textarea = inputRef.current;
-    if (!textarea) {
+    if (!textarea || isComposingRef.current) {
       return;
     }
 

package/src/v2/components/chat/CopilotChatReasoningMessage.tsx

@@ -71,18 +71,31 @@ export function CopilotChatReasoningMessage({
     return () => clearInterval(timer);
   }, [isStreaming]);
 
-  // Default to open while streaming, auto-collapse when streaming ends
+  // Default to open while streaming, auto-collapse when streaming ends.
+  // Track whether the user has manually toggled so auto-collapse doesn't
+  // override their explicit intent (prevents flaky test failures on CI
+  // where async forceUpdate timing can race with click handlers).
   const [isOpen, setIsOpen] = useState(isStreaming);
+  const userToggledRef = useRef(false);
 
   useEffect(() => {
     if (isStreaming) {
+      // Reset user-toggle tracking when a new streaming session starts
+      userToggledRef.current = false;
       setIsOpen(true);
-    } else {
-      // Auto-collapse when reasoning finishes
+    } else if (!userToggledRef.current) {
+      // Auto-collapse only if the user hasn't manually toggled
       setIsOpen(false);
     }
   }, [isStreaming]);
 
+  const handleToggle = hasContent
+    ? () => {
+        userToggledRef.current = true;
+        setIsOpen((prev) => !prev);
+      }
+    : undefined;
+
   const label = isStreaming
     ? "Thinking…"
     : `Thought for ${formatDuration(elapsed)}`;
@@ -92,7 +105,7 @@ export function CopilotChatReasoningMessage({
     label,
     hasContent,
     isStreaming,
-    onClick: hasContent ? () => setIsOpen((prev) => !prev) : undefined,
+    onClick: handleToggle,
   });
 
   const boundContent = renderSlot(

package/src/v2/components/chat/CopilotChatUserMessage.tsx

@@ -18,6 +18,7 @@ import {
   type AudioInputPart,
   type VideoInputPart,
   type DocumentInputPart,
+  copyToClipboard,
 } from "@copilotkit/shared";
 import { CopilotChatAttachmentRenderer } from "./CopilotChatAttachmentRenderer";
 
@@ -147,12 +148,9 @@ export function CopilotChatUserMessage({
     {
       onClick: async () => {
         if (flattenedContent) {
-          try {
-            await navigator.clipboard.writeText(flattenedContent);
-          } catch (err) {
-            console.error("Failed to copy message:", err);
-          }
+          return await copyToClipboard(flattenedContent);
         }
+        return false;
       },
     },
   );
@@ -314,12 +312,17 @@ export namespace CopilotChatUserMessage {
     const labels = config?.labels ?? CopilotChatDefaultLabels;
     const [copied, setCopied] = useState(false);
 
-    const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
-      setCopied(true);
-      setTimeout(() => setCopied(false), 2000);
-
+    const handleClick = async (event: React.MouseEvent<HTMLButtonElement>) => {
+      let success = false;
       if (onClick) {
-        onClick(event);
+        // onClick may return a boolean indicating copy success
+        const result = await Promise.resolve(onClick(event));
+        success = result === true;
+      }
+
+      if (success) {
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
       }
     };