@copilotkit/react-core 1.55.0-next.9 → 1.55.0

package/src/v2/hooks/__tests__/use-attachments.test.tsx

@@ -0,0 +1,169 @@
+import React, { useRef, useEffect } from "react";
+import { renderHook, act } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { useAttachments } from "../use-attachments";
+
+describe("useAttachments", () => {
+  // -----------------------------------------------------------------------
+  // Referential stability — callbacks must not change between renders
+  // -----------------------------------------------------------------------
+
+  describe("referential stability", () => {
+    it("all callbacks are stable across re-renders with same config", () => {
+      const config = { enabled: true, accept: "image/*" };
+      const { result, rerender } = renderHook(() => useAttachments({ config }));
+
+      const first = result.current;
+      rerender();
+      const second = result.current;
+
+      expect(second.processFiles).toBe(first.processFiles);
+      expect(second.handleFileUpload).toBe(first.handleFileUpload);
+      expect(second.handleDragOver).toBe(first.handleDragOver);
+      expect(second.handleDragLeave).toBe(first.handleDragLeave);
+      expect(second.handleDrop).toBe(first.handleDrop);
+      expect(second.removeAttachment).toBe(first.removeAttachment);
+      expect(second.consumeAttachments).toBe(first.consumeAttachments);
+    });
+
+    it("callbacks remain stable when config object reference changes", () => {
+      let config = { enabled: true, accept: "image/*" };
+      const { result, rerender } = renderHook(() => useAttachments({ config }));
+
+      const first = result.current;
+
+      // Create a new config with same values — different reference
+      config = { enabled: true, accept: "image/*" };
+      rerender();
+      const second = result.current;
+
+      expect(second.processFiles).toBe(first.processFiles);
+      expect(second.handleFileUpload).toBe(first.handleFileUpload);
+      expect(second.handleDragOver).toBe(first.handleDragOver);
+      expect(second.handleDragLeave).toBe(first.handleDragLeave);
+      expect(second.handleDrop).toBe(first.handleDrop);
+      expect(second.removeAttachment).toBe(first.removeAttachment);
+      expect(second.consumeAttachments).toBe(first.consumeAttachments);
+    });
+
+    it("refs are stable across re-renders", () => {
+      const { result, rerender } = renderHook(() =>
+        useAttachments({ config: undefined }),
+      );
+
+      const first = result.current;
+      rerender();
+      const second = result.current;
+
+      expect(second.fileInputRef).toBe(first.fileInputRef);
+      expect(second.containerRef).toBe(first.containerRef);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Re-render counting — hook should not cause unnecessary renders
+  // -----------------------------------------------------------------------
+
+  describe("re-render counting", () => {
+    it("does not re-render when consumeAttachments is called on empty queue", () => {
+      let renderCount = 0;
+
+      const { result } = renderHook(() => {
+        renderCount++;
+        return useAttachments({ config: undefined });
+      });
+
+      const initialRenderCount = renderCount;
+
+      act(() => {
+        result.current.consumeAttachments();
+      });
+
+      // consumeAttachments on empty queue should not trigger a state update
+      expect(renderCount).toBe(initialRenderCount);
+    });
+
+    it("does not re-render on repeated consumeAttachments with empty queue", () => {
+      let renderCount = 0;
+
+      const { result } = renderHook(() => {
+        renderCount++;
+        return useAttachments({ config: undefined });
+      });
+
+      const initialRenderCount = renderCount;
+
+      act(() => {
+        result.current.consumeAttachments();
+        result.current.consumeAttachments();
+        result.current.consumeAttachments();
+      });
+
+      expect(renderCount).toBe(initialRenderCount);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // State defaults
+  // -----------------------------------------------------------------------
+
+  describe("initial state", () => {
+    it("returns empty attachments and disabled by default", () => {
+      const { result } = renderHook(() =>
+        useAttachments({ config: undefined }),
+      );
+
+      expect(result.current.attachments).toEqual([]);
+      expect(result.current.enabled).toBe(false);
+      expect(result.current.dragOver).toBe(false);
+    });
+
+    it("returns enabled when config.enabled is true", () => {
+      const { result } = renderHook(() =>
+        useAttachments({ config: { enabled: true } }),
+      );
+
+      expect(result.current.enabled).toBe(true);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // consumeAttachments behavior
+  // -----------------------------------------------------------------------
+
+  describe("consumeAttachments", () => {
+    it("returns empty array when no attachments", () => {
+      const { result } = renderHook(() =>
+        useAttachments({ config: undefined }),
+      );
+
+      let consumed: any[];
+      act(() => {
+        consumed = result.current.consumeAttachments();
+      });
+
+      expect(consumed!).toEqual([]);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // removeAttachment
+  // -----------------------------------------------------------------------
+
+  describe("removeAttachment", () => {
+    it("is a no-op when id does not exist", () => {
+      const { result } = renderHook(() =>
+        useAttachments({ config: undefined }),
+      );
+
+      const before = result.current.attachments;
+
+      act(() => {
+        result.current.removeAttachment("nonexistent");
+      });
+
+      // Should still be empty, no crash
+      expect(result.current.attachments).toEqual([]);
+    });
+  });
+});

package/src/v2/hooks/__tests__/use-threads.test.tsx

@@ -383,6 +383,60 @@ describe("useThreads", () => {
     });
   });
 
+  it("exposes thread-scoped pagination properties", async () => {
+    fetchMock
+      .mockReturnValueOnce(
+        jsonResponse({
+          threads: sampleThreads,
+          joinCode: "jc-1",
+          nextCursor: "cursor-abc",
+        }),
+      )
+      .mockReturnValueOnce(jsonResponse({ joinToken: "jt-1" }));
+
+    const { result } = renderHook(() => useThreads(defaultInput));
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current).toHaveProperty("hasMoreThreads");
+    expect(result.current).toHaveProperty("isFetchingMoreThreads");
+    expect(result.current).toHaveProperty("fetchMoreThreads");
+    expect(result.current).not.toHaveProperty("hasNextPage");
+    expect(result.current).not.toHaveProperty("isFetchingNextPage");
+    expect(result.current).not.toHaveProperty("fetchNextPage");
+
+    expect(result.current.hasMoreThreads).toBe(true);
+    expect(result.current.isFetchingMoreThreads).toBe(false);
+    expect(typeof result.current.fetchMoreThreads).toBe("function");
+  });
+
+  it("does not expose organizationId or createdById on threads", async () => {
+    fetchMock
+      .mockReturnValueOnce(
+        jsonResponse({ threads: sampleThreads, joinCode: "jc-1" }),
+      )
+      .mockReturnValueOnce(jsonResponse({ joinToken: "jt-1" }));
+
+    const { result } = renderHook(() => useThreads(defaultInput));
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    for (const thread of result.current.threads) {
+      expect(thread).not.toHaveProperty("organizationId");
+      expect(thread).not.toHaveProperty("createdById");
+      expect(thread).toHaveProperty("id");
+      expect(thread).toHaveProperty("agentId");
+      expect(thread).toHaveProperty("name");
+      expect(thread).toHaveProperty("archived");
+      expect(thread).toHaveProperty("createdAt");
+      expect(thread).toHaveProperty("updatedAt");
+    }
+  });
+
   it("tears down sockets after repeated connection failures", async () => {
     fetchMock
       .mockReturnValueOnce(

package/src/v2/hooks/index.ts

@@ -16,3 +16,8 @@ export { useInterrupt } from "./use-interrupt";
 export type { UseInterruptConfig } from "./use-interrupt";
 export { useThreads } from "./use-threads";
 export type { Thread, UseThreadsInput, UseThreadsResult } from "./use-threads";
+export { useAttachments } from "./use-attachments";
+export type {
+  UseAttachmentsProps,
+  UseAttachmentsReturn,
+} from "./use-attachments";

package/src/v2/hooks/use-agent.tsx

@@ -24,6 +24,26 @@ export interface UseAgentProps {
   agentId?: string;
   threadId?: string;
   updates?: UseAgentUpdate[];
+  /**
+   * Throttle interval (in milliseconds) for React re-renders triggered by
+   * `OnMessagesChanged` notifications. Useful to reduce re-render frequency
+   * during high-frequency message updates such as streaming.
+   *
+   * Uses leading+trailing: first update fires immediately, subsequent updates
+   * within the window are coalesced, and a trailing timer ensures the most
+   * recent update fires after the window expires. The trailing edge restarts
+   * the throttle window, so no two renders occur within `throttleMs` of each
+   * other. Cleanup on unmount cancels any pending trailing timer.
+   *
+   * Must be a non-negative finite number. Negative or non-finite values fall
+   * back to unthrottled behavior with a `console.error`. Only affects
+   * `OnMessagesChanged` updates — `OnStateChanged` and `OnRunStatusChanged`
+   * always fire immediately. If `updates` does not include
+   * `OnMessagesChanged`, this property has no effect.
+   *
+   * Default: `0` (no throttle).
+   */
+  throttleMs?: number;
 }
 
 /**
@@ -94,16 +114,40 @@ function getOrCreateThreadClone(
   return clone;
 }
 
-export function useAgent({ agentId, threadId, updates }: UseAgentProps = {}) {
+export function useAgent({
+  agentId,
+  threadId,
+  updates,
+  throttleMs,
+}: UseAgentProps = {}) {
   agentId ??= DEFAULT_AGENT_ID;
 
   const { copilotkit } = useCopilotKit();
+  const providerThrottleMs = copilotkit.defaultThrottleMs;
   // Fall back to the enclosing CopilotChatConfigurationProvider's threadId so
   // that useAgent() called without explicit threadId (e.g. inside a custom
   // message renderer) automatically uses the same per-thread clone as the
   // CopilotChat component it lives within.
   const chatConfig = useCopilotChatConfiguration();
   threadId ??= chatConfig?.threadId;
+
+  const effectiveThrottleMs = useMemo(() => {
+    const resolved = throttleMs ?? providerThrottleMs ?? 0;
+    if (!Number.isFinite(resolved) || resolved < 0) {
+      // When both throttleMs and providerThrottleMs are undefined, resolved
+      // is 0 which passes validation — so one of them must be defined here.
+      const source =
+        throttleMs !== undefined
+          ? "hook-level throttleMs"
+          : "provider-level defaultThrottleMs";
+      console.error(
+        `useAgent: ${source} must be a non-negative finite number, got ${resolved}. Falling back to unthrottled.`,
+      );
+      return 0;
+    }
+    return resolved;
+  }, [throttleMs, providerThrottleMs]);
+
   const [, forceUpdate] = useReducer((x) => x + 1, 0);
 
   const updateFlags = useMemo(
@@ -231,17 +275,52 @@ export function useAgent({ agentId, threadId, updates }: UseAgentProps = {}) {
   ]);
 
   useEffect(() => {
-    if (updateFlags.length === 0) {
-      return;
-    }
+    if (updateFlags.length === 0) return;
 
     const handlers: Parameters<AbstractAgent["subscribe"]>[0] = {};
+    let timerId: ReturnType<typeof setTimeout> | null = null;
+    let active = true;
 
     if (updateFlags.includes(UseAgentUpdate.OnMessagesChanged)) {
-      // Content stripping for immutableContent renderers is handled by CopilotKitCoreReact
-      handlers.onMessagesChanged = () => {
-        forceUpdate();
-      };
+      const ms = effectiveThrottleMs;
+      if (ms > 0) {
+        // Throttled onMessagesChanged: leading+trailing pattern.
+        // First notification fires immediately, subsequent ones within the
+        // window are coalesced. Trailing timer fires after the window to
+        // ensure the final state is rendered.
+        let throttleActive = false;
+        // Tracks whether a notification arrived during the throttle window,
+        // so the trailing timer knows whether a re-render is needed.
+        let pending = false;
+
+        const throttledNotify = () => {
+          if (!active) return;
+          if (!throttleActive) {
+            // Leading edge — fire immediately and start the throttle window
+            throttleActive = true;
+            pending = false;
+            forceUpdate();
+            timerId = setTimeout(function trailingEdge() {
+              timerId = null;
+              if (active && pending) {
+                // Trailing edge — fire and restart the window
+                pending = false;
+                forceUpdate();
+                timerId = setTimeout(trailingEdge, ms);
+              } else {
+                // No pending notifications — end the window
+                throttleActive = false;
+              }
+            }, ms);
+          } else {
+            pending = true;
+          }
+        };
+
+        handlers.onMessagesChanged = throttledNotify;
+      } else {
+        handlers.onMessagesChanged = forceUpdate;
+      }
     }
 
     if (updateFlags.includes(UseAgentUpdate.OnStateChanged)) {
@@ -255,9 +334,15 @@ export function useAgent({ agentId, threadId, updates }: UseAgentProps = {}) {
     }
 
     const subscription = agent.subscribe(handlers);
-    return () => subscription.unsubscribe();
+    return () => {
+      active = false;
+      if (timerId !== null) {
+        clearTimeout(timerId);
+      }
+      subscription.unsubscribe();
+    };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [agent, forceUpdate, JSON.stringify(updateFlags)]);
+  }, [agent, forceUpdate, effectiveThrottleMs, updateFlags]);
 
   // Keep HttpAgent headers fresh without mutating inside useMemo, which is
   // unsafe in concurrent mode (React may invoke useMemo multiple times and

package/src/v2/hooks/use-attachments.tsx

@@ -0,0 +1,269 @@
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import {
+  randomUUID,
+  getModalityFromMimeType,
+  exceedsMaxSize,
+  readFileAsBase64,
+  generateVideoThumbnail,
+  matchesAcceptFilter,
+  formatFileSize,
+} from "@copilotkit/shared";
+import type { Attachment, AttachmentsConfig } from "@copilotkit/shared";
+
+export interface UseAttachmentsProps {
+  config?: AttachmentsConfig;
+}
+
+export interface UseAttachmentsReturn {
+  /** Currently selected attachments (uploading + ready). */
+  attachments: Attachment[];
+  /** Whether attachments are enabled. */
+  enabled: boolean;
+  /** Whether the user is dragging a file over the drop zone. */
+  dragOver: boolean;
+  /** Ref for the hidden file input element. */
+  fileInputRef: React.RefObject<HTMLInputElement | null>;
+  /** Ref for the container element (used for scoped paste handling). */
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  /** Process an array of files (validate, upload, add to state). */
+  processFiles: (files: File[]) => Promise<void>;
+  /** Handler for `<input type="file" onChange>`. */
+  handleFileUpload: (e: React.ChangeEvent<HTMLInputElement>) => Promise<void>;
+  /** Handler for `onDragOver` on the drop zone. */
+  handleDragOver: (e: React.DragEvent) => void;
+  /** Handler for `onDragLeave` on the drop zone. */
+  handleDragLeave: (e: React.DragEvent) => void;
+  /** Handler for `onDrop` on the drop zone. */
+  handleDrop: (e: React.DragEvent) => Promise<void>;
+  /** Remove an attachment by ID. */
+  removeAttachment: (id: string) => void;
+  /**
+   * Consume ready attachments and clear the queue.
+   * Returns the attachments that were ready; resets the file input.
+   * No-ops if the queue is already empty (no state update triggered).
+   */
+  consumeAttachments: () => Attachment[];
+}
+
+/**
+ * Hook that manages file attachment state — uploads, drag-and-drop, paste,
+ * and lifecycle. All returned callbacks are referentially stable across
+ * renders (via useCallback) to avoid destabilizing downstream memoization.
+ */
+export function useAttachments({
+  config,
+}: UseAttachmentsProps): UseAttachmentsReturn {
+  const enabled = config?.enabled ?? false;
+
+  const [attachments, setAttachments] = useState<Attachment[]>([]);
+  const [dragOver, setDragOver] = useState(false);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Keep refs to the latest values so stable callbacks can read current
+  // state without appearing in dependency arrays.
+  const configRef = useRef(config);
+  configRef.current = config;
+  const attachmentsRef = useRef<Attachment[]>([]);
+  attachmentsRef.current = attachments;
+
+  // Stable processFiles — reads config from ref, never changes identity
+  const processFiles = useCallback(async (files: File[]) => {
+    const cfg = configRef.current;
+    const accept = cfg?.accept ?? "*/*";
+    const maxSize = cfg?.maxSize ?? 20 * 1024 * 1024;
+
+    const rejectedFiles = files.filter(
+      (file) => !matchesAcceptFilter(file, accept),
+    );
+    for (const file of rejectedFiles) {
+      cfg?.onUploadFailed?.({
+        reason: "invalid-type",
+        file,
+        message: `File "${file.name}" is not accepted. Supported types: ${accept}`,
+      });
+    }
+
+    const validFiles = files.filter((file) =>
+      matchesAcceptFilter(file, accept),
+    );
+
+    for (const file of validFiles) {
+      if (exceedsMaxSize(file, maxSize)) {
+        cfg?.onUploadFailed?.({
+          reason: "file-too-large",
+          file,
+          message: `File "${file.name}" exceeds the maximum size of ${formatFileSize(maxSize)}`,
+        });
+        continue;
+      }
+
+      const modality = getModalityFromMimeType(file.type);
+      const placeholderId = randomUUID();
+      const placeholder: Attachment = {
+        id: placeholderId,
+        type: modality,
+        source: { type: "data", value: "", mimeType: file.type },
+        filename: file.name,
+        size: file.size,
+        status: "uploading",
+      };
+
+      setAttachments((prev) => [...prev, placeholder]);
+
+      try {
+        let source: Attachment["source"];
+        let uploadMetadata: Record<string, unknown> | undefined;
+
+        if (cfg?.onUpload) {
+          const { metadata: meta, ...uploadSource } = await cfg.onUpload(file);
+          source = uploadSource;
+          uploadMetadata = meta;
+        } else {
+          const base64 = await readFileAsBase64(file);
+          source = { type: "data", value: base64, mimeType: file.type };
+        }
+
+        let thumbnail: string | undefined;
+        if (modality === "video") {
+          thumbnail = await generateVideoThumbnail(file);
+        }
+
+        setAttachments((prev) =>
+          prev.map((att) =>
+            att.id === placeholderId
+              ? {
+                  ...att,
+                  source,
+                  status: "ready" as const,
+                  thumbnail,
+                  metadata: uploadMetadata,
+                }
+              : att,
+          ),
+        );
+      } catch (error) {
+        setAttachments((prev) =>
+          prev.filter((att) => att.id !== placeholderId),
+        );
+        console.error(`[CopilotKit] Failed to upload "${file.name}":`, error);
+        cfg?.onUploadFailed?.({
+          reason: "upload-failed",
+          file,
+          message:
+            error instanceof Error
+              ? error.message
+              : `Failed to upload "${file.name}"`,
+        });
+      }
+    }
+  }, []);
+
+  const handleFileUpload = useCallback(
+    async (e: React.ChangeEvent<HTMLInputElement>) => {
+      if (!e.target.files?.length) return;
+      try {
+        await processFiles(Array.from(e.target.files));
+      } catch (error) {
+        console.error("[CopilotKit] Upload error:", error);
+      }
+    },
+    [processFiles],
+  );
+
+  const handleDragOver = useCallback((e: React.DragEvent) => {
+    if (!configRef.current?.enabled) return;
+    e.preventDefault();
+    e.stopPropagation();
+    setDragOver(true);
+  }, []);
+
+  const handleDragLeave = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setDragOver(false);
+  }, []);
+
+  const handleDrop = useCallback(
+    async (e: React.DragEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      setDragOver(false);
+      if (!configRef.current?.enabled) return;
+
+      const files = Array.from(e.dataTransfer.files);
+      if (files.length > 0) {
+        try {
+          await processFiles(files);
+        } catch (error) {
+          console.error("[CopilotKit] Drop error:", error);
+        }
+      }
+    },
+    [processFiles],
+  );
+
+  // Clipboard paste handler — scoped to the container
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handlePaste = async (e: ClipboardEvent) => {
+      const target = e.target as HTMLElement | null;
+      if (!target || !containerRef.current?.contains(target)) return;
+
+      const accept = configRef.current?.accept ?? "*/*";
+      const items = Array.from(e.clipboardData?.items || []);
+      const fileItems = items.filter(
+        (item) =>
+          item.kind === "file" &&
+          item.getAsFile() !== null &&
+          matchesAcceptFilter(item.getAsFile()!, accept),
+      );
+
+      if (fileItems.length === 0) return;
+      e.preventDefault();
+
+      const files = fileItems
+        .map((item) => item.getAsFile())
+        .filter((f): f is File => f !== null);
+
+      try {
+        await processFiles(files);
+      } catch (error) {
+        console.error("[CopilotKit] Paste error:", error);
+      }
+    };
+
+    document.addEventListener("paste", handlePaste);
+    return () => document.removeEventListener("paste", handlePaste);
+  }, [enabled, processFiles]);
+
+  const removeAttachment = useCallback((id: string) => {
+    setAttachments((prev) => prev.filter((a) => a.id !== id));
+  }, []);
+
+  const consumeAttachments = useCallback(() => {
+    const ready = attachmentsRef.current.filter((a) => a.status === "ready");
+    if (ready.length === 0) return ready;
+    setAttachments((prev) => prev.filter((a) => a.status !== "ready"));
+    if (fileInputRef.current) {
+      fileInputRef.current.value = "";
+    }
+    return ready;
+  }, []);
+
+  return {
+    attachments,
+    enabled,
+    dragOver,
+    fileInputRef,
+    containerRef,
+    processFiles,
+    handleFileUpload,
+    handleDragOver,
+    handleDragLeave,
+    handleDrop,
+    removeAttachment,
+    consumeAttachments,
+  };
+}

package/src/v2/hooks/use-frontend-tool.tsx

@@ -22,8 +22,11 @@ export function useFrontendTool<
     }
     copilotkit.addTool(tool);
 
-    // Register/override renderer by name and agentId through core
-    if (tool.render && tool.parameters) {
+    // Register/override renderer by name and agentId through core.
+    // The render function is registered even when tool.parameters is
+    // undefined — tools like HITL confirm dialogs have no parameters
+    // but still need their UI rendered in the chat.
+    if (tool.render) {
       copilotkit.addHookRenderToolCall({
         name,
         args: tool.parameters,