@copilotkit/react-core 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

package/src/hooks/__tests__/use-coagent-config.test.ts

@@ -0,0 +1,351 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { useCoAgent } from "../use-coagent";
+import type { AgentSubscriber } from "@ag-ui/client";
+
+// Mock functions for @copilotkitnext/react
+const mockSetState = jest.fn();
+const mockRunAgent = jest.fn();
+const mockAbortRun = jest.fn();
+const mockSubscribe = jest.fn();
+const mockSetProperties = jest.fn();
+
+// Store the last subscriber for triggering events
+let lastSubscriber: AgentSubscriber | null = null;
+
+const mockAgent = {
+  agentId: "test-agent",
+  state: { count: 0 },
+  isRunning: false,
+  threadId: "thread-123",
+  setState: mockSetState,
+  runAgent: mockRunAgent,
+  abortRun: mockAbortRun,
+  subscribe: mockSubscribe.mockImplementation((subscriber: AgentSubscriber) => {
+    lastSubscriber = subscriber;
+    return {
+      unsubscribe: jest.fn(),
+    };
+  }),
+};
+
+jest.mock("@copilotkitnext/react", () => ({
+  useAgent: jest.fn(() => ({ agent: mockAgent })),
+  useCopilotKit: jest.fn(() => ({
+    copilotkit: {
+      setProperties: mockSetProperties,
+    },
+  })),
+}));
+
+// Mock other dependencies
+const mockAppendMessage = jest.fn();
+const mockRunChatCompletion = jest.fn();
+
+jest.mock("../use-copilot-chat_internal", () => ({
+  useCopilotChat: () => ({
+    appendMessage: mockAppendMessage,
+    runChatCompletion: mockRunChatCompletion,
+  }),
+}));
+
+jest.mock("../use-copilot-runtime-client", () => ({
+  useCopilotRuntimeClient: () => ({
+    loadAgentState: jest.fn().mockResolvedValue({
+      data: { loadAgentState: { state: "{}", threadExists: false } },
+      error: null,
+    }),
+  }),
+}));
+
+jest.mock("../../context", () => ({
+  useCopilotContext: () => ({
+    availableAgents: [],
+    coagentStates: {},
+    coagentStatesRef: { current: {} },
+    threadId: "test-thread",
+    copilotApiConfig: {
+      headers: {},
+      chatApiEndpoint: "test-endpoint",
+      publicApiKey: "test-key",
+    },
+    showDevConsole: false,
+  }),
+  useCopilotMessagesContext: () => ({
+    messages: [],
+  }),
+}));
+
+jest.mock("../../components/toast/toast-provider", () => ({
+  useToast: () => ({
+    setBannerError: jest.fn(),
+  }),
+}));
+
+jest.mock("../../components/error-boundary/error-utils", () => ({
+  useAsyncCallback: (fn: any) => fn,
+}));
+
+jest.mock("../../components/copilot-provider/copilot-messages", () => ({
+  useMessagesTap: () => ({
+    getMessagesFromTap: jest.fn(() => []),
+    updateTapMessages: jest.fn(),
+  }),
+}));
+
+describe("useCoAgent config synchronization", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    lastSubscriber = null;
+  });
+
+  it("should call setProperties when config changes", async () => {
+    const { rerender } = renderHook(
+      ({ config }) =>
+        useCoAgent({
+          name: "test-agent",
+          initialState: { count: 0 },
+          config,
+        }),
+      {
+        initialProps: { config: { configurable: { model: "gpt-4" } } },
+      },
+    );
+
+    // Clear the initial calls
+    mockSetProperties.mockClear();
+
+    // Change config
+    rerender({ config: { configurable: { model: "gpt-4o" } } });
+
+    // Wait for effect to complete and verify setProperties was called
+    await waitFor(() => {
+      expect(mockSetProperties).toHaveBeenCalledWith({
+        configurable: { model: "gpt-4o" },
+      });
+    });
+  });
+
+  it("should not call setProperties when config is unchanged", () => {
+    const config = { configurable: { model: "gpt-4" } };
+
+    const { rerender } = renderHook(
+      ({ config }) =>
+        useCoAgent({
+          name: "test-agent",
+          initialState: { count: 0 },
+          config,
+        }),
+      {
+        initialProps: { config },
+      },
+    );
+
+    // Clear the initial calls
+    mockSetProperties.mockClear();
+
+    // Re-render with same config reference
+    rerender({ config });
+
+    // Should not have called setProperties
+    expect(mockSetProperties).not.toHaveBeenCalled();
+  });
+
+  it("should handle backward compatibility with configurable prop", async () => {
+    const { rerender } = renderHook(
+      ({ configurable }) =>
+        useCoAgent({
+          name: "test-agent",
+          initialState: { count: 0 },
+          configurable,
+        }),
+      {
+        initialProps: { configurable: { model: "gpt-4" } },
+      },
+    );
+
+    // Clear the initial calls
+    mockSetProperties.mockClear();
+
+    // Change configurable prop
+    rerender({ configurable: { model: "gpt-4o" } });
+
+    // Wait for effect to complete and verify setProperties was called
+    await waitFor(() => {
+      expect(mockSetProperties).toHaveBeenCalledWith({
+        configurable: { model: "gpt-4o" },
+      });
+    });
+  });
+
+  it("should not call setProperties when both config and configurable are undefined", () => {
+    renderHook(() =>
+      useCoAgent({
+        name: "test-agent",
+        initialState: { count: 0 },
+      }),
+    );
+
+    // Should not have called setProperties
+    expect(mockSetProperties).not.toHaveBeenCalled();
+  });
+
+  it("should handle deeply nested config changes", async () => {
+    const { rerender } = renderHook(
+      ({ config }) =>
+        useCoAgent({
+          name: "test-agent",
+          initialState: { count: 0 },
+          config,
+        }),
+      {
+        initialProps: {
+          config: {
+            configurable: {
+              model: "gpt-4",
+              settings: { temperature: 0.5 },
+            },
+          },
+        },
+      },
+    );
+
+    // Clear the initial calls
+    mockSetProperties.mockClear();
+
+    // Change nested config
+    rerender({
+      config: {
+        configurable: {
+          model: "gpt-4",
+          settings: { temperature: 0.7 }, // Only nested property changed
+        },
+      },
+    });
+
+    // Wait for effect to complete and verify setProperties was called
+    await waitFor(() => {
+      expect(mockSetProperties).toHaveBeenCalledWith({
+        configurable: {
+          model: "gpt-4",
+          settings: { temperature: 0.7 },
+        },
+      });
+    });
+  });
+
+  describe("State Management", () => {
+    // Helper to create mock subscriber params
+    const createMockParams = (stateOverride: any = {}) => ({
+      messages: [],
+      state: stateOverride,
+      agent: mockAgent as any,
+      input: {} as any,
+    });
+
+    it("should initialize agent state via onRunInitialized event", () => {
+      // Set agent to have NO state (empty object)
+      mockAgent.state = {} as any;
+
+      renderHook(() =>
+        useCoAgent({
+          name: "test-agent",
+          initialState: { count: 42 },
+        }),
+      );
+
+      // Verify subscription was created
+      expect(mockSubscribe).toHaveBeenCalled();
+      expect(lastSubscriber).toBeTruthy();
+
+      // Clear any initial state calls
+      mockSetState.mockClear();
+
+      // Trigger onRunInitialized with no run state
+      lastSubscriber?.onRunInitialized?.(createMockParams({}));
+
+      // Should set state to initialState
+      expect(mockSetState).toHaveBeenCalledWith({ count: 42 });
+
+      // Reset agent state
+      mockAgent.state = { count: 0 };
+    });
+
+    it("should preserve existing agent state on onRunInitialized", () => {
+      // Set agent to have existing state
+      mockAgent.state = { count: 100 };
+
+      renderHook(() =>
+        useCoAgent({
+          name: "test-agent",
+          initialState: { count: 42 },
+        }),
+      );
+
+      // Clear any initial state calls
+      mockSetState.mockClear();
+
+      // Trigger onRunInitialized with no new state
+      lastSubscriber?.onRunInitialized?.(createMockParams({}));
+
+      // Should NOT override existing state
+      expect(mockSetState).not.toHaveBeenCalled();
+
+      // Reset agent state
+      mockAgent.state = { count: 0 };
+    });
+
+    it("should prioritize run state over initialState", () => {
+      renderHook(() =>
+        useCoAgent({
+          name: "test-agent",
+          initialState: { count: 42 },
+        }),
+      );
+
+      // Clear any initial state calls
+      mockSetState.mockClear();
+
+      // Trigger onRunInitialized with state from the run
+      lastSubscriber?.onRunInitialized?.(createMockParams({ count: 999 }));
+
+      // Should use run state, not initialState
+      expect(mockSetState).toHaveBeenCalledWith({ count: 999 });
+    });
+
+    it("should handle setState with object updates", () => {
+      const { result } = renderHook(() =>
+        useCoAgent({
+          name: "test-agent",
+          initialState: { count: 0 },
+        }),
+      );
+
+      // Update state with object
+      result.current.setState({ count: 5 });
+
+      // Should merge with existing state
+      expect(mockSetState).toHaveBeenCalledWith({ count: 5 });
+    });
+
+    it("should handle setState with function updaters", () => {
+      // Set current agent state
+      mockAgent.state = { count: 10 };
+
+      const { result } = renderHook(() =>
+        useCoAgent({
+          name: "test-agent",
+          initialState: { count: 0 },
+        }),
+      );
+
+      // Update state with function
+      result.current.setState((prev) => ({ count: (prev?.count || 0) + 5 }));
+
+      // Should call function with current state and set result
+      expect(mockSetState).toHaveBeenCalledWith({ count: 15 });
+
+      // Reset agent state
+      mockAgent.state = { count: 0 };
+    });
+  });
+});

