@copilotkit/react-core 1.57.3 → 1.58.0

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

@@ -1,269 +0,0 @@
-import React, { useCallback, useEffect, useRef, useState } from "react";
-import {
-  randomUUID,
-  getModalityFromMimeType,
-  exceedsMaxSize,
-  readFileAsBase64,
-  generateVideoThumbnail,
-  matchesAcceptFilter,
-  formatFileSize,
-} from "@copilotkit/shared";
-import type { Attachment, AttachmentsConfig } from "@copilotkit/shared";
-
-export interface UseAttachmentsProps {
-  config?: AttachmentsConfig;
-}
-
-export interface UseAttachmentsReturn {
-  /** Currently selected attachments (uploading + ready). */
-  attachments: Attachment[];
-  /** Whether attachments are enabled. */
-  enabled: boolean;
-  /** Whether the user is dragging a file over the drop zone. */
-  dragOver: boolean;
-  /** Ref for the hidden file input element. */
-  fileInputRef: React.RefObject<HTMLInputElement | null>;
-  /** Ref for the container element (used for scoped paste handling). */
-  containerRef: React.RefObject<HTMLDivElement | null>;
-  /** Process an array of files (validate, upload, add to state). */
-  processFiles: (files: File[]) => Promise<void>;
-  /** Handler for `<input type="file" onChange>`. */
-  handleFileUpload: (e: React.ChangeEvent<HTMLInputElement>) => Promise<void>;
-  /** Handler for `onDragOver` on the drop zone. */
-  handleDragOver: (e: React.DragEvent) => void;
-  /** Handler for `onDragLeave` on the drop zone. */
-  handleDragLeave: (e: React.DragEvent) => void;
-  /** Handler for `onDrop` on the drop zone. */
-  handleDrop: (e: React.DragEvent) => Promise<void>;
-  /** Remove an attachment by ID. */
-  removeAttachment: (id: string) => void;
-  /**
-   * Consume ready attachments and clear the queue.
-   * Returns the attachments that were ready; resets the file input.
-   * No-ops if the queue is already empty (no state update triggered).
-   */
-  consumeAttachments: () => Attachment[];
-}
-
-/**
- * Hook that manages file attachment state — uploads, drag-and-drop, paste,
- * and lifecycle. All returned callbacks are referentially stable across
- * renders (via useCallback) to avoid destabilizing downstream memoization.
- */
-export function useAttachments({
-  config,
-}: UseAttachmentsProps): UseAttachmentsReturn {
-  const enabled = config?.enabled ?? false;
-
-  const [attachments, setAttachments] = useState<Attachment[]>([]);
-  const [dragOver, setDragOver] = useState(false);
-  const fileInputRef = useRef<HTMLInputElement>(null);
-  const containerRef = useRef<HTMLDivElement>(null);
-
-  // Keep refs to the latest values so stable callbacks can read current
-  // state without appearing in dependency arrays.
-  const configRef = useRef(config);
-  configRef.current = config;
-  const attachmentsRef = useRef<Attachment[]>([]);
-  attachmentsRef.current = attachments;
-
-  // Stable processFiles — reads config from ref, never changes identity
-  const processFiles = useCallback(async (files: File[]) => {
-    const cfg = configRef.current;
-    const accept = cfg?.accept ?? "*/*";
-    const maxSize = cfg?.maxSize ?? 20 * 1024 * 1024;
-
-    const rejectedFiles = files.filter(
-      (file) => !matchesAcceptFilter(file, accept),
-    );
-    for (const file of rejectedFiles) {
-      cfg?.onUploadFailed?.({
-        reason: "invalid-type",
-        file,
-        message: `File "${file.name}" is not accepted. Supported types: ${accept}`,
-      });
-    }
-
-    const validFiles = files.filter((file) =>
-      matchesAcceptFilter(file, accept),
-    );
-
-    for (const file of validFiles) {
-      if (exceedsMaxSize(file, maxSize)) {
-        cfg?.onUploadFailed?.({
-          reason: "file-too-large",
-          file,
-          message: `File "${file.name}" exceeds the maximum size of ${formatFileSize(maxSize)}`,
-        });
-        continue;
-      }
-
-      const modality = getModalityFromMimeType(file.type);
-      const placeholderId = randomUUID();
-      const placeholder: Attachment = {
-        id: placeholderId,
-        type: modality,
-        source: { type: "data", value: "", mimeType: file.type },
-        filename: file.name,
-        size: file.size,
-        status: "uploading",
-      };
-
-      setAttachments((prev) => [...prev, placeholder]);
-
-      try {
-        let source: Attachment["source"];
-        let uploadMetadata: Record<string, unknown> | undefined;
-
-        if (cfg?.onUpload) {
-          const { metadata: meta, ...uploadSource } = await cfg.onUpload(file);
-          source = uploadSource;
-          uploadMetadata = meta;
-        } else {
-          const base64 = await readFileAsBase64(file);
-          source = { type: "data", value: base64, mimeType: file.type };
-        }
-
-        let thumbnail: string | undefined;
-        if (modality === "video") {
-          thumbnail = await generateVideoThumbnail(file);
-        }
-
-        setAttachments((prev) =>
-          prev.map((att) =>
-            att.id === placeholderId
-              ? {
-                  ...att,
-                  source,
-                  status: "ready" as const,
-                  thumbnail,
-                  metadata: uploadMetadata,
-                }
-              : att,
-          ),
-        );
-      } catch (error) {
-        setAttachments((prev) =>
-          prev.filter((att) => att.id !== placeholderId),
-        );
-        console.error(`[CopilotKit] Failed to upload "${file.name}":`, error);
-        cfg?.onUploadFailed?.({
-          reason: "upload-failed",
-          file,
-          message:
-            error instanceof Error
-              ? error.message
-              : `Failed to upload "${file.name}"`,
-        });
-      }
-    }
-  }, []);
-
-  const handleFileUpload = useCallback(
-    async (e: React.ChangeEvent<HTMLInputElement>) => {
-      if (!e.target.files?.length) return;
-      try {
-        await processFiles(Array.from(e.target.files));
-      } catch (error) {
-        console.error("[CopilotKit] Upload error:", error);
-      }
-    },
-    [processFiles],
-  );
-
-  const handleDragOver = useCallback((e: React.DragEvent) => {
-    if (!configRef.current?.enabled) return;
-    e.preventDefault();
-    e.stopPropagation();
-    setDragOver(true);
-  }, []);
-
-  const handleDragLeave = useCallback((e: React.DragEvent) => {
-    e.preventDefault();
-    e.stopPropagation();
-    setDragOver(false);
-  }, []);
-
-  const handleDrop = useCallback(
-    async (e: React.DragEvent) => {
-      e.preventDefault();
-      e.stopPropagation();
-      setDragOver(false);
-      if (!configRef.current?.enabled) return;
-
-      const files = Array.from(e.dataTransfer.files);
-      if (files.length > 0) {
-        try {
-          await processFiles(files);
-        } catch (error) {
-          console.error("[CopilotKit] Drop error:", error);
-        }
-      }
-    },
-    [processFiles],
-  );
-
-  // Clipboard paste handler — scoped to the container
-  useEffect(() => {
-    if (!enabled) return;
-
-    const handlePaste = async (e: ClipboardEvent) => {
-      const target = e.target as HTMLElement | null;
-      if (!target || !containerRef.current?.contains(target)) return;
-
-      const accept = configRef.current?.accept ?? "*/*";
-      const items = Array.from(e.clipboardData?.items || []);
-      const fileItems = items.filter(
-        (item) =>
-          item.kind === "file" &&
-          item.getAsFile() !== null &&
-          matchesAcceptFilter(item.getAsFile()!, accept),
-      );
-
-      if (fileItems.length === 0) return;
-      e.preventDefault();
-
-      const files = fileItems
-        .map((item) => item.getAsFile())
-        .filter((f): f is File => f !== null);
-
-      try {
-        await processFiles(files);
-      } catch (error) {
-        console.error("[CopilotKit] Paste error:", error);
-      }
-    };
-
-    document.addEventListener("paste", handlePaste);
-    return () => document.removeEventListener("paste", handlePaste);
-  }, [enabled, processFiles]);
-
-  const removeAttachment = useCallback((id: string) => {
-    setAttachments((prev) => prev.filter((a) => a.id !== id));
-  }, []);
-
-  const consumeAttachments = useCallback(() => {
-    const ready = attachmentsRef.current.filter((a) => a.status === "ready");
-    if (ready.length === 0) return ready;
-    setAttachments((prev) => prev.filter((a) => a.status !== "ready"));
-    if (fileInputRef.current) {
-      fileInputRef.current.value = "";
-    }
-    return ready;
-  }, []);
-
-  return {
-    attachments,
-    enabled,
-    dragOver,
-    fileInputRef,
-    containerRef,
-    processFiles,
-    handleFileUpload,
-    handleDragOver,
-    handleDragLeave,
-    handleDrop,
-    removeAttachment,
-    consumeAttachments,
-  };
-}

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

