@copilotkit/react-core 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

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

@@ -0,0 +1,135 @@
+/**
+ * `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 "@copilotkitnext/react";
+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

@@ -0,0 +1,164 @@
+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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,105 @@
+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

@@ -0,0 +1,96 @@
+import React, { useEffect, 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 "@copilotkitnext/core";
+import {
+  type ReactFrontendTool,
+  useFrontendTool as useFrontendToolVNext,
+} from "@copilotkitnext/react";
+
+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 } = tool;
+  const zodParameters = getZodParameters(parameters);
+
+  const normalizedRender: FrontendToolOptions<T>["render"] | undefined = (() => {
+    if (typeof render === "undefined") {
+      return undefined;
+    }
+
+    if (typeof render === "string") {
+      const staticRender = render;
+      return (() =>
+        React.createElement(
+          React.Fragment,
+          null,
+          staticRender,
+        )) as FrontendToolOptions<T>["render"];
+    }
+
+    return ((args: FrontendToolRenderArgs<T>) => {
+      const renderArgs = {
+        ...args,
+        result: typeof args.result === "string" ? parseJson(args.result, args.result) : args.result,
+      } as ActionRenderProps<T>;
+
+      const rendered = render(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,
+  });
+}

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

@@ -0,0 +1,122 @@
+import { ActionRenderProps, ActionRenderPropsWait, FrontendAction } from "../types";
+import {
+  CopilotKitError,
+  CopilotKitErrorCode,
+  MappedParameterTypes,
+  Parameter,
+  getZodParameters,
+  parseJson,
+} from "@copilotkit/shared";
+import { useHumanInTheLoop as useHumanInTheLoopVNext } from "@copilotkitnext/react";
+import { ToolCallStatus } from "@copilotkitnext/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"],
+  });
+}