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

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

@@ -0,0 +1,311 @@
+/**
+ * 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 "../../providers/CopilotKitProvider";
+import { useFrontendTool } from "../use-frontend-tool";
+import type { ReactToolCallRenderer } from "../../types/react-tool-call-renderer";
+
+vi.mock("../../providers/CopilotKitProvider", () => ({
+  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

@@ -0,0 +1,18 @@
+// 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 { 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";

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

@@ -0,0 +1,45 @@
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+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

@@ -0,0 +1,155 @@
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useMemo, useEffect, useReducer, useRef } from "react";
+import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
+import { AbstractAgent } from "@ag-ui/client";
+import {
+  ProxiedCopilotRuntimeAgent,
+  CopilotKitCoreRuntimeConnectionStatus,
+} 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[];
+}
+
+export function useAgent({ agentId, updates }: UseAgentProps = {}) {
+  agentId ??= DEFAULT_AGENT_ID;
+
+  const { copilotkit } = useCopilotKit();
+  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 provisional = new ProxiedCopilotRuntimeAgent({
+        runtimeUrl: copilotkit.runtimeUrl,
+        agentId,
+        transport: copilotkit.runtimeTransport,
+        runtimeMode: "pending",
+      });
+      provisional.headers = { ...copilotkit.headers };
+      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;
+    }
+
+    const handlers: Parameters<AbstractAgent["subscribe"]>[0] = {};
+
+    if (updateFlags.includes(UseAgentUpdate.OnMessagesChanged)) {
+      // Content stripping for immutableContent renderers is handled by CopilotKitCoreReact
+      handlers.onMessagesChanged = () => {
+        forceUpdate();
+      };
+    }
+
+    if (updateFlags.includes(UseAgentUpdate.OnStateChanged)) {
+      handlers.onStateChanged = forceUpdate;
+    }
+
+    if (updateFlags.includes(UseAgentUpdate.OnRunStatusChanged)) {
+      handlers.onRunInitialized = forceUpdate;
+      handlers.onRunFinalized = forceUpdate;
+      handlers.onRunFailed = forceUpdate;
+    }
+
+    const subscription = agent.subscribe(handlers);
+    return () => subscription.unsubscribe();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [agent, forceUpdate, JSON.stringify(updateFlags)]);
+
+  return {
+    agent,
+  };
+}

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

@@ -0,0 +1,89 @@
+import type { StandardSchemaV1, InferSchemaOutput } from "@copilotkit/shared";
+import type { ComponentType } from "react";
+import { useFrontendTool } from "./use-frontend-tool";
+
+type InferRenderProps<T> = T extends StandardSchemaV1
+  ? InferSchemaOutput<T>
+  : any;
+
+/**
+ * Registers a React component as a frontend tool renderer in chat.
+ *
+ * This hook is a convenience wrapper around `useFrontendTool` that:
+ * - builds a model-facing tool description,
+ * - forwards optional schema parameters (any Standard Schema V1 compatible library),
+ * - renders your component with tool call parameters.
+ *
+ * Use this when you want to display a typed visual component for a tool call
+ * without manually wiring a full frontend tool object.
+ *
+ * When `parameters` is provided, render props are inferred from the schema.
+ * When omitted, the render component may accept any props.
+ *
+ * @typeParam TSchema - Schema describing tool parameters, or `undefined` when no schema is given.
+ * @param config - Tool registration config.
+ * @param deps - Optional dependencies to refresh registration (same semantics as `useEffect`).
+ *
+ * @example
+ * ```tsx
+ * // Without parameters — render accepts any props
+ * useComponent({
+ *   name: "showGreeting",
+ *   render: ({ message }: { message: string }) => <div>{message}</div>,
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With parameters — render props inferred from schema
+ * useComponent({
+ *   name: "showWeatherCard",
+ *   parameters: z.object({ city: z.string() }),
+ *   render: ({ city }) => <div>{city}</div>,
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * useComponent(
+ *   {
+ *     name: "renderProfile",
+ *     parameters: z.object({ userId: z.string() }),
+ *     render: ProfileCard,
+ *     agentId: "support-agent",
+ *   },
+ *   [selectedAgentId],
+ * );
+ * ```
+ */
+export function useComponent<
+  TSchema extends StandardSchemaV1 | undefined = undefined,
+>(
+  config: {
+    name: string;
+    description?: string;
+    parameters?: TSchema;
+    render: ComponentType<NoInfer<InferRenderProps<TSchema>>>;
+    agentId?: string;
+  },
+  deps?: ReadonlyArray<unknown>,
+): void {
+  const prefix = `Use this tool to display the "${config.name}" component in the chat. This tool renders a visual UI component for the user.`;
+  const fullDescription = config.description
+    ? `${prefix}\n\n${config.description}`
+    : prefix;
+
+  useFrontendTool(
+    {
+      name: config.name,
+      description: fullDescription,
+      parameters: config.parameters,
+      render: ({ args }: { args: unknown }) => {
+        const Component = config.render;
+        return <Component {...(args as InferRenderProps<TSchema>)} />;
+      },
+      agentId: config.agentId,
+    },
+    deps,
+  );
+}