@copilotkit/react-core 1.57.3 → 1.58.0

package/src/hooks/use-copilot-readable.ts

@@ -1,135 +0,0 @@
-/**
- * `useCopilotReadable` is a React hook that provides app-state and other information
- * to the Copilot. Optionally, the hook can also handle hierarchical state within your
- * application, passing these parent-child relationships to the Copilot.
- *
- * ## Usage
- *
- * ### Simple Usage
- *
- * In its most basic usage, useCopilotReadable accepts a single string argument
- * representing any piece of app state, making it available for the Copilot to use
- * as context when responding to user input.
- *
- * ```tsx
- * import { useCopilotReadable } from "@copilotkit/react-core";
- *
- * export function MyComponent() {
- *   const [employees, setEmployees] = useState([]);
- *
- *   useCopilotReadable({
- *     description: "The list of employees",
- *     value: employees,
- *   });
- * }
- * ```
- *
- * ### Nested Components
- *
- * Optionally, you can maintain the hierarchical structure of information by passing
- * `parentId`. This allows you to use `useCopilotReadable` in nested components:
- *
- * ```tsx /employeeContextId/1 {17,23}
- * import { useCopilotReadable } from "@copilotkit/react-core";
- *
- * function Employee(props: EmployeeProps) {
- *   const { employeeName, workProfile, metadata } = props;
- *
- *   // propagate any information to copilot
- *   const employeeContextId = useCopilotReadable({
- *     description: "Employee name",
- *     value: employeeName
- *   });
- *
- *   // Pass a parentID to maintain a hierarchical structure.
- *   // Especially useful with child React components, list elements, etc.
- *   useCopilotReadable({
- *     description: "Work profile",
- *     value: workProfile.description(),
- *     parentId: employeeContextId
- *   });
- *
- *   useCopilotReadable({
- *     description: "Employee metadata",
- *     value: metadata.description(),
- *     parentId: employeeContextId
- *   });
- *
- *   return (
- *     // Render as usual...
- *   );
- * }
- * ```
- */
-import { useCopilotKit } from "../v2";
-import { useEffect, useRef } from "react";
-
-/**
- * Options for the useCopilotReadable hook.
- */
-export interface UseCopilotReadableOptions {
-  /**
-   * The description of the information to be added to the Copilot context.
-   */
-  description: string;
-  /**
-   * The value to be added to the Copilot context. Object values are automatically stringified.
-   */
-  value: any;
-  /**
-   * The ID of the parent context, if any.
-   */
-  parentId?: string;
-  /**
-   * An array of categories to control which context are visible where. Particularly useful
-   * with CopilotTextarea (see `useMakeAutosuggestionFunction`)
-   */
-  categories?: string[];
-
-  /**
-   * Whether the context is available to the Copilot.
-   */
-  available?: "enabled" | "disabled";
-
-  /**
-   * A custom conversion function to use to serialize the value to a string. If not provided, the value
-   * will be serialized using `JSON.stringify`.
-   */
-  convert?: (description: string, value: any) => string;
-}
-
-/**
- * Adds the given information to the Copilot context to make it readable by Copilot.
- */
-export function useCopilotReadable(
-  { description, value, convert, available }: UseCopilotReadableOptions,
-  dependencies?: any[],
-): string | undefined {
-  const { copilotkit } = useCopilotKit();
-  const ctxIdRef = useRef<string | undefined>(undefined);
-  useEffect(() => {
-    if (!copilotkit) return;
-
-    const found = Object.entries(copilotkit.context).find(([id, ctxItem]) => {
-      return JSON.stringify({ description, value }) == JSON.stringify(ctxItem);
-    });
-    if (found) {
-      ctxIdRef.current = found[0];
-      if (available === "disabled") copilotkit.removeContext(ctxIdRef.current);
-      return;
-    }
-    if (!found && available === "disabled") return;
-
-    ctxIdRef.current = copilotkit.addContext({
-      description,
-      value: (convert ?? JSON.stringify)(value),
-    });
-
-    return () => {
-      if (!ctxIdRef.current) return;
-      copilotkit.removeContext(ctxIdRef.current);
-    };
-  }, [description, value, convert]);
-
-  return ctxIdRef.current;
-}

package/src/hooks/use-copilot-runtime-client.ts

