@copilotkit/vue 2.0.0-rc.1 → 2.0.0-rc.11

package/src/hooks/__tests__/zod-parameters.test.ts

@@ -0,0 +1,520 @@
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import type { Parameter } from "@copilotkit/shared";
+import {
+  convertJsonSchemaToZodSchema,
+  getZodParameters,
+} from "../zod-parameters";
+
+describe("convertJsonSchemaToZodSchema", () => {
+  it("should convert a simple JSON schema to a Zod schema", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        age: { type: "number" },
+      },
+      required: ["name", "age"],
+    };
+
+    const expectedSchema = z.object({
+      name: z.string(),
+      age: z.number(),
+    });
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const resultSchemaJson = z.toJSONSchema(result);
+    const expectedSchemaJson = z.toJSONSchema(expectedSchema);
+
+    expect(resultSchemaJson).toStrictEqual(expectedSchemaJson);
+  });
+
+  it("should convert a JSON schema with nested objects to a Zod schema", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        address: {
+          type: "object",
+          properties: {
+            street: { type: "string" },
+            city: { type: "string" },
+          },
+          required: ["street", "city"],
+        },
+      },
+      required: ["name", "address"],
+    };
+
+    const expectedSchema = z.object({
+      name: z.string(),
+      address: z.object({
+        street: z.string(),
+        city: z.string(),
+      }),
+    });
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const resultSchemaJson = z.toJSONSchema(result);
+    const expectedSchemaJson = z.toJSONSchema(expectedSchema);
+
+    expect(resultSchemaJson).toStrictEqual(expectedSchemaJson);
+  });
+
+  it("should convert a JSON schema with arrays to a Zod schema", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        names: {
+          type: "array",
+          items: { type: "string" },
+        },
+      },
+      required: ["names"],
+    };
+
+    const expectedSchema = z.object({
+      names: z.array(z.string()),
+    });
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const resultSchemaJson = z.toJSONSchema(result);
+    const expectedSchemaJson = z.toJSONSchema(expectedSchema);
+
+    expect(resultSchemaJson).toStrictEqual(expectedSchemaJson);
+  });
+
+  it("should convert a JSON schema with optional properties to a Zod schema", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        age: { type: "number", required: false },
+      },
+    };
+
+    const expectedSchema = z
+      .object({
+        name: z.string().optional(),
+        age: z.number().optional(),
+      })
+      .optional();
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, false);
+
+    const resultSchemaJson = z.toJSONSchema(result);
+    const expectedSchemaJson = z.toJSONSchema(expectedSchema);
+
+    expect(resultSchemaJson).toStrictEqual(expectedSchemaJson);
+  });
+
+  it("should convert a JSON schema with different types to a Zod schema", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        age: { type: "number" },
+        isAdmin: { type: "boolean" },
+      },
+      required: ["name", "age", "isAdmin"],
+    };
+
+    const expectedSchema = z.object({
+      name: z.string(),
+      age: z.number(),
+      isAdmin: z.boolean(),
+    });
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const resultSchemaJson = z.toJSONSchema(result);
+    const expectedSchemaJson = z.toJSONSchema(expectedSchema);
+
+    expect(resultSchemaJson).toStrictEqual(expectedSchemaJson);
+  });
+
+  it("should handle edge case where JSON schema has no properties", () => {
+    const jsonSchema = {
+      type: "object",
+    };
+
+    const expectedSchema = z.object({});
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const resultSchemaJson = z.toJSONSchema(result);
+    const expectedSchemaJson = z.toJSONSchema(expectedSchema);
+
+    expect(resultSchemaJson).toStrictEqual(expectedSchemaJson);
+  });
+
+  it("should preserve string enum constraints", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          description: "The status",
+          enum: ["todo", "done"],
+        },
+      },
+      required: ["status"],
+    };
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const statusSchema = (result as z.ZodObject<any>).shape.status;
+    expect(statusSchema).toBeInstanceOf(z.ZodEnum);
+    expect(statusSchema.options).toEqual(["todo", "done"]);
+  });
+
+  it("should handle null-union type ['string', 'null'] as nullable", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        nickname: {
+          type: ["string", "null"],
+          description: "Optional nickname",
+        },
+      },
+      required: ["nickname"],
+    };
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const shape = (result as z.ZodObject<any>).shape;
+
+    // The nickname field should accept both string and null
+    expect(shape.nickname.safeParse("hello").success).toBe(true);
+    expect(shape.nickname.safeParse(null).success).toBe(true);
+    expect(shape.nickname.safeParse(42).success).toBe(false);
+  });
+
+  it("should handle null-union type ['number', 'null'] as nullable number", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        score: {
+          type: ["number", "null"],
+        },
+      },
+      required: ["score"],
+    };
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const shape = (result as z.ZodObject<any>).shape;
+
+    expect(shape.score.safeParse(42).success).toBe(true);
+    expect(shape.score.safeParse(null).success).toBe(true);
+    expect(shape.score.safeParse("hello").success).toBe(false);
+  });
+
+  it("should handle edge case where JSON schema has no required properties", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        age: { type: "number" },
+      },
+    };
+
+    const expectedSchema = z
+      .object({
+        name: z.string().optional(),
+        age: z.number().optional(),
+      })
+      .optional();
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, false);
+    const resultSchemaJson = z.toJSONSchema(result);
+    const expectedSchemaJson = z.toJSONSchema(expectedSchema);
+
+    expect(resultSchemaJson).toStrictEqual(expectedSchemaJson);
+  });
+
+  it("should resolve non-circular $ref definitions correctly", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        address: { $ref: "#/$defs/Address" },
+      },
+      required: ["address"],
+      $defs: {
+        Address: {
+          type: "object",
+          properties: {
+            street: { type: "string", description: "Street name" },
+            city: { type: "string", description: "City name" },
+          },
+          required: ["street", "city"],
+          description: "A postal address",
+        },
+      },
+    };
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const resultJson = z.toJSONSchema(result);
+
+    const expectedSchema = z.object({
+      address: z
+        .object({
+          street: z.string().describe("Street name"),
+          city: z.string().describe("City name"),
+        })
+        .describe("A postal address"),
+    });
+    const expectedJson = z.toJSONSchema(expectedSchema);
+
+    expect(resultJson).toStrictEqual(expectedJson);
+  });
+
+  it("should handle circular $ref without crashing and return z.any()", () => {
+    // A schema where Node references itself — this would cause infinite
+    // recursion without cycle detection.
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        root: { $ref: "#/$defs/Node" },
+      },
+      required: ["root"],
+      $defs: {
+        Node: {
+          type: "object",
+          properties: {
+            value: { type: "string", description: "Node value" },
+            child: { $ref: "#/$defs/Node" },
+          },
+          required: ["value"],
+          description: "A tree node",
+        },
+      },
+    };
+
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    // Must not throw or hang
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    expect(result).toBeDefined();
+
+    // The circular ref should have produced a console.warn
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Circular $ref detected"),
+    );
+
+    // The top-level shape should still have a "root" key that is an object
+    const shape = (result as z.ZodObject<any>).shape;
+    expect(shape.root).toBeDefined();
+
+    // Inside root, "value" should be a string and "child" should be z.any()
+    // (child is optional since it's not in required[], so unwrap ZodOptional)
+    const rootShape = (shape.root as z.ZodObject<any>).shape;
+    expect(rootShape.value).toBeInstanceOf(z.ZodString);
+    const child = rootShape.child;
+    if (child instanceof z.ZodOptional) {
+      expect(child.unwrap()).toBeInstanceOf(z.ZodAny);
+    } else {
+      expect(child).toBeInstanceOf(z.ZodAny);
+    }
+
+    warnSpy.mockRestore();
+  });
+
+  it("should resolve the same $ref used by multiple sibling properties", () => {
+    // Two properties reference the same $def — the visited set must NOT
+    // mark the second usage as circular.
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        billing: { $ref: "#/$defs/Address" },
+        shipping: { $ref: "#/$defs/Address" },
+      },
+      required: ["billing", "shipping"],
+      $defs: {
+        Address: {
+          type: "object",
+          properties: {
+            street: { type: "string", description: "Street" },
+            city: { type: "string", description: "City" },
+          },
+          required: ["street", "city"],
+          description: "An address",
+        },
+      },
+    };
+
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const shape = (result as z.ZodObject<any>).shape;
+
+    // Both should be fully resolved objects, NOT z.any()
+    expect(shape.billing).toBeInstanceOf(z.ZodObject);
+    expect(shape.shipping).toBeInstanceOf(z.ZodObject);
+
+    // No circular-ref warning should have been emitted
+    expect(warnSpy).not.toHaveBeenCalled();
+
+    warnSpy.mockRestore();
+  });
+
+  it("should resolve a shared $ref used in different branches of a $ref chain", () => {
+    // Wrapper -> Container (via $ref) which has two children both using $ref to Leaf.
+    // Without set cloning, the second Leaf ref in Container would be wrongly flagged
+    // as circular because the first Leaf resolution already added it to the set.
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        wrapper: { $ref: "#/$defs/Container" },
+      },
+      required: ["wrapper"],
+      $defs: {
+        Container: {
+          type: "object",
+          properties: {
+            first: { $ref: "#/$defs/Leaf" },
+            second: { $ref: "#/$defs/Leaf" },
+          },
+          required: ["first", "second"],
+          description: "A container with two leaves",
+        },
+        Leaf: {
+          type: "object",
+          properties: {
+            label: { type: "string", description: "Leaf label" },
+          },
+          required: ["label"],
+          description: "A leaf node",
+        },
+      },
+    };
+
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const wrapperShape = (
+      (result as z.ZodObject<any>).shape.wrapper as z.ZodObject<any>
+    ).shape;
+
+    // Both first and second should be fully resolved Leaf objects
+    expect(wrapperShape.first).toBeInstanceOf(z.ZodObject);
+    expect(wrapperShape.second).toBeInstanceOf(z.ZodObject);
+
+    // No circular-ref warning should have been emitted
+    expect(warnSpy).not.toHaveBeenCalled();
+
+    warnSpy.mockRestore();
+  });
+
+  it("should handle anyOf with $ref variants", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        pet: {
+          anyOf: [{ $ref: "#/$defs/Cat" }, { $ref: "#/$defs/Dog" }],
+          description: "A pet",
+        },
+      },
+      required: ["pet"],
+      $defs: {
+        Cat: {
+          type: "object",
+          properties: { meow: { type: "boolean" } },
+          required: ["meow"],
+        },
+        Dog: {
+          type: "object",
+          properties: { bark: { type: "boolean" } },
+          required: ["bark"],
+        },
+      },
+    };
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    expect(result).toBeDefined();
+
+    // Should produce a union inside the "pet" property
+    const petSchema = (result as z.ZodObject<any>).shape.pet;
+    expect(petSchema).toBeInstanceOf(z.ZodUnion);
+  });
+
+  it("should handle integer type as z.number()", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        count: { type: "integer", description: "A count" },
+      },
+      required: ["count"],
+    };
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const shape = (result as z.ZodObject<any>).shape;
+    expect(shape.count).toBeInstanceOf(z.ZodNumber);
+  });
+
+  it("should handle null type", () => {
+    const jsonSchema = {
+      type: "object",
+      properties: {
+        empty: { type: "null", description: "Always null" },
+      },
+      required: ["empty"],
+    };
+
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+    const shape = (result as z.ZodObject<any>).shape;
+    expect(shape.empty).toBeInstanceOf(z.ZodNull);
+  });
+
+  it("should warn and return z.any() for unsupported schema types", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const jsonSchema = { type: "custom_unsupported" };
+    const result = convertJsonSchemaToZodSchema(jsonSchema, true);
+
+    expect(result).toBeInstanceOf(z.ZodAny);
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Unsupported JSON schema type "custom_unsupported"',
+      ),
+    );
+
+    warnSpy.mockRestore();
+  });
+});
+
+describe("getZodParameters", () => {
+  it("returns an empty object schema without parameters", () => {
+    expect(z.toJSONSchema(getZodParameters(undefined))).toStrictEqual(
+      z.toJSONSchema(z.object({})),
+    );
+  });
+
+  it("converts v1 parameters to a Zod object schema", () => {
+    const parameters: Parameter[] = [
+      { name: "name", type: "string", description: "User name" },
+      { name: "age", type: "number", required: false },
+      { name: "role", type: "string", enum: ["admin", "user"] },
+      {
+        name: "address",
+        type: "object",
+        attributes: [{ name: "city", type: "string" }],
+      },
+      { name: "tags", type: "string[]" },
+    ];
+
+    const schema = getZodParameters(parameters);
+
+    expect(
+      schema.safeParse({
+        name: "Ada",
+        role: "admin",
+        address: { city: "London" },
+        tags: ["a"],
+      }).success,
+    ).toBe(true);
+    expect(
+      schema.safeParse({
+        name: "Ada",
+        role: "owner",
+        address: { city: "London" },
+        tags: [],
+      }).success,
+    ).toBe(false);
+    expect(schema.safeParse({ role: "user" }).success).toBe(false);
+  });
+});

