@copilotkit/shared 1.55.3 → 1.56.0

package/src/a2ui-prompts.ts

@@ -47,29 +47,38 @@ CRITICAL: Do NOT use "/name" (absolute) inside templates — use "name" (relativ
 The container's path ("/items") uses a leading slash (absolute), but all
 components INSIDE the template use paths WITHOUT leading slash.
 
-DATA MODEL:
-The "data" key in the tool args is a plain JSON object that initializes the surface
-data model. Components bound to paths (e.g. "value": { "path": "/form/name" })
-read from and write to this data model. Examples:
-  For forms:  "data": { "form": { "name": "Alice", "email": "" } }
-  For lists:  "data": { "items": [{"name": "Product A"}, {"name": "Product B"}] }
-  For mixed:  "data": { "form": { "query": "" }, "results": [...] }
+COMPONENT VALUES — DEFAULT RULE:
+Use inline literal values for ALL component properties. Pass strings, numbers,
+arrays, and objects directly on the component. Do NOT use { "path": "..." }
+objects unless the property's schema explicitly allows it (see exception below).
+CRITICAL: USING { "path": "..." } ON A PROPERTY THAT DOES NOT DECLARE PATH
+SUPPORT IN ITS SCHEMA WILL CAUSE A RUNTIME CRASH AND BREAK THE ENTIRE UI.
+ALWAYS CHECK THE COMPONENT SCHEMA FIRST — IF THE PROPERTY ONLY ACCEPTS A
+PLAIN TYPE, YOU MUST USE A LITERAL VALUE.
+VERY IMPORTANT: THE APPLICATION WILL BREAK IF YOU DO NOT FOLLOW THIS RULE!
 
-FORMS AND TWO-WAY DATA BINDING:
-To create editable forms, bind input components to data model paths using { "path": "..." }.
-The client automatically writes user input back to the data model at the bound path.
-CRITICAL: Using a literal value (e.g. "value": "") makes the field READ-ONLY.
-You MUST use { "path": "..." } to make inputs editable.
+For example, a chart's "data" must always be an inline array:
+  "data": [{"label": "Jan", "value": 100}, {"label": "Feb", "value": 200}]
+A metric's "value" must always be an inline string:
+  "value": "$1,200"
 
-Input components use "value" as the binding property:
-  "value": { "path": "/form/fieldName" }
+PATH BINDING EXCEPTION — SCHEMA-DRIVEN:
+A few properties accept { "path": "/some/path" } as an alternative to a literal
+value. You can identify these in the Available Components schema: the property
+will list BOTH a literal type AND an object-with-path option. If a property only
+shows a single type (string, number, array, etc.), it does NOT support path
+binding — use a literal value only.
 
-To retrieve form values when a button is clicked, include "context" with path references
-in the button's action. Paths are resolved to their current values at click time:
-  "action": { "event": { "name": "submit", "context": { "userName": { "path": "/form/name" } } } }
+Path binding is typically used for editable form inputs so the client can write
+user input back to the data model. When building forms:
+- Bind input "value" to a data model path: "value": { "path": "/form/name" }
+- Pre-fill via the "data" tool argument: "data": { "form": { "name": "Alice" } }
+- Capture values on submit via button action context:
+    "action": { "event": { "name": "submit", "context": { "name": { "path": "/form/name" } } } }
 
-To pre-fill form values, pass initial data via the "data" tool argument:
-  "data": { "form": { "name": "Markus" } }`;
+REPEATING CONTENT uses a structural children format (not the same as value binding):
+  children: { componentId: "card-id", path: "/items" }
+Components inside templates use RELATIVE paths (no leading slash): { "path": "name" }.`;
 
 /**
  * Design guidelines — visual design rules, component hierarchy tips,
@@ -94,8 +103,8 @@ Design principles:
     "action": { "event": { "name": "myAction", "context": { "key": "value" } } }
   The "event" key holds an OBJECT with "name" (required) and "context" (optional).
   Do NOT use a flat format like {"event": "name"} — "event" must be an object.
-- For forms: every input MUST use path binding on the "value" property
-  (e.g. "value": { "path": "/form/name" }) to be editable. The submit button's
-  action context MUST reference the same paths to capture the user's input.
+- For forms: check the component schema — if an input's "value" property
+  supports path binding, use it for editable fields. The submit button's
+  action context should reference the same paths to capture user input.
 
 Use the SAME surfaceId as the main surface. Match action names to button action event names.`;

package/src/debug.ts

@@ -0,0 +1,55 @@
+/**
+ * Granular debug configuration for CopilotKit runtime and client.
+ * Pass `true` to enable events + lifecycle logging (but NOT verbose payloads),
+ * or an object for granular control including `verbose: true` for full payloads.
+ */
+export type DebugConfig =
+  | boolean
+  | {
+      /** Log every event emitted/received. Default: true */
+      events?: boolean;
+      /** Log request/run lifecycle. Default: true */
+      lifecycle?: boolean;
+      /** Log full event payloads instead of summaries. Default: false — must be explicitly opted in */
+      verbose?: boolean;
+    };
+
+/** Normalized debug configuration — all fields resolved to booleans. */
+export interface ResolvedDebugConfig {
+  enabled: boolean;
+  events: boolean;
+  lifecycle: boolean;
+  verbose: boolean;
+}
+
+/** The all-off config used when debug is falsy. */
+const DEBUG_OFF: ResolvedDebugConfig = {
+  enabled: false,
+  events: false,
+  lifecycle: false,
+  verbose: false,
+};
+
+/**
+ * Normalizes a DebugConfig value into a ResolvedDebugConfig.
+ *
+ * - `false` / `undefined` → all off
+ * - `true` → events + lifecycle on, verbose off (no PII in logs)
+ * - object → merges with defaults (events: true, lifecycle: true, verbose: false)
+ */
+export function resolveDebugConfig(
+  debug: DebugConfig | undefined,
+): ResolvedDebugConfig {
+  if (!debug) return DEBUG_OFF;
+
+  if (debug === true) {
+    return { enabled: true, events: true, lifecycle: true, verbose: false };
+  }
+
+  const events = debug.events ?? true;
+  const lifecycle = debug.lifecycle ?? true;
+  const enabled = events || lifecycle;
+  const verbose = enabled && (debug.verbose ?? false);
+
+  return { enabled, events, lifecycle, verbose };
+}

package/src/index.ts

@@ -2,6 +2,7 @@ export * from "./types";
 export * from "./utils";
 export * from "./constants";
 export * from "./telemetry";
+export * from "./debug";
 export * from "./standard-schema";
 export * from "./attachments";
 

package/src/utils/__tests__/clipboard.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { copyToClipboard } from "../clipboard";
+
+// Mock navigator for Node 20 environments where it doesn't exist
+if (typeof globalThis.navigator === "undefined") {
+  Object.defineProperty(globalThis, "navigator", {
+    value: { clipboard: { writeText: vi.fn() } },
+    writable: true,
+    configurable: true,
+  });
+}
+
+describe("copyToClipboard", () => {
+  let originalClipboard: Clipboard;
+
+  beforeEach(() => {
+    originalClipboard = navigator.clipboard;
+  });
+
+  afterEach(() => {
+    Object.defineProperty(navigator, "clipboard", {
+      value: originalClipboard,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  it("returns true on successful clipboard write", async () => {
+    const writeTextMock = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, "clipboard", {
+      value: { writeText: writeTextMock },
+      writable: true,
+      configurable: true,
+    });
+
+    const result = await copyToClipboard("hello");
+    expect(result).toBe(true);
+    expect(writeTextMock).toHaveBeenCalledWith("hello");
+  });
+
+  it("returns false when clipboard API is unavailable", async () => {
+    Object.defineProperty(navigator, "clipboard", {
+      value: undefined,
+      writable: true,
+      configurable: true,
+    });
+
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const result = await copyToClipboard("hello");
+    expect(result).toBe(false);
+    expect(consoleSpy).toHaveBeenCalledWith("Clipboard API is not available");
+    consoleSpy.mockRestore();
+  });
+
+  it("returns false when writeText is not available", async () => {
+    Object.defineProperty(navigator, "clipboard", {
+      value: {},
+      writable: true,
+      configurable: true,
+    });
+
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const result = await copyToClipboard("hello");
+    expect(result).toBe(false);
+    consoleSpy.mockRestore();
+  });
+
+  it("returns false when writeText rejects", async () => {
+    const writeTextMock = vi
+      .fn()
+      .mockRejectedValue(new Error("Permission denied"));
+    Object.defineProperty(navigator, "clipboard", {
+      value: { writeText: writeTextMock },
+      writable: true,
+      configurable: true,
+    });
+
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const result = await copyToClipboard("hello");
+    expect(result).toBe(false);
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "Failed to copy to clipboard:",
+      expect.any(Error),
+    );
+    consoleSpy.mockRestore();
+  });
+});

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";