@@ -1,178 +0,0 @@
-import {
-  CopilotRuntimeClient,
-  CopilotRuntimeClientOptions,
-  GraphQLError,
-} from "@copilotkit/runtime-client-gql";
-import { useToast } from "../components/toast/toast-provider";
-import { useMemo, useRef } from "react";
-import {
-  ErrorVisibility,
-  CopilotKitApiDiscoveryError,
-  CopilotKitRemoteEndpointDiscoveryError,
-  CopilotKitAgentDiscoveryError,
-  CopilotKitError,
-  CopilotKitErrorCode,
-  CopilotErrorHandler,
-  CopilotErrorEvent,
-} from "@copilotkit/shared";
-import { shouldShowDevConsole } from "../utils/dev-console";
-
-export interface CopilotRuntimeClientHookOptions extends CopilotRuntimeClientOptions {
-  showDevConsole?: boolean;
-  onError: CopilotErrorHandler;
-}
-
-export const useCopilotRuntimeClient = (
-  options: CopilotRuntimeClientHookOptions,
-) => {
-  const { setBannerError } = useToast();
-  const { showDevConsole, onError, ...runtimeOptions } = options;
-
-  // Deduplication state for structured errors
-  const lastStructuredErrorRef = useRef<{
-    message: string;
-    timestamp: number;
-  } | null>(null);
-
-  // Helper function to trace UI errors
-  const traceUIError = async (error: CopilotKitError, originalError?: any) => {
-    try {
-      const errorEvent: CopilotErrorEvent = {
-        type: "error",
-        timestamp: Date.now(),
-        context: {
-          source: "ui",
-          request: {
-            operation: "runtimeClient",
-            url: runtimeOptions.url,
-            startTime: Date.now(),
-          },
-          technical: {
-            environment: "browser",
-            userAgent:
-              typeof navigator !== "undefined"
-                ? navigator.userAgent
-                : undefined,
-            stackTrace:
-              originalError instanceof Error ? originalError.stack : undefined,
-          },
-        },
-        error,
-      };
-      await onError(errorEvent);
-    } catch (error) {
-      console.error("Error in onError handler:", error);
-    }
-  };
-
-  const runtimeClient = useMemo(() => {
-    return new CopilotRuntimeClient({
-      ...runtimeOptions,
-      handleGQLErrors: (error) => {
-        if ((error as any).graphQLErrors?.length) {
-          const graphQLErrors = (error as any).graphQLErrors as GraphQLError[];
-
-          // Route all errors to banners for consistent UI
-          const routeError = (gqlError: GraphQLError) => {
-            const extensions = gqlError.extensions;
-            const visibility = extensions?.visibility as ErrorVisibility;
-
-            // Silent errors - just log
-            if (visibility === ErrorVisibility.SILENT) {
-              console.error("CopilotKit Silent Error:", gqlError.message);
-              return;
-            }
-
-            // All errors (including DEV_ONLY) show as banners for consistency
-            // Deduplicate to prevent spam
-            const now = Date.now();
-            const errorMessage = gqlError.message;
-            if (
-              lastStructuredErrorRef.current &&
-              lastStructuredErrorRef.current.message === errorMessage &&
-              now - lastStructuredErrorRef.current.timestamp < 150
-            ) {
-              return; // Skip duplicate
-            }
-            lastStructuredErrorRef.current = {
-              message: errorMessage,
-              timestamp: now,
-            };
-
-            const ckError = createStructuredError(gqlError);
-            if (ckError) {
-              setBannerError(ckError);
-              // Trace the error
-              traceUIError(ckError, gqlError);
-              // TODO: if onError & renderError should work without key, insert here
-            } else {
-              // Fallback for unstructured errors
-              const fallbackError = new CopilotKitError({
-                message: gqlError.message,
-                code: CopilotKitErrorCode.UNKNOWN,
-              });
-              setBannerError(fallbackError);
-              // Trace the fallback error
-              traceUIError(fallbackError, gqlError);
-              // TODO: if onError & renderError should work without key, insert here
-            }
-          };
-
-          // Process all errors as banners
-          graphQLErrors.forEach(routeError);
-        } else {
-          // Route non-GraphQL errors to banner as well
-          const fallbackError = new CopilotKitError({
-            message: error?.message || String(error),
-            code: CopilotKitErrorCode.UNKNOWN,
-          });
-          setBannerError(fallbackError);
-          // Trace the non-GraphQL error
-          traceUIError(fallbackError, error);
-          // TODO: if onError & renderError should work without key, insert here
-        }
-      },
-      handleGQLWarning: (message: string) => {
-        console.warn(message);
-        // Show warnings as banners too for consistency
-        const warningError = new CopilotKitError({
-          message,
-          code: CopilotKitErrorCode.UNKNOWN,
-        });
-        setBannerError(warningError);
-      },
-    });
-  }, [runtimeOptions, setBannerError, onError]);
-
-  return runtimeClient;
-};
-
-// Create appropriate structured error from GraphQL error
-function createStructuredError(gqlError: GraphQLError): CopilotKitError | null {
-  const extensions = gqlError.extensions;
-  const originalError = extensions?.originalError as any;
-  const message = originalError?.message || gqlError.message;
-  const code = extensions?.code as CopilotKitErrorCode;
-
-  if (code) {
-    return new CopilotKitError({ message, code });
-  }
-
-  // Legacy error detection by stack trace
-  if (originalError?.stack?.includes("CopilotApiDiscoveryError")) {
-    return new CopilotKitApiDiscoveryError({ message });
-  }
-  if (
-    originalError?.stack?.includes("CopilotKitRemoteEndpointDiscoveryError")
-  ) {
-    return new CopilotKitRemoteEndpointDiscoveryError({ message });
-  }
-  if (originalError?.stack?.includes("CopilotKitAgentDiscoveryError")) {
-    return new CopilotKitAgentDiscoveryError({
-      agentName: "",
-      availableAgents: [],
-    });
-  }
-
-  return null;
-}

