fix: add circular $ref cycle detection in JSON schema to Zod conversion

Recursive JSON schemas that reference themselves via $ref would cause
infinite recursion and stack overflow. This adds a visited set that
tracks which $ref paths have been seen during resolution. When a cycle
is detected, it breaks with z.any() and logs a console.warn so users
get feedback. Also adds console.warn for the generic z.any() fallback
on unsupported schema types.

Adds tests for circular refs, non-circular $ref resolution, anyOf with
$ref variants, integer type, null type, and unsupported type warning.

Author: jpr5

packages/shared/src/utils/__tests__/json-schema.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { z } from "zod";
 import {
   convertJsonSchemaToZodSchema,
@@ -191,6 +191,169 @@ describe("convertJsonSchemaToZodSchema", () => {
 
     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 = zodToJsonSchema(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 = zodToJsonSchema(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._def.typeName).toBe("ZodString");
+    const childDef = rootShape.child._def;
+    if (childDef.typeName === "ZodOptional") {
+      expect(childDef.innerType._def.typeName).toBe("ZodAny");
+    } else {
+      expect(childDef.typeName).toBe("ZodAny");
+    }
+
+    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._def.typeName).toBe("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._def.typeName).toBe("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._def.typeName).toBe("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._def.typeName).toBe("ZodAny");
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'Unsupported JSON schema type "custom_unsupported"',
+      ),
+    );
+
+    warnSpy.mockRestore();
+  });
 });
 
 describe("jsonSchemaToActionParameters", () => {

packages/shared/src/utils/json-schema.ts

@@ -242,16 +242,37 @@ 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) {
-      return convertJsonSchemaToZodSchema(resolved, required, definitions);
+      refs.add(refPath);
+      return convertJsonSchemaToZodSchema(
+        resolved,
+        required,
+        definitions,
+        refs,
+      );
     }
   }
 
@@ -262,10 +283,15 @@ export function convertJsonSchemaToZodSchema(
   const unionVariants = jsonSchema.anyOf ?? jsonSchema.oneOf;
   if (Array.isArray(unionVariants) && unionVariants.length > 0) {
     if (unionVariants.length === 1) {
-      return convertJsonSchemaToZodSchema(unionVariants[0], required, defs);
+      return convertJsonSchemaToZodSchema(
+        unionVariants[0],
+        required,
+        defs,
+        visitedRefs,
+      );
     }
     const schemas = unionVariants.map((v: any) =>
-      convertJsonSchemaToZodSchema(v, true, defs),
+      convertJsonSchemaToZodSchema(v, true, defs, visitedRefs),
     );
     let schema = z.union(
       schemas as [z.ZodSchema, z.ZodSchema, ...z.ZodSchema[]],
@@ -288,6 +314,7 @@ export function convertJsonSchemaToZodSchema(
         value,
         jsonSchema.required ? jsonSchema.required.includes(key) : false,
         defs,
+        visitedRefs,
       );
     }
     let schema = z.object(spec).describe(jsonSchema.description);
@@ -308,7 +335,12 @@ export function convertJsonSchemaToZodSchema(
     let schema = z.boolean().describe(jsonSchema.description);
     return required ? schema : schema.optional();
   } else if (jsonSchema.type === "array") {
-    let itemSchema = convertJsonSchemaToZodSchema(jsonSchema.items, true, defs);
+    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") {
@@ -317,6 +349,9 @@ export function convertJsonSchemaToZodSchema(
   }
 
   // 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);