@copilotkit/react-core 1.56.0 → 1.56.2-canary.pin-to-send

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

@@ -2,6 +2,7 @@ import React from "react";
 import { act, renderHook, waitFor } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { useCopilotKit } from "../../providers/CopilotKitProvider";
+import { CopilotKitCoreRuntimeConnectionStatus } from "@copilotkit/core";
 
 vi.mock("../../providers/CopilotKitProvider", () => ({
   useCopilotKit: vi.fn(),
@@ -148,6 +149,7 @@ function setupCopilotKit(runtimeUrl = "http://localhost:4000") {
   mockUseCopilotKit.mockReturnValue({
     copilotkit: {
       runtimeUrl,
+      runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus.Connected,
       headers: { Authorization: "Bearer test-token" },
       intelligence: {
         wsUrl: "ws://localhost:4000/client",
@@ -484,4 +486,70 @@ describe("useThreads", () => {
     expect(channel.left).toBe(true);
     expect(socket.disconnected).toBe(true);
   });
+
+  it("waits for runtimeConnectionStatus=Connected before fetching /threads", async () => {
+    // Start in Connecting — hook should hold off on dispatching any request
+    // so the initial list fetch includes wsUrl and avoids a redundant second
+    // call once /info resolves.
+    mockUseCopilotKit.mockReturnValue({
+      copilotkit: {
+        runtimeUrl: "http://localhost:4000",
+        runtimeConnectionStatus:
+          CopilotKitCoreRuntimeConnectionStatus.Connecting,
+        headers: { Authorization: "Bearer test-token" },
+        intelligence: undefined,
+      },
+    });
+
+    fetchMock
+      .mockReturnValueOnce(
+        jsonResponse({ threads: sampleThreads, joinCode: "jc-1" }),
+      )
+      .mockReturnValueOnce(jsonResponse({ joinToken: "jt-1" }));
+
+    const { result, rerender } = renderHook(() => useThreads(defaultInput));
+
+    // Give effects a tick to settle; no fetch should occur while Connecting.
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // While waiting for Connected, the hook must surface isLoading=true so
+    // consumers don't render an empty-state flash before the first fetch
+    // is even dispatched. The store's own isLoading is false at this
+    // point (no contextChanged action yet), so the hook synthesizes it.
+    expect(result.current.isLoading).toBe(true);
+    expect(result.current.threads).toEqual([]);
+
+    // Flip to Connected with wsUrl populated, re-render. The effect now
+    // dispatches exactly one list fetch (+ one subscribe after it lands).
+    mockUseCopilotKit.mockReturnValue({
+      copilotkit: {
+        runtimeUrl: "http://localhost:4000",
+        runtimeConnectionStatus:
+          CopilotKitCoreRuntimeConnectionStatus.Connected,
+        headers: { Authorization: "Bearer test-token" },
+        intelligence: { wsUrl: "ws://localhost:4000/client" },
+      },
+    });
+
+    rerender();
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledWith(
+        expect.stringContaining("/threads?agentId=agent-1"),
+        expect.objectContaining({ method: "GET" }),
+      );
+    });
+
+    // Exactly the expected pair — no speculative list call before Connected.
+    const listCalls = fetchMock.mock.calls.filter(
+      ([url]) => typeof url === "string" && /\/threads\?agentId=/.test(url),
+    );
+    expect(listCalls).toHaveLength(1);
+
+    // After the fetch settles, isLoading returns to false.
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+  });
 });

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

@@ -6,6 +6,7 @@ import { AbstractAgent, HttpAgent } from "@ag-ui/client";
 import {
   ProxiedCopilotRuntimeAgent,
   CopilotKitCoreRuntimeConnectionStatus,
+  type SubscribeToAgentSubscriber,
 } from "@copilotkit/core";
 
 export enum UseAgentUpdate {
@@ -25,23 +26,26 @@ export interface UseAgentProps {
   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.
+   * Throttle interval (in milliseconds) for re-renders triggered by
+   * `onMessagesChanged` and `onStateChanged` notifications. Useful to reduce
+   * re-render frequency during high-frequency streaming updates.
    *
-   * 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.
+   * Uses a leading+trailing pattern with a shared window — 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. See `CopilotKitCore.subscribeToAgentWithOptions` in `@copilotkit/core`
+   * for details.
    *
-   * 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.
+   * Resolved as: `throttleMs ?? provider defaultThrottleMs ?? 0`.
+   * Passing `throttleMs={0}` explicitly disables throttling even when the
+   * provider specifies a non-zero `defaultThrottleMs`.
    *
-   * Default: `0` (no throttle).
+   * Run lifecycle callbacks (`onRunInitialized`, `onRunFinalized`,
+   * `onRunFailed`, `onRunErrorEvent`) always fire immediately.
+   *
+   * @default undefined
+   * When unset, inherits from the provider's `defaultThrottleMs`;
+   * if that is also unset, the effective value is `0` (no throttle).
    */
   throttleMs?: number;
 }
@@ -123,6 +127,9 @@ export function useAgent({
   agentId ??= DEFAULT_AGENT_ID;
 
   const { copilotkit } = useCopilotKit();
+  // Read the provider-level default so it appears in the effect's dep array.
+  // subscribeToAgentWithOptions reads it from the core instance, but React needs the dep
+  // to know when to re-subscribe.
   const providerThrottleMs = copilotkit.defaultThrottleMs;
   // Fall back to the enclosing CopilotChatConfigurationProvider's threadId so
   // that useAgent() called without explicit threadId (e.g. inside a custom
@@ -131,23 +138,6 @@ export function useAgent({
   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(
@@ -277,9 +267,8 @@ export function useAgent({
   useEffect(() => {
     if (updateFlags.length === 0) return;
 
-    const handlers: Parameters<AbstractAgent["subscribe"]>[0] = {};
-    let timerId: ReturnType<typeof setTimeout> | null = null;
     let active = true;
+    const handlers: SubscribeToAgentSubscriber = {};
 
     // Microtask-batched forceUpdate: coalesces multiple synchronous
     // notifications (e.g. OnStateChanged + OnRunStatusChanged firing in the
@@ -301,45 +290,7 @@ export function useAgent({
     };
 
     if (updateFlags.includes(UseAgentUpdate.OnMessagesChanged)) {
-      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;
-      }
+      handlers.onMessagesChanged = forceUpdate;
     }
 
     if (updateFlags.includes(UseAgentUpdate.OnStateChanged)) {
@@ -350,18 +301,24 @@ export function useAgent({
       handlers.onRunInitialized = batchedForceUpdate;
       handlers.onRunFinalized = batchedForceUpdate;
       handlers.onRunFailed = batchedForceUpdate;
+      // Protocol-level RUN_ERROR event (distinct from onRunFailed which
+      // handles local exceptions like network errors).
+      handlers.onRunErrorEvent = batchedForceUpdate;
     }
 
-    const subscription = agent.subscribe(handlers);
+    const subscription = copilotkit.subscribeToAgentWithOptions(
+      agent,
+      handlers,
+      {
+        throttleMs,
+      },
+    );
     return () => {
       active = false;
-      if (timerId !== null) {
-        clearTimeout(timerId);
-      }
       subscription.unsubscribe();
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [agent, forceUpdate, effectiveThrottleMs, updateFlags]);
+  }, [agent, forceUpdate, throttleMs, providerThrottleMs, 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-pin-to-send.ts

@@ -0,0 +1,94 @@
+import { useContext, useEffect, useRef } from "react";
+import { LastUserMessageContext } from "../components/chat/last-user-message-context";
+
+export type UsePinToSendOptions = {
+  scrollRef: React.RefObject<HTMLElement | null>;
+  contentRef: React.RefObject<HTMLElement | null>;
+  spacerRef: React.RefObject<HTMLElement | null>;
+  topOffset?: number;
+};
+
+export function usePinToSend({
+  scrollRef,
+  contentRef,
+  spacerRef,
+  topOffset = 16,
+}: UsePinToSendOptions): void {
+  const { id, sendNonce } = useContext(LastUserMessageContext);
+  const lastNonceRef = useRef<number>(-1);
+  const currentSpacerHeightRef = useRef<number>(0);
+
+  useEffect(() => {
+    if (sendNonce === lastNonceRef.current) return;
+    lastNonceRef.current = sendNonce;
+
+    if (!id) return;
+    const scrollEl = scrollRef.current;
+    const contentEl = contentRef.current;
+    const spacerEl = spacerRef.current;
+    if (!scrollEl || !contentEl || !spacerEl) return;
+
+    const escaped =
+      typeof CSS !== "undefined" && CSS.escape
+        ? CSS.escape(id)
+        : id.replace(/[!"#$%&'()*+,./:;<=>?@[\\\]^`{|}~]/g, "\\$&");
+    const targetEl = contentEl.querySelector<HTMLElement>(
+      `[data-message-id="${escaped}"]`,
+    );
+    if (!targetEl) return;
+
+    // The target message's element has a top padding (e.g. `pt-10`) that
+    // creates breathing room above the visible bubble. When we "anchor at
+    // the top", we mean anchor the *bubble*, not the element's padded box.
+    // So we scroll past the padding (it goes above the viewport, hiding
+    // whatever was above the element too — including the previous message's
+    // trailing copy button).
+    const viewportHeight = scrollEl.clientHeight;
+    const userMessageHeight = targetEl.getBoundingClientRect().height;
+    const paddingTop = parseFloat(getComputedStyle(targetEl).paddingTop) || 0;
+    const bubbleHeight = Math.max(0, userMessageHeight - paddingTop);
+    const spacerHeight = Math.max(0, viewportHeight - bubbleHeight - topOffset);
+
+    spacerEl.style.height = `${spacerHeight}px`;
+    currentSpacerHeightRef.current = spacerHeight;
+
+    const raf = requestAnimationFrame(() => {
+      // Scroll so the BUBBLE is `topOffset` from the viewport top — the
+      // padding above the bubble ends up scrolled off-screen.
+      const targetTop =
+        computeOffsetTop(targetEl, scrollEl) + paddingTop - topOffset;
+      scrollEl.scrollTo({ top: Math.max(0, targetTop), behavior: "smooth" });
+    });
+
+    // Shrink-only ResizeObserver: as the assistant response grows below the
+    // anchored user message, collapse the spacer by the same amount so total
+    // scrollable space below the bubble stays constant (and the bubble stays
+    // pinned). Never grow the spacer after initial sizing.
+    const ro = new ResizeObserver(() => {
+      if (!contentEl || !spacerEl || !scrollEl) return;
+      const contentHeight = contentEl.getBoundingClientRect().height;
+      const targetOffsetWithinContent = computeOffsetTop(targetEl, contentEl);
+      const consumedBelow =
+        contentHeight - targetOffsetWithinContent - userMessageHeight;
+      const remaining = Math.max(0, spacerHeight - consumedBelow);
+      if (remaining < currentSpacerHeightRef.current) {
+        spacerEl.style.height = `${remaining}px`;
+        currentSpacerHeightRef.current = remaining;
+      }
+    });
+    ro.observe(contentEl);
+
+    return () => {
+      cancelAnimationFrame(raf);
+      ro.disconnect();
+    };
+  }, [id, sendNonce, scrollRef, contentRef, spacerRef, topOffset]);
+}
+
+// Compute the offset of el relative to stopAt, accounting for stopAt's current scrollTop.
+// Uses getBoundingClientRect so it works regardless of CSS positioning (including position:static).
+function computeOffsetTop(el: HTMLElement, stopAt: HTMLElement): number {
+  const elRect = el.getBoundingClientRect();
+  const stopRect = stopAt.getBoundingClientRect();
+  return elRect.top - stopRect.top + stopAt.scrollTop;
+}

package/src/v2/hooks/use-render-custom-messages.tsx

@@ -45,7 +45,7 @@ export function useRenderCustomMessages() {
     const registryAgent = copilotkit.getAgent(agentId);
     const agent = getThreadClone(registryAgent, threadId) ?? registryAgent;
     if (!agent) {
-      throw new Error("Agent not found");
+      return null;
     }
 
     const messagesIdsInRun = resolvedRunId

package/src/v2/hooks/use-render-tool-call.tsx

@@ -47,6 +47,7 @@ const ToolCallRenderer = React.memo(
       return (
         <RenderComponent
           name={toolName}
+          toolCallId={toolCall.id}
           args={args}
           status={ToolCallStatus.Complete}
           result={toolMessage.content}
@@ -56,6 +57,7 @@ const ToolCallRenderer = React.memo(
       return (
         <RenderComponent
           name={toolName}
+          toolCallId={toolCall.id}
           args={args}
           status={ToolCallStatus.Executing}
           result={undefined}
@@ -65,6 +67,7 @@ const ToolCallRenderer = React.memo(
       return (
         <RenderComponent
           name={toolName}
+          toolCallId={toolCall.id}
           args={args}
           status={ToolCallStatus.InProgress}
           result={undefined}

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

@@ -7,6 +7,7 @@ const EMPTY_DEPS: ReadonlyArray<unknown> = [];
 
 export interface RenderToolInProgressProps<S extends StandardSchemaV1> {
   name: string;
+  toolCallId: string;
   parameters: Partial<InferSchemaOutput<S>>;
   status: "inProgress";
   result: undefined;
@@ -14,6 +15,7 @@ export interface RenderToolInProgressProps<S extends StandardSchemaV1> {
 
 export interface RenderToolExecutingProps<S extends StandardSchemaV1> {
   name: string;
+  toolCallId: string;
   parameters: InferSchemaOutput<S>;
   status: "executing";
   result: undefined;
@@ -21,6 +23,7 @@ export interface RenderToolExecutingProps<S extends StandardSchemaV1> {
 
 export interface RenderToolCompleteProps<S extends StandardSchemaV1> {
   name: string;
+  toolCallId: string;
   parameters: InferSchemaOutput<S>;
   status: "complete";
   result: string;

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

@@ -1,5 +1,6 @@
 import { useCopilotKit } from "../providers/CopilotKitProvider";
 import {
+  CopilotKitCoreRuntimeConnectionStatus,
   ɵcreateThreadStore,
   ɵselectThreads,
   ɵselectThreadsError,
@@ -30,6 +31,13 @@ export interface Thread {
   archived: boolean;
   createdAt: string;
   updatedAt: string;
+  /**
+   * ISO-8601 timestamp of the most recent agent run on this thread. Absent
+   * when the thread has never been run. Prefer this over `updatedAt` for
+   * user-facing "last activity" displays — it is not bumped by metadata-only
+   * actions like rename or archive.
+   */
+  lastRunAt?: string;
 }
 
 /**
@@ -179,13 +187,14 @@ export function useThreads({
   const threads: Thread[] = useMemo(
     () =>
       coreThreads.map(
-        ({ id, agentId, name, archived, createdAt, updatedAt }) => ({
+        ({ id, agentId, name, archived, createdAt, updatedAt, lastRunAt }) => ({
           id,
           agentId,
           name,
           archived,
           createdAt,
           updatedAt,
+          ...(lastRunAt !== undefined ? { lastRunAt } : {}),
         }),
       ),
     [coreThreads],
@@ -211,7 +220,18 @@ export function useThreads({
 
     return new Error("Runtime URL is not configured");
   }, [copilotkit.runtimeUrl]);
-  const isLoading = runtimeError ? false : storeIsLoading;
+
+  // Tracks whether we've dispatched the first real context to the store.
+  // The store itself starts with `isLoading: false`, so before we dispatch
+  // consumers would otherwise see an empty, non-loading state (empty-list
+  // flash). While runtimeUrl is set and we haven't dispatched yet, we
+  // synthesize `isLoading: true` so the UI keeps its loading indicator until
+  // the first fetch is in flight (at which point the store's own
+  // isLoading takes over).
+  const [hasDispatchedContext, setHasDispatchedContext] = useState(false);
+  const preConnectLoading = !!copilotkit.runtimeUrl && !hasDispatchedContext;
+
+  const isLoading = runtimeError ? false : preConnectLoading || storeIsLoading;
   const error = runtimeError ?? storeError;
 
   useEffect(() => {
@@ -221,22 +241,45 @@ export function useThreads({
     };
   }, [store]);
 
+  // Defer setting the context until the runtime reports Connected. Before
+  // `/info` resolves we don't know `intelligence.wsUrl`, so dispatching the
+  // context early would issue a list fetch with `wsUrl: undefined`, then a
+  // second list fetch (and a `/threads/subscribe`) once the flag lands.
+  // Waiting lets the hook issue just one `/threads?…` + one `/threads/subscribe`.
+  //
+  // When `runtimeUrl` is absent we dispatch `null` to clear the store. For
+  // transient states (Disconnected/Connecting/Error with a URL still set) we
+  // leave the previously-dispatched context in place — any in-flight
+  // realtime subscription or cached thread list stays usable while the
+  // runtime recovers, and we don't re-trigger a fetch storm on transitions.
+  const runtimeStatus = copilotkit.runtimeConnectionStatus;
   useEffect(() => {
-    const context: ɵThreadRuntimeContext | null = copilotkit.runtimeUrl
-      ? {
-          runtimeUrl: copilotkit.runtimeUrl,
-          headers: { ...copilotkit.headers },
-          wsUrl: copilotkit.intelligence?.wsUrl,
-          agentId,
-          includeArchived,
-          limit,
-        }
-      : null;
+    if (!copilotkit.runtimeUrl) {
+      store.setContext(null);
+      return;
+    }
+
+    // Wait for /info to land so we can include `wsUrl` in the initial
+    // context and avoid a redundant second list fetch.
+    if (runtimeStatus !== CopilotKitCoreRuntimeConnectionStatus.Connected) {
+      return;
+    }
+
+    const context: ɵThreadRuntimeContext = {
+      runtimeUrl: copilotkit.runtimeUrl,
+      headers: { ...copilotkit.headers },
+      wsUrl: copilotkit.intelligence?.wsUrl,
+      agentId,
+      includeArchived,
+      limit,
+    };
 
     store.setContext(context);
+    setHasDispatchedContext(true);
   }, [
     store,
     copilotkit.runtimeUrl,
+    runtimeStatus,
     headersKey,
     copilotkit.intelligence?.wsUrl,
     agentId,

package/src/v2/providers/CopilotKitProvider.tsx

@@ -720,19 +720,10 @@ export const CopilotKitProvider: React.FC<CopilotKitProviderProps> = ({
   }, []);
 
   // Sync defaultThrottleMs to the core instance on prop changes.
-  // Initial value is set synchronously during instance creation (below the
-  // ref init) so child hooks see the correct value on their first render.
+  // Initial value is set synchronously during instance creation (inside the
+  // ref-init block above) so child hooks see the correct value on first render.
   // This effect handles subsequent updates when the prop changes.
   useEffect(() => {
-    if (
-      defaultThrottleMs !== undefined &&
-      (!Number.isFinite(defaultThrottleMs) || defaultThrottleMs < 0)
-    ) {
-      console.error(
-        `CopilotKitProvider: defaultThrottleMs must be a non-negative finite number, got ${defaultThrottleMs}. ` +
-          `useAgent hooks without an explicit throttleMs will fall back to unthrottled.`,
-      );
-    }
     copilotkit.setDefaultThrottleMs(defaultThrottleMs);
   }, [copilotkit, defaultThrottleMs]);
 

package/src/v2/types/defineToolCallRenderer.ts

@@ -14,18 +14,21 @@ import { ToolCallStatus } from "@copilotkit/core";
 type RenderProps<T> =
   | {
       name: string;
+      toolCallId: string;
       args: Partial<T>;
       status: ToolCallStatus.InProgress;
       result: undefined;
     }
   | {
       name: string;
+      toolCallId: string;
       args: T;
       status: ToolCallStatus.Executing;
       result: undefined;
     }
   | {
       name: string;
+      toolCallId: string;
       args: T;
       status: ToolCallStatus.Complete;
       result: string;

package/src/v2/types/react-tool-call-renderer.ts

@@ -12,18 +12,21 @@ export interface ReactToolCallRenderer<T = unknown> {
   render: React.ComponentType<
     | {
         name: string;
+        toolCallId: string;
         args: Partial<T>;
         status: ToolCallStatus.InProgress;
         result: undefined;
       }
     | {
         name: string;
+        toolCallId: string;
         args: T;
         status: ToolCallStatus.Executing;
         result: undefined;
       }
     | {
         name: string;
+        toolCallId: string;
         args: T;
         status: ToolCallStatus.Complete;
         result: string;