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

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

@@ -0,0 +1,187 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurationProvider";
+import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
+import {
+  DynamicSuggestionsConfig,
+  StaticSuggestionsConfig,
+  SuggestionsConfig,
+  Suggestion,
+} from "@copilotkit/core";
+
+type StaticSuggestionInput = Omit<Suggestion, "isLoading"> &
+  Partial<Pick<Suggestion, "isLoading">>;
+
+type StaticSuggestionsConfigInput = Omit<
+  StaticSuggestionsConfig,
+  "suggestions"
+> & {
+  suggestions: StaticSuggestionInput[];
+};
+
+type SuggestionsConfigInput =
+  | DynamicSuggestionsConfig
+  | StaticSuggestionsConfigInput;
+
+export function useConfigureSuggestions(
+  config: SuggestionsConfigInput | null | undefined,
+  deps?: ReadonlyArray<unknown>,
+): void {
+  const { copilotkit } = useCopilotKit();
+  const chatConfig = useCopilotChatConfiguration();
+  const extraDeps = deps ?? [];
+
+  const resolvedConsumerAgentId = useMemo(
+    () => chatConfig?.agentId ?? DEFAULT_AGENT_ID,
+    [chatConfig?.agentId],
+  );
+
+  const rawConsumerAgentId = useMemo(
+    () =>
+      config ? (config as SuggestionsConfigInput).consumerAgentId : undefined,
+    [config],
+  );
+
+  const normalizationCacheRef = useRef<{
+    serialized: string | null;
+    config: SuggestionsConfig | null;
+  }>({
+    serialized: null,
+    config: null,
+  });
+
+  const { normalizedConfig, serializedConfig } = useMemo(() => {
+    if (!config) {
+      normalizationCacheRef.current = { serialized: null, config: null };
+      return { normalizedConfig: null, serializedConfig: null };
+    }
+
+    if (config.available === "disabled") {
+      normalizationCacheRef.current = { serialized: null, config: null };
+      return { normalizedConfig: null, serializedConfig: null };
+    }
+
+    let built: SuggestionsConfig;
+    if (isDynamicConfig(config)) {
+      built = {
+        ...config,
+      } satisfies DynamicSuggestionsConfig;
+    } else {
+      const normalizedSuggestions = normalizeStaticSuggestions(
+        config.suggestions,
+      );
+      const baseConfig: StaticSuggestionsConfig = {
+        ...config,
+        suggestions: normalizedSuggestions,
+      };
+      built = baseConfig;
+    }
+
+    const serialized = JSON.stringify(built);
+    const cache = normalizationCacheRef.current;
+    if (cache.serialized === serialized && cache.config) {
+      return { normalizedConfig: cache.config, serializedConfig: serialized };
+    }
+
+    normalizationCacheRef.current = { serialized, config: built };
+    return { normalizedConfig: built, serializedConfig: serialized };
+  }, [config, resolvedConsumerAgentId, ...extraDeps]);
+  const latestConfigRef = useRef<SuggestionsConfig | null>(null);
+  latestConfigRef.current = normalizedConfig;
+  const previousSerializedConfigRef = useRef<string | null>(null);
+
+  const targetAgentId = useMemo(() => {
+    if (!normalizedConfig) {
+      return resolvedConsumerAgentId;
+    }
+    const consumer = (
+      normalizedConfig as StaticSuggestionsConfig | DynamicSuggestionsConfig
+    ).consumerAgentId;
+    if (!consumer || consumer === "*") {
+      return resolvedConsumerAgentId;
+    }
+    return consumer;
+  }, [normalizedConfig, resolvedConsumerAgentId]);
+
+  const isGlobalConfig =
+    rawConsumerAgentId === undefined || rawConsumerAgentId === "*";
+
+  const requestReload = useCallback(() => {
+    if (!normalizedConfig) {
+      return;
+    }
+
+    if (isGlobalConfig) {
+      const agents = Object.values(copilotkit.agents ?? {});
+      for (const entry of agents) {
+        const agentId = entry.agentId;
+        if (!agentId) {
+          continue;
+        }
+        if (!entry.isRunning) {
+          copilotkit.reloadSuggestions(agentId);
+        }
+      }
+      return;
+    }
+
+    if (!targetAgentId) {
+      return;
+    }
+
+    copilotkit.reloadSuggestions(targetAgentId);
+  }, [copilotkit, isGlobalConfig, normalizedConfig, targetAgentId]);
+
+  useEffect(() => {
+    if (!serializedConfig || !latestConfigRef.current) {
+      return;
+    }
+
+    const id = copilotkit.addSuggestionsConfig(latestConfigRef.current);
+
+    requestReload();
+
+    return () => {
+      copilotkit.removeSuggestionsConfig(id);
+    };
+  }, [copilotkit, serializedConfig, requestReload]);
+
+  useEffect(() => {
+    if (!normalizedConfig) {
+      previousSerializedConfigRef.current = null;
+      return;
+    }
+    if (
+      serializedConfig &&
+      previousSerializedConfigRef.current === serializedConfig
+    ) {
+      return;
+    }
+    if (serializedConfig) {
+      previousSerializedConfigRef.current = serializedConfig;
+    }
+    requestReload();
+  }, [normalizedConfig, requestReload, serializedConfig]);
+
+  useEffect(() => {
+    if (!normalizedConfig || extraDeps.length === 0) {
+      return;
+    }
+    requestReload();
+  }, [extraDeps.length, normalizedConfig, requestReload, ...extraDeps]);
+}
+
+function isDynamicConfig(
+  config: SuggestionsConfigInput,
+): config is DynamicSuggestionsConfig {
+  return "instructions" in config;
+}
+
+function normalizeStaticSuggestions(
+  suggestions: StaticSuggestionInput[],
+): Suggestion[] {
+  return suggestions.map((suggestion) => ({
+    ...suggestion,
+    isLoading: suggestion.isLoading ?? false,
+  }));
+}

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

@@ -0,0 +1,254 @@
+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,
+  );
+}
+
+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
+      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
+              style={{
+                fontSize: "13px",
+                fontWeight: 600,
+                color: "#18181b",
+                overflow: "hidden",
+                textOverflow: "ellipsis",
+                whiteSpace: "nowrap",
+              }}
+            >
+              {name}
+            </span>
+          </div>
+
+          <span
+            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>
+  );
+}

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

@@ -0,0 +1,43 @@
+import { useEffect } from "react";
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+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
+    if (tool.render && tool.parameters) {
+      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, extraDeps.length, ...extraDeps]);
+}

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

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