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

package/src/v2/hooks/use-render-tool-call.tsx

@@ -0,0 +1,175 @@
+import React, { useCallback, useMemo, useSyncExternalStore } from "react";
+import { ToolCall, ToolMessage } from "@ag-ui/core";
+import { ToolCallStatus } from "@copilotkit/core";
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurationProvider";
+import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
+import { partialJSONParse } from "@copilotkit/shared";
+import { ReactToolCallRenderer } from "../types/react-tool-call-renderer";
+
+export interface UseRenderToolCallProps {
+  toolCall: ToolCall;
+  toolMessage?: ToolMessage;
+}
+
+/**
+ * Props for the memoized ToolCallRenderer component
+ */
+interface ToolCallRendererProps {
+  toolCall: ToolCall;
+  toolMessage?: ToolMessage;
+  RenderComponent: ReactToolCallRenderer<unknown>["render"];
+  isExecuting: boolean;
+}
+
+/**
+ * Memoized component that renders a single tool call.
+ * This prevents unnecessary re-renders when parent components update
+ * but the tool call data hasn't changed.
+ */
+const ToolCallRenderer = React.memo(
+  function ToolCallRenderer({
+    toolCall,
+    toolMessage,
+    RenderComponent,
+    isExecuting,
+  }: ToolCallRendererProps) {
+    // Memoize args based on the arguments string to maintain stable reference
+    const args = useMemo(
+      () => partialJSONParse(toolCall.function.arguments),
+      [toolCall.function.arguments],
+    );
+
+    const toolName = toolCall.function.name;
+
+    // Render based on status to preserve discriminated union type inference
+    if (toolMessage) {
+      return (
+        <RenderComponent
+          name={toolName}
+          args={args}
+          status={ToolCallStatus.Complete}
+          result={toolMessage.content}
+        />
+      );
+    } else if (isExecuting) {
+      return (
+        <RenderComponent
+          name={toolName}
+          args={args}
+          status={ToolCallStatus.Executing}
+          result={undefined}
+        />
+      );
+    } else {
+      return (
+        <RenderComponent
+          name={toolName}
+          args={args}
+          status={ToolCallStatus.InProgress}
+          result={undefined}
+        />
+      );
+    }
+  },
+  // Custom comparison function to prevent re-renders when tool call data hasn't changed
+  (prevProps, nextProps) => {
+    // Compare tool call identity and content
+    if (prevProps.toolCall.id !== nextProps.toolCall.id) return false;
+    if (prevProps.toolCall.function.name !== nextProps.toolCall.function.name)
+      return false;
+    if (
+      prevProps.toolCall.function.arguments !==
+      nextProps.toolCall.function.arguments
+    )
+      return false;
+
+    // Compare tool message (result)
+    const prevResult = prevProps.toolMessage?.content;
+    const nextResult = nextProps.toolMessage?.content;
+    if (prevResult !== nextResult) return false;
+
+    // Compare executing state
+    if (prevProps.isExecuting !== nextProps.isExecuting) return false;
+
+    // Compare render component reference
+    if (prevProps.RenderComponent !== nextProps.RenderComponent) return false;
+
+    return true;
+  },
+);
+
+/**
+ * Hook that returns a function to render tool calls based on the render functions
+ * defined in CopilotKitProvider.
+ *
+ * @returns A function that takes a tool call and optional tool message and returns the rendered component
+ */
+export function useRenderToolCall() {
+  const { copilotkit, executingToolCallIds } = useCopilotKit();
+  const config = useCopilotChatConfiguration();
+  const agentId = config?.agentId ?? DEFAULT_AGENT_ID;
+
+  // Subscribe to render tool calls changes using useSyncExternalStore
+  // This ensures we always have the latest value, even if subscriptions run in any order
+  const renderToolCalls = useSyncExternalStore(
+    (callback) => {
+      return copilotkit.subscribe({
+        onRenderToolCallsChanged: callback,
+      }).unsubscribe;
+    },
+    () => copilotkit.renderToolCalls,
+    () => copilotkit.renderToolCalls,
+  );
+
+  // Note: executingToolCallIds is now provided by CopilotKitProvider context.
+  // This is critical for HITL reconnection: when connecting to a thread with
+  // pending tool calls, the onToolExecutionStart event fires before child components
+  // mount. By tracking at the provider level, the executing state is already
+  // available when this hook first runs.
+
+  const renderToolCall = useCallback(
+    ({
+      toolCall,
+      toolMessage,
+    }: UseRenderToolCallProps): React.ReactElement | null => {
+      // Find the render config for this tool call by name
+      // For rendering, we show all tool calls regardless of agentId
+      // The agentId scoping only affects handler execution (in core)
+      // Priority order:
+      // 1. Exact match by name (prefer agent-specific if multiple exist)
+      // 2. Wildcard (*) renderer
+      const exactMatches = renderToolCalls.filter(
+        (rc) => rc.name === toolCall.function.name,
+      );
+
+      // If multiple renderers with same name exist, prefer the one matching our agentId
+      const renderConfig =
+        exactMatches.find((rc) => rc.agentId === agentId) ||
+        exactMatches.find((rc) => !rc.agentId) ||
+        exactMatches[0] ||
+        renderToolCalls.find((rc) => rc.name === "*");
+
+      if (!renderConfig) {
+        return null;
+      }
+
+      const RenderComponent = renderConfig.render;
+      const isExecuting = executingToolCallIds.has(toolCall.id);
+
+      // Use the memoized ToolCallRenderer component to prevent unnecessary re-renders
+      return (
+        <ToolCallRenderer
+          key={toolCall.id}
+          toolCall={toolCall}
+          toolMessage={toolMessage}
+          RenderComponent={RenderComponent}
+          isExecuting={isExecuting}
+        />
+      );
+    },
+    [renderToolCalls, executingToolCallIds, agentId],
+  );
+
+  return renderToolCall;
+}

