@copilotkit/shared 1.55.3 → 1.56.1

package/dist/utils/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","names":[],"sources":["../../src/utils/types.ts"],"sourcesContent":["export type MaybePromise<T> = T | PromiseLike<T>;\n\n/**\n * More specific utility for records with at least one key\n */\nexport type NonEmptyRecord<T> =\n  T extends Record<string, unknown>\n    ? keyof T extends never\n      ? never\n      : T\n    : never;\n\n/**\n * Type representing an agent's basic information\n */\nexport interface AgentDescription {\n  name: string;\n  className: string;\n  description: string;\n}\n\nexport type RuntimeMode = \"sse\" | \"intelligence\";\n\nexport const RUNTIME_MODE_SSE = \"sse\" as const;\nexport const RUNTIME_MODE_INTELLIGENCE = \"intelligence\" as const;\n\nexport interface IntelligenceRuntimeInfo {\n  wsUrl: string;\n}\n\nexport type RuntimeLicenseStatus =\n  | \"valid\"\n  | \"none\"\n  | \"expired\"\n  | \"expiring\"\n  | \"invalid\"\n  | \"unknown\";\n\nexport interface RuntimeInfo {\n  version: string;\n  agents: Record<string, AgentDescription>;\n  audioFileTranscriptionEnabled: boolean;\n  mode: RuntimeMode;\n  intelligence?: IntelligenceRuntimeInfo;\n  a2uiEnabled?: boolean;\n  openGenerativeUIEnabled?: boolean;\n  licenseStatus?: RuntimeLicenseStatus;\n}\n"],"mappings":";AAuBA,MAAa,mBAAmB;AAChC,MAAa,4BAA4B"}
+{"version":3,"file":"types.mjs","names":[],"sources":["../../src/utils/types.ts"],"sourcesContent":["import type { AgentCapabilities } from \"@ag-ui/core\";\n\nexport type MaybePromise<T> = T | PromiseLike<T>;\n\n/**\n * More specific utility for records with at least one key\n */\nexport type NonEmptyRecord<T> =\n  T extends Record<string, unknown>\n    ? keyof T extends never\n      ? never\n      : T\n    : never;\n\n/**\n * Type representing an agent's basic information\n */\nexport interface AgentDescription {\n  name: string;\n  className: string;\n  description: string;\n  capabilities?: AgentCapabilities;\n}\n\nexport type RuntimeMode = \"sse\" | \"intelligence\";\n\nexport const RUNTIME_MODE_SSE = \"sse\" as const;\nexport const RUNTIME_MODE_INTELLIGENCE = \"intelligence\" as const;\n\nexport interface IntelligenceRuntimeInfo {\n  wsUrl: string;\n}\n\nexport type RuntimeLicenseStatus =\n  | \"valid\"\n  | \"none\"\n  | \"expired\"\n  | \"expiring\"\n  | \"invalid\"\n  | \"unknown\";\n\nexport interface RuntimeInfo {\n  version: string;\n  agents: Record<string, AgentDescription>;\n  audioFileTranscriptionEnabled: boolean;\n  mode: RuntimeMode;\n  intelligence?: IntelligenceRuntimeInfo;\n  a2uiEnabled?: boolean;\n  openGenerativeUIEnabled?: boolean;\n  licenseStatus?: RuntimeLicenseStatus;\n}\n"],"mappings":";AA0BA,MAAa,mBAAmB;AAChC,MAAa,4BAA4B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/shared",
-  "version": "1.55.3",
+  "version": "1.56.1",
   "private": false,
   "keywords": [
     "ai",

package/src/__tests__/debug.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest";
+import { resolveDebugConfig } from "../debug";
+
+describe("resolveDebugConfig", () => {
+  it("returns all-off for undefined", () => {
+    expect(resolveDebugConfig(undefined)).toEqual({
+      enabled: false,
+      events: false,
+      lifecycle: false,
+      verbose: false,
+    });
+  });
+
+  it("returns all-off for false", () => {
+    expect(resolveDebugConfig(false)).toEqual({
+      enabled: false,
+      events: false,
+      lifecycle: false,
+      verbose: false,
+    });
+  });
+
+  it("returns events + lifecycle on but verbose off for true (PII safety)", () => {
+    expect(resolveDebugConfig(true)).toEqual({
+      enabled: true,
+      events: true,
+      lifecycle: true,
+      verbose: false,
+    });
+  });
+
+  it("allows explicit verbose opt-in via object shorthand", () => {
+    expect(resolveDebugConfig({ verbose: true })).toEqual({
+      enabled: true,
+      events: true,
+      lifecycle: true,
+      verbose: true,
+    });
+  });
+
+  it("allows explicit verbose opt-in with events", () => {
+    expect(resolveDebugConfig({ events: true, verbose: true })).toEqual({
+      enabled: true,
+      events: true,
+      lifecycle: true,
+      verbose: true,
+    });
+  });
+
+  it("defaults events and lifecycle to true, verbose to false for empty object", () => {
+    expect(resolveDebugConfig({})).toEqual({
+      enabled: true,
+      events: true,
+      lifecycle: true,
+      verbose: false,
+    });
+  });
+
+  it("respects explicit events: true", () => {
+    expect(resolveDebugConfig({ events: true })).toEqual({
+      enabled: true,
+      events: true,
+      lifecycle: true,
+      verbose: false,
+    });
+  });
+
+  it("respects explicit events: false (lifecycle still defaults true)", () => {
+    expect(resolveDebugConfig({ events: false })).toEqual({
+      enabled: true,
+      events: false,
+      lifecycle: true,
+      verbose: false,
+    });
+  });
+
+  it("respects explicit lifecycle: false (events still defaults true)", () => {
+    expect(resolveDebugConfig({ lifecycle: false })).toEqual({
+      enabled: true,
+      events: true,
+      lifecycle: false,
+      verbose: false,
+    });
+  });
+
+  it("sets enabled to false when both events and lifecycle are false", () => {
+    expect(resolveDebugConfig({ events: false, lifecycle: false })).toEqual({
+      enabled: false,
+      events: false,
+      lifecycle: false,
+      verbose: false,
+    });
+  });
+
+  it("clamps verbose to false when enabled is false (events and lifecycle both false)", () => {
+    expect(
+      resolveDebugConfig({ events: false, lifecycle: false, verbose: true }),
+    ).toEqual({
+      enabled: false,
+      events: false,
+      lifecycle: false,
+      verbose: false,
+    });
+  });
+
+  it("handles mixed config: events true, lifecycle false, verbose true", () => {
+    expect(
+      resolveDebugConfig({ events: true, lifecycle: false, verbose: true }),
+    ).toEqual({
+      enabled: true,
+      events: true,
+      lifecycle: false,
+      verbose: true,
+    });
+  });
+});

package/src/__tests__/standard-schema.test.ts

@@ -210,6 +210,98 @@ describe("schemaToJsonSchema", () => {
     });
   });
 