@@ -1,25 +0,0 @@
-import type { AgentCapabilities } from "@ag-ui/core";
-import { useAgent } from "./use-agent";
-
-/**
- * Returns the capabilities declared by the given agent (or the default agent).
- * Capabilities are populated from the runtime `/info` response at connection
- * time. The hook reads them synchronously from the agent instance — there is
- * no separate loading state, but the value will be `undefined` until the
- * runtime handshake completes.
- *
- * @param agentId - Optional agent ID. If omitted, uses the default agent.
- * @returns The agent's capabilities, or `undefined` if the agent doesn't
- *          declare capabilities.
- */
-export function useCapabilities(
-  agentId?: string,
-): AgentCapabilities | undefined {
-  const { agent } = useAgent({ agentId });
-
-  if (agent && "capabilities" in agent) {
-    return (agent as { capabilities?: AgentCapabilities }).capabilities;
-  }
-
-  return undefined;
-}

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

@@ -1,91 +0,0 @@
-import type { StandardSchemaV1, InferSchemaOutput } from "@copilotkit/shared";
-import type { ComponentType } from "react";
-import { useFrontendTool } from "./use-frontend-tool";
-
-type InferRenderProps<T> = T extends StandardSchemaV1
-  ? InferSchemaOutput<T>
-  : any;
-
-/**
- * Registers a React component as a frontend tool renderer in chat.
- *
- * This hook is a convenience wrapper around `useFrontendTool` that:
- * - builds a model-facing tool description,
- * - forwards optional schema parameters (any Standard Schema V1 compatible library),
- * - renders your component with tool call parameters.
- *
- * Use this when you want to display a typed visual component for a tool call
- * without manually wiring a full frontend tool object.
- *
- * When `parameters` is provided, render props are inferred from the schema.
- * When omitted, the render component may accept any props.
- *
- * @typeParam TSchema - Schema describing tool parameters, or `undefined` when no schema is given.
- * @param config - Tool registration config.
- * @param deps - Optional dependencies to refresh registration (same semantics as `useEffect`).
- *
- * @example
- * ```tsx
- * // Without parameters — render accepts any props
- * useComponent({
- *   name: "showGreeting",
- *   render: ({ message }: { message: string }) => <div>{message}</div>,
- * });
- * ```
- *
- * @example
- * ```tsx
- * // With parameters — render props inferred from schema
- * useComponent({
- *   name: "showWeatherCard",
- *   parameters: z.object({ city: z.string() }),
- *   render: ({ city }) => <div>{city}</div>,
- * });
- * ```
- *
- * @example
- * ```tsx
- * useComponent(
- *   {
- *     name: "renderProfile",
- *     parameters: z.object({ userId: z.string() }),
- *     render: ProfileCard,
- *     agentId: "support-agent",
- *   },
- *   [selectedAgentId],
- * );
- * ```
- */
-export function useComponent<
-  TSchema extends StandardSchemaV1 | undefined = undefined,
->(
-  config: {
-    name: string;
-    description?: string;
-    parameters?: TSchema;
-    render: ComponentType<NoInfer<InferRenderProps<TSchema>>>;
-    agentId?: string;
-    followUp?: boolean;
-  },
-  deps?: ReadonlyArray<unknown>,
-): void {
-  const prefix = `Use this tool to display the "${config.name}" component in the chat. This tool renders a visual UI component for the user.`;
-  const fullDescription = config.description
-    ? `${prefix}\n\n${config.description}`
-    : prefix;
-
-  useFrontendTool(
-    {
-      name: config.name,
-      description: fullDescription,
-      parameters: config.parameters,
-      render: ({ args }: { args: unknown }) => {
-        const Component = config.render;
-        return <Component {...(args as InferRenderProps<TSchema>)} />;
-      },
-      agentId: config.agentId,
-      followUp: config.followUp,
-    },
-    deps,
-  );
-}

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