package/src/v2/hooks/use-render-tool.tsx

@@ -0,0 +1,181 @@
+import { useEffect } from "react";
+import type { StandardSchemaV1, InferSchemaOutput } from "@copilotkit/shared";
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { defineToolCallRenderer } from "../types/defineToolCallRenderer";
+
+const EMPTY_DEPS: ReadonlyArray<unknown> = [];
+
+export interface RenderToolInProgressProps<S extends StandardSchemaV1> {
+  name: string;
+  parameters: Partial<InferSchemaOutput<S>>;
+  status: "inProgress";
+  result: undefined;
+}
+
+export interface RenderToolExecutingProps<S extends StandardSchemaV1> {
+  name: string;
+  parameters: InferSchemaOutput<S>;
+  status: "executing";
+  result: undefined;
+}
+
+export interface RenderToolCompleteProps<S extends StandardSchemaV1> {
+  name: string;
+  parameters: InferSchemaOutput<S>;
+  status: "complete";
+  result: string;
+}
+
+export type RenderToolProps<S extends StandardSchemaV1> =
+  | RenderToolInProgressProps<S>
+  | RenderToolExecutingProps<S>
+  | RenderToolCompleteProps<S>;
+
+type RenderToolConfig<S extends StandardSchemaV1> = {
+  name: string;
+  parameters?: S;
+  render: (props: RenderToolProps<S>) => React.ReactElement;
+  agentId?: string;
+};
+
+/**
+ * Registers a wildcard (`"*"`) renderer for tool calls.
+ *
+ * The wildcard renderer is used as a fallback when no exact name-matched
+ * renderer is registered for a tool call.
+ *
+ * @param config - Wildcard renderer configuration.
+ * @param deps - Optional dependencies to refresh registration.
+ *
+ * @example
+ * ```tsx
+ * useRenderTool(
+ *   {
+ *     name: "*",
+ *     render: ({ name, status }) => (
+ *       <div>
+ *         {status === "complete" ? "✓" : "⏳"} {name}
+ *       </div>
+ *     ),
+ *   },
+ *   [],
+ * );
+ * ```
+ */
+export function useRenderTool(
+  config: {
+    name: "*";
+    render: (props: any) => React.ReactElement;
+    agentId?: string;
+  },
+  deps?: ReadonlyArray<unknown>,
+): void;
+
+/**
+ * Registers a name-scoped renderer for tool calls.
+ *
+ * The provided `parameters` schema defines the typed shape of `props.parameters`
+ * in `render` for `executing` and `complete` states. Accepts any Standard Schema V1
+ * compatible library (Zod, Valibot, ArkType, etc.).
+ *
+ * @typeParam S - Schema type describing tool call parameters.
+ * @param config - Named renderer configuration.
+ * @param deps - Optional dependencies to refresh registration.
+ *
+ * @example
+ * ```tsx
+ * useRenderTool(
+ *   {
+ *     name: "searchDocs",
+ *     parameters: z.object({ query: z.string() }),
+ *     render: ({ status, parameters, result }) => {
+ *       if (status === "inProgress") return <div>Preparing...</div>;
+ *       if (status === "executing") return <div>Searching {parameters.query}</div>;
+ *       return <div>{result}</div>;
+ *     },
+ *   },
+ *   [],
+ * );
+ * ```
+ */
+export function useRenderTool<S extends StandardSchemaV1>(
+  config: {
+    name: string;
+    parameters: S;
+    render: (props: RenderToolProps<S>) => React.ReactElement;
+    agentId?: string;
+  },
+  deps?: ReadonlyArray<unknown>,
+): void;
+
+/**
+ * Registers a renderer entry in CopilotKit's `renderToolCalls` registry.
+ *
+ * Key behavior:
+ * - deduplicates by `agentId:name` (latest registration wins),
+ * - keeps renderer entries on cleanup so historical chat tool calls can still render,
+ * - refreshes registration when `deps` change.
+ *
+ * @typeParam S - Schema type describing tool call parameters.
+ * @param config - Renderer config for wildcard or named tools.
+ * @param deps - Optional dependencies to refresh registration.
+ *
+ * @example
+ * ```tsx
+ * useRenderTool(
+ *   {
+ *     name: "searchDocs",
+ *     parameters: z.object({ query: z.string() }),
+ *     render: ({ status, parameters, result }) => {
+ *       if (status === "executing") return <div>Searching {parameters.query}</div>;
+ *       if (status === "complete") return <div>{result}</div>;
+ *       return <div>Preparing...</div>;
+ *     },
+ *   },
+ *   [],
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * useRenderTool(
+ *   {
+ *     name: "summarize",
+ *     parameters: z.object({ text: z.string() }),
+ *     agentId: "research-agent",
+ *     render: ({ name, status }) => <div>{name}: {status}</div>,
+ *   },
+ *   [selectedAgentId],
+ * );
+ * ```
+ */
+export function useRenderTool<S extends StandardSchemaV1>(
+  config: RenderToolConfig<S>,
+  deps?: ReadonlyArray<unknown>,
+): void {
+  const { copilotkit } = useCopilotKit();
+  const extraDeps = deps ?? EMPTY_DEPS;
+
+  useEffect(() => {
+    // Build the ReactToolCallRenderer via defineToolCallRenderer
+    const renderer =
+      config.name === "*" && !config.parameters
+        ? defineToolCallRenderer({
+            name: "*",
+            render: (props) =>
+              config.render({ ...props, parameters: props.args }),
+            ...(config.agentId ? { agentId: config.agentId } : {}),
+          })
+        : defineToolCallRenderer({
+            name: config.name,
+            args: config.parameters!,
+            render: (props) =>
+              config.render({ ...props, parameters: props.args }),
+            ...(config.agentId ? { agentId: config.agentId } : {}),
+          });
+
+    copilotkit.addHookRenderToolCall(renderer);
+
+    // No cleanup removal — keeps renderer for chat history, same as useFrontendTool
+  }, [config.name, copilotkit, extraDeps.length, ...extraDeps]);
+}

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

