@copilotkit/react-core 1.54.1 → 1.55.0-next.8

package/src/v2/lib/react-core.ts

@@ -0,0 +1,156 @@
+import React from "react";
+import { ReactActivityMessageRenderer, ReactToolCallRenderer } from "../types";
+import { ReactCustomMessageRenderer } from "../types/react-custom-message-renderer";
+import {
+  CopilotKitCore,
+  type CopilotKitCoreConfig,
+  type CopilotKitCoreSubscriber,
+  type CopilotKitCoreSubscription,
+} from "@copilotkit/core";
+
+export interface CopilotKitCoreReactConfig extends CopilotKitCoreConfig {
+  // Add any additional configuration properties specific to the React implementation
+  renderToolCalls?: ReactToolCallRenderer<any>[];
+  renderActivityMessages?: ReactActivityMessageRenderer<any>[];
+
+  // Add custom message renderers
+  renderCustomMessages?: ReactCustomMessageRenderer[];
+}
+
+export interface CopilotKitCoreReactSubscriber extends CopilotKitCoreSubscriber {
+  onRenderToolCallsChanged?: (event: {
+    copilotkit: CopilotKitCore;
+    renderToolCalls: ReactToolCallRenderer<any>[];
+  }) => void | Promise<void>;
+  onInterruptElementChanged?: (event: {
+    copilotkit: CopilotKitCore;
+    interruptElement: React.ReactElement | null;
+  }) => void | Promise<void>;
+}
+
+export class CopilotKitCoreReact extends CopilotKitCore {
+  private _renderToolCalls: ReactToolCallRenderer<any>[] = [];
+  private _hookRenderToolCalls: Map<string, ReactToolCallRenderer<any>> =
+    new Map();
+  private _cachedMergedRenderToolCalls: ReactToolCallRenderer<any>[] | null =
+    null;
+  private _renderCustomMessages: ReactCustomMessageRenderer[] = [];
+  private _renderActivityMessages: ReactActivityMessageRenderer<any>[] = [];
+  private _interruptElement: React.ReactElement | null = null;
+
+  constructor(config: CopilotKitCoreReactConfig) {
+    super(config);
+    this._renderToolCalls = config.renderToolCalls ?? [];
+    this._renderCustomMessages = config.renderCustomMessages ?? [];
+    this._renderActivityMessages = config.renderActivityMessages ?? [];
+  }
+
+  get renderCustomMessages(): Readonly<ReactCustomMessageRenderer[]> {
+    return this._renderCustomMessages;
+  }
+
+  get renderActivityMessages(): Readonly<ReactActivityMessageRenderer<any>>[] {
+    return this._renderActivityMessages;
+  }
+
+  get renderToolCalls(): Readonly<ReactToolCallRenderer<any>>[] {
+    if (this._hookRenderToolCalls.size === 0) {
+      return this._renderToolCalls;
+    }
+    if (this._cachedMergedRenderToolCalls) {
+      return this._cachedMergedRenderToolCalls;
+    }
+    // Merge: hook entries override prop entries with the same key
+    const merged = new Map<string, ReactToolCallRenderer<any>>();
+    for (const rc of this._renderToolCalls) {
+      merged.set(`${rc.agentId ?? ""}:${rc.name}`, rc);
+    }
+    for (const [key, rc] of this._hookRenderToolCalls) {
+      merged.set(key, rc);
+    }
+    this._cachedMergedRenderToolCalls = Array.from(merged.values());
+    return this._cachedMergedRenderToolCalls;
+  }
+
+  setRenderActivityMessages(
+    renderers: ReactActivityMessageRenderer<any>[],
+  ): void {
+    this._renderActivityMessages = renderers;
+  }
+
+  setRenderCustomMessages(renderers: ReactCustomMessageRenderer[]): void {
+    this._renderCustomMessages = renderers;
+  }
+
+  setRenderToolCalls(renderToolCalls: ReactToolCallRenderer<any>[]): void {
+    this._renderToolCalls = renderToolCalls;
+    this._cachedMergedRenderToolCalls = null;
+    this._notifyRenderToolCallsChanged();
+  }
+
+  addHookRenderToolCall(entry: ReactToolCallRenderer<any>): void {
+    const key = `${entry.agentId ?? ""}:${entry.name}`;
+    this._hookRenderToolCalls.set(key, entry);
+    this._cachedMergedRenderToolCalls = null;
+    this._notifyRenderToolCallsChanged();
+  }
+
+  removeHookRenderToolCall(name: string, agentId?: string): void {
+    const key = `${agentId ?? ""}:${name}`;
+    if (this._hookRenderToolCalls.delete(key)) {
+      this._cachedMergedRenderToolCalls = null;
+      this._notifyRenderToolCallsChanged();
+    }
+  }
+
+  private _notifyRenderToolCallsChanged(): void {
+    void this.notifySubscribers((subscriber) => {
+      const reactSubscriber = subscriber as CopilotKitCoreReactSubscriber;
+      if (reactSubscriber.onRenderToolCallsChanged) {
+        reactSubscriber.onRenderToolCallsChanged({
+          copilotkit: this,
+          renderToolCalls: this.renderToolCalls,
+        });
+      }
+    }, "Subscriber onRenderToolCallsChanged error:");
+  }
+
+  get interruptElement(): React.ReactElement | null {
+    return this._interruptElement;
+  }
+
+  setInterruptElement(element: React.ReactElement | null): void {
+    this._interruptElement = element;
+    void this.notifySubscribers((subscriber) => {
+      const reactSubscriber = subscriber as CopilotKitCoreReactSubscriber;
+      reactSubscriber.onInterruptElementChanged?.({
+        copilotkit: this,
+        interruptElement: this._interruptElement,
+      });
+    }, "Subscriber onInterruptElementChanged error:");
+  }
+
+  // Override to accept React-specific subscriber type
+  subscribe(
+    subscriber: CopilotKitCoreReactSubscriber,
+  ): CopilotKitCoreSubscription {
+    return super.subscribe(subscriber);
+  }
+
+  /**
+   * Wait for pending React state updates before the follow-up agent run.
+   *
+   * When a frontend tool handler calls setState(), React 18 batches the update
+   * and schedules a commit via its internal scheduler (MessageChannel). The
+   * useAgentContext hook registers context via useLayoutEffect, which runs
+   * synchronously after React commits that batch.
+   *
+   * Awaiting a zero-delay timeout yields to the macrotask queue. React's
+   * MessageChannel task runs first, committing the pending state and running
+   * useLayoutEffect (which updates the context store). The follow-up runAgent
+   * call then reads fresh context.
+   */
+  async waitForPendingFrameworkUpdates(): Promise<void> {
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  }
+}

