@copilotkit/vue 2.0.0-rc.3 → 2.0.0-rc.30

package/src/hooks/zod-parameters.ts

@@ -0,0 +1,162 @@
+import * as z from "zod";
+import { actionParametersToJsonSchema } from "@copilotkit/shared";
+import type { Parameter } from "@copilotkit/shared";
+
+/**
+ * Convert a JSON Schema to a Zod schema. Resolves `$ref` against `$defs` /
+ * `definitions`, maps `anyOf` / `oneOf` to unions, and falls back to
+ * `z.any()` for circular refs and unsupported types.
+ *
+ * Moved here from `@copilotkit/shared` in 2.0 so that shared does not depend
+ * on zod.
+ */
+export function convertJsonSchemaToZodSchema(
+  jsonSchema: any,
+  required: boolean,
+  definitions?: Record<string, any>,
+  visitedRefs?: Set<string>,
+): z.ZodSchema {
+  // Resolve $ref references
+  if (jsonSchema.$ref && definitions) {
+    const refPath = jsonSchema.$ref.replace(
+      /^#\/\$defs\/|^#\/definitions\//,
+      "",
+    );
+
+    // Detect circular $ref cycles
+    const refs = visitedRefs ?? new Set<string>();
+    if (refs.has(refPath)) {
+      console.warn(
+        `[CopilotKit] Circular $ref detected for "${refPath}" — falling back to z.any()`,
+      );
+      let schema = z.any();
+      if (jsonSchema.description) {
+        schema = schema.describe(jsonSchema.description);
+      }
+      return required ? schema : schema.optional();
+    }
+
+    const resolved = definitions[refPath];
+    if (resolved) {
+      // Clone the set so sibling branches don't see each other's visited refs
+      const nextRefs = new Set(refs);
+      nextRefs.add(refPath);
+      return convertJsonSchemaToZodSchema(
+        resolved,
+        required,
+        definitions,
+        nextRefs,
+      );
+    }
+  }
+
+  // Collect top-level definitions for $ref resolution
+  const defs = definitions ?? jsonSchema.$defs ?? jsonSchema.definitions;
+
+  // Handle null-union types like ["string", "null"]
+  if (Array.isArray(jsonSchema.type)) {
+    const types = jsonSchema.type as string[];
+    const hasNull = types.includes("null");
+    const nonNullTypes = types.filter((t: string) => t !== "null");
+    const resolvedType = nonNullTypes.length > 0 ? nonNullTypes[0] : "string";
+    const innerSchema = convertJsonSchemaToZodSchema(
+      { ...jsonSchema, type: resolvedType },
+      true,
+      defs,
+      visitedRefs,
+    );
+    let schema = hasNull ? z.union([innerSchema, z.null()]) : innerSchema;
+    if (jsonSchema.description) {
+      schema = schema.describe(jsonSchema.description);
+    }
+    return required ? schema : schema.optional();
+  }
+
+  // Handle anyOf / oneOf as z.union
+  const unionVariants = jsonSchema.anyOf ?? jsonSchema.oneOf;
+  if (Array.isArray(unionVariants) && unionVariants.length > 0) {
+    if (unionVariants.length === 1) {
+      return convertJsonSchemaToZodSchema(
+        unionVariants[0],
+        required,
+        defs,
+        visitedRefs,
+      );
+    }
+    const schemas = unionVariants.map((v: any) =>
+      convertJsonSchemaToZodSchema(v, true, defs, visitedRefs),
+    );
+    let schema = z.union(
+      schemas as [z.ZodSchema, z.ZodSchema, ...z.ZodSchema[]],
+    );
+    if (jsonSchema.description) {
+      schema = schema.describe(jsonSchema.description);
+    }
+    return required ? schema : schema.optional();
+  }
+
+  if (jsonSchema.type === "object") {
+    const spec: { [key: string]: z.ZodSchema } = {};
+
+    if (!jsonSchema.properties || !Object.keys(jsonSchema.properties).length) {
+      return !required ? z.object(spec).optional() : z.object(spec);
+    }
+
+    for (const [key, value] of Object.entries(jsonSchema.properties)) {
+      spec[key] = convertJsonSchemaToZodSchema(
+        value,
+        jsonSchema.required ? jsonSchema.required.includes(key) : false,
+        defs,
+        visitedRefs,
+      );
+    }
+    let schema = z.object(spec).describe(jsonSchema.description);
+    return required ? schema : schema.optional();
+  } else if (jsonSchema.type === "string") {
+    if (jsonSchema.enum && jsonSchema.enum.length > 0) {
+      let schema = z
+        .enum(jsonSchema.enum as [string, ...string[]])
+        .describe(jsonSchema.description);
+      return required ? schema : schema.optional();
+    }
+    let schema = z.string().describe(jsonSchema.description);
+    return required ? schema : schema.optional();
+  } else if (jsonSchema.type === "number" || jsonSchema.type === "integer") {
+    let schema = z.number().describe(jsonSchema.description);
+    return required ? schema : schema.optional();
+  } else if (jsonSchema.type === "boolean") {
+    let schema = z.boolean().describe(jsonSchema.description);
+    return required ? schema : schema.optional();
+  } else if (jsonSchema.type === "array") {
+    let itemSchema = convertJsonSchemaToZodSchema(
+      jsonSchema.items,
+      true,
+      defs,
+      visitedRefs,
+    );
+    let schema = z.array(itemSchema).describe(jsonSchema.description);
+    return required ? schema : schema.optional();
+  } else if (jsonSchema.type === "null") {
+    let schema = z.null().describe(jsonSchema.description);
+    return required ? schema : schema.optional();
+  }
+
+  // Fallback: accept any value rather than throwing
+  console.warn(
+    `[CopilotKit] Unsupported JSON schema type "${jsonSchema.type ?? "unknown"}" — falling back to z.any()`,
+  );
+  let schema = z.any();
+  if (jsonSchema.description) {
+    schema = schema.describe(jsonSchema.description);
+  }
+  return required ? schema : schema.optional();
+}
+
+/** Convert v1 `Parameter[]` action parameters to a Zod object schema. */
+export function getZodParameters<T extends [] | Parameter[] | undefined>(
+  parameters: T,
+): any {
+  if (!parameters) return z.object({});
+  const jsonParams = actionParametersToJsonSchema(parameters);
+  return convertJsonSchemaToZodSchema(jsonParams, true);
+}

