@copilotkit/react-core 1.10.6 → 1.50.0-beta.0

package/src/context/coagent-state-renders-context.tsx

@@ -0,0 +1,76 @@
+import React, {
+  createContext,
+  useContext,
+  useCallback,
+  useState,
+  useRef,
+  ReactNode,
+  RefObject,
+} from "react";
+import { CoAgentStateRender } from "../types/coagent-action";
+
+interface StateRenderClaim {
+  stateRenderId: string;
+  stateSnapshot?: any;
+  runId?: string;
+  locked?: boolean;
+}
+
+type ClaimsRef = Record<string, StateRenderClaim>;
+
+export interface CoAgentStateRendersContextValue {
+  coAgentStateRenders: Record<string, CoAgentStateRender<any>>;
+  setCoAgentStateRender: (id: string, stateRender: CoAgentStateRender<any>) => void;
+  removeCoAgentStateRender: (id: string) => void;
+  claimsRef: RefObject<ClaimsRef>;
+}
+
+const CoAgentStateRendersContext = createContext<CoAgentStateRendersContextValue | undefined>(
+  undefined,
+);
+
+export function CoAgentStateRendersProvider({ children }: { children: ReactNode }) {
+  const [coAgentStateRenders, setCoAgentStateRenders] = useState<
+    Record<string, CoAgentStateRender<any>>
+  >({});
+
+  const setCoAgentStateRender = useCallback((id: string, stateRender: CoAgentStateRender<any>) => {
+    setCoAgentStateRenders((prevPoints) => ({
+      ...prevPoints,
+      [id]: stateRender,
+    }));
+  }, []);
+
+  const removeCoAgentStateRender = useCallback((id: string) => {
+    setCoAgentStateRenders((prevPoints) => {
+      const newPoints = { ...prevPoints };
+      delete newPoints[id];
+      return newPoints;
+    });
+  }, []);
+
+  const claimsRef = useRef<ClaimsRef>({});
+
+  return (
+    <CoAgentStateRendersContext.Provider
+      value={{
+        coAgentStateRenders,
+        setCoAgentStateRender,
+        removeCoAgentStateRender,
+        claimsRef,
+      }}
+    >
+      {children}
+    </CoAgentStateRendersContext.Provider>
+  );
+}
+
+export function useCoAgentStateRenders() {
+  const context = useContext(CoAgentStateRendersContext);
+  if (!context) {
+    throw new Error("useCoAgentStateRenders must be used within CoAgentStateRendersProvider");
+  }
+  return context;
+}
+
+export { CoAgentStateRendersContext };

package/src/context/copilot-context.tsx

@@ -22,10 +22,10 @@ import {
 } from "@copilotkit/runtime-client-gql";
 import { Agent } from "@copilotkit/runtime-client-gql";
 import {
-  LangGraphInterruptAction,
+  LangGraphInterruptRender,
   LangGraphInterruptActionSetter,
+  QueuedInterruptEvent,
 } from "../types/interrupt-action";
-import { SuggestionItem } from "../utils/suggestions";
 
 /**
  * Interface for the configuration of the Copilot API.
@@ -95,10 +95,10 @@ export interface CopilotApiConfig {
 }
 
 export type InChatRenderFunction<TProps = ActionRenderProps<any> | CatchAllActionRenderProps<any>> =
-  (props: TProps) => string | JSX.Element;
+  (props: TProps) => string | React.JSX.Element;
 export type CoagentInChatRenderFunction = (
   props: CoAgentStateRenderProps<any>,
-) => string | JSX.Element | undefined | null;
+) => string | React.JSX.Element | undefined | null;
 
 export interface ChatComponentsCache {
   actions: Record<string, InChatRenderFunction | string>;
@@ -127,10 +127,9 @@ export interface CopilotContextParams {
   setAction: (id: string, action: FrontendAction<any>) => void;
   removeAction: (id: string) => void;
 
-  // coagent actions
-  coAgentStateRenders: Record<string, CoAgentStateRender<any>>;
-  setCoAgentStateRender: (id: string, stateRender: CoAgentStateRender<any>) => void;
-  removeCoAgentStateRender: (id: string) => void;
+  // registered actions for component-based rendering
+  setRegisteredActions: (actionConfig: any) => string;
+  removeRegisteredAction: (actionKey: string) => void;
 
   chatComponentsCache: React.RefObject<ChatComponentsCache>;
 
@@ -195,9 +194,6 @@ export interface CopilotContextParams {
   // i.e. when using `stop()` from `useChat`
   chatAbortControllerRef: React.MutableRefObject<AbortController | null>;
 
-  // runtime
-  runtimeClient: CopilotRuntimeClient;
-
   /**
    * The forwarded parameters to use for the task.
    */