package/src/hooks/use-default-tool.ts

@@ -1,13 +0,0 @@
-import { useCopilotAction } from "./use-copilot-action";
-import { CatchAllFrontendAction } from "../types/frontend-action";
-
-export function useDefaultTool(
-  tool: Omit<CatchAllFrontendAction, "name">,
-  dependencies?: any[],
-) {
-  // Use the existing useCopilotAction hook
-  useCopilotAction(
-    { ...tool, name: "*" } satisfies CatchAllFrontendAction,
-    dependencies,
-  );
-}

package/src/hooks/use-flat-category-store.ts

@@ -1,109 +0,0 @@
-import { useCallback, useReducer } from "react";
-import { randomId } from "@copilotkit/shared";
-
-export type FlatCategoryStoreId = string;
-
-export interface UseFlatCategoryStoreReturn<T> {
-  addElement: (value: T, categories: string[]) => FlatCategoryStoreId;
-  removeElement: (id: FlatCategoryStoreId) => void;
-  allElements: (categories: string[]) => T[];
-}
-
-interface FlatCategoryStoreElement<T> {
-  id: FlatCategoryStoreId;
-  value: T;
-  categories: Set<string>;
-}
-
-const useFlatCategoryStore = <T>(): UseFlatCategoryStoreReturn<T> => {
-  const [elements, dispatch] = useReducer(
-    flatCategoryStoreReducer<T>,
-    new Map<FlatCategoryStoreId, FlatCategoryStoreElement<T>>(),
-  );
-
-  const addElement = useCallback(
-    (value: T, categories: string[]): FlatCategoryStoreId => {
-      const newId = randomId();
-      dispatch({
-        type: "ADD_ELEMENT",
-        value,
-        id: newId,
-        categories,
-      });
-      return newId;
-    },
-    [],
-  );
-
-  const removeElement = useCallback((id: FlatCategoryStoreId): void => {
-    dispatch({ type: "REMOVE_ELEMENT", id });
-  }, []);
-
-  const allElements = useCallback(
-    (categories: string[]): T[] => {
-      const categoriesSet = new Set(categories);
-      const result: T[] = [];
-      elements.forEach((element) => {
-        if (setsHaveIntersection(categoriesSet, element.categories)) {
-          result.push(element.value);
-        }
-      });
-      return result;
-    },
-    [elements],
-  );
-
-  return { addElement, removeElement, allElements };
-};
-
-export default useFlatCategoryStore;
-
-// Action types
-type Action<T> =
-  | {
-      type: "ADD_ELEMENT";
-      value: T;
-      id: FlatCategoryStoreId;
-      categories: string[];
-    }
-  | { type: "REMOVE_ELEMENT"; id: FlatCategoryStoreId };
-
-// Reducer
-function flatCategoryStoreReducer<T>(
-  state: Map<FlatCategoryStoreId, FlatCategoryStoreElement<T>>,
-  action: Action<T>,
-): Map<FlatCategoryStoreId, FlatCategoryStoreElement<T>> {
-  switch (action.type) {
-    case "ADD_ELEMENT": {
-      const { value, id, categories } = action;
-      const newElement: FlatCategoryStoreElement<T> = {
-        id,
-        value,
-        categories: new Set(categories),
-      };
-      const newState = new Map(state);
-      newState.set(id, newElement);
-      return newState;
-    }
-    case "REMOVE_ELEMENT": {
-      const newState = new Map(state);
-      newState.delete(action.id);
-      return newState;
-    }
-    default:
-      return state;
-  }
-}
-
-function setsHaveIntersection<T>(setA: Set<T>, setB: Set<T>): boolean {
-  const [smallerSet, largerSet] =
-    setA.size <= setB.size ? [setA, setB] : [setB, setA];
-
-  for (let item of smallerSet) {
-    if (largerSet.has(item)) {
-      return true;
-    }
-  }
-
-  return false;
-}