+  describe("Zod v4 schemas (via toJSONSchema method)", () => {
+    it("calls toJSONSchema() when the method exists on the schema", () => {
+      const expectedOutput = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+
+      const mockZod4Schema: StandardSchemaV1 = {
+        "~standard": {
+          version: 1,
+          vendor: "zod",
+          validate: (value: unknown) => ({ value }),
+        },
+        toJSONSchema: () => expectedOutput,
+      } as any;
+
+      const result = schemaToJsonSchema(mockZod4Schema);
+      expect(result).toEqual(expectedOutput);
+    });
+
+    it("uses toJSONSchema() even without zodToJsonSchema option", () => {
+      const mockZod4Schema: StandardSchemaV1 = {
+        "~standard": {
+          version: 1,
+          vendor: "zod",
+          validate: (value: unknown) => ({ value }),
+        },
+        toJSONSchema: () => ({
+          type: "object",
+          properties: { city: { type: "string" } },
+        }),
+      } as any;
+
+      // No options passed — toJSONSchema() should still work
+      const result = schemaToJsonSchema(mockZod4Schema);
+      expect(result).toHaveProperty("properties.city.type", "string");
+    });
+
+    it("prefers toJSONSchema() over zodToJsonSchema fallback for Zod v4", () => {
+      const mockZod4Schema: StandardSchemaV1 = {
+        "~standard": {
+          version: 1,
+          vendor: "zod",
+          validate: (value: unknown) => ({ value }),
+        },
+        toJSONSchema: () => ({
+          type: "object",
+          properties: { fromNative: { type: "boolean" } },
+        }),
+      } as any;
+
+      const zodFallback = () => ({
+        type: "object",
+        properties: { fromFallback: { type: "boolean" } },
+      });
+
+      const result = schemaToJsonSchema(mockZod4Schema, {
+        zodToJsonSchema: zodFallback,
+      });
+
+      expect(result).toHaveProperty("properties.fromNative");
+      expect(result).not.toHaveProperty("properties.fromFallback");
+    });
+
+    it("prefers ~standard.jsonSchema over toJSONSchema()", () => {
+      const mockSchema = {
+        "~standard": {
+          version: 1,
+          vendor: "zod",
+          validate: (value: unknown) => ({ value }),
+          jsonSchema: {
+            input: () => ({
+              type: "object",
+              properties: { fromStandard: { type: "boolean" } },
+            }),
+          },
+        },
+        toJSONSchema: () => ({
+          type: "object",
+          properties: { fromToJSONSchema: { type: "boolean" } },
+        }),
+      };
+
+      const result = schemaToJsonSchema(mockSchema);
+
+      // Standard JSON Schema V1 should take priority
+      expect(result).toHaveProperty("properties.fromStandard");
+      expect(result).not.toHaveProperty("properties.fromToJSONSchema");
+    });
+  });
+
   describe("Error handling", () => {
     it("throws when schema has no jsonSchema support and no zodToJsonSchema", () => {
       const mockSchema: StandardSchemaV1 = {

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/standard-schema.ts

@@ -48,9 +48,10 @@ function hasStandardJsonSchema(
  * Strategy:
  * 1. If the schema implements Standard JSON Schema V1 (`~standard.jsonSchema`),
  *    call `schema['~standard'].jsonSchema.input({ target: 'draft-07' })`.
- * 2. If the schema is a Zod v3 schema (`~standard.vendor === 'zod'`), use the
+ * 2. If the schema exposes a `toJSONSchema()` method (Zod v4), call it directly.
+ * 3. If the schema is a Zod v3 schema (`~standard.vendor === 'zod'`), use the
  *    injected `zodToJsonSchema()` function.
- * 3. Otherwise throw a descriptive error.
+ * 4. Otherwise throw a descriptive error.
  */
 export function schemaToJsonSchema(
   schema: StandardSchemaV1,
@@ -61,7 +62,12 @@ export function schemaToJsonSchema(
     return schema["~standard"].jsonSchema.input({ target: "draft-07" });
   }
 
-  // 2. Zod v3 fallback
+  // 2. Zod v4 native — exposes toJSONSchema() on the schema itself
+  if (typeof (schema as any).toJSONSchema === "function") {
+    return (schema as any).toJSONSchema() as Record<string, unknown>;
+  }
+
+  // 3. Zod v3 fallback
   const vendor = schema["~standard"].vendor;
   if (vendor === "zod" && options?.zodToJsonSchema) {
     return options.zodToJsonSchema(schema, { $refStrategy: "none" });

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