@copilotkit/react-core 1.57.3 → 1.58.0

package/src/v2/hooks/__tests__/zod-regression.test.tsx

@@ -1,311 +0,0 @@
-/**
- * Regression tests proving that React hooks and helpers still work
- * identically with Zod schemas after the Standard Schema migration.
- *
- * Covers:
- * 1. useRenderTool with complex Zod schemas
- * 2. defineToolCallRenderer with Zod (named + wildcard default z.any())
- * 3. useComponent with Zod schemas
- * 4. The registered schema object is the original Zod instance (identity check)
- */
-import React from "react";
-import { render } from "@testing-library/react";
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import { z } from "zod";
-import { useRenderTool } from "../use-render-tool";
-import { useComponent } from "../use-component";
-import { defineToolCallRenderer } from "../../types/defineToolCallRenderer";
-import { useCopilotKit } from "../../context";
-import { useFrontendTool } from "../use-frontend-tool";
-import type { ReactToolCallRenderer } from "../../types/react-tool-call-renderer";
-
-vi.mock("../../context", () => ({
-  useCopilotKit: vi.fn(),
-}));
-
-vi.mock("../use-frontend-tool", () => ({
-  useFrontendTool: vi.fn(),
-}));
-
-type MockCore = {
-  renderToolCalls: ReactToolCallRenderer[];
-  setRenderToolCalls: ReturnType<typeof vi.fn>;
-  addHookRenderToolCall: ReturnType<typeof vi.fn>;
-  removeHookRenderToolCall: ReturnType<typeof vi.fn>;
-};
-
-const mockUseCopilotKit = useCopilotKit as ReturnType<typeof vi.fn>;
-const mockUseFrontendTool = useFrontendTool as ReturnType<typeof vi.fn>;
-
-function createMockCore(initial: ReactToolCallRenderer[] = []): MockCore {
-  const hookEntries = new Map<string, ReactToolCallRenderer>();
-  const core: MockCore = {
-    renderToolCalls: initial,
-    setRenderToolCalls: vi.fn((next: ReactToolCallRenderer[]) => {
-      core.renderToolCalls = next;
-    }),
-    addHookRenderToolCall: vi.fn((entry: ReactToolCallRenderer) => {
-      const key = `${entry.agentId ?? ""}:${entry.name}`;
-      hookEntries.set(key, entry);
-      core.renderToolCalls = [...initial, ...hookEntries.values()];
-    }),
-    removeHookRenderToolCall: vi.fn(),
-  };
-  return core;
-}
-
-describe("useRenderTool Zod regression", () => {
-  beforeEach(() => vi.clearAllMocks());
-
-  it("registers with a complex Zod schema and preserves schema identity", () => {
-    const core = createMockCore();
-    mockUseCopilotKit.mockReturnValue({ copilotkit: core });
-
-    const schema = z.object({
-      query: z.string().describe("Search query"),
-      filters: z
-        .object({
-          category: z.enum(["books", "movies"]).optional(),
-          tags: z.array(z.string()).optional(),
-        })
-        .optional(),
-    });
-
-    const Harness: React.FC = () => {
-      useRenderTool(
-        {
-          name: "complexSearch",
-          parameters: schema,
-          render: () => <div>result</div>,
-        },
-        [],
-      );
-      return null;
-    };
-
-    render(<Harness />);
-
-    expect(core.addHookRenderToolCall).toHaveBeenCalledTimes(1);
-    const renderer = core.renderToolCalls.find(
-      (r) => r.name === "complexSearch",
-    );
-    expect(renderer).toBeDefined();
-    // The args should be the exact same Zod schema object (identity)
-    expect(renderer?.args).toBe(schema);
-  });
-
-  it("registers with a Zod schema using enums and defaults", () => {
-    const core = createMockCore();
-    mockUseCopilotKit.mockReturnValue({ copilotkit: core });
-
-    const schema = z.object({
-      sortBy: z.enum(["relevance", "date", "rating"]).default("relevance"),
-      page: z.number().int().positive().default(1),
-    });
-
-    const Harness: React.FC = () => {
-      useRenderTool(
-        {
-          name: "sortable",
-          parameters: schema,
-          render: () => <div>sorted</div>,
-        },
-        [],
-      );
-      return null;
-    };
-
-    render(<Harness />);
-
-    const renderer = core.renderToolCalls.find((r) => r.name === "sortable");
-    expect(renderer).toBeDefined();
-    expect(renderer?.args).toBe(schema);
-  });
-
-  it("registers with a Zod schema using discriminated union", () => {
-    const core = createMockCore();
-    mockUseCopilotKit.mockReturnValue({ copilotkit: core });
-
-    const schema = z.object({
-      action: z.discriminatedUnion("type", [
-        z.object({ type: z.literal("search"), query: z.string() }),
-        z.object({ type: z.literal("navigate"), url: z.string().url() }),
-      ]),
-    });
-
-    const Harness: React.FC = () => {
-      useRenderTool(
-        {
-          name: "actionRenderer",
-          parameters: schema,
-          render: () => <div>action</div>,
-        },
-        [],
-      );
-      return null;
-    };
-
-    render(<Harness />);
-
-    const renderer = core.renderToolCalls.find(
-      (r) => r.name === "actionRenderer",
-    );
-    expect(renderer).toBeDefined();
-    expect(renderer?.args).toBe(schema);
-  });
-
-  it("registers with a Zod schema using nullable and arrays", () => {
-    const core = createMockCore();
-    mockUseCopilotKit.mockReturnValue({ copilotkit: core });
-
-    const schema = z.object({
-      title: z.string(),
-      description: z.string().nullable(),
-      tags: z.array(z.string()),
-    });
-
-    const Harness: React.FC = () => {
-      useRenderTool(
-        {
-          name: "taggedItem",
-          parameters: schema,
-          render: () => <div>item</div>,
-        },
-        [],
-      );
-      return null;
-    };
-
-    render(<Harness />);
-
-    const renderer = core.renderToolCalls.find((r) => r.name === "taggedItem");
-    expect(renderer).toBeDefined();
-    expect(renderer?.args).toBe(schema);
-  });
-});
-
-describe("defineToolCallRenderer Zod regression", () => {
-  it("wildcard tool defaults to z.any() for args", () => {
-    const renderer = defineToolCallRenderer({
-      name: "*",
-      render: () => React.createElement("div", null, "wildcard"),
-    });
-
-    expect(renderer.name).toBe("*");
-    // z.any() has vendor "zod" on ~standard
-    expect(renderer.args["~standard"].vendor).toBe("zod");
-  });
-
-  it("named tool with Zod args preserves schema identity", () => {
-    const schema = z.object({
-      city: z.string(),
-      units: z.enum(["celsius", "fahrenheit"]).optional(),
-    });
-
-    const renderer = defineToolCallRenderer({
-      name: "weather",
-      args: schema,
-      render: () => React.createElement("div", null, "weather"),
-    });
-
-    expect(renderer.name).toBe("weather");
-    expect(renderer.args).toBe(schema);
-  });
-
-  it("named tool with complex Zod args", () => {
-    const schema = z.object({
-      results: z.array(
-        z.object({
-          id: z.number(),
-          title: z.string(),
-          score: z.number().min(0).max(1),
-        }),
-      ),
-    });
-
-    const renderer = defineToolCallRenderer({
-      name: "searchResults",
-      args: schema,
-      render: () => React.createElement("div", null, "results"),
-    });
-
-    expect(renderer.name).toBe("searchResults");
-    expect(renderer.args).toBe(schema);
-  });
-
-  it("named tool with agentId", () => {
-    const schema = z.object({ query: z.string() });
-
-    const renderer = defineToolCallRenderer({
-      name: "agentSearch",
-      args: schema,
-      render: () => React.createElement("div", null, "agent"),
-      agentId: "agent-123",
-    });
-
-    expect(renderer.name).toBe("agentSearch");
-    expect(renderer.agentId).toBe("agent-123");
-    expect(renderer.args).toBe(schema);
-  });
-});
-
-describe("useComponent Zod regression", () => {
-  beforeEach(() => vi.clearAllMocks());
-
-  it("registers a component with a Zod schema", () => {
-    const WeatherCard: React.FC<{ city: string }> = ({ city }) => (
-      <div>{city}</div>
-    );
-
-    const schema = z.object({ city: z.string() });
-
-    const Harness: React.FC = () => {
-      useComponent({
-        name: "weatherCard",
-        parameters: schema,
-        render: WeatherCard,
-      });
-      return null;
-    };
-
-    render(<Harness />);
-
-    expect(mockUseFrontendTool).toHaveBeenCalledTimes(1);
-    const [toolConfig] = mockUseFrontendTool.mock.calls[0] as [
-      { name: string; parameters: any },
-    ];
-    expect(toolConfig.name).toBe("weatherCard");
-    expect(toolConfig.parameters).toBe(schema);
-    expect(toolConfig.parameters["~standard"].vendor).toBe("zod");
-  });
-
-  it("registers a component with a complex Zod schema", () => {
-    const DataGrid: React.FC<{
-      columns: string[];
-      sortBy: string;
-    }> = () => <div>grid</div>;
-
-    const schema = z.object({
-      columns: z.array(z.string()),
-      sortBy: z.enum(["name", "date", "size"]).default("name"),
-    });
-
-    const Harness: React.FC = () => {
-      useComponent({
-        name: "dataGrid",
-        parameters: schema,
-        render: DataGrid,
-      });
-      return null;
-    };
-
-    render(<Harness />);
-
-    expect(mockUseFrontendTool).toHaveBeenCalledTimes(1);
-    const [toolConfig] = mockUseFrontendTool.mock.calls[0] as [
-      { name: string; parameters: any },
-    ];
-    expect(toolConfig.name).toBe("dataGrid");
-    expect(toolConfig.parameters).toBe(schema);
-  });
-});