package/src/v2/__tests__/exports.test.ts

@@ -24,6 +24,16 @@ describe("package exports", () => {
     expect(typeof VuePackage.MCPAppsActivityRenderer).toBe("object");
     expect(VuePackage.A2UISurfaceActivityType).toBe("a2ui-surface");
     expect(typeof VuePackage.A2UISurfaceActivityRenderer).toBe("object");
+    expect(
+      VuePackage.getOperationSurfaceId({ createSurface: { surfaceId: "s" } }),
+    ).toBe("s");
+    // Standard Schemas since 2.0 (see the generative UI migration guide).
+    expect(VuePackage.OpenGenerativeUIContentSchema["~standard"].vendor).toBe(
+      "copilotkit",
+    );
+    expect(VuePackage.GenerateSandboxedUiArgsSchema["~standard"].vendor).toBe(
+      "copilotkit",
+    );
   });
 
   it("exports the default A2UI catalog for the catalog-on-provider path", () => {

package/src/v2/__tests__/mocks/web-inspector.ts

@@ -12,6 +12,12 @@ export class WebInspectorElement extends HTMLElement {
   connectedCallback() {
     this.autoAttachCoreAtConnection = this.autoAttachCore;
     this.coreAtConnection = this.core;
+    // The real element reports that it is shown after its first render.
+    this.dispatchEvent(
+      new CustomEvent("cpk-inspector-visibility-change", {
+        detail: { visible: true },
+      }),
+    );
   }
 }
 

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

@@ -178,11 +178,26 @@ export class MockStepwiseAgent extends AbstractAgent {
 
   run(_input: RunAgentInput): Observable<BaseEvent> {
     return new Observable<BaseEvent>((observer) => {
-      const subscription = this.subject.subscribe(observer);
+      // Finish each run at its terminal event, as a real agent does, while
+      // keeping the shared subject for the next run in a multi-turn test. A
+      // send waits for the run in flight, so a run that never ends would hold
+      // every later send.
+      const deliver = (event: BaseEvent) => {
+        observer.next(event);
+        const isTerminal =
+          event.type === EventType.RUN_FINISHED ||
+          event.type === EventType.RUN_ERROR;
+        if (isTerminal) observer.complete();
+      };
+      const subscription = this.subject.subscribe({
+        next: deliver,
+        error: (error: unknown) => observer.error(error),
+        complete: () => observer.complete(),
+      });
       void this.enqueueDelivery(async () => {
         if (this.bufferedEvents.length > 0) {
           for (const event of this.bufferedEvents) {
-            observer.next(event);
+            deliver(event);
           }
           this.bufferedEvents = [];
         }
@@ -386,11 +401,26 @@ export class MockReconnectableAgent extends AbstractAgent {
 
   run(_input: RunAgentInput): Observable<BaseEvent> {
     return new Observable<BaseEvent>((observer) => {
-      const subscription = this.subject.subscribe(observer);
+      // Finish each run at its terminal event, as a real agent does, while
+      // keeping the shared subject for the next run in a multi-turn test. A
+      // send waits for the run in flight, so a run that never ends would hold
+      // every later send.
+      const deliver = (event: BaseEvent) => {
+        observer.next(event);
+        const isTerminal =
+          event.type === EventType.RUN_FINISHED ||
+          event.type === EventType.RUN_ERROR;
+        if (isTerminal) observer.complete();
+      };
+      const subscription = this.subject.subscribe({
+        next: deliver,
+        error: (error: unknown) => observer.error(error),
+        complete: () => observer.complete(),
+      });
       void this.enqueueDelivery(async () => {
         if (this.bufferedEvents.length > 0) {
           for (const event of this.bufferedEvents) {
-            observer.next(event);
+            deliver(event);
           }
           this.bufferedEvents = [];
         }

package/src/v2/components/A2UIMessageRenderer.ts

@@ -1,20 +1,22 @@
-import { computed, defineComponent, h } from "vue";
-import type { PropType } from "vue";
-import { z } from "zod";
+import { defineComponent, h, onBeforeUnmount, shallowRef, watch } from "vue";
+import type { Component, PropType } from "vue";
+import {
+  ɵA2UIActivityController,
+  ɵA2UI_SURFACE_ACTIVITY_TYPE,
+  ɵA2UI_SURFACE_CONTENT_SCHEMA,
+} from "@copilotkit/core";
+import type {
+  ɵA2UIActionAgent,
+  ɵA2UIActionInterceptor,
+  ɵA2UISurfaceContent,
+} from "@copilotkit/core";
+import type { ActivityMessage } from "@ag-ui/core";
 import type { VueActivityMessageRenderer } from "../types";
 import type { A2UITheme } from "../types";
 import A2UISurfaceActivityRenderer from "./A2UISurfaceActivityRenderer.vue";
-import {
-  A2UIBuildingState,
-  A2UILifecycleFields,
-  A2UIRecoveryFailure,
-  A2UIRetryingState,
-  resolveDebugExposure,
-} from "./a2ui/A2UIRecoveryStates";
+import { renderA2UILifecycleState } from "./a2ui/A2UIRecoveryStates";
 import type { A2UIRecoveryRendererOptions } from "./a2ui/A2UIRecoveryStates";
 
-const A2UI_OPERATIONS_KEY = "a2ui_operations";
-
 export type A2UIMessageRendererOptions = {
   theme: A2UITheme;
   catalog?: any;
@@ -25,88 +27,116 @@ export type A2UIMessageRendererOptions = {
    * sub-label appears, and how much retry/debug detail to surface.
    */
   recovery?: A2UIRecoveryRendererOptions;
+  /**
+   * Intercept actions before they reach the agent: return `null` to handle an
+   * action client-side, return an action to forward that one instead, or
+   * return nothing to forward it unchanged.
+   */
+  onAction?: ɵA2UIActionInterceptor;
 };
 
+function isComponent(value: unknown): value is Component {
+  return (
+    typeof value === "function" || (typeof value === "object" && value !== null)
+  );
+}
+
 /**
  * The `a2ui-surface` activity carries the WHOLE generative-UI lifecycle on one
  * stable messageId: pre-paint `status` ("building" | "retrying" | "failed")
- * with recovery detail, then `a2ui_operations` on paint. The states swap in
- * place, so the painted surface replaces the skeleton. `.passthrough()` keeps
- * the operations and any future fields.
+ * with recovery detail, then `a2ui_operations` on paint. Core's
+ * `ɵA2UIActivityController` decides what shows; this renderer draws it and
+ * keeps the surface mounted, hidden under the loader, until it has painted.
  */
-const A2UISurfaceContentSchema = z
-  .object({
-    a2ui_operations: z.array(z.any()).optional(),
-    ...A2UILifecycleFields,
-  })
-  .passthrough();
-
 export function createA2UIMessageRenderer(
   options: A2UIMessageRendererOptions,
 ): VueActivityMessageRenderer<any> {
-  const showAfterMs = options.recovery?.showAfterMs ?? 2000;
-  const showAfterAttempts = options.recovery?.showAfterAttempts ?? 2;
-  const optionDebugExposure = options.recovery?.debugExposure ?? "collapsed";
-
-  // Renders the pre-paint lifecycle state for a content snapshot.
-  const renderLifecycle = (content: any) => {
-    const debugExposure = resolveDebugExposure(content, optionDebugExposure);
-    if (content?.status === "failed") {
-      return h(A2UIRecoveryFailure, { content, debugExposure });
-    }
-    if (content?.status === "retrying") {
-      return h(A2UIRetryingState, {
-        content,
-        showAfterMs,
-        showAfterAttempts,
-        debugExposure,
-      });
-    }
-    // "building" / default: a host-supplied loader wins; else the skeleton.
-    if (options.loadingComponent) {
-      return h(options.loadingComponent as any);
-    }
-    return h(A2UIBuildingState, { content });
-  };
+  const loadingComponent = isComponent(options.loadingComponent)
+    ? options.loadingComponent
+    : undefined;
 
   return {
-    activityType: "a2ui-surface",
-    content: A2UISurfaceContentSchema,
+    activityType: ɵA2UI_SURFACE_ACTIVITY_TYPE,
+    content: ɵA2UI_SURFACE_CONTENT_SCHEMA,
     render: defineComponent({
       name: "A2UIMessageRendererHost",
       props: {
         activityType: { type: String, required: true },
-        content: { type: Object as PropType<any>, required: true },
-        message: { type: Object as PropType<any>, required: true },
+        content: {
+          type: Object as PropType<ɵA2UISurfaceContent>,
+          required: true,
+        },
+        message: { type: Object as PropType<ActivityMessage>, required: true },
         agent: {
-          type: Object as PropType<any>,
+          type: Object as PropType<ɵA2UIActionAgent>,
           required: false,
           default: undefined,
         },
       },
       setup(props) {
-        const operations = computed(() =>
-          Array.isArray(props.content?.[A2UI_OPERATIONS_KEY])
-            ? props.content[A2UI_OPERATIONS_KEY]
-            : [],
+        const controller = new ɵA2UIActivityController({
+          recovery: options.recovery,
+          warn:
+            process.env.NODE_ENV !== "production"
+              ? (message) => console.warn(message)
+              : undefined,
+        });
+        const snapshot = shallowRef(controller.getSnapshot());
+        const unsubscribe = controller.subscribe(() => {
+          snapshot.value = controller.getSnapshot();
+        });
+        watch(
+          () => props.content,
+          (content) => controller.setContent(content),
+          { immediate: true },
         );
+        onBeforeUnmount(() => {
+          unsubscribe();
+          controller.dispose();
+        });
+        const markRendered = () => controller.markRendered();
 
         return () => {
-          // No painted surface yet → the pre-paint lifecycle state. It shares
-          // this activity's messageId, so the painted surface below replaces
-          // it in place once operations arrive.
-          if (operations.value.length === 0) {
-            return renderLifecycle(props.content);
+          const current = snapshot.value;
+          if (current.view === "lifecycle") {
+            return renderA2UILifecycleState(current, loadingComponent);
           }
 
-          return h(A2UISurfaceActivityRenderer, {
-            activityType: "a2ui-surface",
-            content: { operations: operations.value },
-            message: props.message,
-            agent: props.agent,
-            theme: options.theme,
-            catalog: options.catalog,
-          });
+          const handingOff = current.view === "handoff";
+          return h("div", { style: { position: "relative" } }, [
+            // The surface stays mounted in the same place across the
+            // hand-off; only its wrapper styling changes, so what painted
+            // while hidden is kept.
+            h(
+              "div",
+              {
+                "aria-hidden": handingOff ? "true" : undefined,
+                style: handingOff
+                  ? {
+                      position: "absolute",
+                      inset: "0",
+                      opacity: 0,
+                      pointerEvents: "none",
+                    }
+                  : undefined,
+              },
+              [
+                h(A2UISurfaceActivityRenderer, {
+                  activityType: ɵA2UI_SURFACE_ACTIVITY_TYPE,
+                  content: { operations: current.operations },
+                  message: props.message,
+                  agent: props.agent,
+                  theme: options.theme,
+                  catalog: options.catalog,
+                  onAction: options.onAction,
+                  onRendered: markRendered,
+                }),
+              ],
+            ),
+            handingOff
+              ? renderA2UILifecycleState(current, loadingComponent)
+              : null,
+          ]);
         };
       },
     }),