@@ -1,236 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef } from "react";
-import { useCopilotKit } from "../context";
-import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurationProvider";
-import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
-import type {
-  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 isDynamicConfigType = useMemo(
-    () => !!normalizedConfig && "instructions" in normalizedConfig,
-    [normalizedConfig],
-  );
-
-  const requestReload = useCallback(() => {
-    if (!normalizedConfig) {
-      return;
-    }
-
-    if (isGlobalConfig) {
-      const seen = new Set<string>();
-      const agents = Object.values(copilotkit.agents ?? {});
-      for (const entry of agents) {
-        const agentId = entry.agentId;
-        if (!agentId) {
-          continue;
-        }
-        seen.add(agentId);
-        if (!entry.isRunning) {
-          copilotkit.reloadSuggestions(agentId);
-        }
-      }
-      // Also reload for the chat's resolved consumer agent. The registry can
-      // be empty at this point (e.g. runtime info still loading), in which
-      // case the loop above wouldn't have fired for the agent the user is
-      // actually chatting with — and the welcome screen would render with
-      // no suggestions until they navigate away and back.
-      if (targetAgentId && !seen.has(targetAgentId)) {
-        copilotkit.reloadSuggestions(targetAgentId);
-      }
-      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]);
-
-  // When agents arrive after the initial render (runtime info just landed),
-  // re-request a reload so dynamic configs that need a real agent can finally
-  // generate.  Skip for static configs — they don't need an agent and the
-  // initial mount reload already handled them.  Skip when the target agent
-  // is already in the registry — the initial reload already covered it, and
-  // re-firing on every subsequent `onAgentsChanged` (e.g. dev-mode hot
-  // reloads, sibling chat configs mounting) would stack overlapping
-  // generations.
-  useEffect(() => {
-    if (!normalizedConfig || !isDynamicConfigType) return;
-    if (!targetAgentId) return;
-
-    const initiallyPresent = !!copilotkit.getAgent(targetAgentId);
-    if (initiallyPresent) return;
-
-    const subscription = copilotkit.subscribe({
-      onAgentsChanged: () => {
-        if (copilotkit.getAgent(targetAgentId)) {
-          requestReload();
-          subscription.unsubscribe();
-        }
-      },
-    });
-    return () => {
-      subscription.unsubscribe();
-    };
-  }, [
-    copilotkit,
-    normalizedConfig,
-    isDynamicConfigType,
-    targetAgentId,
-    requestReload,
-  ]);
-}
-
-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,
-  }));
-}