package/src/hooks/use-frontend-tool.ts

@@ -1,113 +0,0 @@
-import React, { useEffect, useMemo, useRef } from "react";
-import { ActionRenderProps, FrontendAction } from "../types/frontend-action";
-import {
-  Parameter,
-  getZodParameters,
-  MappedParameterTypes,
-} from "@copilotkit/shared";
-import { parseJson } from "@copilotkit/shared";
-import { ToolCallStatus } from "@copilotkit/core";
-import {
-  type ReactFrontendTool,
-  useFrontendTool as useFrontendToolVNext,
-} from "../v2";
-
-type FrontendToolOptions<T extends Parameter[] | []> = ReactFrontendTool<
-  MappedParameterTypes<T>
->;
-type FrontendToolRenderArgs<T extends Parameter[] | []> =
-  | {
-      name: string;
-      args: Partial<MappedParameterTypes<T>>;
-      status: ToolCallStatus.InProgress;
-      result: undefined;
-    }
-  | {
-      name: string;
-      args: MappedParameterTypes<T>;
-      status: ToolCallStatus.Executing;
-      result: undefined;
-    }
-  | {
-      name: string;
-      args: MappedParameterTypes<T>;
-      status: ToolCallStatus.Complete;
-      result: string;
-    };
-
-export type UseFrontendToolArgs<T extends Parameter[] | [] = []> = {
-  available?: "disabled" | "enabled";
-} & Pick<
-  FrontendAction<T>,
-  "name" | "description" | "parameters" | "handler" | "followUp" | "render"
->;
-
-export function useFrontendTool<const T extends Parameter[] = []>(
-  tool: UseFrontendToolArgs<T>,
-  dependencies?: any[],
-) {
-  const { name, description, parameters, render, followUp, available } = tool;
-  const zodParameters = getZodParameters(parameters);
-
-  const renderRef = useRef<typeof render>(render);
-
-  useEffect(() => {
-    renderRef.current = render;
-  }, [render, ...(dependencies ?? [])]);
-
-  const normalizedRender: FrontendToolOptions<T>["render"] | undefined =
-    useMemo(() => {
-      if (typeof render === "undefined") {
-        return undefined;
-      }
-
-      return ((args: FrontendToolRenderArgs<T>) => {
-        const currentRender = renderRef.current;
-
-        if (typeof currentRender === "undefined") {
-          return null;
-        }
-
-        if (typeof currentRender === "string") {
-          return React.createElement(React.Fragment, null, currentRender);
-        }
-
-        const renderArgs = {
-          ...args,
-          result:
-            typeof args.result === "string"
-              ? parseJson(args.result, args.result)
-              : args.result,
-        } as ActionRenderProps<T>;
-
-        const rendered = currentRender(renderArgs);
-
-        if (typeof rendered === "string") {
-          return React.createElement(React.Fragment, null, rendered);
-        }
-
-        return rendered ?? null;
-      }) as FrontendToolOptions<T>["render"];
-    }, []);
-
-  // Handler ref to avoid stale closures
-  const handlerRef = useRef<typeof tool.handler>(tool.handler);
-
-  useEffect(() => {
-    handlerRef.current = tool.handler;
-  }, [tool.handler, ...(dependencies ?? [])]);
-
-  const normalizedHandler = tool.handler
-    ? (args: MappedParameterTypes<T>) => handlerRef.current?.(args)
-    : undefined;
-
-  useFrontendToolVNext<MappedParameterTypes<T>>({
-    name,
-    description,
-    parameters: zodParameters,
-    handler: normalizedHandler,
-    followUp,
-    render: normalizedRender,
-    available: available === undefined ? undefined : available !== "disabled",
-  });
-}