package/src/hooks/use-copilot-action.ts

@@ -7,7 +7,8 @@
 import type { WatchSource } from "vue";
 import type { WebMCPToolConfig } from "@copilotkit/core";
 import type { Parameter, MappedParameterTypes } from "@copilotkit/shared";
-import { getZodParameters, parseJson } from "@copilotkit/shared";
+import { parseJson } from "@copilotkit/shared";
+import { getZodParameters } from "./zod-parameters";
 import { useFrontendTool as useFrontendToolV2 } from "../v2/hooks/use-frontend-tool";
 import { useHumanInTheLoop as useHumanInTheLoopV2 } from "../v2/hooks/use-human-in-the-loop";
 import { useRenderTool as useRenderToolV2 } from "../v2/hooks/use-render-tool";

package/src/hooks/use-frontend-tool.ts

@@ -6,12 +6,9 @@
  */
 import type { WatchSource } from "vue";
 import type { WebMCPToolConfig } from "@copilotkit/core";
-import {
-  type Parameter,
-  type MappedParameterTypes,
-  getZodParameters,
-  parseJson,
-} from "@copilotkit/shared";
+import { parseJson } from "@copilotkit/shared";
+import type { Parameter, MappedParameterTypes } from "@copilotkit/shared";
+import { getZodParameters } from "./zod-parameters";
 import { useFrontendTool as useFrontendToolV2 } from "../v2/hooks/use-frontend-tool";
 import type { VueFrontendTool } from "../v2/types";
 

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);
+}