@@ -0,0 +1,91 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Suggestion } from "@copilotkit/core";
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurationProvider";
+import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
+
+export interface UseSuggestionsOptions {
+  agentId?: string;
+}
+
+export interface UseSuggestionsResult {
+  suggestions: Suggestion[];
+  reloadSuggestions: () => void;
+  clearSuggestions: () => void;
+  isLoading: boolean;
+}
+
+export function useSuggestions({
+  agentId,
+}: UseSuggestionsOptions = {}): UseSuggestionsResult {
+  const { copilotkit } = useCopilotKit();
+  const config = useCopilotChatConfiguration();
+  const resolvedAgentId = useMemo(
+    () => agentId ?? config?.agentId ?? DEFAULT_AGENT_ID,
+    [agentId, config?.agentId],
+  );
+
+  const [suggestions, setSuggestions] = useState<Suggestion[]>(() => {
+    const result = copilotkit.getSuggestions(resolvedAgentId);
+    return result.suggestions;
+  });
+  const [isLoading, setIsLoading] = useState(() => {
+    const result = copilotkit.getSuggestions(resolvedAgentId);
+    return result.isLoading;
+  });
+
+  useEffect(() => {
+    const result = copilotkit.getSuggestions(resolvedAgentId);
+    setSuggestions(result.suggestions);
+    setIsLoading(result.isLoading);
+  }, [copilotkit, resolvedAgentId]);
+
+  useEffect(() => {
+    const subscription = copilotkit.subscribe({
+      onSuggestionsChanged: ({ agentId: changedAgentId, suggestions }) => {
+        if (changedAgentId !== resolvedAgentId) {
+          return;
+        }
+        setSuggestions(suggestions);
+      },
+      onSuggestionsStartedLoading: ({ agentId: changedAgentId }) => {
+        if (changedAgentId !== resolvedAgentId) {
+          return;
+        }
+        setIsLoading(true);
+      },
+      onSuggestionsFinishedLoading: ({ agentId: changedAgentId }) => {
+        if (changedAgentId !== resolvedAgentId) {
+          return;
+        }
+        setIsLoading(false);
+      },
+      onSuggestionsConfigChanged: () => {
+        const result = copilotkit.getSuggestions(resolvedAgentId);
+        setSuggestions(result.suggestions);
+        setIsLoading(result.isLoading);
+      },
+    });
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [copilotkit, resolvedAgentId]);
+
+  const reloadSuggestions = useCallback(() => {
+    copilotkit.reloadSuggestions(resolvedAgentId);
+    // Loading state is handled by onSuggestionsStartedLoading event
+  }, [copilotkit, resolvedAgentId]);
+
+  const clearSuggestions = useCallback(() => {
+    copilotkit.clearSuggestions(resolvedAgentId);
+    // State updates are handled by onSuggestionsChanged event
+  }, [copilotkit, resolvedAgentId]);
+
+  return {
+    suggestions,
+    reloadSuggestions,
+    clearSuggestions,
+    isLoading,
+  };
+}

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

@@ -0,0 +1,256 @@
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+import {
+  ɵcreateThreadStore,
+  ɵselectThreads,
+  ɵselectThreadsError,
+  ɵselectThreadsIsLoading,
+  ɵselectHasNextPage,
+  ɵselectIsFetchingNextPage,
+  type ɵThread as CoreThread,
+  type ɵThreadRuntimeContext,
+  type ɵThreadStore,
+} from "@copilotkit/core";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from "react";
+
+/**
+ * A conversation thread managed by the Intelligence platform.
+ *
+ * Each thread has a unique `id`, an optional human-readable `name`, and
+ * timestamp fields tracking creation and update times.
+ */
+export interface Thread extends CoreThread {}
+
+/**
+ * Configuration for the {@link useThreads} hook.
+ *
+ * Thread operations are scoped to the runtime-authenticated user and the
+ * provided agent on the Intelligence platform.
+ */
+export interface UseThreadsInput {
+  /** The ID of the agent whose threads to list and manage. */
+  agentId: string;
+  /** When `true`, archived threads are included in the list. Defaults to `false`. */
+  includeArchived?: boolean;
+  /** Maximum number of threads to fetch per page. When set, enables cursor-based pagination. */
+  limit?: number;
+}
+
+/**
+ * Return value of the {@link useThreads} hook.
+ *
+ * The `threads` array is kept in sync with the platform via a realtime
+ * WebSocket subscription (when available) and is sorted most-recently-updated
+ * first. Mutations reject with an `Error` if the platform request fails.
+ */
+export interface UseThreadsResult {
+  /**
+   * Threads for the current user/agent pair, sorted by most recently
+   * updated first. Updated in realtime when the platform pushes metadata
+   * events. Includes archived threads only when `includeArchived` is set.
+   */
+  threads: Thread[];
+  /**
+   * `true` while the initial thread list is being fetched from the platform.
+   * Subsequent realtime updates do not re-enter the loading state.
+   */
+  isLoading: boolean;
+  /**
+   * The most recent error from fetching threads or executing a mutation,
+   * or `null` when there is no error. Reset to `null` on the next
+   * successful fetch.
+   */
+  error: Error | null;
+  /**
+   * `true` when there are more threads available to fetch via
+   * {@link fetchNextPage}. Only meaningful when `limit` is set.
+   */
+  hasNextPage: boolean;
+  /**
+   * `true` while a subsequent page of threads is being fetched.
+   */
+  isFetchingNextPage: boolean;
+  /**
+   * Fetch the next page of threads. No-op when {@link hasNextPage} is
+   * `false` or a page fetch is already in progress.
+   */
+  fetchNextPage: () => void;
+  /**
+   * Rename a thread on the platform.
+   * Resolves when the server confirms the update; rejects on failure.
+   */
+  renameThread: (threadId: string, name: string) => Promise<void>;
+  /**
+   * Archive a thread on the platform.
+   * Archived threads are excluded from subsequent list results.
+   * Resolves when the server confirms the update; rejects on failure.
+   */
+  archiveThread: (threadId: string) => Promise<void>;
+  /**
+   * Permanently delete a thread from the platform.
+   * This is irreversible. Resolves when the server confirms deletion;
+   * rejects on failure.
+   */
+  deleteThread: (threadId: string) => Promise<void>;
+}
+
+function useThreadStoreSelector<T>(
+  store: ɵThreadStore,
+  selector: (state: ReturnType<ɵThreadStore["getState"]>) => T,
+): T {
+  return useSyncExternalStore(
+    useCallback(
+      (onStoreChange) => {
+        const subscription = store.select(selector).subscribe(onStoreChange);
+        return () => subscription.unsubscribe();
+      },
+      [store, selector],
+    ),
+    () => selector(store.getState()),
+  );
+}
+
+/**
+ * React hook for listing and managing Intelligence platform threads.
+ *
+ * On mount the hook fetches the thread list for the runtime-authenticated user
+ * and the given `agentId`. When the Intelligence platform exposes a WebSocket
+ * URL, it also opens a realtime subscription so the `threads` array stays
+ * current without polling — thread creates, renames, archives, and deletes
+ * from any client are reflected immediately.
+ *
+ * Mutation methods (`renameThread`, `archiveThread`, `deleteThread`) return
+ * promises that resolve once the platform confirms the operation and reject
+ * with an `Error` on failure.
+ *
+ * @param input - Agent identifier and optional list controls.
+ * @returns Thread list state and stable mutation callbacks.
+ *
+ * @example
+ * ```tsx
+ * import { useThreads } from "@copilotkit/react-core";
+ *
+ * function ThreadList() {
+ *   const { threads, isLoading, renameThread, deleteThread } = useThreads({
+ *     agentId: "agent-1",
+ *   });
+ *
+ *   if (isLoading) return <p>Loading…</p>;
+ *
+ *   return (
+ *     <ul>
+ *       {threads.map((t) => (
+ *         <li key={t.id}>
+ *           {t.name ?? "Untitled"}
+ *           <button onClick={() => renameThread(t.id, "New name")}>Rename</button>
+ *           <button onClick={() => deleteThread(t.id)}>Delete</button>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function useThreads({
+  agentId,
+  includeArchived,
+  limit,
+}: UseThreadsInput): UseThreadsResult {
+  const { copilotkit } = useCopilotKit();
+
+  const [store] = useState(() =>
+    ɵcreateThreadStore({
+      fetch: globalThis.fetch,
+    }),
+  );
+
+  const threads = useThreadStoreSelector(store, ɵselectThreads);
+  const storeIsLoading = useThreadStoreSelector(store, ɵselectThreadsIsLoading);
+  const storeError = useThreadStoreSelector(store, ɵselectThreadsError);
+  const hasNextPage = useThreadStoreSelector(store, ɵselectHasNextPage);
+  const isFetchingNextPage = useThreadStoreSelector(
+    store,
+    ɵselectIsFetchingNextPage,
+  );
+  const headersKey = useMemo(() => {
+    return JSON.stringify(
+      Object.entries(copilotkit.headers ?? {}).sort(([left], [right]) =>
+        left.localeCompare(right),
+      ),
+    );
+  }, [copilotkit.headers]);
+  const runtimeError = useMemo(() => {
+    if (copilotkit.runtimeUrl) {
+      return null;
+    }
+
+    return new Error("Runtime URL is not configured");
+  }, [copilotkit.runtimeUrl]);
+  const isLoading = runtimeError ? false : storeIsLoading;
+  const error = runtimeError ?? storeError;
+
+  useEffect(() => {
+    store.start();
+    return () => {
+      store.stop();
+    };
+  }, [store]);
+
+  useEffect(() => {
+    const context: ɵThreadRuntimeContext | null = copilotkit.runtimeUrl
+      ? {
+          runtimeUrl: copilotkit.runtimeUrl,
+          headers: { ...copilotkit.headers },
+          wsUrl: copilotkit.intelligence?.wsUrl,
+          agentId,
+          includeArchived,
+          limit,
+        }
+      : null;
+
+    store.setContext(context);
+  }, [
+    store,
+    copilotkit.runtimeUrl,
+    headersKey,
+    copilotkit.intelligence?.wsUrl,
+    agentId,
+    copilotkit.headers,
+    includeArchived,
+    limit,
+  ]);
+
+  const renameThread = useCallback(
+    (threadId: string, name: string) => store.renameThread(threadId, name),
+    [store],
+  );
+
+  const archiveThread = useCallback(
+    (threadId: string) => store.archiveThread(threadId),
+    [store],
+  );
+
+  const deleteThread = useCallback(
+    (threadId: string) => store.deleteThread(threadId),
+    [store],
+  );
+
+  const fetchNextPage = useCallback(() => store.fetchNextPage(), [store]);
+
+  return {
+    threads,
+    isLoading,
+    error,
+    hasNextPage,
+    isFetchingNextPage,
+    fetchNextPage,
+    renameThread,
+    archiveThread,
+    deleteThread,
+  };
+}