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

package/src/v2/__tests__/A2UIMessageRenderer.test.tsx

@@ -22,19 +22,25 @@ describe("A2UIMessageRenderer rendering integration", () => {
     });
 
     const content = {
-      operations: [
+      a2ui_operations: [
         {
-          beginRendering: {
+          version: "v0.9",
+          createSurface: {
             surfaceId: "test-surface",
-            root: "root",
-            styles: {},
+            catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json",
           },
         },
         {
-          surfaceUpdate: {
+          version: "v0.9",
+          updateComponents: {
             surfaceId: "test-surface",
             components: [
-              { id: "root", text: { literalString: "Hello World" } },
+              {
+                id: "root",
+                component: "Text",
+                text: "Hello World",
+                variant: "body",
+              },
             ],
           },
         },
@@ -69,12 +75,27 @@ describe("A2UIMessageRenderer rendering integration", () => {
     let setContent: (content: any) => void;
     const TestWrapper = () => {
       const [content, _setContent] = useState({
-        operations: [
-          { beginRendering: { surfaceId: "test", root: "root", styles: {} } },
+        a2ui_operations: [
           {
-            surfaceUpdate: {
+            version: "v0.9",
+            createSurface: {
               surfaceId: "test",
-              components: [{ id: "root", text: { literalString: "Initial" } }],
+              catalogId:
+                "https://a2ui.org/specification/v0_9/basic_catalog.json",
+            },
+          },
+          {
+            version: "v0.9",
+            updateComponents: {
+              surfaceId: "test",
+              components: [
+                {
+                  id: "root",
+                  component: "Text",
+                  text: "Initial",
+                  variant: "body",
+                },
+              ],
             },
           },
         ],
@@ -94,12 +115,27 @@ describe("A2UIMessageRenderer rendering integration", () => {
 
     await act(async () => {
       setContent({
-        operations: [
-          { beginRendering: { surfaceId: "test", root: "root", styles: {} } },
+        a2ui_operations: [
+          {
+            version: "v0.9",
+            createSurface: {
+              surfaceId: "test",
+              catalogId:
+                "https://a2ui.org/specification/v0_9/basic_catalog.json",
+            },
+          },
           {
-            surfaceUpdate: {
+            version: "v0.9",
+            updateComponents: {
               surfaceId: "test",
-              components: [{ id: "root", text: { literalString: "Updated" } }],
+              components: [
+                {
+                  id: "root",
+                  component: "Text",
+                  text: "Updated",
+                  variant: "body",
+                },
+              ],
             },
           },
         ],
@@ -119,7 +155,7 @@ describe("A2UIMessageRenderer rendering integration", () => {
     const RenderComponent = renderer.render as React.FC<any>;
 
     const TestWrapper = () => (
-      <RenderComponent content={{ operations: [] }} agent={null} />
+      <RenderComponent content={{ a2ui_operations: [] }} agent={null} />
     );
 
     let container: HTMLElement;
@@ -140,19 +176,47 @@ describe("A2UIMessageRenderer rendering integration", () => {
     const RenderComponent = renderer.render as React.FC<any>;
 
     const content = {
-      operations: [
-        { beginRendering: { surfaceId: "s1", root: "r1", styles: {} } },
-        { beginRendering: { surfaceId: "s2", root: "r2", styles: {} } },
+      a2ui_operations: [
+        {
+          version: "v0.9",
+          createSurface: {
+            surfaceId: "s1",
+            catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json",
+          },
+        },
+        {
+          version: "v0.9",
+          createSurface: {
+            surfaceId: "s2",
+            catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json",
+          },
+        },
         {
-          surfaceUpdate: {
+          version: "v0.9",
+          updateComponents: {
             surfaceId: "s1",
-            components: [{ id: "r1", text: { literalString: "Surface 1" } }],
+            components: [
+              {
+                id: "root",
+                component: "Text",
+                text: "Surface 1",
+                variant: "body",
+              },
+            ],
           },
         },
         {
-          surfaceUpdate: {
+          version: "v0.9",
+          updateComponents: {
             surfaceId: "s2",
-            components: [{ id: "r2", text: { literalString: "Surface 2" } }],
+            components: [
+              {
+                id: "root",
+                component: "Text",
+                text: "Surface 2",
+                variant: "body",
+              },
+            ],
           },
         },
       ],

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

@@ -51,9 +51,18 @@ export class MockStepwiseAgent extends AbstractAgent {
     });
   }
 
-  clone(): MockStepwiseAgent {
-    // For tests, return same instance so we can keep controlling it
-    return this;
+  clone(): this {
+    // Return a new instance that shares the same subject so tests can keep
+    // controlling events via the original reference while satisfying the
+    // clone() contract (must return a distinct object).
+    // Use the concrete constructor so subclasses (e.g. FailingConnectAgent)
+    // preserve their overridden methods.
+    const cloned = new (this
+      .constructor as new () => MockStepwiseAgent)() as this;
+    cloned.agentId = this.agentId;
+    (cloned as unknown as { subject: Subject<BaseEvent> }).subject =
+      this.subject;
+    return cloned;
   }
 
   // No-op: prevent the base class from tearing down the Subject
@@ -110,7 +119,21 @@ export class MockReconnectableAgent extends AbstractAgent {
   }
 
   clone(): MockReconnectableAgent {
-    return this;
+    const cloned = new MockReconnectableAgent();
+    cloned.agentId = this.agentId;
+    (
+      cloned as unknown as {
+        subject: Subject<BaseEvent>;
+        storedEvents: BaseEvent[];
+      }
+    ).subject = this.subject;
+    (
+      cloned as unknown as {
+        subject: Subject<BaseEvent>;
+        storedEvents: BaseEvent[];
+      }
+    ).storedEvents = this.storedEvents;
+    return cloned;
   }
 
   // No-op: prevent the base class from tearing down the Subject
@@ -141,6 +164,7 @@ export function renderWithCopilotKit({
   humanInTheLoop,
   agentId,
   threadId,
+  defaultThrottleMs,
   children,
 }: {
   agent?: AbstractAgent;
@@ -152,6 +176,7 @@ export function renderWithCopilotKit({
   humanInTheLoop?: any[];
   agentId?: string;
   threadId?: string;
+  defaultThrottleMs?: number;
   children?: React.ReactNode;
 }): ReturnType<typeof render> {
   const resolvedAgents = agents || (agent ? { default: agent } : undefined);
@@ -166,6 +191,7 @@ export function renderWithCopilotKit({
       renderActivityMessages={renderActivityMessages}
       frontendTools={frontendTools}
       humanInTheLoop={humanInTheLoop}
+      defaultThrottleMs={defaultThrottleMs}
     >
       <CopilotChatConfigurationProvider
         agentId={resolvedAgentId}
@@ -394,6 +420,70 @@ export function testId(prefix: string): string {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
 }
 
+// Varied content lengths for realistic message sizes in perf tests.
+const SAMPLE_ASSISTANT_TEXTS = [
+  "Sure! I'd be happy to help you with that.",
+  "The weather in San Francisco today is 65°F with partly cloudy skies.",
+  "Here are the main points from the meeting: 1) Roadmap review, 2) Bug triage, 3) Release planning.",
+  "To configure a custom agent, extend AbstractAgent and implement the run() method. Register it with CopilotKitProvider via the agents__unsafe_dev_only prop.",
+  "Here is a React component that fetches data from an API endpoint using useEffect and useState.",
+];
+
+/**
+ * Generate a realistic sequence of BaseEvents for N assistant messages.
+ * Uses TEXT_MESSAGE_CHUNK (the only event type proven to create rendered messages
+ * in jsdom tests). Every 5th message includes a tool call.
+ *
+ * Wrap in RUN_STARTED / RUN_FINISHED yourself if you need a full run sequence:
+ * @example
+ * agent.emit(runStartedEvent());
+ * for (const event of generateMessages(100)) agent.emit(event);
+ * agent.emit(runFinishedEvent());
+ */
+export function generateMessages(n: number): BaseEvent[] {
+  const events: BaseEvent[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const msgId = `gen-msg-${i}`;
+    const text = SAMPLE_ASSISTANT_TEXTS[i % SAMPLE_ASSISTANT_TEXTS.length];
+
+    // Stream content in ~20-char chunks to simulate real streaming
+    for (let offset = 0; offset < text.length; offset += 20) {
+      events.push(textChunkEvent(msgId, text.slice(offset, offset + 20)));
+    }
+
+    // Every 5th message has a tool call for realistic variety
+    if (i % 5 === 4) {
+      const tcId = `gen-tc-${i}`;
+      const tcResult = `{"result":"tool output for message ${i}"}`;
+      events.push(
+        toolCallChunkEvent({
+          toolCallId: tcId,
+          toolCallName: "exampleTool",
+          parentMessageId: msgId,
+          delta: "",
+        }),
+      );
+      events.push(
+        toolCallChunkEvent({
+          toolCallId: tcId,
+          parentMessageId: msgId,
+          delta: tcResult,
+        }),
+      );
+      events.push(
+        toolCallResultEvent({
+          toolCallId: tcId,
+          messageId: `${msgId}-result`,
+          content: tcResult,
+        }),
+      );
+    }
+  }
+
+  return events;
+}
+
 /**
  * Helper to emit a complete suggestion tool call with streaming chunks
  */
@@ -440,10 +530,20 @@ export function emitSuggestionToolCall(
  * A MockStepwiseAgent that emits suggestion events when run() is called
  */
 export class SuggestionsProviderAgent extends MockStepwiseAgent {
-  private _suggestions: Array<{ title: string; message: string }> = [];
+  // Shared via a container so clone() and original see the same value even
+  // when setSuggestions() is called after the clone is created.
+  private _shared: { suggestions: Array<{ title: string; message: string }> } =
+    { suggestions: [] };
 
   setSuggestions(suggestions: Array<{ title: string; message: string }>) {
-    this._suggestions = suggestions;
+    this._shared.suggestions = suggestions;
+  }
+
+  clone(): this {
+    const cloned = super.clone();
+    (cloned as unknown as { _shared: typeof this._shared })._shared =
+      this._shared;
+    return cloned;
   }
 
   run(_input: RunAgentInput): Observable<BaseEvent> {
@@ -458,7 +558,7 @@ export class SuggestionsProviderAgent extends MockStepwiseAgent {
       emitSuggestionToolCall(this, {
         toolCallId: testId("tc"),
         parentMessageId: messageId,
-        suggestions: this._suggestions,
+        suggestions: this._shared.suggestions,
       });
 
       this.emit({ type: EventType.RUN_FINISHED } as BaseEvent);

package/src/v2/a2ui/A2UICatalogContext.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import {
+  buildCatalogContextValue,
+  A2UI_SCHEMA_CONTEXT_DESCRIPTION,
+  extractCatalogComponentSchemas,
+} from "@copilotkit/a2ui-renderer";
+import {
+  A2UI_DEFAULT_GENERATION_GUIDELINES,
+  A2UI_DEFAULT_DESIGN_GUIDELINES,
+} from "@copilotkit/shared";
+import { useAgentContext } from "../hooks/use-agent-context";
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useLayoutEffect, useMemo } from "react";
+
+/**
+ * Renders agent context describing the available A2UI catalog and custom components.
+ * Only mount this component when A2UI is enabled.
+ *
+ * When `includeSchema` is true, the full component schemas (JSON Schema) are also
+ * sent as context using the same description key as the A2UI middleware, so the
+ * middleware can optionally overwrite it with a server-side schema.
+ */
+export function A2UICatalogContext({
+  catalog,
+  includeSchema,
+}: {
+  catalog?: any;
+  includeSchema?: boolean;
+}) {
+  const contextValue = buildCatalogContextValue(catalog);
+
+  useAgentContext({
+    description:
+      "A2UI catalog capabilities: available catalog IDs and custom component definitions the client can render.",
+    value: contextValue,
+  });
+
+  // When includeSchema is true, send full component schemas in the same format
+  // as the A2UI middleware so it can overwrite with a server-side schema if needed.
+  const { copilotkit } = useCopilotKit();
+  const schemaValue = useMemo(
+    () =>
+      includeSchema !== false
+        ? JSON.stringify(extractCatalogComponentSchemas(catalog))
+        : null,
+    [catalog, includeSchema],
+  );
+
+  useLayoutEffect(() => {
+    if (!copilotkit || !schemaValue) return;
+    const ids: string[] = [];
+    ids.push(
+      copilotkit.addContext({
+        description: A2UI_SCHEMA_CONTEXT_DESCRIPTION,
+        value: schemaValue,
+      }),
+    );
+    ids.push(
+      copilotkit.addContext({
+        description:
+          "A2UI generation guidelines — protocol rules, tool arguments, path rules, data model format, and form/two-way-binding instructions.",
+        value: A2UI_DEFAULT_GENERATION_GUIDELINES,
+      }),
+    );
+    ids.push(
+      copilotkit.addContext({
+        description:
+          "A2UI design guidelines — visual design rules, component hierarchy tips, and action handler patterns.",
+        value: A2UI_DEFAULT_DESIGN_GUIDELINES,
+      }),
+    );
+    return () => {
+      for (const id of ids) copilotkit.removeContext(id);
+    };
+  }, [copilotkit, schemaValue]);
+
+  return null;
+}

package/src/v2/a2ui/A2UIMessageRenderer.tsx

@@ -5,6 +5,7 @@ import { z } from "zod";
 import {
   A2UIProvider,
   useA2UIActions,
+  useA2UIError,
   A2UIRenderer,
   initializeDefaultCatalog,
   injectStyles,
@@ -12,6 +13,12 @@ import {
 } from "@copilotkit/a2ui-renderer";
 import type { Theme, A2UIClientEventMessage } from "@copilotkit/a2ui-renderer";
 
+/**
+ * The container key used to wrap A2UI operations for explicit detection.
+ * Must match A2UI_OPERATIONS_KEY in @ag-ui/a2ui-middleware and copilotkit.a2ui (Python).
+ */
+const A2UI_OPERATIONS_KEY = "a2ui_operations";
+
 // Initialize the React renderer's component catalog and styles once
 let initialized = false;
 function ensureInitialized() {
@@ -22,14 +29,30 @@ function ensureInitialized() {
   }
 }
 
+/**
+ * User action with dataContextPath, as dispatched by A2UI components.
+ */
+export type A2UIUserAction = {
+  name: string;
+  sourceComponentId: string;
+  surfaceId: string;
+  timestamp: string;
+  context?: Record<string, unknown>;
+  dataContextPath?: string;
+};
+
 export type A2UIMessageRendererOptions = {
   theme: Theme;
+  /** Optional component catalog to pass to A2UIProvider */
+  catalog?: any;
+  /** Optional custom loading component shown while A2UI surface is generating. */
+  loadingComponent?: React.ComponentType;
 };
 
 export function createA2UIMessageRenderer(
   options: A2UIMessageRendererOptions,
 ): ReactActivityMessageRenderer<any> {
-  const { theme } = options;
+  const { theme, catalog, loadingComponent } = options;
 
   return {
     activityType: "a2ui-surface",
@@ -38,24 +61,20 @@ export function createA2UIMessageRenderer(
       ensureInitialized();
 
       const [operations, setOperations] = useState<any[]>([]);
-      const lastSignatureRef = useRef<string | null>(null);
       const { copilotkit } = useCopilotKit();
 
+      const lastContentRef = useRef<unknown>(null);
       useEffect(() => {
-        if (!content || !Array.isArray(content.operations)) {
-          lastSignatureRef.current = null;
-          setOperations([]);
-          return;
-        }
-
-        const incoming = content.operations as any[];
-        const signature = stringifyOperations(incoming);
+        // Skip if same content reference
+        if (content === lastContentRef.current) return;
+        lastContentRef.current = content;
 
-        if (signature && signature === lastSignatureRef.current) {
+        const incoming = content?.[A2UI_OPERATIONS_KEY];
+        if (!content || !Array.isArray(incoming)) {
+          setOperations([]);
           return;
         }
 
-        lastSignatureRef.current = signature;
         setOperations(incoming);
       }, [content]);
 
@@ -77,7 +96,9 @@ export function createA2UIMessageRenderer(
       }, [operations]);
 
       if (!groupedOperations.size) {
-        return null;
+        // Show loading state while A2UI surface is being generated
+        const LoadingComponent = loadingComponent ?? DefaultA2UILoading;
+        return <LoadingComponent />;
       }
 
       return (
@@ -90,6 +111,7 @@ export function createA2UIMessageRenderer(
               theme={theme}
               agent={agent}
               copilotkit={copilotkit}
+              catalog={catalog}
             />
           ))}
         </div>
@@ -104,6 +126,8 @@ type ReactSurfaceHostProps = {
   theme: Theme;
   agent: any;
   copilotkit: any;
+  /** Optional component catalog to pass to A2UIProvider */
+  catalog?: any;
 };
 
 /**
@@ -116,15 +140,16 @@ function ReactSurfaceHost({
   theme,
   agent,
   copilotkit,
+  catalog,
 }: ReactSurfaceHostProps) {
-  // Bridge: when the React renderer dispatches an action, send it to CopilotKit
+  // Bridge: when the React renderer dispatches an action, forward to CopilotKit
   const handleAction = useCallback(
     async (message: A2UIClientEventMessage) => {
       if (!agent) return;
 
-      try {
-        console.info("[A2UI] Action dispatched", message.userAction);
+      const action = message.userAction as A2UIUserAction | undefined;
 
+      try {
         copilotkit.setProperties({
           ...(copilotkit.properties ?? {}),
           a2uiAction: message,
@@ -143,17 +168,33 @@ function ReactSurfaceHost({
 
   return (
     <div className="cpk:flex cpk:w-full cpk:flex-none cpk:flex-col cpk:gap-4">
-      <A2UIProvider onAction={handleAction} theme={theme}>
+      <A2UIProvider onAction={handleAction} theme={theme} catalog={catalog}>
         <SurfaceMessageProcessor
           surfaceId={surfaceId}
           operations={operations}
         />
-        <A2UIRenderer surfaceId={surfaceId} className="cpk:flex cpk:flex-1" />
+        <A2UISurfaceOrError surfaceId={surfaceId} />
       </A2UIProvider>
     </div>
   );
 }
 
+/**
+ * Renders the A2UI surface, or an error message if processing failed.
+ * Must be a child of A2UIProvider to access the error state.
+ */
+function A2UISurfaceOrError({ surfaceId }: { surfaceId: string }) {
+  const error = useA2UIError();
+  if (error) {
+    return (
+      <div className="cpk:rounded-lg cpk:border cpk:border-red-200 cpk:bg-red-50 cpk:p-3 cpk:text-sm cpk:text-red-700">
+        A2UI render error: {error}
+      </div>
+    );
+  }
+  return <A2UIRenderer surfaceId={surfaceId} className="cpk:flex cpk:flex-1" />;
+}
+
 /**
  * Processes A2UI operations into the provider's message processor.
  * Must be a child of A2UIProvider to access the actions context.
@@ -165,20 +206,74 @@ function SurfaceMessageProcessor({
   surfaceId: string;
   operations: any[];
 }) {
-  const { processMessages } = useA2UIActions();
-  const lastProcessedRef = useRef<string>("");
-
+  const { processMessages, getSurface } = useA2UIActions();
+  const lastHashRef = useRef<string>("");
   useEffect(() => {
-    const key = `${surfaceId}-${JSON.stringify(operations)}`;
-    if (key === lastProcessedRef.current) return;
-    lastProcessedRef.current = key;
+    // Skip if operations haven't actually changed (deep compare via hash).
+    // ACTIVITY_DELTA + ACTIVITY_SNAPSHOT can trigger multiple renders with
+    // the same logical content but different object references.
+    const hash = JSON.stringify(operations);
+    if (hash === lastHashRef.current) return;
+    lastHashRef.current = hash;
 
-    processMessages(operations);
-  }, [processMessages, surfaceId, operations]);
+    // Filter out createSurface if the surface already exists — the
+    // MessageProcessor throws on duplicate createSurface, but content
+    // snapshots always include the full operation list.
+    const existing = getSurface(surfaceId);
+    const ops = existing
+      ? operations.filter((op) => !op?.createSurface)
+      : operations;
+
+    // Error handling is done inside A2UIProvider.processMessages
+    processMessages(ops);
+  }, [processMessages, getSurface, surfaceId, operations]);
 
   return null;
 }
 
+/**
+ * Default loading component shown while an A2UI surface is generating.
+ * Displays an animated shimmer skeleton.
+ */
+function DefaultA2UILoading() {
+  return (
+    <div
+      className="cpk:flex cpk:flex-col cpk:gap-3 cpk:rounded-xl cpk:border cpk:border-gray-100 cpk:bg-gray-50/50 cpk:p-5"
+      style={{ minHeight: 120 }}
+    >
+      <div className="cpk:flex cpk:items-center cpk:gap-2">
+        <div
+          className="cpk:h-3 cpk:w-3 cpk:rounded-full cpk:bg-gray-200"
+          style={{
+            animation: "cpk-a2ui-pulse 1.5s ease-in-out infinite",
+          }}
+        />
+        <span className="cpk:text-xs cpk:font-medium cpk:text-gray-400">
+          Generating UI...
+        </span>
+      </div>
+      <div className="cpk:flex cpk:flex-col cpk:gap-2">
+        {[0.8, 0.6, 0.4].map((width, i) => (
+          <div
+            key={i}
+            className="cpk:h-3 cpk:rounded cpk:bg-gray-200/70"
+            style={{
+              width: `${width * 100}%`,
+              animation: `cpk-a2ui-pulse 1.5s ease-in-out ${i * 0.15}s infinite`,
+            }}
+          />
+        ))}
+      </div>
+      <style>{`
+        @keyframes cpk-a2ui-pulse {
+          0%, 100% { opacity: 0.4; }
+          50% { opacity: 1; }
+        }
+      `}</style>
+    </div>
+  );
+}
+
 function getOperationSurfaceId(operation: any): string | null {
   if (!operation || typeof operation !== "object") {
     return null;
@@ -188,19 +283,12 @@ function getOperationSurfaceId(operation: any): string | null {
     return operation.surfaceId;
   }
 
+  // v0.9 message keys
   return (
-    operation?.beginRendering?.surfaceId ??
-    operation?.surfaceUpdate?.surfaceId ??
-    operation?.dataModelUpdate?.surfaceId ??
+    operation?.createSurface?.surfaceId ??
+    operation?.updateComponents?.surfaceId ??
+    operation?.updateDataModel?.surfaceId ??
     operation?.deleteSurface?.surfaceId ??
     null
   );
 }
-
-function stringifyOperations(ops: any[]): string | null {
-  try {
-    return JSON.stringify(ops);
-  } catch (error) {
-    return null;
-  }
-}