@copilotkit/react-core 1.57.3 → 1.58.0

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

@@ -1,271 +0,0 @@
-import React, { useState } from "react";
-import { useRenderTool } from "./use-render-tool";
-
-type DefaultRenderProps = {
-  /** The name of the tool being called. */
-  name: string;
-  /** The parsed parameters passed to the tool call. */
-  parameters: unknown;
-  /** Current execution status of the tool call. */
-  status: "inProgress" | "executing" | "complete";
-  /** The tool call result string, available only when `status` is `"complete"`. */
-  result: string | undefined;
-};
-
-/**
- * Registers a wildcard (`"*"`) tool-call renderer via `useRenderTool`.
- *
- * - Call with no config to use CopilotKit's built-in default tool-call card.
- * - Pass `config.render` to replace the default UI with your own fallback renderer.
- *
- * This is useful when you want a generic renderer for tools that do not have a
- * dedicated `useRenderTool({ name: "..." })` registration.
- *
- * @param config - Optional custom wildcard render function.
- * @param deps - Optional dependencies to refresh registration.
- *
- * @example
- * ```tsx
- * useDefaultRenderTool();
- * ```
- *
- * @example
- * ```tsx
- * useDefaultRenderTool({
- *   render: ({ name, status }) => <div>{name}: {status}</div>,
- * });
- * ```
- *
- * @example
- * ```tsx
- * useDefaultRenderTool(
- *   {
- *     render: ({ name, result }) => (
- *       <ToolEventRow title={name} payload={result} compact={compactMode} />
- *     ),
- *   },
- *   [compactMode],
- * );
- * ```
- */
-export function useDefaultRenderTool(
-  config?: {
-    render?: (props: DefaultRenderProps) => React.ReactElement;
-  },
-  deps?: ReadonlyArray<unknown>,
-): void {
-  useRenderTool(
-    {
-      name: "*",
-      render: config?.render ?? DefaultToolCallRenderer,
-    },
-    deps,
-  );
-}
-
-export function DefaultToolCallRenderer({
-  name,
-  parameters,
-  status,
-  result,
-}: DefaultRenderProps): React.ReactElement {
-  const [isExpanded, setIsExpanded] = useState(false);
-
-  const statusString = String(status) as
-    | "inProgress"
-    | "executing"
-    | "complete";
-  const isActive =
-    statusString === "inProgress" || statusString === "executing";
-  const isComplete = statusString === "complete";
-
-  const statusLabel = isActive ? "Running" : isComplete ? "Done" : status;
-  const dotColor = isActive ? "#f59e0b" : isComplete ? "#10b981" : "#a1a1aa";
-  const badgeBg = isActive ? "#fef3c7" : isComplete ? "#d1fae5" : "#f4f4f5";
-  const badgeColor = isActive ? "#92400e" : isComplete ? "#065f46" : "#3f3f46";
-
-  return (
-    <div
-      data-testid="copilot-tool-render"
-      data-tool-name={name}
-      data-status={statusString}
-      data-args={safeStringifyForAttr(parameters)}
-      data-result={safeStringifyForAttr(result)}
-      style={{
-        marginTop: "8px",
-        paddingBottom: "8px",
-      }}
-    >
-      <div
-        style={{
-          borderRadius: "12px",
-          border: "1px solid #e4e4e7",
-          backgroundColor: "#fafafa",
-          padding: "14px 16px",
-        }}
-      >
-        {/* Header row — always visible */}
-        <div
-          onClick={() => setIsExpanded(!isExpanded)}
-          style={{
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "space-between",
-            gap: "10px",
-            cursor: "pointer",
-            userSelect: "none",
-          }}
-        >
-          <div
-            style={{
-              display: "flex",
-              alignItems: "center",
-              gap: "8px",
-              minWidth: 0,
-            }}
-          >
-            <svg
-              style={{
-                height: "14px",
-                width: "14px",
-                color: "#71717a",
-                transition: "transform 0.15s",
-                transform: isExpanded ? "rotate(90deg)" : "rotate(0deg)",
-                flexShrink: 0,
-              }}
-              fill="none"
-              viewBox="0 0 24 24"
-              strokeWidth={2}
-              stroke="currentColor"
-            >
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                d="M8.25 4.5l7.5 7.5-7.5 7.5"
-              />
-            </svg>
-            <span
-              style={{
-                display: "inline-block",
-                height: "8px",
-                width: "8px",
-                borderRadius: "50%",
-                backgroundColor: dotColor,
-                flexShrink: 0,
-              }}
-            />
-            <span
-              data-testid="copilot-tool-render-name"
-              style={{
-                fontSize: "13px",
-                fontWeight: 600,
-                color: "#18181b",
-                overflow: "hidden",
-                textOverflow: "ellipsis",
-                whiteSpace: "nowrap",
-              }}
-            >
-              {name}
-            </span>
-          </div>
-
-          <span
-            data-testid="copilot-tool-render-status"
-            style={{
-              display: "inline-flex",
-              alignItems: "center",
-              borderRadius: "9999px",
-              padding: "2px 8px",
-              fontSize: "11px",
-              fontWeight: 500,
-              backgroundColor: badgeBg,
-              color: badgeColor,
-              flexShrink: 0,
-            }}
-          >
-            {statusLabel}
-          </span>
-        </div>
-
-        {/* Expandable details */}
-        {isExpanded && (
-          <div style={{ marginTop: "12px", display: "grid", gap: "12px" }}>
-            <div>
-              <div
-                style={{
-                  fontSize: "10px",
-                  textTransform: "uppercase",
-                  letterSpacing: "0.05em",
-                  color: "#71717a",
-                }}
-              >
-                Arguments
-              </div>
-              <pre
-                style={{
-                  marginTop: "6px",
-                  maxHeight: "200px",
-                  overflow: "auto",
-                  borderRadius: "6px",
-                  backgroundColor: "#f4f4f5",
-                  padding: "10px",
-                  fontSize: "11px",
-                  lineHeight: 1.6,
-                  color: "#27272a",
-                  whiteSpace: "pre-wrap",
-                  wordBreak: "break-word",
-                }}
-              >
-                {JSON.stringify(parameters ?? {}, null, 2)}
-              </pre>
-            </div>
-
-            {result !== undefined && (
-              <div>
-                <div
-                  style={{
-                    fontSize: "10px",
-                    textTransform: "uppercase",
-                    letterSpacing: "0.05em",
-                    color: "#71717a",
-                  }}
-                >
-                  Result
-                </div>
-                <pre
-                  style={{
-                    marginTop: "6px",
-                    maxHeight: "200px",
-                    overflow: "auto",
-                    borderRadius: "6px",
-                    backgroundColor: "#f4f4f5",
-                    padding: "10px",
-                    fontSize: "11px",
-                    lineHeight: 1.6,
-                    color: "#27272a",
-                    whiteSpace: "pre-wrap",
-                    wordBreak: "break-word",
-                  }}
-                >
-                  {typeof result === "string"
-                    ? result
-                    : JSON.stringify(result, null, 2)}
-                </pre>
-              </div>
-            )}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
-
-function safeStringifyForAttr(value: unknown): string {
-  if (value === undefined || value === null) return "";
-  if (typeof value === "string") return value;
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return String(value);
-  }
-}

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

@@ -1,46 +0,0 @@
-import { useEffect } from "react";
-import { useCopilotKit } from "../context";
-import type { ReactFrontendTool } from "../types/frontend-tool";
-
-const EMPTY_DEPS: ReadonlyArray<unknown> = [];
-
-export function useFrontendTool<
-  T extends Record<string, unknown> = Record<string, unknown>,
->(tool: ReactFrontendTool<T>, deps?: ReadonlyArray<unknown>) {
-  const { copilotkit } = useCopilotKit();
-  const extraDeps = deps ?? EMPTY_DEPS;
-
-  useEffect(() => {
-    const name = tool.name;
-
-    // Always register/override the tool for this name on mount
-    if (copilotkit.getTool({ toolName: name, agentId: tool.agentId })) {
-      console.warn(
-        `Tool '${name}' already exists for agent '${tool.agentId || "global"}'. Overriding with latest registration.`,
-      );
-      copilotkit.removeTool(name, tool.agentId);
-    }
-    copilotkit.addTool(tool);
-
-    // Register/override renderer by name and agentId through core.
-    // The render function is registered even when tool.parameters is
-    // undefined — tools like HITL confirm dialogs have no parameters
-    // but still need their UI rendered in the chat.
-    if (tool.render) {
-      copilotkit.addHookRenderToolCall({
-        name,
-        args: tool.parameters,
-        agentId: tool.agentId,
-        render: tool.render,
-      });
-    }
-
-    return () => {
-      copilotkit.removeTool(name, tool.agentId);
-      // we are intentionally not removing the render here so that the tools can still render in the chat history
-    };
-    // Depend on stable keys by default and allow callers to opt into
-    // additional dependencies for dynamic tool configuration.
-    // tool.available is included so toggling availability re-registers the tool.
-  }, [tool.name, tool.available, copilotkit, JSON.stringify(extraDeps)]);
-}

package/src/v2/hooks/use-human-in-the-loop.tsx

@@ -1,81 +0,0 @@
-import { useCopilotKit } from "../context";
-import type { ReactFrontendTool } from "../types/frontend-tool";
-import type { ReactHumanInTheLoop } from "../types/human-in-the-loop";
-import type { ReactToolCallRenderer } from "../types/react-tool-call-renderer";
-import { useCallback, useEffect, useRef } from "react";
-import React from "react";
-import { useFrontendTool } from "./use-frontend-tool";
-
-export function useHumanInTheLoop<
-  T extends Record<string, unknown> = Record<string, unknown>,
->(tool: ReactHumanInTheLoop<T>, deps?: ReadonlyArray<unknown>) {
-  const { copilotkit } = useCopilotKit();
-  const resolvePromiseRef = useRef<((result: unknown) => void) | null>(null);
-
-  const respond = useCallback(async (result: unknown) => {
-    if (resolvePromiseRef.current) {
-      resolvePromiseRef.current(result);
-      resolvePromiseRef.current = null;
-    }
-  }, []);
-
-  const handler = useCallback(async () => {
-    return new Promise((resolve) => {
-      resolvePromiseRef.current = resolve;
-    });
-  }, []);
-
-  const RenderComponent: ReactToolCallRenderer<T>["render"] = useCallback(
-    (props) => {
-      const ToolComponent = tool.render;
-
-      // Enhance props based on current status
-      if (props.status === "inProgress") {
-        const enhancedProps = {
-          ...props,
-          name: tool.name,
-          description: tool.description || "",
-          respond: undefined,
-        };
-        return React.createElement(ToolComponent, enhancedProps);
-      } else if (props.status === "executing") {
-        const enhancedProps = {
-          ...props,
-          name: tool.name,
-          description: tool.description || "",
-          respond,
-        };
-        return React.createElement(ToolComponent, enhancedProps);
-      } else if (props.status === "complete") {
-        const enhancedProps = {
-          ...props,
-          name: tool.name,
-          description: tool.description || "",
-          respond: undefined,
-        };
-        return React.createElement(ToolComponent, enhancedProps);
-      }
-
-      // Fallback - just render with original props
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      return React.createElement(ToolComponent, props as any);
-    },
-    [tool.render, tool.name, tool.description, respond],
-  );
-
-  const frontendTool: ReactFrontendTool<T> = {
-    ...tool,
-    handler,
-    render: RenderComponent,
-  };
-
-  useFrontendTool(frontendTool, deps);
-
-  // Human-in-the-loop tools should remove their renderer on unmount
-  // since they can't respond to user interactions anymore
-  useEffect(() => {
-    return () => {
-      copilotkit.removeHookRenderToolCall(tool.name, tool.agentId);
-    };
-  }, [copilotkit, tool.name, tool.agentId]);
-}

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

@@ -1,305 +0,0 @@
-import React, {
-  useState,
-  useEffect,
-  useCallback,
-  useMemo,
-  useRef,
-} from "react";
-import { useCopilotKit } from "../context";
-import { useAgent } from "./use-agent";
-import type {
-  InterruptEvent,
-  InterruptRenderProps,
-  InterruptHandlerProps,
-} from "../types/interrupt";
-
-export type { InterruptEvent, InterruptRenderProps, InterruptHandlerProps };
-
-const INTERRUPT_EVENT_NAME = "on_interrupt";
-
-type InterruptHandlerFn<TValue, TResult> = (
-  props: InterruptHandlerProps<TValue>,
-) => TResult | PromiseLike<TResult>;
-
-type InterruptResultFromHandler<THandler> = THandler extends (
-  ...args: never[]
-) => infer TResult
-  ? TResult extends PromiseLike<infer TResolved>
-    ? TResolved | null
-    : TResult | null
-  : null;
-
-type InterruptResult<TValue, TResult> = InterruptResultFromHandler<
-  InterruptHandlerFn<TValue, TResult>
->;
-
-type InterruptRenderInChat = boolean | undefined;
-
-type UseInterruptReturn<TRenderInChat extends InterruptRenderInChat> =
-  TRenderInChat extends false
-    ? React.ReactElement | null
-    : TRenderInChat extends true | undefined
-      ? void
-      : React.ReactElement | null | void;
-
-export function isPromiseLike<TValue>(
-  value: TValue | PromiseLike<TValue>,
-): value is PromiseLike<TValue> {
-  return (
-    (typeof value === "object" || typeof value === "function") &&
-    value !== null &&
-    typeof Reflect.get(value, "then") === "function"
-  );
-}
-
-/**
- * Configuration options for `useInterrupt`.
- */
-interface UseInterruptConfigBase<TValue = unknown, TResult = never> {
-  /**
-   * Render function for the interrupt UI.
-   *
-   * This is called once an interrupt is finalized and accepted by `enabled` (if provided).
-   * Use `resolve` from render props to resume the agent run with user input.
-   */
-  render: (
-    props: InterruptRenderProps<TValue, InterruptResult<TValue, TResult>>,
-  ) => React.ReactElement;
-  /**
-   * Optional pre-render handler invoked when an interrupt is received.
-   *
-   * Return either a sync value or an async value to pass into `render` as `result`.
-   * Rejecting/throwing falls back to `result = null`.
-   */
-  handler?: InterruptHandlerFn<TValue, TResult>;
-  /**
-   * Optional predicate to filter which interrupts should be handled by this hook.
-   * Return `false` to ignore an interrupt.
-   */
-  enabled?: (event: InterruptEvent<TValue>) => boolean;
-  /** Optional agent id. Defaults to the current configured chat agent. */
-  agentId?: string;
-}
-
-export interface UseInterruptInChatConfig<
-  TValue = unknown,
-  TResult = never,
-> extends UseInterruptConfigBase<TValue, TResult> {
-  /** When true (default), the interrupt UI renders inside `<CopilotChat>` automatically. Set to false to render it yourself. */
-  renderInChat?: true;
-}
-
-export interface UseInterruptExternalConfig<
-  TValue = unknown,
-  TResult = never,
-> extends UseInterruptConfigBase<TValue, TResult> {
-  /** When true (default), the interrupt UI renders inside `<CopilotChat>` automatically. Set to false to render it yourself. */
-  renderInChat: false;
-}
-
-export interface UseInterruptDynamicConfig<
-  TValue = unknown,
-  TResult = never,
-> extends UseInterruptConfigBase<TValue, TResult> {
-  /** Dynamic boolean mode. When non-literal, return type is a union. */
-  renderInChat: boolean;
-}
-
-export type UseInterruptConfig<
-  TValue = unknown,
-  TResult = never,
-  TRenderInChat extends InterruptRenderInChat = undefined,
-> = UseInterruptConfigBase<TValue, TResult> & {
-  /** When true (default), the interrupt UI renders inside `<CopilotChat>` automatically. Set to false to render it yourself. */
-  renderInChat?: TRenderInChat;
-};
-
-/**
- * Handles agent interrupts (`on_interrupt`) with optional filtering, preprocessing, and resume behavior.
- *
- * The hook listens to custom events on the active agent, stores interrupt payloads per run,
- * and surfaces a render callback once the run finalizes. Call `resolve` from your UI to resume
- * execution with user-provided data.
- *
- * - `renderInChat: true` (default): the element is published into `<CopilotChat>` and this hook returns `void`.
- * - `renderInChat: false`: the hook returns the interrupt element so you can place it anywhere in your component tree.
- *
- * `event.value` is typed as `any` since the interrupt payload shape depends on your agent.
- * Type-narrow it in your callbacks (e.g. `handler`, `enabled`, `render`) as needed.
- *
- * @typeParam TResult - Inferred from `handler` return type. Exposed as `result` in `render`.
- * @param config - Interrupt configuration (renderer, optional handler/filter, and render mode).
- * @returns When `renderInChat` is `false`, returns the interrupt element (or `null` when idle).
- * Otherwise returns `void` and publishes the element into chat. In `render`, `result` is always
- * either the handler's resolved return value or `null` (including when no handler is provided,
- * when filtering skips the interrupt, or when handler execution fails).
- *
- * @example
- * ```tsx
- * import { useInterrupt } from "@copilotkit/react-core/v2";
- *
- * function InterruptUI() {
- *   useInterrupt({
- *     render: ({ event, resolve }) => (
- *       <div>
- *         <p>{event.value.question}</p>
- *         <button onClick={() => resolve({ approved: true })}>Approve</button>
- *         <button onClick={() => resolve({ approved: false })}>Reject</button>
- *       </div>
- *     ),
- *   });
- *
- *   return null;
- * }
- * ```
- *
- * @example
- * ```tsx
- * import { useInterrupt } from "@copilotkit/react-core/v2";
- *
- * function CustomPanel() {
- *   const interruptElement = useInterrupt({
- *     renderInChat: false,
- *     enabled: (event) => event.value.startsWith("approval:"),
- *     handler: async ({ event }) => ({ label: event.value.toUpperCase() }),
- *     render: ({ event, result, resolve }) => (
- *       <aside>
- *         <strong>{result?.label ?? ""}</strong>
- *         <button onClick={() => resolve({ value: event.value })}>Continue</button>
- *       </aside>
- *     ),
- *   });
- *
- *   return <>{interruptElement}</>;
- * }
- * ```
- */
-/* eslint-disable @typescript-eslint/no-explicit-any */
-export function useInterrupt<
-  TResult = never,
-  TRenderInChat extends InterruptRenderInChat = undefined,
->(
-  config: UseInterruptConfig<any, TResult, TRenderInChat>,
-): UseInterruptReturn<TRenderInChat> {
-  /* eslint-enable @typescript-eslint/no-explicit-any */
-  const { copilotkit } = useCopilotKit();
-  const { agent } = useAgent({ agentId: config.agentId });
-  const [pendingEvent, setPendingEvent] = useState<InterruptEvent | null>(null);
-  const pendingEventRef = useRef(pendingEvent);
-  pendingEventRef.current = pendingEvent;
-  const [handlerResult, setHandlerResult] =
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    useState<InterruptResult<any, TResult>>(null);
-
-  useEffect(() => {
-    let localInterrupt: InterruptEvent | null = null;
-
-    const subscription = agent.subscribe({
-      onCustomEvent: ({ event }) => {
-        if (event.name === INTERRUPT_EVENT_NAME) {
-          localInterrupt = { name: event.name, value: event.value };
-        }
-      },
-      onRunStartedEvent: () => {
-        localInterrupt = null;
-        setPendingEvent(null);
-      },
-      onRunFinalized: () => {
-        if (localInterrupt) {
-          setPendingEvent(localInterrupt);
-          localInterrupt = null;
-        }
-      },
-      onRunFailed: () => {
-        localInterrupt = null;
-      },
-    });
-
-    return () => subscription.unsubscribe();
-  }, [agent]);
-
-  const resolve = useCallback(
-    (response: unknown) => {
-      setPendingEvent(null);
-      copilotkit.runAgent({
-        agent,
-        forwardedProps: {
-          command: {
-            resume: response,
-            interruptEvent: pendingEventRef.current?.value,
-          },
-        },
-      });
-    },
-    [agent, copilotkit],
-  );
-
-  useEffect(() => {
-    // No interrupt to process — reset any stale handler result from a previous interrupt
-    if (!pendingEvent) {
-      setHandlerResult(null);
-      return;
-    }
-    // Interrupt exists but the consumer's filter rejects it — treat as no-op
-    if (config.enabled && !config.enabled(pendingEvent)) {
-      setHandlerResult(null);
-      return;
-    }
-    const handler = config.handler;
-    // No handler provided — skip straight to rendering with a null result
-    if (!handler) {
-      setHandlerResult(null);
-      return;
-    }
-
-    let cancelled = false;
-    const maybePromise = handler({
-      event: pendingEvent,
-      resolve,
-    });
-
-    // If the handler returns a promise/thenable, wait for resolution before setting result.
-    if (isPromiseLike(maybePromise)) {
-      Promise.resolve(maybePromise)
-        .then((resolved) => {
-          if (!cancelled) setHandlerResult(resolved);
-        })
-        .catch(() => {
-          if (!cancelled) setHandlerResult(null);
-        });
-    } else {
-      setHandlerResult(maybePromise);
-    }
-
-    return () => {
-      cancelled = true;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [pendingEvent, config.enabled, config.handler, resolve]);
-
-  const element = useMemo(() => {
-    if (!pendingEvent) return null;
-    if (config.enabled && !config.enabled(pendingEvent)) return null;
-
-    return config.render({
-      event: pendingEvent,
-      result: handlerResult,
-      resolve,
-    });
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [pendingEvent, handlerResult, config.enabled, config.render, resolve]);
-
-  // Publish to core for in-chat rendering
-  useEffect(() => {
-    if (config.renderInChat === false) return;
-    copilotkit.setInterruptElement(element);
-    return () => copilotkit.setInterruptElement(null);
-  }, [element, config.renderInChat, copilotkit]);
-
-  // Only return element when rendering outside chat
-  if (config.renderInChat === false) {
-    return element as UseInterruptReturn<TRenderInChat>;
-  }
-
-  return undefined as UseInterruptReturn<TRenderInChat>;
-}