package/src/hooks/index.ts

@@ -0,0 +1,34 @@
+export { useCopilotChat } from "./use-copilot-chat";
+export type { UseCopilotChatReturn } from "./use-copilot-chat";
+export type { UseCopilotChatOptions } from "./use-copilot-chat_internal";
+export {
+  type UseCopilotChatReturn_c,
+  type UseCopilotChatOptions_c,
+  useCopilotChatHeadless_c,
+} from "./use-copilot-chat-headless_c";
+export {
+  useCopilotChatInternal,
+  type ChatSuggestions,
+  type OnReloadMessages,
+  type OnStopGeneration,
+} 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 { useCopilotReadable } from "./use-copilot-readable";
+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";
+export { useLangGraphInterruptRender } from "./use-langgraph-interrupt-render";
+export { useCopilotAdditionalInstructions } from "./use-copilot-additional-instructions";
+export type { Tree, TreeNode } from "./use-tree";
+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 {
+  useCopilotChatSuggestions,
+  type UseCopilotChatSuggestionsConfiguration,
+} from "./use-copilot-chat-suggestions";

package/src/hooks/use-agent-nodename.ts

@@ -0,0 +1,30 @@
+import { useEffect, useRef } from "react";
+import type { AgentSubscriber } from "@ag-ui/client";
+import { useAgent } from "@copilotkitnext/react";
+
+export function useAgentNodeName(agentName?: string) {
+  const { agent } = useAgent({ agentId: agentName });
+  const nodeNameRef = useRef<string>("start");
+
+  useEffect(() => {
+    if (!agent) return;
+    const subscriber: AgentSubscriber = {
+      onStepStartedEvent: ({ event }) => {
+        nodeNameRef.current = event.stepName;
+      },
+      onRunStartedEvent: () => {
+        nodeNameRef.current = "start";
+      },
+      onRunFinishedEvent: () => {
+        nodeNameRef.current = "end";
+      },
+    };
+
+    const subscription = agent.subscribe(subscriber);
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [agent]);
+
+  return nodeNameRef.current;
+}

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) {
+  if (!state) return {};
+  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]);
+
+  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(getStateWithoutConstantKeys(c.stateSnapshot)) ===
+          dataToUUID(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(() => {
+    if (messageIndexInRun !== 0) {
+      return null;
+    }
+
+    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,
+    messageIndexInRun,
+  ]);
+}
+
+export function CoAgentStateRenderBridge(props: CoAgentStateRenderBridgeProps) {
+  return useCoagentStateRenderBridge(props.agentId, props);
+}