@copilotkit/react-core 1.54.1 → 1.55.0-next.7

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

@@ -0,0 +1,401 @@
+import React, { useState } from "react";
+import { render, act } from "@testing-library/react";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { useAgentContext, type AgentContextInput } from "../use-agent-context";
+import { useCopilotKit } from "../../providers/CopilotKitProvider";
+
+// Mock the CopilotKitProvider
+vi.mock("../../providers/CopilotKitProvider", () => ({
+  useCopilotKit: vi.fn(),
+}));
+
+const mockUseCopilotKit = useCopilotKit as ReturnType<typeof vi.fn>;
+
+describe("useAgentContext", () => {
+  let addContextMock: ReturnType<typeof vi.fn>;
+  let removeContextMock: ReturnType<typeof vi.fn>;
+  let contextIdCounter: number;
+
+  beforeEach(() => {
+    contextIdCounter = 0;
+    addContextMock = vi.fn(() => `context-${++contextIdCounter}`);
+    removeContextMock = vi.fn();
+
+    mockUseCopilotKit.mockReturnValue({
+      copilotkit: {
+        addContext: addContextMock,
+        removeContext: removeContextMock,
+      },
+    } as any);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("context cleanup on unmount", () => {
+    it("removes the context when the component unmounts", () => {
+      const TestComponent: React.FC<{ context: AgentContextInput }> = ({
+        context,
+      }) => {
+        useAgentContext(context);
+        return <div>Test</div>;
+      };
+
+      const { unmount } = render(
+        <TestComponent
+          context={{ description: "test context", value: "test value" }}
+        />,
+      );
+
+      // Context should be added
+      expect(addContextMock).toHaveBeenCalledTimes(1);
+      expect(addContextMock).toHaveBeenCalledWith({
+        description: "test context",
+        value: "test value",
+      });
+
+      const addedContextId = addContextMock.mock.results[0]?.value;
+
+      // Unmount the component
+      unmount();
+
+      // Context should be removed with the correct ID
+      expect(removeContextMock).toHaveBeenCalledTimes(1);
+      expect(removeContextMock).toHaveBeenCalledWith(addedContextId);
+    });
+
+    it("removes context when conditionally unmounted", () => {
+      const ContextUser: React.FC = () => {
+        useAgentContext({
+          description: "conditional context",
+          value: "conditional value",
+        });
+        return <div data-testid="context-user">Context User</div>;
+      };
+
+      const ParentComponent: React.FC = () => {
+        const [showContext, setShowContext] = useState(true);
+        return (
+          <>
+            <button
+              data-testid="toggle"
+              onClick={() => setShowContext((prev) => !prev)}
+            >
+              Toggle
+            </button>
+            {showContext && <ContextUser />}
+          </>
+        );
+      };
+
+      const { getByTestId, queryByTestId } = render(<ParentComponent />);
+
+      // Context should be added
+      expect(addContextMock).toHaveBeenCalledTimes(1);
+      expect(queryByTestId("context-user")).not.toBeNull();
+
+      const addedContextId = addContextMock.mock.results[0]?.value;
+
+      // Toggle off - should unmount ContextUser
+      act(() => {
+        getByTestId("toggle").click();
+      });
+
+      // Context should be removed
+      expect(removeContextMock).toHaveBeenCalledTimes(1);
+      expect(removeContextMock).toHaveBeenCalledWith(addedContextId);
+      expect(queryByTestId("context-user")).toBeNull();
+    });
+  });
+
+  describe("re-render idempotence", () => {
+    it("does not add additional context on re-render with same values", () => {
+      const TestComponent: React.FC<{
+        context: AgentContextInput;
+        counter: number;
+      }> = ({ context, counter }) => {
+        useAgentContext(context);
+        return <div>Counter: {counter}</div>;
+      };
+
+      const context: AgentContextInput = {
+        description: "stable context",
+        value: "stable value",
+      };
+
+      const { rerender } = render(
+        <TestComponent context={context} counter={0} />,
+      );
+
+      // Initial render - context added once
+      expect(addContextMock).toHaveBeenCalledTimes(1);
+
+      // Re-render with different counter but same context
+      rerender(<TestComponent context={context} counter={1} />);
+
+      // Context should not be added again
+      expect(addContextMock).toHaveBeenCalledTimes(1);
+
+      // Re-render again
+      rerender(<TestComponent context={context} counter={2} />);
+
+      // Still only one add
+      expect(addContextMock).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not add additional context when parent re-renders", () => {
+      const ContextUser: React.FC = () => {
+        useAgentContext({
+          description: "child context",
+          value: "child value",
+        });
+        return <div>Child</div>;
+      };
+
+      const ParentComponent: React.FC = () => {
+        const [counter, setCounter] = useState(0);
+        return (
+          <>
+            <button
+              data-testid="increment"
+              onClick={() => setCounter((c) => c + 1)}
+            >
+              Increment ({counter})
+            </button>
+            <ContextUser />
+          </>
+        );
+      };
+
+      const { getByTestId } = render(<ParentComponent />);
+
+      // Initial render
+      expect(addContextMock).toHaveBeenCalledTimes(1);
+
+      // Trigger parent re-render multiple times
+      act(() => {
+        getByTestId("increment").click();
+      });
+      act(() => {
+        getByTestId("increment").click();
+      });
+      act(() => {
+        getByTestId("increment").click();
+      });
+
+      // Context should still only be added once
+      expect(addContextMock).toHaveBeenCalledTimes(1);
+      // No removals should have happened
+      expect(removeContextMock).toHaveBeenCalledTimes(0);
+    });
+
+    it("re-adds context when description changes", () => {
+      const TestComponent: React.FC<{ description: string }> = ({
+        description,
+      }) => {
+        useAgentContext({ description, value: "same value" });
+        return <div>{description}</div>;
+      };
+
+      const { rerender } = render(<TestComponent description="first" />);
+
+      expect(addContextMock).toHaveBeenCalledTimes(1);
+      expect(addContextMock).toHaveBeenLastCalledWith({
+        description: "first",
+        value: "same value",
+      });
+
+      const firstContextId = addContextMock.mock.results[0]?.value;
+
+      // Change description
+      rerender(<TestComponent description="second" />);
+
+      // Old context removed, new context added
+      expect(removeContextMock).toHaveBeenCalledTimes(1);
+      expect(removeContextMock).toHaveBeenCalledWith(firstContextId);
+      expect(addContextMock).toHaveBeenCalledTimes(2);
+      expect(addContextMock).toHaveBeenLastCalledWith({
+        description: "second",
+        value: "same value",
+      });
+    });
+
+    it("re-adds context when value changes", () => {
+      const TestComponent: React.FC<{ value: string }> = ({ value }) => {
+        useAgentContext({ description: "same description", value });
+        return <div>{value}</div>;
+      };
+
+      const { rerender } = render(<TestComponent value="first" />);
+
+      expect(addContextMock).toHaveBeenCalledTimes(1);
+      const firstContextId = addContextMock.mock.results[0]?.value;
+
+      // Change value
+      rerender(<TestComponent value="second" />);
+
+      // Old context removed, new context added
+      expect(removeContextMock).toHaveBeenCalledTimes(1);
+      expect(removeContextMock).toHaveBeenCalledWith(firstContextId);
+      expect(addContextMock).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("JSON serialization", () => {
+    it("passes string values through unchanged", () => {
+      const TestComponent: React.FC = () => {
+        useAgentContext({
+          description: "string context",
+          value: "plain string value",
+        });
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      expect(addContextMock).toHaveBeenCalledWith({
+        description: "string context",
+        value: "plain string value",
+      });
+    });
+
+    it("serializes object values to JSON", () => {
+      const TestComponent: React.FC = () => {
+        useAgentContext({
+          description: "object context",
+          value: { name: "John", age: 30 },
+        });
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      expect(addContextMock).toHaveBeenCalledWith({
+        description: "object context",
+        value: '{"name":"John","age":30}',
+      });
+    });
+
+    it("serializes array values to JSON", () => {
+      const TestComponent: React.FC = () => {
+        useAgentContext({
+          description: "array context",
+          value: [1, 2, 3, "four"],
+        });
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      expect(addContextMock).toHaveBeenCalledWith({
+        description: "array context",
+        value: '[1,2,3,"four"]',
+      });
+    });
+
+    it("serializes number values to JSON", () => {
+      const TestComponent: React.FC = () => {
+        useAgentContext({
+          description: "number context",
+          value: 42,
+        });
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      expect(addContextMock).toHaveBeenCalledWith({
+        description: "number context",
+        value: "42",
+      });
+    });
+
+    it("serializes boolean values to JSON", () => {
+      const TestComponent: React.FC = () => {
+        useAgentContext({
+          description: "boolean context",
+          value: true,
+        });
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      expect(addContextMock).toHaveBeenCalledWith({
+        description: "boolean context",
+        value: "true",
+      });
+    });
+
+    it("serializes null values to JSON", () => {
+      const TestComponent: React.FC = () => {
+        useAgentContext({
+          description: "null context",
+          value: null,
+        });
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      expect(addContextMock).toHaveBeenCalledWith({
+        description: "null context",
+        value: "null",
+      });
+    });
+
+    it("serializes nested objects to JSON", () => {
+      const TestComponent: React.FC = () => {
+        useAgentContext({
+          description: "nested context",
+          value: {
+            user: {
+              name: "Alice",
+              settings: {
+                theme: "dark",
+                notifications: true,
+              },
+            },
+            items: [1, 2, { nested: "value" }],
+          },
+        });
+        return null;
+      };
+
+      render(<TestComponent />);
+
+      expect(addContextMock).toHaveBeenCalledWith({
+        description: "nested context",
+        value:
+          '{"user":{"name":"Alice","settings":{"theme":"dark","notifications":true}},"items":[1,2,{"nested":"value"}]}',
+      });
+    });
+  });
+
+  describe("copilotkit not available", () => {
+    it("does nothing when copilotkit is null", () => {
+      mockUseCopilotKit.mockReturnValue({
+        copilotkit: null,
+      } as any);
+
+      const TestComponent: React.FC = () => {
+        useAgentContext({
+          description: "test",
+          value: "test",
+        });
+        return null;
+      };
+
+      const { unmount } = render(<TestComponent />);
+
+      // Should not throw and should not call addContext
+      expect(addContextMock).not.toHaveBeenCalled();
+
+      unmount();
+
+      // Should not call removeContext either
+      expect(removeContextMock).not.toHaveBeenCalled();
+    });
+  });
+});

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

@@ -0,0 +1,44 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { CopilotKitProvider } from "../../providers/CopilotKitProvider";
+import { useAgent } from "../use-agent";
+
+describe("useAgent error state", () => {
+  const originalFetch = global.fetch;
+  const originalWindow = (globalThis as { window?: unknown }).window;
+
+  beforeEach(() => {
+    // Simulate browser environment
+    (globalThis as { window?: unknown }).window = {};
+    // Mock fetch to reject (simulates runtime unreachable)
+    global.fetch = vi.fn().mockRejectedValue(new Error("network failure"));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    global.fetch = originalFetch;
+    if (originalWindow === undefined) {
+      delete (globalThis as { window?: unknown }).window;
+    } else {
+      (globalThis as { window?: unknown }).window = originalWindow;
+    }
+  });
+
+  it("returns a provisional agent instead of throwing when runtime is in error state", async () => {
+    function TestComponent() {
+      const { agent } = useAgent({ agentId: "nonexistent" });
+      return <div data-testid="agent-id">{agent.agentId}</div>;
+    }
+
+    render(
+      <CopilotKitProvider runtimeUrl="http://localhost:59999/nonexistent">
+        <TestComponent />
+      </CopilotKitProvider>,
+    );
+
+    // Should render without crashing — agent is provisional
+    const el = await screen.findByTestId("agent-id");
+    expect(el.textContent).toBe("nonexistent");
+  });
+});

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

@@ -0,0 +1,205 @@
+import React from "react";
+import { render } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { AbstractAgent } from "@ag-ui/client";
+import { useCopilotKit } from "../../providers/CopilotKitProvider";
+import { MockStepwiseAgent } from "../../__tests__/utils/test-helpers";
+import { useAgent } from "../use-agent";
+import { CopilotKitCoreRuntimeConnectionStatus } from "@copilotkit/core";
+
+// Mock the CopilotKitProvider to control copilotkit state directly
+vi.mock("../../providers/CopilotKitProvider", () => ({
+  useCopilotKit: vi.fn(),
+}));
+
+const mockUseCopilotKit = useCopilotKit as ReturnType<typeof vi.fn>;
+
+/**
+ * Tests for useAgent referential stability during runtime connection lifecycle.
+ *
+ * Bug: useAgent creates multiple ProxiedCopilotRuntimeAgent instances during
+ * Disconnected→Connecting→Connected transitions because the useMemo recalculates
+ * on every dependency change and creates a new agent each time.
+ */
+describe("useAgent stability during runtime connection", () => {
+  let mockCopilotkit: {
+    getAgent: ReturnType<typeof vi.fn>;
+    runtimeUrl: string | undefined;
+    runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
+    runtimeTransport: string;
+    headers: Record<string, string>;
+    agents: Record<string, AbstractAgent>;
+  };
+
+  beforeEach(() => {
+    mockCopilotkit = {
+      getAgent: vi.fn(() => undefined),
+      runtimeUrl: "http://localhost:3000/api/copilotkit",
+      runtimeConnectionStatus:
+        CopilotKitCoreRuntimeConnectionStatus.Disconnected,
+      runtimeTransport: "rest",
+      headers: {},
+      agents: {},
+    };
+
+    mockUseCopilotKit.mockReturnValue({
+      copilotkit: mockCopilotkit,
+      executingToolCallIds: new Set(),
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should reuse the same provisional agent across re-renders during Disconnected→Connecting", () => {
+    const agentInstances: AbstractAgent[] = [];
+
+    function AgentTracker() {
+      const { agent } = useAgent({ agentId: "test-agent" });
+      if (
+        agentInstances.length === 0 ||
+        agentInstances[agentInstances.length - 1] !== agent
+      ) {
+        agentInstances.push(agent);
+      }
+      return <div>{agent.threadId}</div>;
+    }
+
+    // Render 1: Disconnected — creates provisional agent
+    const { rerender } = render(<AgentTracker />);
+    expect(agentInstances.length).toBe(1);
+    const provisionalThreadId = agentInstances[0]!.threadId;
+
+    // Render 2: Connecting — should reuse same provisional agent
+    mockCopilotkit.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Connecting;
+    rerender(<AgentTracker />);
+
+    // BUG: Current code creates a new agent instance here (agentInstances.length === 2)
+    // FIX: Should still be 1 (same provisional reused)
+    expect(agentInstances.length).toBe(1);
+    expect(agentInstances[0]!.threadId).toBe(provisionalThreadId);
+  });
+
+  it("should reuse provisional agent when headers change during connecting", () => {
+    const agentInstances: AbstractAgent[] = [];
+
+    function AgentTracker() {
+      const { agent } = useAgent({ agentId: "test-agent" });
+      if (
+        agentInstances.length === 0 ||
+        agentInstances[agentInstances.length - 1] !== agent
+      ) {
+        agentInstances.push(agent);
+      }
+      return <div>{agent.threadId}</div>;
+    }
+
+    // Render 1: Disconnected
+    const { rerender } = render(<AgentTracker />);
+    expect(agentInstances.length).toBe(1);
+
+    // Render 2: Connecting
+    mockCopilotkit.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Connecting;
+    rerender(<AgentTracker />);
+
+    // Render 3: Headers change (e.g., auth token set)
+    mockCopilotkit.headers = { "X-CopilotCloud-Public-Api-Key": "test-key" };
+    rerender(<AgentTracker />);
+
+    // Render 4: Another minor change
+    mockCopilotkit.headers = {
+      "X-CopilotCloud-Public-Api-Key": "test-key",
+      "X-Custom": "value",
+    };
+    rerender(<AgentTracker />);
+
+    // BUG: Current code creates a new agent on each re-render (agentInstances.length >= 3)
+    // FIX: Should still be 1 (same provisional reused throughout connecting phase)
+    expect(agentInstances.length).toBe(1);
+  });
+
+  it("should keep the same agent instance across the full Disconnected→Connected lifecycle", () => {
+    const agentInstances: AbstractAgent[] = [];
+
+    function AgentTracker() {
+      const { agent } = useAgent({ agentId: "test-agent" });
+      if (
+        agentInstances.length === 0 ||
+        agentInstances[agentInstances.length - 1] !== agent
+      ) {
+        agentInstances.push(agent);
+      }
+      return <div>{agent.threadId}</div>;
+    }
+
+    // Phase 1: Disconnected — provisional created
+    const { rerender } = render(<AgentTracker />);
+    const provisionalThreadId = agentInstances[0]!.threadId;
+
+    // Phase 2: Connecting
+    mockCopilotkit.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Connecting;
+    rerender(<AgentTracker />);
+
+    // Phase 3: Headers change during connecting
+    mockCopilotkit.headers = { "X-Auth": "token" };
+    rerender(<AgentTracker />);
+
+    // Phase 4: Connected — registered agent now available
+    const registeredAgent = new MockStepwiseAgent();
+    registeredAgent.agentId = "test-agent";
+    registeredAgent.description = "Agent from /info";
+
+    mockCopilotkit.getAgent.mockReturnValue(registeredAgent);
+    mockCopilotkit.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Connected;
+    mockCopilotkit.agents = { "test-agent": registeredAgent };
+    rerender(<AgentTracker />);
+
+    // Phase 5: agents notification (separate re-render in real app)
+    rerender(<AgentTracker />);
+
+    // 2 instances: 1 provisional (Disconnected/Connecting) + 1 registered (Connected).
+    // The provisional is stable across all pre-connection renders.
+    // CopilotChat's connect guard ensures connect fires only once (when Connected),
+    // so the agent reference change doesn't cause a duplicate connect.
+    expect(agentInstances.length).toBe(2);
+    // First instance was the provisional
+    expect(agentInstances[0]!.threadId).toBe(provisionalThreadId);
+    // Second instance is the registered agent
+    expect(agentInstances[1]).toBe(registeredAgent);
+  });
+
+  it("should return local dev agents directly without a provisional", () => {
+    const localAgent = new MockStepwiseAgent();
+    localAgent.agentId = "local-agent";
+
+    // Simulate agents__unsafe_dev_only: no runtimeUrl, agent found immediately
+    mockCopilotkit.runtimeUrl = undefined;
+    mockCopilotkit.getAgent.mockReturnValue(localAgent);
+    mockCopilotkit.agents = { "local-agent": localAgent };
+
+    const agentInstances: AbstractAgent[] = [];
+
+    function AgentTracker() {
+      const { agent } = useAgent({ agentId: "local-agent" });
+      if (
+        agentInstances.length === 0 ||
+        agentInstances[agentInstances.length - 1] !== agent
+      ) {
+        agentInstances.push(agent);
+      }
+      return <div>{agent.threadId}</div>;
+    }
+
+    const { rerender } = render(<AgentTracker />);
+    rerender(<AgentTracker />);
+
+    // Local agent is returned directly — exactly 1 instance, the original
+    expect(agentInstances.length).toBe(1);
+    expect(agentInstances[0]).toBe(localAgent);
+  });
+});