@copilotkit/shared 1.55.3 → 1.56.1

package/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,255 @@ 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 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._def.typeName).toBe("ZodObject");
+    expect(shape.shipping._def.typeName).toBe("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._def.typeName).toBe("ZodObject");
+    expect(wrapperShape.second._def.typeName).toBe("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._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", () => {

package/src/utils/clipboard.ts

@@ -0,0 +1,23 @@
+/**
+ * Safely copies text to the clipboard.
+ *
+ * Checks that the Clipboard API is available before attempting the write,
+ * and catches any errors (e.g. permission denied, insecure context).
+ *
+ * @param text - The text to copy to the clipboard.
+ * @returns `true` if the text was successfully copied, `false` otherwise.
+ */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  if (!navigator.clipboard?.writeText) {
+    console.error("Clipboard API is not available");
+    return false;
+  }
+
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch (err) {
+    console.error("Failed to copy to clipboard:", err);
+    return false;
+  }
+}

package/src/utils/index.ts

@@ -1,3 +1,4 @@
+export * from "./clipboard";
 export * from "./conditions";
 export * from "./console-styling";
 export * from "./errors";

package/src/utils/json-schema.ts

@@ -241,7 +241,69 @@ function convertAttribute(attribute: Parameter): JSONSchema {
 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 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 } = {};
 
@@ -253,6 +315,8 @@ export function convertJsonSchemaToZodSchema(
       spec[key] = convertJsonSchemaToZodSchema(
         value,
         jsonSchema.required ? jsonSchema.required.includes(key) : false,
+        defs,
+        visitedRefs,
       );
     }
     let schema = z.object(spec).describe(jsonSchema.description);
@@ -266,18 +330,35 @@ export function convertJsonSchemaToZodSchema(
     }
     let schema = z.string().describe(jsonSchema.description);
     return required ? schema : schema.optional();
-  } else if (jsonSchema.type === "number") {
+  } 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);
+    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);
   }
-  throw new Error("Invalid JSON schema");
+  return required ? schema : schema.optional();
 }
 
 export function getZodParameters<T extends [] | Parameter[] | undefined>(

package/src/utils/types.ts

@@ -1,3 +1,5 @@
+import type { AgentCapabilities } from "@ag-ui/core";
+
 export type MaybePromise<T> = T | PromiseLike<T>;
 
 /**
@@ -17,6 +19,7 @@ export interface AgentDescription {
   name: string;
   className: string;
   description: string;
+  capabilities?: AgentCapabilities;
 }
 
 export type RuntimeMode = "sse" | "intelligence";