package/src/v2/hooks/index.ts

@@ -1,24 +0,0 @@
-// React hooks for CopilotKit2
-export { useRenderToolCall } from "./use-render-tool-call";
-export { useRenderCustomMessages } from "./use-render-custom-messages";
-export { useRenderActivityMessage } from "./use-render-activity-message";
-export { useFrontendTool } from "./use-frontend-tool";
-export { useComponent } from "./use-component";
-export { useRenderTool } from "./use-render-tool";
-export { useDefaultRenderTool } from "./use-default-render-tool";
-export { useHumanInTheLoop } from "./use-human-in-the-loop";
-export { useAgent, UseAgentUpdate } from "./use-agent";
-export { useCapabilities } from "./use-capabilities";
-export { useAgentContext } from "./use-agent-context";
-export type { AgentContextInput, JsonSerializable } from "./use-agent-context";
-export { useSuggestions } from "./use-suggestions";
-export { useConfigureSuggestions } from "./use-configure-suggestions";
-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-context.tsx

@@ -1,45 +0,0 @@
-import { useCopilotKit } from "../context";
-import { useLayoutEffect, useMemo } from "react";
-
-/**
- * Represents any value that can be serialized to JSON.
- */
-export type JsonSerializable =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonSerializable[]
-  | { [key: string]: JsonSerializable };
-
-/**
- * Context configuration for useAgentContext.
- * Accepts any JSON-serializable value which will be converted to a string.
- */
-export interface AgentContextInput {
-  /** A human-readable description of what this context represents */
-  description: string;
-  /** The context value - will be converted to a JSON string if not already a string */
-  value: JsonSerializable;
-}
-
-export function useAgentContext(context: AgentContextInput) {
-  const { description, value } = context;
-  const { copilotkit } = useCopilotKit();
-
-  const stringValue = useMemo(() => {
-    if (typeof value === "string") {
-      return value;
-    }
-    return JSON.stringify(value);
-  }, [value]);
-
-  useLayoutEffect(() => {
-    if (!copilotkit) return;
-
-    const id = copilotkit.addContext({ description, value: stringValue });
-    return () => {
-      copilotkit.removeContext(id);
-    };
-  }, [description, stringValue, copilotkit]);
-}

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