package/src/hooks/use-human-in-the-loop.ts

@@ -1,138 +0,0 @@
-import {
-  ActionRenderProps,
-  ActionRenderPropsWait,
-  FrontendAction,
-} from "../types";
-import {
-  CopilotKitError,
-  CopilotKitErrorCode,
-  MappedParameterTypes,
-  Parameter,
-  getZodParameters,
-  parseJson,
-} from "@copilotkit/shared";
-import { useHumanInTheLoop as useHumanInTheLoopVNext } from "../v2";
-import { ToolCallStatus } from "@copilotkit/core";
-import React, {
-  ComponentType,
-  FunctionComponent,
-  useEffect,
-  useRef,
-} from "react";
-
-type HumanInTheLoopOptions = Parameters<typeof useHumanInTheLoopVNext>[0];
-type HumanInTheLoopRender = HumanInTheLoopOptions["render"];
-type HumanInTheLoopRenderArgs = HumanInTheLoopRender extends (
-  props: infer P,
-) => any
-  ? P
-  : never;
-
-export type UseHumanInTheLoopArgs<T extends Parameter[] | [] = []> = {
-  available?: "disabled" | "enabled";
-  render: FrontendAction<T>["renderAndWaitForResponse"];
-  followUp?: FrontendAction<T>["followUp"];
-} & Pick<FrontendAction<T>, "name" | "description" | "parameters">;
-
-type HitlRendererArgs =
-  | {
-      name: string;
-      description: string;
-      args: Partial<Record<string, unknown>>;
-      status: ToolCallStatus.InProgress;
-      result: undefined;
-      respond: undefined;
-    }
-  | {
-      name: string;
-      description: string;
-      args: Record<string, unknown>;
-      status: ToolCallStatus.Executing;
-      result: undefined;
-      respond: (result: unknown) => Promise<void>;
-    }
-  | {
-      name: string;
-      description: string;
-      args: Record<string, unknown>;
-      status: ToolCallStatus.Complete;
-      result: string;
-      respond: undefined;
-    };
-type HitlRenderer = FunctionComponent<HitlRendererArgs>;
-
-export function useHumanInTheLoop<const T extends Parameter[] | [] = []>(
-  tool: UseHumanInTheLoopArgs<T>,
-  dependencies?: any[],
-) {
-  const { render, ...toolRest } = tool;
-  const { name, description, parameters, followUp } = toolRest;
-  const zodParameters = getZodParameters(parameters);
-  const renderRef = useRef<HitlRenderer | null>(null);
-
-  useEffect(() => {
-    renderRef.current = (args: HitlRendererArgs): React.ReactElement | null => {
-      if (typeof render === "string") {
-        return React.createElement(React.Fragment, null, render);
-      }
-
-      if (!render) {
-        return null;
-      }
-
-      const renderProps: ActionRenderPropsWait<T> = (() => {
-        const mappedArgs = args.args as unknown as MappedParameterTypes<T>;
-
-        switch (args.status) {
-          case ToolCallStatus.InProgress:
-            return {
-              args: mappedArgs,
-              respond: args.respond,
-              status: args.status,
-              handler: undefined,
-            };
-          case ToolCallStatus.Executing:
-            return {
-              args: mappedArgs,
-              respond: args.respond,
-              status: args.status,
-              handler: () => {},
-            };
-          case ToolCallStatus.Complete:
-            return {
-              args: mappedArgs,
-              respond: args.respond,
-              status: args.status,
-              result: args.result
-                ? parseJson(args.result, args.result)
-                : args.result,
-              handler: undefined,
-            };
-          default:
-            throw new CopilotKitError({
-              code: CopilotKitErrorCode.UNKNOWN,
-              message: `Invalid tool call status: ${(args as unknown as { status: string }).status}`,
-            });
-        }
-      })();
-
-      const rendered = render(renderProps);
-
-      if (typeof rendered === "string") {
-        return React.createElement(React.Fragment, null, rendered);
-      }
-
-      return rendered ?? null;
-    };
-  }, [render, ...(dependencies ?? [])]);
-
-  useHumanInTheLoopVNext({
-    name,
-    description,
-    followUp,
-    parameters: zodParameters,
-    render: ((args: HumanInTheLoopRenderArgs) =>
-      renderRef.current?.(args as HitlRendererArgs) ??
-      null) as HumanInTheLoopOptions["render"],
-  });
-}