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

package/src/v2/__tests__/utils/test-helpers.tsx

@@ -0,0 +1,470 @@
+import React from "react";
+import { render, act } from "@testing-library/react";
+import { CopilotKitProvider } from "../../providers/CopilotKitProvider";
+import { CopilotChat } from "../../components/chat/CopilotChat";
+import { CopilotChatConfigurationProvider } from "../../providers/CopilotChatConfigurationProvider";
+import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
+import {
+  AbstractAgent,
+  EventType,
+  type BaseEvent,
+  type RunAgentInput,
+} from "@ag-ui/client";
+import { Observable, Subject, from, delay } from "rxjs";
+import {
+  ReactActivityMessageRenderer,
+  ReactToolCallRenderer,
+} from "../../types";
+import { ReactCustomMessageRenderer } from "../../types/react-custom-message-renderer";
+
+/**
+ * A controllable mock agent for deterministic E2E testing.
+ * Exposes emit() and complete() methods to drive agent events step-by-step.
+ */
+export class MockStepwiseAgent extends AbstractAgent {
+  private subject = new Subject<BaseEvent>();
+
+  /**
+   * Emit a single agent event
+   */
+  emit(event: BaseEvent) {
+    if (event.type === EventType.RUN_STARTED) {
+      this.isRunning = true;
+    } else if (
+      event.type === EventType.RUN_FINISHED ||
+      event.type === EventType.RUN_ERROR
+    ) {
+      this.isRunning = false;
+    }
+    act(() => {
+      this.subject.next(event);
+    });
+  }
+
+  /**
+   * Complete the agent stream
+   */
+  complete() {
+    this.isRunning = false;
+    act(() => {
+      this.subject.complete();
+    });
+  }
+
+  clone(): MockStepwiseAgent {
+    // For tests, return same instance so we can keep controlling it
+    return this;
+  }
+
+  // No-op: prevent the base class from tearing down the Subject
+  // before tests have finished emitting events.
+  async detachActiveRun(): Promise<void> {}
+
+  run(_input: RunAgentInput): Observable<BaseEvent> {
+    return this.subject.asObservable();
+  }
+}
+
+/**
+ * A mock agent that supports both run() and connect() for testing reconnection scenarios.
+ * On run(), emits events and stores them.
+ * On connect(), replays stored events (simulating thread history replay).
+ */
+export class MockReconnectableAgent extends AbstractAgent {
+  private subject = new Subject<BaseEvent>();
+  private storedEvents: BaseEvent[] = [];
+
+  /**
+   * Emit a single agent event during run
+   */
+  emit(event: BaseEvent) {
+    if (event.type === EventType.RUN_STARTED) {
+      this.isRunning = true;
+    } else if (
+      event.type === EventType.RUN_FINISHED ||
+      event.type === EventType.RUN_ERROR
+    ) {
+      this.isRunning = false;
+    }
+    this.storedEvents.push(event);
+    act(() => {
+      this.subject.next(event);
+    });
+  }
+
+  /**
+   * Complete the agent stream
+   */
+  complete() {
+    this.isRunning = false;
+    act(() => {
+      this.subject.complete();
+    });
+  }
+
+  /**
+   * Reset for reconnection test - creates new subject for connect
+   */
+  reset() {
+    this.subject = new Subject<BaseEvent>();
+  }
+
+  clone(): MockReconnectableAgent {
+    return this;
+  }
+
+  // No-op: prevent the base class from tearing down the Subject
+  // before tests have finished emitting events.
+  async detachActiveRun(): Promise<void> {}
+
+  run(_input: RunAgentInput): Observable<BaseEvent> {
+    return this.subject.asObservable();
+  }
+
+  connect(_input: RunAgentInput): Observable<BaseEvent> {
+    // Replay stored events with async delay to simulate HTTP transport
+    // This is critical for reproducing timing bugs that occur in real scenarios
+    return from(this.storedEvents).pipe(delay(10));
+  }
+}
+
+/**
+ * Helper to render components with CopilotKitProvider for E2E tests
+ */
+export function renderWithCopilotKit({
+  agent,
+  agents,
+  renderToolCalls,
+  renderCustomMessages,
+  renderActivityMessages,
+  frontendTools,
+  humanInTheLoop,
+  agentId,
+  threadId,
+  children,
+}: {
+  agent?: AbstractAgent;
+  agents?: Record<string, AbstractAgent>;
+  renderToolCalls?: ReactToolCallRenderer<any>[];
+  renderCustomMessages?: ReactCustomMessageRenderer[];
+  renderActivityMessages?: ReactActivityMessageRenderer<any>[];
+  frontendTools?: any[];
+  humanInTheLoop?: any[];
+  agentId?: string;
+  threadId?: string;
+  children?: React.ReactNode;
+}): ReturnType<typeof render> {
+  const resolvedAgents = agents || (agent ? { default: agent } : undefined);
+  const resolvedAgentId = agentId ?? DEFAULT_AGENT_ID;
+  const resolvedThreadId = threadId ?? "test-thread";
+
+  return render(
+    <CopilotKitProvider
+      agents__unsafe_dev_only={resolvedAgents}
+      renderToolCalls={renderToolCalls}
+      renderCustomMessages={renderCustomMessages}
+      renderActivityMessages={renderActivityMessages}
+      frontendTools={frontendTools}
+      humanInTheLoop={humanInTheLoop}
+    >
+      <CopilotChatConfigurationProvider
+        agentId={resolvedAgentId}
+        threadId={resolvedThreadId}
+      >
+        {children || (
+          <div style={{ height: 400 }}>
+            <CopilotChat welcomeScreen={false} />
+          </div>
+        )}
+      </CopilotChatConfigurationProvider>
+    </CopilotKitProvider>,
+  );
+}
+
+/**
+ * Helper to create a RUN_STARTED event
+ */
+export function runStartedEvent(): BaseEvent {
+  return { type: EventType.RUN_STARTED } as BaseEvent;
+}
+
+/**
+ * Helper to create a RUN_FINISHED event
+ */
+export function runFinishedEvent(): BaseEvent {
+  return { type: EventType.RUN_FINISHED } as BaseEvent;
+}
+
+/**
+ * Helper to create a STATE_SNAPSHOT event
+ */
+export function stateSnapshotEvent(snapshot: unknown): BaseEvent {
+  return {
+    type: EventType.STATE_SNAPSHOT,
+    snapshot,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to create an ACTIVITY_SNAPSHOT event
+ */
+export function activitySnapshotEvent({
+  messageId,
+  activityType,
+  content,
+}: {
+  messageId: string;
+  activityType: string;
+  content: Record<string, unknown>;
+}): BaseEvent {
+  return {
+    type: EventType.ACTIVITY_SNAPSHOT,
+    messageId,
+    activityType,
+    content,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to start an assistant text message
+ */
+export function textMessageStartEvent(
+  messageId: string,
+  role: "assistant" | "developer" | "system" | "user" = "assistant",
+): BaseEvent {
+  return {
+    type: EventType.TEXT_MESSAGE_START,
+    messageId,
+    role,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to stream text message content
+ */
+export function textMessageContentEvent(
+  messageId: string,
+  delta: string,
+): BaseEvent {
+  return {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId,
+    delta,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to end a text message
+ */
+export function textMessageEndEvent(messageId: string): BaseEvent {
+  return {
+    type: EventType.TEXT_MESSAGE_END,
+    messageId,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to create a TEXT_MESSAGE_CHUNK event
+ */
+export function textChunkEvent(messageId: string, delta: string): BaseEvent {
+  return {
+    type: EventType.TEXT_MESSAGE_CHUNK,
+    messageId,
+    delta,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to create a TOOL_CALL_CHUNK event
+ */
+export function toolCallChunkEvent({
+  toolCallId,
+  toolCallName,
+  parentMessageId,
+  delta,
+}: {
+  toolCallId: string;
+  toolCallName?: string;
+  parentMessageId: string;
+  delta: string;
+}): BaseEvent {
+  return {
+    type: EventType.TOOL_CALL_CHUNK,
+    toolCallId,
+    toolCallName,
+    parentMessageId,
+    delta,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to create a TOOL_CALL_RESULT event
+ */
+export function toolCallResultEvent({
+  toolCallId,
+  messageId,
+  content,
+}: {
+  toolCallId: string;
+  messageId: string;
+  content: string;
+}): BaseEvent {
+  return {
+    type: EventType.TOOL_CALL_RESULT,
+    toolCallId,
+    messageId,
+    content,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to create a REASONING_START event
+ */
+export function reasoningStartEvent(messageId: string): BaseEvent {
+  return {
+    type: EventType.REASONING_START,
+    messageId,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to create a REASONING_MESSAGE_START event
+ */
+export function reasoningMessageStartEvent(messageId: string): BaseEvent {
+  return {
+    type: EventType.REASONING_MESSAGE_START,
+    messageId,
+    role: "reasoning",
+  } as BaseEvent;
+}
+
+/**
+ * Helper to create a REASONING_MESSAGE_CONTENT event
+ */
+export function reasoningMessageContentEvent(
+  messageId: string,
+  delta: string,
+): BaseEvent {
+  return {
+    type: EventType.REASONING_MESSAGE_CONTENT,
+    messageId,
+    delta,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to create a REASONING_MESSAGE_END event
+ */
+export function reasoningMessageEndEvent(messageId: string): BaseEvent {
+  return {
+    type: EventType.REASONING_MESSAGE_END,
+    messageId,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to create a REASONING_END event
+ */
+export function reasoningEndEvent(messageId: string): BaseEvent {
+  return {
+    type: EventType.REASONING_END,
+    messageId,
+  } as BaseEvent;
+}
+
+/**
+ * Helper to emit a complete reasoning sequence (all 5 events)
+ */
+export function emitReasoningSequence(
+  agent: MockStepwiseAgent,
+  messageId: string,
+  content: string,
+) {
+  agent.emit(reasoningStartEvent(messageId));
+  agent.emit(reasoningMessageStartEvent(messageId));
+  agent.emit(reasoningMessageContentEvent(messageId, content));
+  agent.emit(reasoningMessageEndEvent(messageId));
+  agent.emit(reasoningEndEvent(messageId));
+}
+
+/**
+ * Helper to generate unique IDs for tests
+ */
+export function testId(prefix: string): string {
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Helper to emit a complete suggestion tool call with streaming chunks
+ */
+export function emitSuggestionToolCall(
+  agent: MockStepwiseAgent,
+  {
+    toolCallId,
+    parentMessageId,
+    suggestions,
+  }: {
+    toolCallId: string;
+    parentMessageId: string;
+    suggestions: Array<{ title: string; message: string }>;
+  },
+) {
+  // Convert suggestions to JSON string
+  const suggestionsJson = JSON.stringify({ suggestions });
+
+  // Emit the tool call name first
+  agent.emit(
+    toolCallChunkEvent({
+      toolCallId,
+      toolCallName: "copilotkitSuggest",
+      parentMessageId,
+      delta: "",
+    }),
+  );
+
+  // Stream the JSON in chunks to simulate streaming
+  const chunkSize = 10; // Characters per chunk
+  for (let i = 0; i < suggestionsJson.length; i += chunkSize) {
+    const chunk = suggestionsJson.substring(i, i + chunkSize);
+    agent.emit(
+      toolCallChunkEvent({
+        toolCallId,
+        parentMessageId,
+        delta: chunk,
+      }),
+    );
+  }
+}
+
+/**
+ * A MockStepwiseAgent that emits suggestion events when run() is called
+ */
+export class SuggestionsProviderAgent extends MockStepwiseAgent {
+  private _suggestions: Array<{ title: string; message: string }> = [];
+
+  setSuggestions(suggestions: Array<{ title: string; message: string }>) {
+    this._suggestions = suggestions;
+  }
+
+  run(_input: RunAgentInput): Observable<BaseEvent> {
+    // Call the parent's run() to get the Subject that's already set up
+    const parentObservable = super.run(_input);
+
+    // Use setTimeout to emit events asynchronously through the existing subject
+    setTimeout(() => {
+      const messageId = testId("suggest-msg");
+      this.emit({ type: EventType.RUN_STARTED } as BaseEvent);
+
+      emitSuggestionToolCall(this, {
+        toolCallId: testId("tc"),
+        parentMessageId: messageId,
+        suggestions: this._suggestions,
+      });
+
+      this.emit({ type: EventType.RUN_FINISHED } as BaseEvent);
+      this.complete();
+    }, 0);
+
+    return parentObservable;
+  }
+}

package/src/v2/a2ui/A2UIMessageRenderer.tsx

@@ -0,0 +1,206 @@
+import { useCopilotKit } from "../providers";
+import type { ReactActivityMessageRenderer } from "../types/react-activity-message-renderer";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { z } from "zod";
+import {
+  A2UIProvider,
+  useA2UIActions,
+  A2UIRenderer,
+  initializeDefaultCatalog,
+  injectStyles,
+  DEFAULT_SURFACE_ID,
+} from "@copilotkit/a2ui-renderer";
+import type { Theme, A2UIClientEventMessage } from "@copilotkit/a2ui-renderer";
+
+// Initialize the React renderer's component catalog and styles once
+let initialized = false;
+function ensureInitialized() {
+  if (!initialized) {
+    initializeDefaultCatalog();
+    injectStyles();
+    initialized = true;
+  }
+}
+
+export type A2UIMessageRendererOptions = {
+  theme: Theme;
+};
+
+export function createA2UIMessageRenderer(
+  options: A2UIMessageRendererOptions,
+): ReactActivityMessageRenderer<any> {
+  const { theme } = options;
+
+  return {
+    activityType: "a2ui-surface",
+    content: z.any(),
+    render: ({ content, agent }) => {
+      ensureInitialized();
+
+      const [operations, setOperations] = useState<any[]>([]);
+      const lastSignatureRef = useRef<string | null>(null);
+      const { copilotkit } = useCopilotKit();
+
+      useEffect(() => {
+        if (!content || !Array.isArray(content.operations)) {
+          lastSignatureRef.current = null;
+          setOperations([]);
+          return;
+        }
+
+        const incoming = content.operations as any[];
+        const signature = stringifyOperations(incoming);
+
+        if (signature && signature === lastSignatureRef.current) {
+          return;
+        }
+
+        lastSignatureRef.current = signature;
+        setOperations(incoming);
+      }, [content]);
+
+      // Group operations by surface ID
+      const groupedOperations = useMemo(() => {
+        const groups = new Map<string, any[]>();
+
+        for (const operation of operations) {
+          const surfaceId =
+            getOperationSurfaceId(operation) ?? DEFAULT_SURFACE_ID;
+
+          if (!groups.has(surfaceId)) {
+            groups.set(surfaceId, []);
+          }
+          groups.get(surfaceId)!.push(operation);
+        }
+
+        return groups;
+      }, [operations]);
+
+      if (!groupedOperations.size) {
+        return null;
+      }
+
+      return (
+        <div className="cpk:flex cpk:min-h-0 cpk:flex-1 cpk:flex-col cpk:gap-6 cpk:overflow-auto cpk:py-6">
+          {Array.from(groupedOperations.entries()).map(([surfaceId, ops]) => (
+            <ReactSurfaceHost
+              key={surfaceId}
+              surfaceId={surfaceId}
+              operations={ops}
+              theme={theme}
+              agent={agent}
+              copilotkit={copilotkit}
+            />
+          ))}
+        </div>
+      );
+    },
+  };
+}
+
+type ReactSurfaceHostProps = {
+  surfaceId: string;
+  operations: any[];
+  theme: Theme;
+  agent: any;
+  copilotkit: any;
+};
+
+/**
+ * Renders a single A2UI surface using the React renderer.
+ * Wraps A2UIProvider + A2UIRenderer and bridges actions back to CopilotKit.
+ */
+function ReactSurfaceHost({
+  surfaceId,
+  operations,
+  theme,
+  agent,
+  copilotkit,
+}: ReactSurfaceHostProps) {
+  // Bridge: when the React renderer dispatches an action, send it to CopilotKit
+  const handleAction = useCallback(
+    async (message: A2UIClientEventMessage) => {
+      if (!agent) return;
+
+      try {
+        console.info("[A2UI] Action dispatched", message.userAction);
+
+        copilotkit.setProperties({
+          ...(copilotkit.properties ?? {}),
+          a2uiAction: message,
+        });
+
+        await copilotkit.runAgent({ agent });
+      } finally {
+        if (copilotkit.properties) {
+          const { a2uiAction, ...rest } = copilotkit.properties;
+          copilotkit.setProperties(rest);
+        }
+      }
+    },
+    [agent, copilotkit],
+  );
+
+  return (
+    <div className="cpk:flex cpk:w-full cpk:flex-none cpk:flex-col cpk:gap-4">
+      <A2UIProvider onAction={handleAction} theme={theme}>
+        <SurfaceMessageProcessor
+          surfaceId={surfaceId}
+          operations={operations}
+        />
+        <A2UIRenderer surfaceId={surfaceId} className="cpk:flex cpk:flex-1" />
+      </A2UIProvider>
+    </div>
+  );
+}
+
+/**
+ * Processes A2UI operations into the provider's message processor.
+ * Must be a child of A2UIProvider to access the actions context.
+ */
+function SurfaceMessageProcessor({
+  surfaceId,
+  operations,
+}: {
+  surfaceId: string;
+  operations: any[];
+}) {
+  const { processMessages } = useA2UIActions();
+  const lastProcessedRef = useRef<string>("");
+
+  useEffect(() => {
+    const key = `${surfaceId}-${JSON.stringify(operations)}`;
+    if (key === lastProcessedRef.current) return;
+    lastProcessedRef.current = key;
+
+    processMessages(operations);
+  }, [processMessages, surfaceId, operations]);
+
+  return null;
+}
+
+function getOperationSurfaceId(operation: any): string | null {
+  if (!operation || typeof operation !== "object") {
+    return null;
+  }
+
+  if (typeof operation.surfaceId === "string") {
+    return operation.surfaceId;
+  }
+
+  return (
+    operation?.beginRendering?.surfaceId ??
+    operation?.surfaceUpdate?.surfaceId ??
+    operation?.dataModelUpdate?.surfaceId ??
+    operation?.deleteSurface?.surfaceId ??
+    null
+  );
+}
+
+function stringifyOperations(ops: any[]): string | null {
+  try {
+    return JSON.stringify(ops);
+  } catch (error) {
+    return null;
+  }
+}

package/src/v2/components/CopilotKitInspector.tsx

@@ -0,0 +1,50 @@
+import * as React from "react";
+import { createComponent } from "@lit-labs/react";
+import type { CopilotKitCore } from "@copilotkit/core";
+
+type CopilotKitInspectorBaseProps = {
+  core?: CopilotKitCore | null;
+  [key: string]: unknown;
+};
+
+type InspectorComponent = React.ComponentType<CopilotKitInspectorBaseProps>;
+
+export interface CopilotKitInspectorProps extends CopilotKitInspectorBaseProps {}
+
+export const CopilotKitInspector: React.FC<CopilotKitInspectorProps> = ({
+  core,
+  ...rest
+}) => {
+  const [InspectorComponent, setInspectorComponent] =
+    React.useState<InspectorComponent | null>(null);
+
+  React.useEffect(() => {
+    let mounted = true;
+
+    // Load the web component only on the client to keep SSR output stable.
+    import("@copilotkit/web-inspector").then((mod) => {
+      mod.defineWebInspector?.();
+
+      const Component = createComponent({
+        tagName: mod.WEB_INSPECTOR_TAG,
+        elementClass: mod.WebInspectorElement,
+        react: React,
+      }) as InspectorComponent;
+
+      if (mounted) {
+        setInspectorComponent(() => Component);
+      }
+    });
+
+    return () => {
+      mounted = false;
+    };
+  }, []);
+
+  // During SSR (and until the client finishes loading), render nothing to keep markup consistent.
+  if (!InspectorComponent) return null;
+
+  return <InspectorComponent {...rest} core={core ?? null} />;
+};
+
+CopilotKitInspector.displayName = "CopilotKitInspector";