package/src/v2/lib/slots.tsx

@@ -0,0 +1,143 @@
+import React from "react";
+import { twMerge } from "tailwind-merge";
+
+/** Existing union (unchanged) */
+export type SlotValue<C extends React.ComponentType<any>> =
+  | C
+  | string
+  | Partial<React.ComponentProps<C>>;
+
+/**
+ * Shallow equality comparison for objects.
+ */
+export function shallowEqual<T extends Record<string, unknown>>(
+  obj1: T,
+  obj2: T,
+): boolean {
+  const keys1 = Object.keys(obj1);
+  const keys2 = Object.keys(obj2);
+
+  if (keys1.length !== keys2.length) return false;
+
+  for (const key of keys1) {
+    if (obj1[key] !== obj2[key]) return false;
+  }
+
+  return true;
+}
+
+/** Utility: concrete React elements for every slot */
+type SlotElements<S> = { [K in keyof S]: React.ReactElement };
+
+export type WithSlots<
+  S extends Record<string, React.ComponentType<any>>,
+  Rest = {},
+> = {
+  /** Per‑slot overrides */
+  [K in keyof S]?: SlotValue<S[K]>;
+} & {
+  children?: (props: SlotElements<S> & Rest) => React.ReactNode;
+} & Omit<Rest, "children">;
+
+/**
+ * Check if a value is a React component type (function, class, forwardRef, memo, etc.)
+ */
+export function isReactComponentType(
+  value: unknown,
+): value is React.ComponentType<any> {
+  if (typeof value === "function") {
+    return true;
+  }
+  // forwardRef, memo, lazy have $$typeof but are not valid elements
+  if (
+    value &&
+    typeof value === "object" &&
+    "$$typeof" in value &&
+    !React.isValidElement(value)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Internal function to render a slot value as a React element (non-memoized).
+ */
+function renderSlotElement(
+  slot: SlotValue<React.ComponentType<any>> | undefined,
+  DefaultComponent: React.ComponentType<any>,
+  props: Record<string, unknown>,
+): React.ReactElement {
+  if (typeof slot === "string") {
+    // When slot is a string, treat it as a className and merge with existing className
+    const existingClassName = props.className as string | undefined;
+    return React.createElement(DefaultComponent, {
+      ...props,
+      className: twMerge(existingClassName, slot),
+    });
+  }
+
+  // Check if slot is a React component type (function, forwardRef, memo, etc.)
+  if (isReactComponentType(slot)) {
+    return React.createElement(slot, props);
+  }
+
+  // If slot is a plain object (not a React element), treat it as props override
+  if (slot && typeof slot === "object" && !React.isValidElement(slot)) {
+    return React.createElement(DefaultComponent, {
+      ...props,
+      ...slot,
+    });
+  }
+
+  return React.createElement(DefaultComponent, props);
+}
+
+/**
+ * Internal memoized wrapper component for renderSlot.
+ * Uses forwardRef to support ref forwarding.
+ */
+const MemoizedSlotWrapper = React.memo(
+  React.forwardRef<unknown, any>(function MemoizedSlotWrapper(props, ref) {
+    const { $slot, $component, ...rest } = props;
+    const propsWithRef: Record<string, unknown> =
+      ref !== null ? { ...rest, ref } : rest;
+    return renderSlotElement($slot, $component, propsWithRef);
+  }),
+  (prev: any, next: any) => {
+    // Compare slot and component references
+    if (prev.$slot !== next.$slot) return false;
+    if (prev.$component !== next.$component) return false;
+
+    // Shallow compare remaining props (ref is handled separately by React)
+    const { $slot: _ps, $component: _pc, ...prevRest } = prev;
+    const { $slot: _ns, $component: _nc, ...nextRest } = next;
+    return shallowEqual(
+      prevRest as Record<string, unknown>,
+      nextRest as Record<string, unknown>,
+    );
+  },
+);
+
+/**
+ * Renders a slot value as a memoized React element.
+ * Automatically prevents unnecessary re-renders using shallow prop comparison.
+ * Supports ref forwarding.
+ *
+ * @example
+ * renderSlot(customInput, CopilotChatInput, { onSubmit: handleSubmit })
+ */
+export function renderSlot<
+  C extends React.ComponentType<any>,
+  P = React.ComponentProps<C>,
+>(
+  slot: SlotValue<C> | undefined,
+  DefaultComponent: C,
+  props: P,
+): React.ReactElement {
+  return React.createElement(MemoizedSlotWrapper, {
+    ...props,
+    $slot: slot,
+    $component: DefaultComponent,
+  } as any);
+}

package/src/v2/lib/transcription-client.ts

@@ -0,0 +1,184 @@
+import type { CopilotKitCoreReact } from "./react-core";
+import {
+  TranscriptionErrorCode,
+  type TranscriptionErrorResponse,
+} from "@copilotkit/shared";
+
+export interface TranscriptionResult {
+  text: string;
+  size: number;
+  type: string;
+}
+
+/**
+ * Error info parsed from transcription endpoint error responses.
+ */
+export interface TranscriptionErrorInfo {
+  code: TranscriptionErrorCode;
+  message: string;
+  retryable: boolean;
+}
+
+// Re-export error code enum for convenience
+export { TranscriptionErrorCode };
+
+/**
+ * Convert a Blob to a base64 string
+ */
+async function blobToBase64(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => {
+      const result = reader.result as string;
+      // Remove the data URL prefix to get pure base64
+      const base64 = result.split(",")[1];
+      resolve(base64 ?? "");
+    };
+    reader.onerror = () => reject(new Error("Failed to read audio data"));
+    reader.readAsDataURL(blob);
+  });
+}
+
+/**
+ * Check if an error response matches our expected format
+ */
+function isTranscriptionErrorResponse(
+  data: unknown,
+): data is TranscriptionErrorResponse {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    "error" in data &&
+    "message" in data &&
+    typeof (data as TranscriptionErrorResponse).error === "string" &&
+    typeof (data as TranscriptionErrorResponse).message === "string"
+  );
+}
+
+/**
+ * Parse error info from a transcription error response
+ */
+function parseTranscriptionError(
+  response: TranscriptionErrorResponse,
+): TranscriptionErrorInfo {
+  return {
+    code: response.error,
+    message: response.message,
+    retryable: response.retryable ?? false,
+  };
+}
+
+/**
+ * Custom error type for transcription failures.
+ * Extends Error with transcription-specific info for contextual error handling.
+ */
+export class TranscriptionError extends Error {
+  public readonly info: TranscriptionErrorInfo;
+
+  constructor(info: TranscriptionErrorInfo) {
+    super(info.message);
+    this.name = "TranscriptionError";
+    this.info = info;
+  }
+}
+
+/**
+ * Transcribe an audio blob using the CopilotKit runtime
+ *
+ * Supports both REST mode (multipart/form-data) and single-endpoint mode (base64 JSON)
+ *
+ * @throws {TranscriptionError} When transcription fails with typed error information
+ */
+export async function transcribeAudio(
+  core: CopilotKitCoreReact,
+  audioBlob: Blob,
+  filename: string = "recording.webm",
+): Promise<TranscriptionResult> {
+  const runtimeUrl = core.runtimeUrl;
+  if (!runtimeUrl) {
+    throw new TranscriptionError({
+      code: TranscriptionErrorCode.INVALID_REQUEST,
+      message: "Runtime URL is not configured",
+      retryable: false,
+    });
+  }
+
+  const headers: Record<string, string> = { ...core.headers };
+  let response: Response;
+
+  try {
+    if (core.runtimeTransport === "single") {
+      // Single-endpoint mode: POST JSON with base64 audio
+      const base64Audio = await blobToBase64(audioBlob);
+
+      headers["Content-Type"] = "application/json";
+
+      response = await fetch(runtimeUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          method: "transcribe",
+          body: {
+            audio: base64Audio,
+            mimeType: audioBlob.type || "audio/webm",
+            filename,
+          },
+        }),
+      });
+    } else {
+      // REST mode: POST multipart/form-data to /transcribe
+      // Don't set Content-Type - browser will set it with boundary for FormData
+      delete headers["Content-Type"];
+
+      const formData = new FormData();
+      formData.append("audio", audioBlob, filename);
+
+      response = await fetch(`${runtimeUrl}/transcribe`, {
+        method: "POST",
+        headers,
+        body: formData,
+      });
+    }
+  } catch (error) {
+    // Network error - fetch failed
+    throw new TranscriptionError({
+      code: TranscriptionErrorCode.NETWORK_ERROR,
+      message:
+        error instanceof Error ? error.message : "Network request failed",
+      retryable: true,
+    });
+  }
+
+  if (!response.ok) {
+    let errorData: unknown;
+    try {
+      errorData = await response.json();
+    } catch {
+      // Could not parse error response
+      throw new TranscriptionError({
+        code: TranscriptionErrorCode.PROVIDER_ERROR,
+        message: `HTTP ${response.status}: ${response.statusText}`,
+        retryable: response.status >= 500,
+      });
+    }
+
+    // If we got a typed error response, use it
+    if (isTranscriptionErrorResponse(errorData)) {
+      throw new TranscriptionError(parseTranscriptionError(errorData));
+    }
+
+    // Unknown error format
+    throw new TranscriptionError({
+      code: TranscriptionErrorCode.PROVIDER_ERROR,
+      message:
+        typeof errorData === "object" &&
+        errorData !== null &&
+        "message" in errorData
+          ? String((errorData as { message: unknown }).message)
+          : "Transcription failed",
+      retryable: response.status >= 500,
+    });
+  }
+
+  return (await response.json()) as TranscriptionResult;
+}

