@copilotkit/sdk-js 2.0.0-rc.1 → 2.0.0-rc.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1032,11 +1032,12 @@ describe("auto-A2UI injection", () => {
1032
1032
  // zodState — Standard-Schema JSON-schema augmentation
1033
1033
  // ---------------------------------------------------------------------------
1034
1034
  //
1035
- // Contract: a Zod v4 schema only carries `~standard.validate` + `vendor`, so
1036
- // LangGraph's `isStandardJSONSchema()` returns false and the field is dropped
1037
- // from `output_schema`. `zodState` patches `~standard.jsonSchema.input` onto
1038
- // the schema so the field survives serialization and reaches the frontend
1039
- // via AG-UI `STATE_SNAPSHOT` events.
1035
+ // Contract: a Standard Schema without `~standard.jsonSchema` makes LangGraph's
1036
+ // `isStandardJSONSchema()` return false, and the field is dropped from
1037
+ // `output_schema`. `zodState` patches `~standard.jsonSchema.input` onto such a
1038
+ // schema so the field survives serialization and reaches the frontend via
1039
+ // AG-UI `STATE_SNAPSHOT` events. Zod 4.2+ implements the hook natively, and
1040
+ // `zodState` leaves it alone.
1040
1041
 
1041
1042
  type JsonSchema = {
1042
1043
  type?: string;
@@ -1045,27 +1046,41 @@ type JsonSchema = {
1045
1046
  type StdJson = { jsonSchema?: { input: () => JsonSchema } };
1046
1047
  const standardOf = (s: object): StdJson | undefined =>
1047
1048
  (s as { "~standard"?: StdJson })["~standard"];
1048
- const hasZodV4ToJsonSchema = (): boolean =>
1049
- typeof (z as { toJSONSchema?: unknown }).toJSONSchema === "function";
1050
1049
 
1051
1050
  describe("zodState", () => {
1052
- it("attaches a ~standard.jsonSchema.input hook to a Zod schema", () => {
1051
+ it("keeps the native ~standard.jsonSchema hook of a Zod 4.2+ schema", () => {
1053
1052
  const schema = z.object({ name: z.string() });
1054
- expect(standardOf(schema)?.jsonSchema).toBeUndefined();
1053
+ const native = standardOf(schema)?.jsonSchema;
1054
+ expect(typeof native?.input).toBe("function");
1055
+
1056
+ const wrapped = zodState(schema);
1057
+
1058
+ expect(standardOf(wrapped)?.jsonSchema).toBe(native);
1059
+ expect(standardOf(wrapped)?.jsonSchema?.input()).toMatchObject({
1060
+ type: "object",
1061
+ properties: { name: { type: "string" } },
1062
+ });
1063
+ });
1064
+
1065
+ it("attaches a ~standard.jsonSchema.input hook to a Standard Schema without one", () => {
1066
+ const schema = {
1067
+ "~standard": {
1068
+ version: 1,
1069
+ vendor: "other",
1070
+ validate: (value: unknown) => ({ value }),
1071
+ },
1072
+ };
1055
1073
 
1056
1074
  const wrapped = zodState(schema);
1057
1075
 
1058
1076
  const std = standardOf(wrapped);
1059
- expect(std?.jsonSchema).toBeDefined();
1060
1077
  expect(typeof std?.jsonSchema?.input).toBe("function");
1078
+ // Not a Zod schema, so `z.toJSONSchema` throws and the hook falls back
1079
+ // to an opaque `{}`.
1080
+ expect(std?.jsonSchema?.input()).toEqual({});
1061
1081
  });
1062
1082
 
1063
- it("returns a plain object from input() (real JSON Schema when zod v4 is available, else `{}`)", () => {
1064
- // The contract langgraph cares about is just "input() returns an
1065
- // object" — `isStandardJSONSchema()` doesn't introspect the shape.
1066
- // When zod v4's `toJSONSchema` is present we get the real schema;
1067
- // otherwise we get `{}`, which is still enough for the field to
1068
- // appear in `output_schema` (langgraph-api treats it as opaque).
1083
+ it("returns the real JSON Schema from input() for a Zod schema", () => {
1069
1084
  const schema = z.object({ todos: z.array(z.string()) });
1070
1085
  const wrapped = zodState(schema);
1071
1086
 
@@ -1073,14 +1088,18 @@ describe("zodState", () => {
1073
1088
 
1074
1089
  expect(json).toBeTypeOf("object");
1075
1090
  expect(json).not.toBeNull();
1076
- if (hasZodV4ToJsonSchema()) {
1077
- expect(json?.type).toBe("object");
1078
- expect(json?.properties?.todos).toBeDefined();
1079
- }
1091
+ expect(json?.type).toBe("object");
1092
+ expect(json?.properties?.todos).toBeDefined();
1080
1093
  });
1081
1094
 
1082
1095
  it("caches the JSON Schema across calls (input() returns the same object)", () => {
1083
- const schema = z.object({ x: z.string() });
1096
+ const schema = {
1097
+ "~standard": {
1098
+ version: 1,
1099
+ vendor: "other",
1100
+ validate: (value: unknown) => ({ value }),
1101
+ },
1102
+ };
1084
1103
  const wrapped = zodState(schema);
1085
1104
  const std = standardOf(wrapped);
1086
1105
 
@@ -1123,9 +1142,7 @@ describe("zodState", () => {
1123
1142
  expect(std?.jsonSchema).toBeDefined();
1124
1143
  const json = std?.jsonSchema?.input();
1125
1144
  expect(json).toBeTypeOf("object");
1126
- if (hasZodV4ToJsonSchema()) {
1127
- expect(json?.type).toBe("array");
1128
- }
1145
+ expect(json?.type).toBe("array");
1129
1146
  });
1130
1147
 
1131
1148
  it("makes the wrapped field pass a StandardJSONSchemaV1-style probe", () => {
@@ -0,0 +1,151 @@
1
+ import { z } from "zod";
2
+
3
+ /**
4
+ * Convert a JSON Schema to a Zod schema. Resolves `$ref` against `$defs` /
5
+ * `definitions`, maps `anyOf` / `oneOf` to unions, and falls back to
6
+ * `z.any()` for circular refs and unsupported types.
7
+ *
8
+ * Moved here from `@copilotkit/shared` in 2.0 so that shared does not depend
9
+ * on zod.
10
+ */
11
+ export function convertJsonSchemaToZodSchema(
12
+ jsonSchema: any,
13
+ required: boolean,
14
+ definitions?: Record<string, any>,
15
+ visitedRefs?: Set<string>,
16
+ ): z.ZodSchema {
17
+ // Resolve $ref references
18
+ if (jsonSchema.$ref && definitions) {
19
+ const refPath = jsonSchema.$ref.replace(
20
+ /^#\/\$defs\/|^#\/definitions\//,
21
+ "",
22
+ );
23
+
24
+ // Detect circular $ref cycles
25
+ const refs = visitedRefs ?? new Set<string>();
26
+ if (refs.has(refPath)) {
27
+ console.warn(
28
+ `[CopilotKit] Circular $ref detected for "${refPath}" — falling back to z.any()`,
29
+ );
30
+ let schema = z.any();
31
+ if (jsonSchema.description) {
32
+ schema = schema.describe(jsonSchema.description);
33
+ }
34
+ return required ? schema : schema.optional();
35
+ }
36
+
37
+ const resolved = definitions[refPath];
38
+ if (resolved) {
39
+ // Clone the set so sibling branches don't see each other's visited refs
40
+ const nextRefs = new Set(refs);
41
+ nextRefs.add(refPath);
42
+ return convertJsonSchemaToZodSchema(
43
+ resolved,
44
+ required,
45
+ definitions,
46
+ nextRefs,
47
+ );
48
+ }
49
+ }
50
+
51
+ // Collect top-level definitions for $ref resolution
52
+ const defs = definitions ?? jsonSchema.$defs ?? jsonSchema.definitions;
53
+
54
+ // Handle null-union types like ["string", "null"]
55
+ if (Array.isArray(jsonSchema.type)) {
56
+ const types = jsonSchema.type as string[];
57
+ const hasNull = types.includes("null");
58
+ const nonNullTypes = types.filter((t: string) => t !== "null");
59
+ const resolvedType = nonNullTypes.length > 0 ? nonNullTypes[0] : "string";
60
+ const innerSchema = convertJsonSchemaToZodSchema(
61
+ { ...jsonSchema, type: resolvedType },
62
+ true,
63
+ defs,
64
+ visitedRefs,
65
+ );
66
+ let schema = hasNull ? z.union([innerSchema, z.null()]) : innerSchema;
67
+ if (jsonSchema.description) {
68
+ schema = schema.describe(jsonSchema.description);
69
+ }
70
+ return required ? schema : schema.optional();
71
+ }
72
+
73
+ // Handle anyOf / oneOf as z.union
74
+ const unionVariants = jsonSchema.anyOf ?? jsonSchema.oneOf;
75
+ if (Array.isArray(unionVariants) && unionVariants.length > 0) {
76
+ if (unionVariants.length === 1) {
77
+ return convertJsonSchemaToZodSchema(
78
+ unionVariants[0],
79
+ required,
80
+ defs,
81
+ visitedRefs,
82
+ );
83
+ }
84
+ const schemas = unionVariants.map((v: any) =>
85
+ convertJsonSchemaToZodSchema(v, true, defs, visitedRefs),
86
+ );
87
+ let schema = z.union(
88
+ schemas as [z.ZodSchema, z.ZodSchema, ...z.ZodSchema[]],
89
+ );
90
+ if (jsonSchema.description) {
91
+ schema = schema.describe(jsonSchema.description);
92
+ }
93
+ return required ? schema : schema.optional();
94
+ }
95
+
96
+ if (jsonSchema.type === "object") {
97
+ const spec: { [key: string]: z.ZodSchema } = {};
98
+
99
+ if (!jsonSchema.properties || !Object.keys(jsonSchema.properties).length) {
100
+ return !required ? z.object(spec).optional() : z.object(spec);
101
+ }
102
+
103
+ for (const [key, value] of Object.entries(jsonSchema.properties)) {
104
+ spec[key] = convertJsonSchemaToZodSchema(
105
+ value,
106
+ jsonSchema.required ? jsonSchema.required.includes(key) : false,
107
+ defs,
108
+ visitedRefs,
109
+ );
110
+ }
111
+ let schema = z.object(spec).describe(jsonSchema.description);
112
+ return required ? schema : schema.optional();
113
+ } else if (jsonSchema.type === "string") {
114
+ if (jsonSchema.enum && jsonSchema.enum.length > 0) {
115
+ let schema = z
116
+ .enum(jsonSchema.enum as [string, ...string[]])
117
+ .describe(jsonSchema.description);
118
+ return required ? schema : schema.optional();
119
+ }
120
+ let schema = z.string().describe(jsonSchema.description);
121
+ return required ? schema : schema.optional();
122
+ } else if (jsonSchema.type === "number" || jsonSchema.type === "integer") {
123
+ let schema = z.number().describe(jsonSchema.description);
124
+ return required ? schema : schema.optional();
125
+ } else if (jsonSchema.type === "boolean") {
126
+ let schema = z.boolean().describe(jsonSchema.description);
127
+ return required ? schema : schema.optional();
128
+ } else if (jsonSchema.type === "array") {
129
+ let itemSchema = convertJsonSchemaToZodSchema(
130
+ jsonSchema.items,
131
+ true,
132
+ defs,
133
+ visitedRefs,
134
+ );
135
+ let schema = z.array(itemSchema).describe(jsonSchema.description);
136
+ return required ? schema : schema.optional();
137
+ } else if (jsonSchema.type === "null") {
138
+ let schema = z.null().describe(jsonSchema.description);
139
+ return required ? schema : schema.optional();
140
+ }
141
+
142
+ // Fallback: accept any value rather than throwing
143
+ console.warn(
144
+ `[CopilotKit] Unsupported JSON schema type "${jsonSchema.type ?? "unknown"}" — falling back to z.any()`,
145
+ );
146
+ let schema = z.any();
147
+ if (jsonSchema.description) {
148
+ schema = schema.describe(jsonSchema.description);
149
+ }
150
+ return required ? schema : schema.optional();
151
+ }
@@ -134,11 +134,13 @@ type WithJsonSchema<T> = T extends { "~standard": infer S }
134
134
  * `getJsonSchemaFromSchema` (called from `StateSchema.getJsonSchema`)
135
135
  * can serialize the field.
136
136
  *
137
- * Without this, Zod v4 fields carry `~standard.validate` + `vendor` only,
138
- * and `isStandardJSONSchema()` returns false, so the field is silently
139
- * dropped from the graph's `output_schema`. That makes AG-UI
140
- * `STATE_SNAPSHOT` events filter the field out of the payload sent to
141
- * the frontend even though the underlying thread state has the value.
137
+ * Zod 4.2+ schemas already implement `~standard.jsonSchema` and are
138
+ * returned unchanged. A Standard Schema without that hook carries
139
+ * `~standard.validate` + `vendor` only, so `isStandardJSONSchema()` returns
140
+ * false and the field is silently dropped from the graph's `output_schema`.
141
+ * That makes AG-UI `STATE_SNAPSHOT` events filter the field out of the
142
+ * payload sent to the frontend even though the underlying thread state has
143
+ * the value.
142
144
  *
143
145
  * Use this on any custom state field you want visible to the frontend
144
146
  * via `useAgent().state.*`.
@@ -430,11 +432,11 @@ const copilotKitStateSchema = z
430
432
  interceptedToolCalls: z.array(z.any()).optional(),
431
433
  originalAIMessageId: z.string().optional(),
432
434
  })
433
- .passthrough()
435
+ .loose()
434
436
  .optional(),
435
437
  ),
436
438
  })
437
- .passthrough();
439
+ .loose();
438
440
 
439
441
  const isToolCallContentBlock = (block: unknown) =>
440
442
  typeof block === "object" &&
@@ -1,7 +1,6 @@
1
1
  import type { RunnableConfig } from "@langchain/core/runnables";
2
2
  import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
3
3
  import {
4
- convertJsonSchemaToZodSchema,
5
4
  randomId,
6
5
  randomUUID,
7
6
  CopilotKitMisuseError,
@@ -10,6 +9,7 @@ import { interrupt } from "@langchain/langgraph";
10
9
  import { DynamicStructuredTool } from "@langchain/core/tools";
11
10
  import { AIMessage } from "@langchain/core/messages";
12
11
  import type { OptionsConfig } from "./types";
12
+ import { convertJsonSchemaToZodSchema } from "./json-schema-to-zod";
13
13
 
14
14
  /**
15
15
  * Customize the LangGraph configuration for use in CopilotKit.