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

package/src/v2/hooks/__tests__/use-agent.e2e.test.tsx

@@ -19,10 +19,21 @@ import { CopilotChat } from "../../components/chat/CopilotChat";
  * Mock agent that captures RunAgentInput to verify state is passed correctly
  */
 class StateCapturingMockAgent extends MockStepwiseAgent {
-  public lastRunInput?: RunAgentInput;
+  // Shared via a container so the clone and original both see the same value
+  private _capture: { lastRunInput?: RunAgentInput } = {};
+
+  get lastRunInput(): RunAgentInput | undefined {
+    return this._capture.lastRunInput;
+  }
+
+  clone(): this {
+    const cloned = super.clone();
+    (cloned as unknown as StateCapturingMockAgent)._capture = this._capture;
+    return cloned;
+  }
 
   run(input: RunAgentInput): Observable<BaseEvent> {
-    this.lastRunInput = input;
+    this._capture.lastRunInput = input;
     return super.run(input);
   }
 }

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-frontend-tool.e2e.test.tsx

@@ -502,13 +502,24 @@ describe("useFrontendTool E2E - Dynamic Registration", () => {
   describe("Agent input plumbing", () => {
     it("forwards registered frontend tools to runAgent input", async () => {
       class InstrumentedMockAgent extends MockStepwiseAgent {
-        public lastRunParameters?: RunAgentParameters;
+        // Shared so the clone and original both see the captured parameters
+        private _capture: { lastRunParameters?: RunAgentParameters } = {};
+
+        get lastRunParameters(): RunAgentParameters | undefined {
+          return this._capture.lastRunParameters;
+        }
+
+        clone(): this {
+          const cloned = super.clone();
+          (cloned as unknown as InstrumentedMockAgent)._capture = this._capture;
+          return cloned;
+        }
 
         async runAgent(
           parameters?: RunAgentParameters,
           subscriber?: AgentSubscriber,
         ) {
-          this.lastRunParameters = parameters;
+          this._capture.lastRunParameters = parameters;
           return super.runAgent(parameters, subscriber);
         }
       }
@@ -568,8 +579,16 @@ describe("useFrontendTool E2E - Dynamic Registration", () => {
       class OneShotToolCallAgent extends AbstractAgent {
         private runCount = 0;
         clone(): OneShotToolCallAgent {
-          // Keep state across runs so the second run emits different args
-          return this;
+          const cloned = new OneShotToolCallAgent();
+          cloned.agentId = this.agentId;
+          // Share runCount via reference so the second run emits different args
+          Object.defineProperty(cloned, "runCount", {
+            get: () => this.runCount,
+            set: (v: number) => {
+              this.runCount = v;
+            },
+          });
+          return cloned;
         }
         async detachActiveRun(): Promise<void> {}
         run(_input: RunAgentInput): Observable<BaseEvent> {

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

@@ -1,7 +1,8 @@
 import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurationProvider";
 import { useMemo, useEffect, useReducer, useRef } from "react";
 import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
-import { AbstractAgent } from "@ag-ui/client";
+import { AbstractAgent, HttpAgent } from "@ag-ui/client";
 import {
   ProxiedCopilotRuntimeAgent,
   CopilotKitCoreRuntimeConnectionStatus,
@@ -21,13 +22,132 @@ const ALL_UPDATES: UseAgentUpdate[] = [
 
 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;
 }
 
-export function useAgent({ agentId, updates }: UseAgentProps = {}) {
+/**
+ * Clone a registry agent for per-thread isolation.
+ * Copies agent configuration (transport, headers, etc.) but resets conversation
+ * state (messages, threadId, state) so each thread starts fresh.
+ */
+function cloneForThread(
+  source: AbstractAgent,
+  threadId: string,
+  headers: Record<string, string>,
+): AbstractAgent {
+  const clone = source.clone();
+  if (clone === source) {
+    throw new Error(
+      `useAgent: ${source.constructor.name}.clone() returned the same instance. ` +
+        `clone() must return a new, independent object.`,
+    );
+  }
+  clone.threadId = threadId;
+  clone.setMessages([]);
+  clone.setState({});
+  if (clone instanceof HttpAgent) {
+    clone.headers = { ...headers };
+  }
+  return clone;
+}
+
+/**
+ * Module-level WeakMap: registryAgent → (threadId → clone).
+ * Shared across all useAgent() calls so that every component using the same
+ * (agentId, threadId) pair receives the same agent instance. Using WeakMap
+ * ensures the clone map is garbage-collected when the registry agent is
+ * replaced (e.g. after reconnect or hot-reload).
+ */
+export const globalThreadCloneMap = new WeakMap<
+  AbstractAgent,
+  Map<string, AbstractAgent>
+>();
+
+/**
+ * Look up an existing per-thread clone without creating one.
+ * Returns undefined when no clone has been created yet for this pair.
+ */
+export function getThreadClone(
+  registryAgent: AbstractAgent | undefined | null,
+  threadId: string | undefined | null,
+): AbstractAgent | undefined {
+  if (!registryAgent || !threadId) return undefined;
+  return globalThreadCloneMap.get(registryAgent)?.get(threadId);
+}
+
+function getOrCreateThreadClone(
+  existing: AbstractAgent,
+  threadId: string,
+  headers: Record<string, string>,
+): AbstractAgent {
+  let byThread = globalThreadCloneMap.get(existing);
+  if (!byThread) {
+    byThread = new Map();
+    globalThreadCloneMap.set(existing, byThread);
+  }
+  const cached = byThread.get(threadId);
+  if (cached) return cached;
+
+  const clone = cloneForThread(existing, threadId, headers);
+  byThread.set(threadId, clone);
+  return clone;
+}
+
+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(
@@ -43,11 +163,29 @@ export function useAgent({ agentId, updates }: UseAgentProps = {}) {
   );
 
   const agent: AbstractAgent = useMemo(() => {
+    // Use a composite key when threadId is provided so that different threads
+    // for the same agent get independent instances.
+    const cacheKey = threadId ? `${agentId}:${threadId}` : agentId;
+
     const existing = copilotkit.getAgent(agentId);
     if (existing) {
-      // Real agent found — clear any cached provisional for this ID
+      // Real agent found — clear any cached provisionals for this key and the
+      // bare agentId key (handles the case where a provisional was created
+      // before threadId was available, then the component re-renders with one).
+      provisionalAgentCache.current.delete(cacheKey);
       provisionalAgentCache.current.delete(agentId);
-      return existing;
+
+      if (!threadId) {
+        // No threadId — return the shared registry agent (original behavior)
+        return existing;
+      }
+
+      // threadId provided — return the shared per-thread clone.
+      // The global WeakMap ensures all components using the same
+      // (registryAgent, threadId) pair receive the same instance, so state
+      // mutations (addMessage, setState) are visible everywhere. The WeakMap
+      // entry is GC-collected automatically when the registry agent is replaced.
+      return getOrCreateThreadClone(existing, threadId, copilotkit.headers);
     }
 
     const isRuntimeConfigured = copilotkit.runtimeUrl !== undefined;
@@ -60,7 +198,7 @@ export function useAgent({ agentId, updates }: UseAgentProps = {}) {
         status === CopilotKitCoreRuntimeConnectionStatus.Connecting)
     ) {
       // Return cached provisional if available (keeps reference stable)
-      const cached = provisionalAgentCache.current.get(agentId);
+      const cached = provisionalAgentCache.current.get(cacheKey);
       if (cached) {
         // Update headers on the cached agent in case they changed
         cached.headers = { ...copilotkit.headers };
@@ -75,7 +213,10 @@ export function useAgent({ agentId, updates }: UseAgentProps = {}) {
       });
       // Apply current headers so runs/connects inherit them
       provisional.headers = { ...copilotkit.headers };
-      provisionalAgentCache.current.set(agentId, provisional);
+      if (threadId) {
+        provisional.threadId = threadId;
+      }
+      provisionalAgentCache.current.set(cacheKey, provisional);
       return provisional;
     }
 
@@ -88,6 +229,14 @@ export function useAgent({ agentId, updates }: UseAgentProps = {}) {
       isRuntimeConfigured &&
       status === CopilotKitCoreRuntimeConnectionStatus.Error
     ) {
+      // Cache the provisional so that dep changes while in Error state (e.g.
+      // headers update) return the same agent reference, matching the
+      // Disconnected/Connecting path and preventing spurious re-subscriptions.
+      const cached = provisionalAgentCache.current.get(cacheKey);
+      if (cached) {
+        cached.headers = { ...copilotkit.headers };
+        return cached;
+      }
       const provisional = new ProxiedCopilotRuntimeAgent({
         runtimeUrl: copilotkit.runtimeUrl,
         agentId,
@@ -95,6 +244,10 @@ export function useAgent({ agentId, updates }: UseAgentProps = {}) {
         runtimeMode: "pending",
       });
       provisional.headers = { ...copilotkit.headers };
+      if (threadId) {
+        provisional.threadId = threadId;
+      }
+      provisionalAgentCache.current.set(cacheKey, provisional);
       return provisional;
     }
 
@@ -113,6 +266,7 @@ export function useAgent({ agentId, updates }: UseAgentProps = {}) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     agentId,
+    threadId,
     copilotkit.agents,
     copilotkit.runtimeConnectionStatus,
     copilotkit.runtimeUrl,
@@ -121,17 +275,52 @@ export function useAgent({ agentId, 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)) {
@@ -145,9 +334,25 @@ export function useAgent({ agentId, 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, effectiveThrottleMs, updateFlags]);
+
+  // Keep HttpAgent headers fresh without mutating inside useMemo, which is
+  // unsafe in concurrent mode (React may invoke useMemo multiple times and
+  // discard intermediate results, but mutations always land).
+  useEffect(() => {
+    if (agent instanceof HttpAgent) {
+      agent.headers = { ...copilotkit.headers };
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [agent, forceUpdate, JSON.stringify(updateFlags)]);
+  }, [agent, JSON.stringify(copilotkit.headers)]);
 
   return {
     agent,