package/src/v2/lib/utils.ts

@@ -0,0 +1,8 @@
+import { clsx, type ClassValue } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+const twMerge = extendTailwindMerge({ prefix: "cpk" });
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/v2/providers/CopilotChatConfigurationProvider.tsx

@@ -0,0 +1,162 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  ReactNode,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { DEFAULT_AGENT_ID, randomUUID } from "@copilotkit/shared";
+
+// Default labels
+export const CopilotChatDefaultLabels = {
+  chatInputPlaceholder: "Type a message...",
+  chatInputToolbarStartTranscribeButtonLabel: "Transcribe",
+  chatInputToolbarCancelTranscribeButtonLabel: "Cancel",
+  chatInputToolbarFinishTranscribeButtonLabel: "Finish",
+  chatInputToolbarAddButtonLabel: "Add photos or files",
+  chatInputToolbarToolsButtonLabel: "Tools",
+  assistantMessageToolbarCopyCodeLabel: "Copy",
+  assistantMessageToolbarCopyCodeCopiedLabel: "Copied",
+  assistantMessageToolbarCopyMessageLabel: "Copy",
+  assistantMessageToolbarThumbsUpLabel: "Good response",
+  assistantMessageToolbarThumbsDownLabel: "Bad response",
+  assistantMessageToolbarReadAloudLabel: "Read aloud",
+  assistantMessageToolbarRegenerateLabel: "Regenerate",
+  userMessageToolbarCopyMessageLabel: "Copy",
+  userMessageToolbarEditMessageLabel: "Edit",
+  chatDisclaimerText:
+    "AI can make mistakes. Please verify important information.",
+  chatToggleOpenLabel: "Open chat",
+  chatToggleCloseLabel: "Close chat",
+  modalHeaderTitle: "CopilotKit Chat",
+  welcomeMessageText: "How can I help you today?",
+};
+
+export type CopilotChatLabels = typeof CopilotChatDefaultLabels;
+
+// Define the full configuration interface
+export interface CopilotChatConfigurationValue {
+  labels: CopilotChatLabels;
+  agentId: string;
+  threadId: string;
+  isModalOpen: boolean;
+  setModalOpen: (open: boolean) => void;
+}
+
+// Create the configuration context
+const CopilotChatConfiguration =
+  createContext<CopilotChatConfigurationValue | null>(null);
+
+// Provider props interface
+export interface CopilotChatConfigurationProviderProps {
+  children: ReactNode;
+  labels?: Partial<CopilotChatLabels>;
+  agentId?: string;
+  threadId?: string;
+  isModalDefaultOpen?: boolean;
+}
+
+// Provider component
+export const CopilotChatConfigurationProvider: React.FC<
+  CopilotChatConfigurationProviderProps
+> = ({ children, labels, agentId, threadId, isModalDefaultOpen }) => {
+  const parentConfig = useContext(CopilotChatConfiguration);
+
+  const mergedLabels: CopilotChatLabels = useMemo(
+    () => ({
+      ...CopilotChatDefaultLabels,
+      ...(parentConfig?.labels ?? {}),
+      ...(labels ?? {}),
+    }),
+    [labels, parentConfig?.labels],
+  );
+
+  const resolvedAgentId = agentId ?? parentConfig?.agentId ?? DEFAULT_AGENT_ID;
+
+  const resolvedThreadId = useMemo(() => {
+    if (threadId) {
+      return threadId;
+    }
+    if (parentConfig?.threadId) {
+      return parentConfig.threadId;
+    }
+    return randomUUID();
+  }, [threadId, parentConfig?.threadId]);
+
+  const resolvedDefaultOpen = isModalDefaultOpen ?? true;
+
+  const [internalModalOpen, setInternalModalOpen] =
+    useState<boolean>(resolvedDefaultOpen);
+
+  const hasExplicitDefault = isModalDefaultOpen !== undefined;
+
+  // When this provider owns its modal state, wrap the setter so that changes
+  // propagate upward to any ancestor provider. This allows an outer
+  // CopilotChatConfigurationProvider (e.g. a user's layout-level provider) to
+  // observe open/close events that originate deep in the tree — fixing the
+  // "outer hook always returns true" regression (CPK-7152 Behavior B).
+  const setAndSync = useCallback(
+    (open: boolean) => {
+      setInternalModalOpen(open);
+      parentConfig?.setModalOpen(open);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [parentConfig?.setModalOpen],
+  );
+
+  // Sync parent → child: when an ancestor's modal state is changed externally
+  // (e.g. the user calls setModalOpen from an outer hook), reflect that change
+  // in our own state so the sidebar/popup responds accordingly.
+  // Skip the initial mount so that our own isModalDefaultOpen is respected and
+  // not immediately overwritten by the parent's current value.
+  const isMounted = useRef(false);
+  useEffect(() => {
+    if (!hasExplicitDefault) return;
+    if (!isMounted.current) {
+      isMounted.current = true;
+      return;
+    }
+    if (parentConfig?.isModalOpen === undefined) return;
+    setInternalModalOpen(parentConfig.isModalOpen);
+  }, [parentConfig?.isModalOpen, hasExplicitDefault]);
+
+  const resolvedIsModalOpen = hasExplicitDefault
+    ? internalModalOpen
+    : (parentConfig?.isModalOpen ?? internalModalOpen);
+  const resolvedSetModalOpen = hasExplicitDefault
+    ? setAndSync
+    : (parentConfig?.setModalOpen ?? setInternalModalOpen);
+
+  const configurationValue: CopilotChatConfigurationValue = useMemo(
+    () => ({
+      labels: mergedLabels,
+      agentId: resolvedAgentId,
+      threadId: resolvedThreadId,
+      isModalOpen: resolvedIsModalOpen,
+      setModalOpen: resolvedSetModalOpen,
+    }),
+    [
+      mergedLabels,
+      resolvedAgentId,
+      resolvedThreadId,
+      resolvedIsModalOpen,
+      resolvedSetModalOpen,
+    ],
+  );
+
+  return (
+    <CopilotChatConfiguration.Provider value={configurationValue}>
+      {children}
+    </CopilotChatConfiguration.Provider>
+  );
+};
+
+// Hook to use the full configuration
+export const useCopilotChatConfiguration =
+  (): CopilotChatConfigurationValue | null => {
+    const configuration = useContext(CopilotChatConfiguration);
+    return configuration;
+  };