@@ -1,227 +0,0 @@
-import { useCopilotKit } from "../context";
-import { useMemo, useEffect, useReducer, useRef } from "react";
-import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
-import { AbstractAgent, HttpAgent } from "@ag-ui/client";
-import {
-  ProxiedCopilotRuntimeAgent,
-  CopilotKitCoreRuntimeConnectionStatus,
-  type SubscribeToAgentSubscriber,
-} from "@copilotkit/core";
-
-export enum UseAgentUpdate {
-  OnMessagesChanged = "OnMessagesChanged",
-  OnStateChanged = "OnStateChanged",
-  OnRunStatusChanged = "OnRunStatusChanged",
-}
-
-const ALL_UPDATES: UseAgentUpdate[] = [
-  UseAgentUpdate.OnMessagesChanged,
-  UseAgentUpdate.OnStateChanged,
-  UseAgentUpdate.OnRunStatusChanged,
-];
-
-export interface UseAgentProps {
-  agentId?: string;
-  updates?: UseAgentUpdate[];
-  /**
-   * 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 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.
-   *
-   * Resolved as: `throttleMs ?? provider defaultThrottleMs ?? 0`.
-   * Passing `throttleMs={0}` explicitly disables throttling even when the
-   * provider specifies a non-zero `defaultThrottleMs`.
-   *
-   * 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;
-}
-
-export function useAgent({ agentId, updates, throttleMs }: UseAgentProps = {}) {
-  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;
-
-  const [, forceUpdate] = useReducer((x) => x + 1, 0);
-
-  const updateFlags = useMemo(
-    () => updates ?? ALL_UPDATES,
-    [JSON.stringify(updates)],
-  );
-
-  // Cache provisional agents to avoid creating new references on every render
-  // while the runtime is still connecting. A new reference would cascade into
-  // CopilotChat's connectAgent effect, causing unnecessary HTTP calls.
-  const provisionalAgentCache = useRef<Map<string, ProxiedCopilotRuntimeAgent>>(
-    new Map(),
-  );
-
-  const agent: AbstractAgent = useMemo(() => {
-    const existing = copilotkit.getAgent(agentId);
-    if (existing) {
-      // Real agent found — clear any cached provisional for this ID
-      provisionalAgentCache.current.delete(agentId);
-      return existing;
-    }
-
-    const isRuntimeConfigured = copilotkit.runtimeUrl !== undefined;
-    const status = copilotkit.runtimeConnectionStatus;
-
-    // While runtime is not yet synced, return a provisional runtime agent
-    if (
-      isRuntimeConfigured &&
-      (status === CopilotKitCoreRuntimeConnectionStatus.Disconnected ||
-        status === CopilotKitCoreRuntimeConnectionStatus.Connecting)
-    ) {
-      // Return cached provisional if available (keeps reference stable)
-      const cached = provisionalAgentCache.current.get(agentId);
-      if (cached) {
-        // Update headers on the cached agent in case they changed
-        cached.headers = { ...copilotkit.headers };
-        return cached;
-      }
-
-      const provisional = new ProxiedCopilotRuntimeAgent({
-        runtimeUrl: copilotkit.runtimeUrl,
-        agentId,
-        transport: copilotkit.runtimeTransport,
-        runtimeMode: "pending",
-      });
-      // Apply current headers so runs/connects inherit them
-      provisional.headers = { ...copilotkit.headers };
-      provisionalAgentCache.current.set(agentId, provisional);
-      return provisional;
-    }
-
-    // Runtime is in Error state — return a provisional agent instead of throwing.
-    // The error has already been emitted through the subscriber system
-    // (RUNTIME_INFO_FETCH_FAILED). Throwing here would crash the React tree;
-    // returning a provisional agent lets onError handlers fire while keeping
-    // the app alive.
-    if (
-      isRuntimeConfigured &&
-      status === CopilotKitCoreRuntimeConnectionStatus.Error
-    ) {
-      const cached = provisionalAgentCache.current.get(agentId);
-      if (cached) {
-        cached.headers = { ...copilotkit.headers };
-        return cached;
-      }
-      const provisional = new ProxiedCopilotRuntimeAgent({
-        runtimeUrl: copilotkit.runtimeUrl,
-        agentId,
-        transport: copilotkit.runtimeTransport,
-        runtimeMode: "pending",
-      });
-      provisional.headers = { ...copilotkit.headers };
-      provisionalAgentCache.current.set(agentId, provisional);
-      return provisional;
-    }
-
-    // No runtime configured and agent doesn't exist — this is a configuration error.
-    const knownAgents = Object.keys(copilotkit.agents ?? {});
-    const runtimePart = isRuntimeConfigured
-      ? `runtimeUrl=${copilotkit.runtimeUrl}`
-      : "no runtimeUrl";
-    throw new Error(
-      `useAgent: Agent '${agentId}' not found after runtime sync (${runtimePart}). ` +
-        (knownAgents.length
-          ? `Known agents: [${knownAgents.join(", ")}]`
-          : "No agents registered.") +
-        " Verify your runtime /info and/or agents__unsafe_dev_only.",
-    );
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [
-    agentId,
-    copilotkit.agents,
-    copilotkit.runtimeConnectionStatus,
-    copilotkit.runtimeUrl,
-    copilotkit.runtimeTransport,
-    JSON.stringify(copilotkit.headers),
-  ]);
-
-  useEffect(() => {
-    if (updateFlags.length === 0) return;
-
-    let active = true;
-    const handlers: SubscribeToAgentSubscriber = {};
-
-    // Microtask-batched forceUpdate: coalesces multiple synchronous
-    // notifications (e.g. OnStateChanged + OnRunStatusChanged firing in the
-    // same tick) into a single React re-render. This prevents the scroll
-    // jumping described in #3499 where rapid unbatched forceUpdate calls
-    // cause brief content height fluctuations during streaming.
-    let batchScheduled = false;
-    const batchedForceUpdate = () => {
-      if (!active) return;
-      if (!batchScheduled) {
-        batchScheduled = true;
-        queueMicrotask(() => {
-          batchScheduled = false;
-          if (active) {
-            forceUpdate();
-          }
-        });
-      }
-    };
-
-    if (updateFlags.includes(UseAgentUpdate.OnMessagesChanged)) {
-      handlers.onMessagesChanged = batchedForceUpdate;
-    }
-
-    if (updateFlags.includes(UseAgentUpdate.OnStateChanged)) {
-      handlers.onStateChanged = batchedForceUpdate;
-    }
-
-    if (updateFlags.includes(UseAgentUpdate.OnRunStatusChanged)) {
-      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 = copilotkit.subscribeToAgentWithOptions(
-      agent,
-      handlers,
-      {
-        throttleMs,
-      },
-    );
-    return () => {
-      active = false;
-      subscription.unsubscribe();
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [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
-  // 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, JSON.stringify(copilotkit.headers)]);
-
-  return {
-    agent,
-  };
-}