@@ -221,9 +217,12 @@ export interface CopilotContextParams {
 
   extensions: ExtensionsInput;
   setExtensions: React.Dispatch<React.SetStateAction<ExtensionsInput>>;
-  langGraphInterruptAction: LangGraphInterruptAction | null;
-  setLangGraphInterruptAction: LangGraphInterruptActionSetter;
-  removeLangGraphInterruptAction: (threadId: string) => void;
+  interruptActions: Record<string, LangGraphInterruptRender>;
+  setInterruptAction: LangGraphInterruptActionSetter;
+  removeInterruptAction: (actionId: string) => void;
+  interruptEventQueue: Record<string, QueuedInterruptEvent[]>;
+  addInterruptEvent: (queuedEvent: QueuedInterruptEvent) => void;
+  removeInterruptEvent: (threadId: string, eventId: string) => void;
 
   /**
    * Optional trace handler for comprehensive debugging and observability.
@@ -246,9 +245,8 @@ const emptyCopilotContext: CopilotContextParams = {
   setAction: () => {},
   removeAction: () => {},
 
-  coAgentStateRenders: {},
-  setCoAgentStateRender: () => {},
-  removeCoAgentStateRender: () => {},
+  setRegisteredActions: () => "",
+  removeRegisteredAction: () => {},
 
   chatComponentsCache: { current: { actions: {}, coAgentStateRenders: {} } },
   getContextString: (documents: DocumentPointer[], categories: string[]) =>
@@ -271,7 +269,6 @@ const emptyCopilotContext: CopilotContextParams = {
   getDocumentsContext: (categories: string[]) => returnAndThrowInDebug([]),
   addDocumentContext: () => returnAndThrowInDebug(""),
   removeDocumentContext: () => {},
-  runtimeClient: {} as any,
 
   copilotApiConfig: new (class implements CopilotApiConfig {
     get chatApiEndpoint(): string {
@@ -306,9 +303,12 @@ const emptyCopilotContext: CopilotContextParams = {
   availableAgents: [],
   extensions: {},
   setExtensions: () => {},
-  langGraphInterruptAction: null,
-  setLangGraphInterruptAction: () => {},
-  removeLangGraphInterruptAction: () => {},
+  interruptActions: {},
+  setInterruptAction: () => {},
+  removeInterruptAction: () => {},
+  interruptEventQueue: {},
+  addInterruptEvent: () => {},
+  removeInterruptEvent: () => {},
   onError: () => {},
   bannerError: null,
   setBannerError: () => {},

package/src/context/copilot-messages-context.tsx

@@ -4,13 +4,13 @@
 
 import { Message } from "@copilotkit/runtime-client-gql";
 import React from "react";
-import { SuggestionItem } from "../utils/suggestions";
+import { Suggestion } from "@copilotkitnext/core";
 
 export interface CopilotMessagesContextParams {
   messages: Message[];
   setMessages: React.Dispatch<React.SetStateAction<Message[]>>; // suggestions state
-  suggestions: SuggestionItem[];
-  setSuggestions: React.Dispatch<React.SetStateAction<SuggestionItem[]>>;
+  suggestions: Suggestion[];
+  setSuggestions: React.Dispatch<React.SetStateAction<Suggestion[]>>;
 }
 
 const emptyCopilotContext: CopilotMessagesContextParams = {

package/src/context/index.ts

@@ -1,8 +1,16 @@
 export { CopilotContext, useCopilotContext } from "./copilot-context";
 export { CopilotMessagesContext, useCopilotMessagesContext } from "./copilot-messages-context";
+export {
+  CoAgentStateRendersContext,
+  CoAgentStateRendersProvider,
+  useCoAgentStateRenders,
+} from "./coagent-state-renders-context";
+export { ThreadsContext, ThreadsProvider, useThreads } from "./threads-context";
 export type {
   CopilotContextParams,
   CoagentInChatRenderFunction,
   CopilotApiConfig,
 } from "./copilot-context";
 export type { CopilotMessagesContextParams } from "./copilot-messages-context";
+export type { CoAgentStateRendersContextValue } from "./coagent-state-renders-context";
+export type { ThreadsContextValue, ThreadsProviderProps } from "./threads-context";

package/src/context/threads-context.tsx

@@ -0,0 +1,41 @@
+import React, { createContext, useContext, useState, ReactNode, SetStateAction } from "react";
+import { randomUUID } from "@copilotkit/shared";
+
+export interface ThreadsContextValue {
+  threadId: string;
+  setThreadId: (value: SetStateAction<string>) => void;
+}
+
+const ThreadsContext = createContext<ThreadsContextValue | undefined>(undefined);
+
+export interface ThreadsProviderProps {
+  children: ReactNode;
+  threadId?: string;
+}
+
+export function ThreadsProvider({ children, threadId: explicitThreadId }: ThreadsProviderProps) {
+  const [internalThreadId, setThreadId] = useState<string>(explicitThreadId ?? randomUUID());
+
+  const threadId = internalThreadId;
+
+  return (
+    <ThreadsContext.Provider
+      value={{
+        threadId,
+        setThreadId,
+      }}
+    >
+      {children}
+    </ThreadsContext.Provider>
+  );
+}
+
+export function useThreads() {
+  const context = useContext(ThreadsContext);
+  if (!context) {
+    throw new Error("useThreads must be used within ThreadsProvider");
+  }
+  return context;
+}
+
+export { ThreadsContext };

package/src/hooks/index.ts

@@ -6,13 +6,12 @@ export {
   type UseCopilotChatOptions_c,
   useCopilotChatHeadless_c,
 } from "./use-copilot-chat-headless_c";
-export { useCopilotChat as useCopilotChatInternal } from "./use-copilot-chat_internal";
+export { useCopilotChatInternal, type ChatSuggestions } from "./use-copilot-chat_internal";
 export { useCopilotAction } from "./use-copilot-action";
 export { useCoAgentStateRender } from "./use-coagent-state-render";
 export { useMakeCopilotDocumentReadable } from "./use-make-copilot-document-readable";
-export { type UseChatHelpers } from "./use-chat";
 export { useCopilotReadable } from "./use-copilot-readable";
-export { useCoAgent, type HintFunction, runAgent, startAgent, stopAgent } from "./use-coagent";
+export { useCoAgent, type HintFunction } from "./use-coagent";
 export { useCopilotRuntimeClient } from "./use-copilot-runtime-client";
 export { useCopilotAuthenticatedAction_c } from "./use-copilot-authenticated-action";
 export { useLangGraphInterrupt } from "./use-langgraph-interrupt";
@@ -23,3 +22,8 @@ export { useFrontendTool } from "./use-frontend-tool";
 export { useHumanInTheLoop } from "./use-human-in-the-loop";
 export { useRenderToolCall } from "./use-render-tool-call";
 export { useDefaultTool } from "./use-default-tool";
+export { useLazyToolRenderer } from "./use-lazy-tool-renderer";
+export {
+  useConfigureChatSuggestions,
+  type UseCopilotChatSuggestionsConfiguration,
+} from "./use-configure-chat-suggestions";

package/src/hooks/use-coagent-state-render-bridge.tsx

@@ -0,0 +1,293 @@
+import { ReactCustomMessageRendererPosition, useAgent } from "@copilotkitnext/react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type { AgentSubscriber } from "@ag-ui/client";
+import { useCoAgentStateRenders } from "../context";
+import { dataToUUID, parseJson } from "@copilotkit/shared";
+
+function getStateWithoutConstantKeys(state: any) {
+  const { messages, tools, copilotkit, ...stateWithoutConstantKeys } = state;
+  return stateWithoutConstantKeys;
+}
+
+// Function that compares states, without the constant keys
+function areStatesEquals(a: any, b: any) {
+  if ((a && !b) || (!a && b)) return false;
+  const { messages, tools, copilotkit, ...aWithoutConstantKeys } = a;
+  const {
+    messages: bMessages,
+    tools: bTools,
+    copilotkit: bCopilotkit,
+    ...bWithoutConstantKeys
+  } = b;
+
+  return JSON.stringify(aWithoutConstantKeys) === JSON.stringify(bWithoutConstantKeys);
+}
+
+/**
+ * Bridge hook that connects agent state renders to chat messages.
+ *
+ * ## Purpose
+ * This hook finds matching state render configurations (registered via useCoAgentStateRender)
+ * and returns UI to render in chat.
+ * It ensures each state render appears bound to a specific message, preventing duplicates while
+ * allowing re-binding when the underlying state changes significantly.
+ *
+ * ## Message-ID-Based Claiming System
+ *
+ * ### The Problem
+ * Multiple bridge component instances render simultaneously (one per message). Without coordination,
+ * they would all try to render the same state render, causing duplicates.
+ *
+ * ### The Solution: Message-ID Claims with State Comparison
+ * Each state render is "claimed" by exactly one **message ID** (not runId):
+ *
+ * **Claim Structure**: `claimsRef.current[messageId] = { stateRenderId, runId, stateSnapshot, locked }`
+ *
+ * **Primary binding is by messageId because**:
+ * - runId is not always available immediately (starts as "pending")
+ * - messageId is the stable identifier throughout the message lifecycle
+ * - Claims persist across component remounts via context ref
+ *
+ * ### Claiming Logic Flow
+ *
+ * 1. **Message already has a claim**:
+ *    - Check if the claim matches the current stateRenderId
+ *    - If yes → render (this message owns this render)
+ *    - Update runId if it was "pending" and now available
+ *
+ * 2. **State render claimed by another message**:
+ *    - Compare state snapshots (ignoring constant keys: messages, tools, copilotkit)
+ *    - If states are identical → block rendering (duplicate)
+ *    - **If states are different → allow claiming** (new data, new message)
+ *    - This handles cases where the same render type shows different states in different messages
+ *
+ * 3. **Unclaimed state render**:
+ *    - Only allow claiming if runId is "pending" (initial render)
+ *    - If runId is real but no claim exists → block (edge case protection)
+ *    - Create new claim: `claimsRef.current[messageId] = { stateRenderId, runId }`
+ *
+ * ### State Snapshot Locking
+ *
+ * Once a state snapshot is captured and locked for a message:
+ * - The UI always renders with the locked snapshot (not live agent.state)
+ * - Prevents UI from appearing "wiped" during state transitions
+ * - Locked when: stateSnapshot prop is available (from message persistence)
+ * - Unlocked state: can still update from live agent.state
+ *
+ * ### Synchronous Claiming (Ref-based)
+ *
+ * Claims are stored in a context-level ref (not React state):
+ * - Multiple bridges render in the same tick
+ * - State updates are async - would allow duplicates before update completes
+ * - Ref provides immediate, synchronous claim checking
+ * - Survives component remounts (stored in context, not component)
+ *
+ * ## Flow Example
+ *
+ * ```
+ * Time 1: Message A renders, runId=undefined, state={progress: 50%}
+ *   → effectiveRunId = "pending"
+ *   → Claims: claimsRef["msgA"] = { stateRenderId: "tasks", runId: "pending", stateSnapshot: {progress: 50%} }
+ *   → Renders UI with 50% progress
+ *
+ * Time 2: Message B renders, runId=undefined, same state
+ *   → Checks: "tasks" already claimed by msgA with same state
+ *   → Returns null (blocked - duplicate)
+ *
+ * Time 3: Real runId appears (e.g., "run-123")
+ *   → Updates claim: claimsRef["msgA"].runId = "run-123"
+ *   → Message A continues rendering
+ *
+ * Time 4: Agent processes more, state={progress: 100%}
+ *   → Message A: locked to 50% (stateSnapshot locked)
+ *   → Message C renders with state={progress: 100%}
+ *   → Checks: "tasks" claimed by msgA but state is DIFFERENT (50% vs 100%)
+ *   → Allows new claim: claimsRef["msgC"] = { stateRenderId: "tasks", runId: "run-123", stateSnapshot: {progress: 100%} }
+ *   → Both messages render independently with their own snapshots
+ * ```
+ */
+export interface CoAgentStateRenderBridgeProps {
+  message: any;
+  position: ReactCustomMessageRendererPosition;
+  runId: string;
+  messageIndex: number;
+  messageIndexInRun: number;
+  numberOfMessagesInRun: number;
+  agentId: string;
+  stateSnapshot: any;
+}
+
+export function useCoagentStateRenderBridge(agentId: string, props: CoAgentStateRenderBridgeProps) {
+  const { stateSnapshot, messageIndexInRun, message } = props;
+  const { coAgentStateRenders, claimsRef } = useCoAgentStateRenders();
+  const { agent } = useAgent({ agentId });
+  const [nodeName, setNodeName] = useState<string | undefined>(undefined);
+
+  const runId = props.runId ?? message.runId;
+  const effectiveRunId = runId || "pending";
+
+  useEffect(() => {
+    if (!agent) return;
+    const subscriber: AgentSubscriber = {
+      onStepStartedEvent: ({ event }) => {
+        if (event.stepName !== nodeName) {
+          setNodeName(event.stepName);
+        }
+      },
+      onStepFinishedEvent: ({ event }) => {
+        if (event.stepName === nodeName) {
+          setNodeName(undefined);
+        }
+      },
+    };
+
+    const { unsubscribe } = agent.subscribe(subscriber);
+    return () => {
+      unsubscribe();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [agentId, nodeName]);
+
+  if (messageIndexInRun !== 0) {
+    return null;
+  }
+
+  const getStateRender = useCallback(
+    (messageId: string) => {
+    return Object.entries(coAgentStateRenders).find(([stateRenderId, stateRender]) => {
+      if (claimsRef.current[messageId]) {
+        return stateRenderId === claimsRef.current[messageId].stateRenderId;
+      }
+      const matchingAgentName = stateRender.name === agentId;
+      const matchesNodeContext = stateRender.nodeName
+        ? stateRender.nodeName === nodeName
+        : true;
+      return matchingAgentName && matchesNodeContext;
+    });
+  },
+    [coAgentStateRenders, nodeName, agentId],
+  );
+
+  // Message ID-based claim system - A state render can only be claimed by one message ID
+  const handleRenderRequest = ({
+    stateRenderId,
+    messageId,
+    runId,
+    stateSnapshot: renderSnapshot,
+  }: {
+    stateRenderId: string;
+    messageId: string;
+    runId?: string;
+    stateSnapshot?: any;
+  }): boolean => {
+    // Check if this message has already claimed this state render
+    if (claimsRef.current[messageId]) {
+      const canRender = claimsRef.current[messageId].stateRenderId === stateRenderId;
+
+      // Update runId if it doesn't exist
+      if (
+        canRender &&
+        runId &&
+        (!claimsRef.current[messageId].runId || claimsRef.current[messageId].runId === "pending")
+      ) {
+        claimsRef.current[messageId].runId = runId;
+      }
+
+      return canRender;
+    }
+
+    // Do not allow render if any other message has claimed this state render
+    const renderClaimedByOtherMessage = Object.values(claimsRef.current).find(
+      (c) =>
+        c.stateRenderId === stateRenderId &&
+        dataToUUID(JSON.stringify(getStateWithoutConstantKeys(c.stateSnapshot))) ===
+          dataToUUID(JSON.stringify(getStateWithoutConstantKeys(renderSnapshot))),
+    );
+    if (renderClaimedByOtherMessage) {
+      // If:
+      //   - state render already claimed
+      //   - snapshot exists in the claiming object and is different from current,
+      if (
+        renderSnapshot &&
+        renderClaimedByOtherMessage.stateSnapshot &&
+        !areStatesEquals(renderClaimedByOtherMessage.stateSnapshot, renderSnapshot)
+      ) {
+        claimsRef.current[messageId] = { stateRenderId, runId };
+        return true;
+      }
+      return false;
+    }
+
+    // No existing claim anywhere yet – allow this message to claim even if we already know the runId.
+    if (!runId) {
+      return false;
+    }
+
+    claimsRef.current[messageId] = { stateRenderId, runId };
+    return true;
+  };
+
+  return useMemo(() => {
+    const [stateRenderId, stateRender] = getStateRender(message.id) ?? [];
+
+    if (!stateRender || !stateRenderId) {
+      return null;
+    }
+
+    // Is there any state we can use?
+    const snapshot = stateSnapshot ? parseJson(stateSnapshot, stateSnapshot) : agent?.state;
+
+    // Synchronously check/claim - returns true if this message can render
+    const canRender = handleRenderRequest({
+      stateRenderId,
+      messageId: message.id,
+      runId: effectiveRunId,
+      stateSnapshot: snapshot,
+    });
+    if (!canRender) {
+      return null;
+    }
+
+    // If we found state, and given that now there's a claim for the current message, let's save it in the claim
+    if (snapshot && !claimsRef.current[message.id].locked) {
+      if (stateSnapshot) {
+        claimsRef.current[message.id].stateSnapshot = snapshot;
+        claimsRef.current[message.id].locked = true;
+      } else {
+        claimsRef.current[message.id].stateSnapshot = snapshot;
+      }
+    }
+
+    if (stateRender.handler) {
+      stateRender.handler({
+        state: stateSnapshot ? parseJson(stateSnapshot, stateSnapshot) : (agent?.state ?? {}),
+        nodeName: nodeName ?? "",
+      });
+    }
+
+    if (stateRender.render) {
+      const status = agent?.isRunning ? "inProgress" : "complete";
+
+      if (typeof stateRender.render === "string") return stateRender.render;
+
+    return stateRender.render({
+      status,
+      // Always use state from claim, to make sure the state does not seem "wiped" for a fraction of a second
+      state: claimsRef.current[message.id].stateSnapshot ?? {},
+      nodeName: nodeName ?? "",
+      });
+    }
+  }, [
+    getStateRender,
+    stateSnapshot,
+    agent?.state,
+    agent?.isRunning,
+    nodeName,
+    effectiveRunId,
+    message.id,
+  ]);
+}
+
+export function CoAgentStateRenderBridge(props: CoAgentStateRenderBridgeProps) {
+  return useCoagentStateRenderBridge(props.agentId, props);
+}

package/src/hooks/use-coagent-state-render.ts

@@ -46,6 +46,7 @@ import { CopilotContext } from "../context/copilot-context";
 import { randomId, CopilotKitAgentDiscoveryError } from "@copilotkit/shared";
 import { CoAgentStateRender } from "../types/coagent-action";
 import { useToast } from "../components/toast/toast-provider";
+import { useCoAgentStateRenders } from "../context/coagent-state-renders-context";
 
 /**
  * This hook is used to render agent state with custom UI components or text. This is particularly
@@ -62,13 +63,9 @@ export function useCoAgentStateRender<T = any>(
   action: CoAgentStateRender<T>,
   dependencies?: any[],
 ): void {
-  const {
-    setCoAgentStateRender,
-    removeCoAgentStateRender,
-    coAgentStateRenders,
-    chatComponentsCache,
-    availableAgents,
-  } = useContext(CopilotContext);
+  const { chatComponentsCache, availableAgents } = useContext(CopilotContext);
+  const { setCoAgentStateRender, removeCoAgentStateRender, coAgentStateRenders } =
+    useCoAgentStateRenders();
   const idRef = useRef<string>(randomId());
   const { setBannerError, addToast } = useToast();