@copilotkit/shared 2.0.0-rc.1 → 2.0.0-rc.10

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.
Files changed (220) hide show
  1. package/README.md +3 -14
  2. package/dist/a2ui-prompts.cjs +21 -62
  3. package/dist/a2ui-prompts.cjs.map +1 -1
  4. package/dist/a2ui-prompts.d.cts +8 -1
  5. package/dist/a2ui-prompts.d.cts.map +1 -1
  6. package/dist/a2ui-prompts.d.mts +8 -1
  7. package/dist/a2ui-prompts.d.mts.map +1 -1
  8. package/dist/a2ui-prompts.mjs +22 -62
  9. package/dist/a2ui-prompts.mjs.map +1 -1
  10. package/dist/generative-ui/basic-functions.cjs +1 -1
  11. package/dist/generative-ui/basic-functions.cjs.map +1 -1
  12. package/dist/generative-ui/basic-functions.mjs +1 -1
  13. package/dist/generative-ui/basic-functions.mjs.map +1 -1
  14. package/dist/generative-ui/compact-schema.cjs +187 -0
  15. package/dist/generative-ui/compact-schema.cjs.map +1 -0
  16. package/dist/generative-ui/compact-schema.d.cts +55 -0
  17. package/dist/generative-ui/compact-schema.d.cts.map +1 -0
  18. package/dist/generative-ui/compact-schema.d.mts +55 -0
  19. package/dist/generative-ui/compact-schema.d.mts.map +1 -0
  20. package/dist/generative-ui/compact-schema.mjs +185 -0
  21. package/dist/generative-ui/compact-schema.mjs.map +1 -0
  22. package/dist/generative-ui/prompt-spec.cjs +225 -0
  23. package/dist/generative-ui/prompt-spec.cjs.map +1 -0
  24. package/dist/generative-ui/prompt-spec.d.cts +94 -0
  25. package/dist/generative-ui/prompt-spec.d.cts.map +1 -0
  26. package/dist/generative-ui/prompt-spec.d.mts +94 -0
  27. package/dist/generative-ui/prompt-spec.d.mts.map +1 -0
  28. package/dist/generative-ui/prompt-spec.mjs +220 -0
  29. package/dist/generative-ui/prompt-spec.mjs.map +1 -0
  30. package/dist/generative-ui/prompt.cjs +10 -36
  31. package/dist/generative-ui/prompt.cjs.map +1 -1
  32. package/dist/generative-ui/prompt.d.cts +2 -1
  33. package/dist/generative-ui/prompt.d.cts.map +1 -1
  34. package/dist/generative-ui/prompt.d.mts +2 -1
  35. package/dist/generative-ui/prompt.d.mts.map +1 -1
  36. package/dist/generative-ui/prompt.mjs +12 -38
  37. package/dist/generative-ui/prompt.mjs.map +1 -1
  38. package/dist/generative-ui/schema-render.cjs +242 -0
  39. package/dist/generative-ui/schema-render.cjs.map +1 -0
  40. package/dist/generative-ui/schema-render.d.cts +44 -0
  41. package/dist/generative-ui/schema-render.d.cts.map +1 -0
  42. package/dist/generative-ui/schema-render.d.mts +44 -0
  43. package/dist/generative-ui/schema-render.d.mts.map +1 -0
  44. package/dist/generative-ui/schema-render.mjs +239 -0
  45. package/dist/generative-ui/schema-render.mjs.map +1 -0
  46. package/dist/index.cjs +17 -15
  47. package/dist/index.cjs.map +1 -1
  48. package/dist/index.d.cts +10 -9
  49. package/dist/index.d.cts.map +1 -1
  50. package/dist/index.d.mts +10 -9
  51. package/dist/index.d.mts.map +1 -1
  52. package/dist/index.mjs +9 -7
  53. package/dist/index.mjs.map +1 -1
  54. package/dist/index.umd.js +808 -438
  55. package/dist/index.umd.js.map +1 -1
  56. package/dist/package.cjs +1 -1
  57. package/dist/package.mjs +1 -1
  58. package/dist/standard-schema.cjs +20 -7
  59. package/dist/standard-schema.cjs.map +1 -1
  60. package/dist/standard-schema.d.cts +15 -16
  61. package/dist/standard-schema.d.cts.map +1 -1
  62. package/dist/standard-schema.d.mts +15 -16
  63. package/dist/standard-schema.d.mts.map +1 -1
  64. package/dist/standard-schema.mjs +20 -8
  65. package/dist/standard-schema.mjs.map +1 -1
  66. package/dist/telemetry/lambda-client.cjs.map +1 -1
  67. package/dist/telemetry/lambda-client.d.cts.map +1 -1
  68. package/dist/telemetry/lambda-client.d.mts.map +1 -1
  69. package/dist/telemetry/lambda-client.mjs.map +1 -1
  70. package/dist/telemetry/telemetry-disabled.cjs +3 -6
  71. package/dist/telemetry/telemetry-disabled.cjs.map +1 -1
  72. package/dist/telemetry/telemetry-disabled.d.cts +0 -5
  73. package/dist/telemetry/telemetry-disabled.d.cts.map +1 -1
  74. package/dist/telemetry/telemetry-disabled.d.mts +0 -5
  75. package/dist/telemetry/telemetry-disabled.d.mts.map +1 -1
  76. package/dist/telemetry/telemetry-disabled.mjs +4 -6
  77. package/dist/telemetry/telemetry-disabled.mjs.map +1 -1
  78. package/dist/types/message.d.cts +1 -18
  79. package/dist/types/message.d.cts.map +1 -1
  80. package/dist/types/message.d.mts +1 -18
  81. package/dist/types/message.d.mts.map +1 -1
  82. package/dist/utils/errors.cjs +4 -42
  83. package/dist/utils/errors.cjs.map +1 -1
  84. package/dist/utils/errors.d.cts +16 -34
  85. package/dist/utils/errors.d.cts.map +1 -1
  86. package/dist/utils/errors.d.mts +16 -34
  87. package/dist/utils/errors.d.mts.map +1 -1
  88. package/dist/utils/errors.mjs +5 -41
  89. package/dist/utils/errors.mjs.map +1 -1
  90. package/dist/utils/index.cjs +1 -2
  91. package/dist/utils/index.cjs.map +1 -1
  92. package/dist/utils/index.d.cts +4 -5
  93. package/dist/utils/index.d.cts.map +1 -1
  94. package/dist/utils/index.d.mts +4 -5
  95. package/dist/utils/index.d.mts.map +1 -1
  96. package/dist/utils/index.mjs +4 -5
  97. package/dist/utils/index.mjs.map +1 -1
  98. package/dist/utils/json-schema.cjs +0 -79
  99. package/dist/utils/json-schema.cjs.map +1 -1
  100. package/dist/utils/json-schema.d.cts +1 -4
  101. package/dist/utils/json-schema.d.cts.map +1 -1
  102. package/dist/utils/json-schema.d.mts +1 -4
  103. package/dist/utils/json-schema.d.mts.map +1 -1
  104. package/dist/utils/json-schema.mjs +1 -78
  105. package/dist/utils/json-schema.mjs.map +1 -1
  106. package/dist/utils/process-env.cjs +14 -0
  107. package/dist/utils/process-env.cjs.map +1 -0
  108. package/dist/utils/process-env.d.cts +10 -0
  109. package/dist/utils/process-env.d.cts.map +1 -0
  110. package/dist/utils/process-env.d.mts +10 -0
  111. package/dist/utils/process-env.d.mts.map +1 -0
  112. package/dist/utils/process-env.mjs +13 -0
  113. package/dist/utils/process-env.mjs.map +1 -0
  114. package/dist/utils/random-id.cjs +13 -26
  115. package/dist/utils/random-id.cjs.map +1 -1
  116. package/dist/utils/random-id.d.cts +6 -3
  117. package/dist/utils/random-id.d.cts.map +1 -1
  118. package/dist/utils/random-id.d.mts +6 -3
  119. package/dist/utils/random-id.d.mts.map +1 -1
  120. package/dist/utils/random-id.mjs +14 -25
  121. package/dist/utils/random-id.mjs.map +1 -1
  122. package/package.json +7 -31
  123. package/src/__tests__/a2ui-prompts.test.ts +42 -9
  124. package/src/__tests__/fixtures/prompt-goldens.json +354 -0
  125. package/src/__tests__/prompt-spec.test.ts +191 -0
  126. package/src/__tests__/root-entry-browser-safety.test.ts +5 -7
  127. package/src/__tests__/schema-render.test.ts +245 -0
  128. package/src/__tests__/standard-schema.test.ts +61 -101
  129. package/src/a2ui-prompts.ts +47 -96
  130. package/src/generative-ui/basic-functions.ts +1 -1
  131. package/src/generative-ui/compact-schema.ts +277 -0
  132. package/src/generative-ui/index.ts +3 -0
  133. package/src/generative-ui/prompt-spec.ts +335 -0
  134. package/src/generative-ui/prompt.ts +25 -75
  135. package/src/generative-ui/schema-render.ts +374 -0
  136. package/src/index.ts +3 -16
  137. package/src/standard-schema.ts +24 -27
  138. package/src/telemetry/lambda-client.ts +3 -2
  139. package/src/telemetry/telemetry-disabled.ts +7 -12
  140. package/src/types/message.ts +1 -19
  141. package/src/utils/__tests__/errors.test.ts +44 -0
  142. package/src/utils/__tests__/json-schema.test.ts +3 -479
  143. package/src/utils/__tests__/process-env.test.ts +22 -0
  144. package/src/utils/__tests__/random-id.test.ts +37 -0
  145. package/src/utils/errors.ts +27 -85
  146. package/src/utils/index.ts +1 -2
  147. package/src/utils/json-schema.ts +1 -152
  148. package/src/utils/process-env.ts +14 -0
  149. package/src/utils/random-id.ts +17 -37
  150. package/tsdown.config.ts +2 -19
  151. package/dist/event-transforms/index.cjs +0 -15
  152. package/dist/event-transforms/index.d.cts +0 -4
  153. package/dist/event-transforms/index.d.mts +0 -4
  154. package/dist/event-transforms/index.mjs +0 -5
  155. package/dist/event-transforms/open-generative-ui-middleware.cjs +0 -286
  156. package/dist/event-transforms/open-generative-ui-middleware.cjs.map +0 -1
  157. package/dist/event-transforms/open-generative-ui-middleware.d.cts +0 -60
  158. package/dist/event-transforms/open-generative-ui-middleware.d.cts.map +0 -1
  159. package/dist/event-transforms/open-generative-ui-middleware.d.mts +0 -60
  160. package/dist/event-transforms/open-generative-ui-middleware.d.mts.map +0 -1
  161. package/dist/event-transforms/open-generative-ui-middleware.mjs +0 -283
  162. package/dist/event-transforms/open-generative-ui-middleware.mjs.map +0 -1
  163. package/dist/event-transforms/recorded-events.cjs +0 -59
  164. package/dist/event-transforms/recorded-events.cjs.map +0 -1
  165. package/dist/event-transforms/recorded-events.d.cts +0 -23
  166. package/dist/event-transforms/recorded-events.d.cts.map +0 -1
  167. package/dist/event-transforms/recorded-events.d.mts +0 -23
  168. package/dist/event-transforms/recorded-events.d.mts.map +0 -1
  169. package/dist/event-transforms/recorded-events.mjs +0 -58
  170. package/dist/event-transforms/recorded-events.mjs.map +0 -1
  171. package/dist/telemetry/events.d.cts +0 -72
  172. package/dist/telemetry/events.d.cts.map +0 -1
  173. package/dist/telemetry/events.d.mts +0 -72
  174. package/dist/telemetry/events.d.mts.map +0 -1
  175. package/dist/telemetry/index.cjs +0 -18
  176. package/dist/telemetry/index.d.cts +0 -5
  177. package/dist/telemetry/index.d.mts +0 -5
  178. package/dist/telemetry/index.mjs +0 -6
  179. package/dist/telemetry/telemetry-client.cjs +0 -165
  180. package/dist/telemetry/telemetry-client.cjs.map +0 -1
  181. package/dist/telemetry/telemetry-client.d.cts +0 -87
  182. package/dist/telemetry/telemetry-client.d.cts.map +0 -1
  183. package/dist/telemetry/telemetry-client.d.mts +0 -87
  184. package/dist/telemetry/telemetry-client.d.mts.map +0 -1
  185. package/dist/telemetry/telemetry-client.mjs +0 -164
  186. package/dist/telemetry/telemetry-client.mjs.map +0 -1
  187. package/dist/telemetry/utils.cjs +0 -14
  188. package/dist/telemetry/utils.cjs.map +0 -1
  189. package/dist/telemetry/utils.mjs +0 -13
  190. package/dist/telemetry/utils.mjs.map +0 -1
  191. package/dist/utils/conditions.cjs +0 -32
  192. package/dist/utils/conditions.cjs.map +0 -1
  193. package/dist/utils/conditions.d.cts +0 -31
  194. package/dist/utils/conditions.d.cts.map +0 -1
  195. package/dist/utils/conditions.d.mts +0 -31
  196. package/dist/utils/conditions.d.mts.map +0 -1
  197. package/dist/utils/conditions.mjs +0 -31
  198. package/dist/utils/conditions.mjs.map +0 -1
  199. package/dist/utils/console-styling.cjs +0 -91
  200. package/dist/utils/console-styling.cjs.map +0 -1
  201. package/dist/utils/console-styling.d.cts +0 -65
  202. package/dist/utils/console-styling.d.cts.map +0 -1
  203. package/dist/utils/console-styling.d.mts +0 -65
  204. package/dist/utils/console-styling.d.mts.map +0 -1
  205. package/dist/utils/console-styling.mjs +0 -85
  206. package/dist/utils/console-styling.mjs.map +0 -1
  207. package/src/__tests__/zod-regression.test.ts +0 -319
  208. package/src/event-transforms/index.ts +0 -5
  209. package/src/event-transforms/open-generative-ui-middleware.ts +0 -392
  210. package/src/event-transforms/recorded-events.test.ts +0 -166
  211. package/src/event-transforms/recorded-events.ts +0 -74
  212. package/src/telemetry/events.ts +0 -68
  213. package/src/telemetry/index.ts +0 -9
  214. package/src/telemetry/telemetry-blank-license-identity.test.ts +0 -128
  215. package/src/telemetry/telemetry-client.test.ts +0 -798
  216. package/src/telemetry/telemetry-client.ts +0 -328
  217. package/src/telemetry/utils.ts +0 -15
  218. package/src/utils/__tests__/conditions.test.ts +0 -161
  219. package/src/utils/conditions.ts +0 -116
  220. package/src/utils/console-styling.ts +0 -126
@@ -0,0 +1,374 @@
1
+ import { functionCallers } from "./basic-functions";
2
+ import {
3
+ buildCompactGenerativeUISchema,
4
+ compactProps,
5
+ compactType,
6
+ } from "./compact-schema";
7
+ import type { GenerativeUISchemaSettings } from "./prompt-spec";
8
+ import { GENERATIVE_UI_AGENT_FUNCTION_CALLS } from "./types";
9
+ import type {
10
+ GenerativeUIComponentManifest,
11
+ GenerativeUIJSONSchema,
12
+ GenerativeUIManifest,
13
+ } from "./types";
14
+
15
+ type SchemaManifest = Pick<
16
+ GenerativeUIManifest,
17
+ "catalogId" | "components" | "functions" | "targets" | "surfaces"
18
+ >;
19
+
20
+ /** An own key (shared compiles to ES2017, which has no Object.hasOwn). */
21
+ const hasOwn = (target: object, key: string) =>
22
+ Object.prototype.hasOwnProperty.call(target, key);
23
+
24
+ function isRecord(value: unknown): value is Record<string, unknown> {
25
+ return typeof value === "object" && value !== null && !Array.isArray(value);
26
+ }
27
+
28
+ /** The props schema without the description of each prop. */
29
+ function withoutPropDescriptions(
30
+ schema: GenerativeUIJSONSchema,
31
+ ): GenerativeUIJSONSchema {
32
+ if (!isRecord(schema.properties)) return schema;
33
+ return {
34
+ ...schema,
35
+ properties: Object.fromEntries(
36
+ Object.entries(schema.properties).map(([key, value]) => {
37
+ if (!isRecord(value)) return [key, value];
38
+ const { description: _description, ...rest } = value;
39
+ return [key, rest];
40
+ }),
41
+ ),
42
+ };
43
+ }
44
+
45
+ /** The short signature of a function: its built-in signature, or its schema made short. */
46
+ function functionSignature(fn: GenerativeUIManifest["functions"][string]) {
47
+ const signature = fn.parameters.description;
48
+ const hasSignature =
49
+ typeof signature === "string" &&
50
+ signature.startsWith("{") &&
51
+ Object.keys(fn.parameters).length === 2;
52
+ return hasSignature ? signature : compactType(fn.parameters, 0);
53
+ }
54
+
55
+ /**
56
+ * A function name with its parameters: `pick{ id: string }`, `clearCart{}`
57
+ * for no arguments, `setVolume(number)` for a parameter that is not an object.
58
+ */
59
+ function nameWithParameters(name: string, parameters: string) {
60
+ if (parameters.startsWith("{")) return `${name}${parameters}`;
61
+ if (parameters === "object") return `${name}{}`;
62
+ return `${name}(${parameters})`;
63
+ }
64
+
65
+ /**
66
+ * One component as a TypeScript-like signature line, with its events and
67
+ * slots on the lines below:
68
+ * `- Text(text?: string // The text): Shows text`.
69
+ */
70
+ function signatureLines(
71
+ name: string,
72
+ component: GenerativeUIComponentManifest,
73
+ settings: GenerativeUISchemaSettings,
74
+ ) {
75
+ const props = Object.entries(
76
+ compactProps(component.props, settings.propDescriptions),
77
+ ).map(([key, type]) => `${key}: ${type}`);
78
+ const lines = [
79
+ `- ${name}(${props.join(", ")})${component.description ? `: ${oneLine(component.description)}` : ""}`,
80
+ ];
81
+ const events = Object.entries(component.events ?? {}).map(
82
+ ([event, definition]) =>
83
+ `${event}(${definition.description ? oneLine(definition.description) : compactType(definition.parameters, 0)})`,
84
+ );
85
+ if (events.length > 0) lines.push(` events: ${events.join(", ")}`);
86
+ const slots = Object.entries(component.slots ?? {}).map(
87
+ ([slot, kind]) => `${slot} (${kind})`,
88
+ );
89
+ if (slots.length > 0) lines.push(` slots: ${slots.join(", ")}`);
90
+ return lines;
91
+ }
92
+
93
+ /** The whole schema as signature text: targets, functions, components, surfaces. */
94
+ function signatureSchema(
95
+ manifest: SchemaManifest,
96
+ settings: GenerativeUISchemaSettings,
97
+ ) {
98
+ const targets = manifest.targets.map((t) => {
99
+ const limit = t.components ? `; only ${t.components.join(", ")}` : "";
100
+ return `- ${t.id} (${t.kind}${limit})${t.description ? `: ${oneLine(t.description)}` : ""}`;
101
+ });
102
+ const functions = Object.entries(manifest.functions).map(([name, fn]) => {
103
+ const callers = functionCallers(fn);
104
+ const who =
105
+ callers.agent && GENERATIVE_UI_AGENT_FUNCTION_CALLS
106
+ ? callers.renderer
107
+ ? " (UI or agent)"
108
+ : " (agent only)"
109
+ : "";
110
+ return `- ${nameWithParameters(name, functionSignature(fn))}${who}${fn.description ? `: ${oneLine(fn.description)}` : ""}`;
111
+ });
112
+ const components = Object.entries(manifest.components).flatMap(
113
+ ([name, component]) => signatureLines(name, component, settings),
114
+ );
115
+ const surfaces = Object.entries(manifest.surfaces).map(
116
+ ([id, s]) =>
117
+ `- ${id} (target ${s.target})${s.status ? ` status: ${s.status}` : ""}${s.dataModel ? ` user values: ${JSON.stringify(s.dataModel)}` : ""}${(s.rejected ?? []).map((r) => ` rejected: ${r}`).join("")}`,
118
+ );
119
+ return [
120
+ `Catalog: ${manifest.catalogId}`,
121
+ `Targets:\n${targets.join("\n") || "- none"}`,
122
+ `Functions:\n${functions.join("\n") || "- none"}`,
123
+ `Components:\n${components.join("\n") || "- none"}`,
124
+ `Surfaces:\n${surfaces.join("\n") || "- none"}`,
125
+ ].join("\n\n");
126
+ }
127
+
128
+ /** A description on one line, so its lines cannot read as new entries. */
129
+ function oneLine(text: string) {
130
+ return text.replace(/\s*\n\s*/g, " ");
131
+ }
132
+
133
+ /** Values that would read as a type or a number once their quotes are gone. */
134
+ const AMBIGUOUS_VALUE =
135
+ /^(?:string|number|integer|boolean|true|false|null|object|array|unknown|any|-?\d[\d.]*)$/;
136
+
137
+ /**
138
+ * A compact type with bare enum values and tight unions:
139
+ * `"sm" | "md" | "lg"` becomes `sm|md|lg`. A union keeps its quotes when it
140
+ * also holds a type (`"sm" | number`) or a value that reads as a type or a
141
+ * number (`"number" | "currency"`, `"1" | "2"`), and so do values that are
142
+ * not plain words.
143
+ */
144
+ function bareType(type: string) {
145
+ return type
146
+ .replace(
147
+ /"[A-Za-z0-9_#%.-]+"(?: \| "[A-Za-z0-9_#%.-]+")*(?! \|)/g,
148
+ (union: string, offset: number, whole: string) => {
149
+ if (whole.slice(offset - 2, offset) === "| ") return union;
150
+ const values = union.split(" | ").map((v) => v.slice(1, -1));
151
+ if (values.some((v) => AMBIGUOUS_VALUE.test(v))) return union;
152
+ return values.join("|");
153
+ },
154
+ )
155
+ .replace(/ \| /g, "|");
156
+ }
157
+
158
+ /** A compact prop (`type // description`) as `name: type - description`. */
159
+ function propLine(key: string, value: string) {
160
+ const name = key.endsWith("?") ? key.slice(0, -1) : `${key}*`;
161
+ const cut = value.indexOf(" // ");
162
+ const type = bareType(cut < 0 ? value : value.slice(0, cut));
163
+ const text = cut < 0 ? "" : value.slice(cut + 4).trim();
164
+ const description = text ? ` - ${oneLine(text)}` : "";
165
+ return ` ${name}: ${type}${description}`;
166
+ }
167
+
168
+ /**
169
+ * The whole schema as plain lines: a header line per component and one
170
+ * indented line per prop: events are `action` props and slots `componentId`
171
+ * or `childList` props. Props are optional unless marked `*`, enum values
172
+ * are bare, and the common props are listed once. It carries the same names, types and descriptions as
173
+ * `compact`, in fewer tokens.
174
+ */
175
+ function linesSchema(
176
+ manifest: SchemaManifest,
177
+ settings: GenerativeUISchemaSettings,
178
+ ) {
179
+ const compact = buildCompactGenerativeUISchema(manifest, {
180
+ propDescriptions: settings.propDescriptions,
181
+ commonProps: settings.commonProps,
182
+ });
183
+ const targets = compact.targets
184
+ .map((t) => {
185
+ const limit = t.components ? `, only ${t.components.join(", ")}` : "";
186
+ return `${t.id} (${t.kind}${limit})${t.description ? `: ${oneLine(t.description)}` : ""}`;
187
+ })
188
+ .join("; ");
189
+ const functions = Object.entries(compact.functions).map(
190
+ ([name, fn]) =>
191
+ `${nameWithParameters(name, fn.parameters)}${"callers" in fn ? ` (${fn.callers})` : ""}${fn.description ? `: ${oneLine(fn.description)}` : ""}`,
192
+ );
193
+ const common = compact.commonProps
194
+ ? Object.entries(compact.commonProps).map(([k, v]) => propLine(k, v))
195
+ : [];
196
+ const lineSets = Object.entries(compact.components).map(([name, c]) => ({
197
+ name,
198
+ c,
199
+ own: [
200
+ ...Object.entries(c.props).map(([k, v]) => propLine(k, v)),
201
+ ...Object.entries(c.events ?? {}).map(
202
+ ([e, d]) => ` ${e}: action - ${oneLine(d)}`,
203
+ ),
204
+ ],
205
+ }));
206
+ const components = lineSets.flatMap(({ name, c, own }) => {
207
+ const lines = [
208
+ `${name}${c.includesCommonProps ? " +common" : ""}${c.description ? `: ${oneLine(c.description)}` : ""}`,
209
+ ...own,
210
+ ];
211
+ // Slots are props that take component ids.
212
+ for (const [slot, kind] of Object.entries(c.slots ?? {})) {
213
+ lines.push(
214
+ ` ${slot}: ${kind === "single" ? "componentId" : "childList"}`,
215
+ );
216
+ }
217
+ return lines;
218
+ });
219
+ const surfaces = Object.keys(compact.surfaces).length
220
+ ? JSON.stringify(compact.surfaces)
221
+ : "none";
222
+ return [
223
+ `Catalog ${compact.catalogId}. Targets: ${targets || "none"}`,
224
+ 'Props are optional unless marked *. a|b|c is one of those strings, quoted when one reads as a type or a number. A component marked +common also takes every common prop. A prop of type action is an event prop: give it {"event":{...}} or {"functionCall":{...}}. A componentId prop takes one component id; a childList prop takes a list of ids or a template.',
225
+ `Functions:\n${functions.join("\n")}`,
226
+ ...(common.length ? [`Common props:\n${common.join("\n")}`] : []),
227
+ `Components:\n${components.join("\n")}`,
228
+ `Surfaces: ${surfaces}`,
229
+ ].join("\n\n");
230
+ }
231
+
232
+ /**
233
+ * The component schema of the markdown transport, as the text of its
234
+ * context entry, in the notation of `settings`. `compact` is the schema that
235
+ * ships (`buildCompactGenerativeUISchema`), `json-schema` the manifest parts
236
+ * as JSON, `ts-signature` one line per component, `lines` one line per
237
+ * prop with bare enums (the fewest tokens).
238
+ *
239
+ * @example
240
+ * ```ts
241
+ * const value = renderGenerativeUISchema(manifest, spec.schema.markdown);
242
+ * ```
243
+ */
244
+ export function renderGenerativeUISchema(
245
+ manifest: SchemaManifest,
246
+ settings: GenerativeUISchemaSettings,
247
+ ): string {
248
+ switch (settings.notation) {
249
+ case "compact":
250
+ return JSON.stringify(
251
+ buildCompactGenerativeUISchema(manifest, {
252
+ propDescriptions: settings.propDescriptions,
253
+ commonProps: settings.commonProps,
254
+ }),
255
+ );
256
+ case "json-schema": {
257
+ const components = Object.fromEntries(
258
+ Object.entries(manifest.components).map(([name, c]) => [
259
+ name,
260
+ settings.propDescriptions
261
+ ? c
262
+ : { ...c, props: withoutPropDescriptions(c.props) },
263
+ ]),
264
+ );
265
+ return JSON.stringify({
266
+ catalogId: manifest.catalogId,
267
+ targets: manifest.targets,
268
+ functions: manifest.functions,
269
+ components,
270
+ surfaces: manifest.surfaces,
271
+ });
272
+ }
273
+ case "ts-signature":
274
+ return signatureSchema(manifest, settings);
275
+ case "lines":
276
+ return linesSchema(manifest, settings);
277
+ }
278
+ }
279
+
280
+ /**
281
+ * The component list of the tool guide, one entry per component, in the
282
+ * notation of `settings`. `json-schema` is the list that ships.
283
+ */
284
+ export function renderGenerativeUIComponentList(
285
+ components: GenerativeUIManifest["components"],
286
+ settings: GenerativeUISchemaSettings,
287
+ ): string {
288
+ return Object.entries(components)
289
+ .map(([name, c]) => {
290
+ if (
291
+ settings.notation === "ts-signature" ||
292
+ settings.notation === "lines"
293
+ ) {
294
+ return signatureLines(name, c, settings).join("\n");
295
+ }
296
+ const props =
297
+ settings.notation === "compact"
298
+ ? compactProps(c.props, settings.propDescriptions)
299
+ : settings.propDescriptions
300
+ ? c.props
301
+ : withoutPropDescriptions(c.props);
302
+ const lines = [
303
+ `- **${name}**${c.description ? `: ${oneLine(c.description)}` : ""}`,
304
+ ` props: ${JSON.stringify(props)}`,
305
+ ];
306
+ if (c.events) lines.push(` event props: ${JSON.stringify(c.events)}`);
307
+ if (c.slots)
308
+ lines.push(` slot props (component ids): ${JSON.stringify(c.slots)}`);
309
+ return lines.join("\n");
310
+ })
311
+ .join("\n");
312
+ }
313
+
314
+ /**
315
+ * The manifest with replaced descriptions: `"Name"` replaces the
316
+ * description of a component, `"Name.prop"` the description of one of its
317
+ * props. Keys that name no component or prop are left out of the result
318
+ * and listed in `unknown`. The manifest is not changed.
319
+ */
320
+ export function applyDescriptionOverrides<
321
+ M extends Pick<GenerativeUIManifest, "components">,
322
+ >(
323
+ manifest: M,
324
+ overrides: Record<string, string>,
325
+ ): { manifest: M; unknown: string[] } {
326
+ const components = structuredClone(manifest.components);
327
+ const unknown: string[] = [];
328
+ for (const [key, description] of Object.entries(overrides)) {
329
+ const [name, prop, ...rest] = key.split(".");
330
+ // Own keys only: "__proto__" must never reach Object.prototype.
331
+ const component = hasOwn(components, name) ? components[name] : undefined;
332
+ if (!component || rest.length > 0) {
333
+ unknown.push(key);
334
+ continue;
335
+ }
336
+ if (prop === undefined) {
337
+ component.description = description;
338
+ continue;
339
+ }
340
+ const properties = component.props.properties;
341
+ const property =
342
+ isRecord(properties) && hasOwn(properties, prop)
343
+ ? properties[prop]
344
+ : undefined;
345
+ if (!isRecord(property)) {
346
+ unknown.push(key);
347
+ continue;
348
+ }
349
+ property.description = description;
350
+ }
351
+ return { manifest: { ...manifest, components }, unknown };
352
+ }
353
+
354
+ /**
355
+ * The components and props of `manifest` whose names do not appear in
356
+ * `rendered`. A schema notation that leaves one out would hide part of the
357
+ * catalog from the model.
358
+ */
359
+ export function schemaCoverage(
360
+ manifest: Pick<GenerativeUIManifest, "components">,
361
+ rendered: string,
362
+ ): { missing: string[] } {
363
+ const missing: string[] = [];
364
+ for (const [name, component] of Object.entries(manifest.components)) {
365
+ if (!rendered.includes(name)) missing.push(name);
366
+ const properties = isRecord(component.props.properties)
367
+ ? component.props.properties
368
+ : {};
369
+ for (const prop of Object.keys(properties)) {
370
+ if (!rendered.includes(prop)) missing.push(`${name}.${prop}`);
371
+ }
372
+ }
373
+ return { missing };
374
+ }
package/src/index.ts CHANGED
@@ -1,16 +1,9 @@
1
1
  export * from "./types";
2
2
  export * from "./utils";
3
3
  export * from "./constants";
4
- // Telemetry is split deliberately. `TelemetryClient` imports
5
- // `@segment/analytics-node`, which imports `node-fetch`, which imports the
6
- // Node built-ins `stream`, `http`, `https` and `zlib`. Browser bundlers
7
- // resolve the whole module graph before they tree-shake, so re-exporting
8
- // that module here made every browser build of a dependent package print
9
- // "Module ... has been externalized for browser compatibility" warnings,
10
- // even when the consumer never touched telemetry (#4151). Only the
11
- // browser-safe telemetry surface is re-exported from this entry. Server
12
- // code that needs the client imports it from `@copilotkit/shared/telemetry`.
13
- // This mirrors the license-verifier note below.
4
+ // Only browser-safe telemetry helpers live here. The runtime owns its
5
+ // telemetry client (`packages/runtime/src/runtime/telemetry`), so this package
6
+ // imports no Node-only analytics SDK (#4151).
14
7
  export { isTelemetryDisabled } from "./telemetry/telemetry-disabled";
15
8
  export * from "./telemetry/sampling";
16
9
  // Pure string classification with no imports, so it carries no runtime edge
@@ -23,12 +16,6 @@ export {
23
16
  parseAndWarnTelemetryId,
24
17
  } from "./telemetry/lambda-client";
25
18
  export type { LambdaSendOptions } from "./telemetry/lambda-client";
26
- // Types only: erased at build time, so they add no runtime edge to
27
- // `telemetry-client.ts` and therefore none to @segment/analytics-node.
28
- export type {
29
- TelemetryCapture,
30
- TelemetryIdentity,
31
- } from "./telemetry/telemetry-client";
32
19
  export * from "./debug";
33
20
  export * from "./standard-schema";
34
21
  export * from "./attachments";
@@ -5,6 +5,21 @@ import type {
5
5
 
6
6
  export type { StandardSchemaV1, StandardJSONSchemaV1 };
7
7
 
8
+ /**
9
+ * A Standard Schema that accepts any value and returns it unchanged.
10
+ *
11
+ * Wildcard tool call renderers use it when they declare no `args` schema.
12
+ *
13
+ * @internal Application authors must not depend on this contract.
14
+ */
15
+ export const ɵanySchema: StandardSchemaV1<unknown, unknown> = {
16
+ "~standard": {
17
+ version: 1,
18
+ vendor: "copilotkit",
19
+ validate: (value) => ({ value }),
20
+ },
21
+ };
22
+
8
23
  /**
9
24
  * Extract the Output type from a StandardSchemaV1 schema.
10
25
  * Replaces `z.infer<S>` for generic schema inference.
@@ -12,18 +27,6 @@ export type { StandardSchemaV1, StandardJSONSchemaV1 };
12
27
  export type InferSchemaOutput<S> =
13
28
  S extends StandardSchemaV1<any, infer O> ? O : never;
14
29
 
15
- export interface SchemaToJsonSchemaOptions {
16
- /**
17
- * Injected `zodToJsonSchema` function so that `shared` does not depend on
18
- * `zod-to-json-schema`. Required when the schema is a Zod v3 schema that
19
- * does not implement Standard JSON Schema V1.
20
- */
21
- zodToJsonSchema?: (
22
- schema: unknown,
23
- options?: { $refStrategy?: string },
24
- ) => Record<string, unknown>;
25
- }
26
-
27
30
  /**
28
31
  * Check whether a schema implements the Standard JSON Schema V1 protocol.
29
32
  */
@@ -48,35 +51,29 @@ function hasStandardJsonSchema(
48
51
  * Strategy:
49
52
  * 1. If the schema implements Standard JSON Schema V1 (`~standard.jsonSchema`),
50
53
  * call `schema['~standard'].jsonSchema.input({ target: 'draft-07' })`.
51
- * 2. If the schema exposes a `toJSONSchema()` method (Zod v4), call it directly.
52
- * 3. If the schema is a Zod v3 schema (`~standard.vendor === 'zod'`), use the
53
- * injected `zodToJsonSchema()` function.
54
- * 4. Otherwise throw a descriptive error.
54
+ * Zod 4.2+, ArkType 2.1.28+ and Valibot (via `toStandardJsonSchema`) do.
55
+ * 2. If the schema exposes a `toJSONSchema()` method, call it directly.
56
+ * 3. Otherwise throw a descriptive error. Zod 3 schemas land here: they
57
+ * implement Standard Schema validation but cannot describe themselves as
58
+ * JSON Schema.
55
59
  */
56
60
  export function schemaToJsonSchema(
57
61
  schema: StandardSchemaV1,
58
- options?: SchemaToJsonSchemaOptions,
59
62
  ): Record<string, unknown> {
60
63
  // 1. Standard JSON Schema V1
61
64
  if (hasStandardJsonSchema(schema)) {
62
65
  return schema["~standard"].jsonSchema.input({ target: "draft-07" });
63
66
  }
64
67
 
65
- // 2. Zod v4 native — exposes toJSONSchema() on the schema itself
68
+ // 2. Native toJSONSchema() method
66
69
  if (typeof (schema as any).toJSONSchema === "function") {
67
70
  return (schema as any).toJSONSchema() as Record<string, unknown>;
68
71
  }
69
72
 
70
- // 3. Zod v3 fallback
71
73
  const vendor = schema["~standard"].vendor;
72
- if (vendor === "zod" && options?.zodToJsonSchema) {
73
- return options.zodToJsonSchema(schema, { $refStrategy: "none" });
74
- }
75
-
76
74
  throw new Error(
77
- `Cannot convert schema to JSON Schema. The schema (vendor: "${vendor}") does not implement Standard JSON Schema V1 ` +
78
- `and no zodToJsonSchema fallback is available. ` +
79
- `Use a library that supports Standard JSON Schema (e.g., Zod 3.24+, Valibot v1+, ArkType v2+) ` +
80
- `or pass a zodToJsonSchema function in options.`,
75
+ `Cannot convert schema to JSON Schema. The schema (vendor: "${vendor}") does not implement Standard JSON Schema V1. ` +
76
+ `Use a library that does: Zod 4.2+ (Zod 3 is not supported), Valibot v1+ wrapped with ` +
77
+ `toStandardJsonSchema() from @valibot/to-json-schema, or ArkType v2.1.28+.`,
81
78
  );
82
79
  }
@@ -136,8 +136,9 @@ export function parseTelemetryIdFromLicense(token?: string): string | null {
136
136
  // Parse the telemetry_id from a license token AND emit the rollout smoke
137
137
  // signal if the parse returned null. Returning the parsed id lets callers
138
138
  // cache it in one step (avoiding a second parseTelemetryIdFromLicense
139
- // pass) while keeping the warn text in lockstep between v1 (shared) and
140
- // v2 (runtime) TelemetryClient.setLicenseToken.
139
+ // pass) while keeping the warn text in lockstep between the v1 (shared)
140
+ // TelemetryClient.setLicenseToken and the v2 (runtime)
141
+ // TelemetryClient.setTelemetryIdentity.
141
142
  export function parseAndWarnTelemetryId(licenseToken: string): string | null {
142
143
  const telemetryId = parseTelemetryIdFromLicense(licenseToken);
143
144
  if (!telemetryId) {
@@ -1,22 +1,17 @@
1
+ import { processEnv } from "../utils/process-env";
2
+
1
3
  /**
2
4
  * Checks if telemetry is disabled via environment variables.
3
5
  * Users can opt out by setting:
4
6
  * - COPILOTKIT_TELEMETRY_DISABLED=true or COPILOTKIT_TELEMETRY_DISABLED=1
5
7
  * - DO_NOT_TRACK=true or DO_NOT_TRACK=1
6
- *
7
- * Lives in its own module so that the browser-facing root entry can
8
- * re-export it without pulling in `telemetry-client.ts`, whose
9
- * `@segment/analytics-node` import drags Node built-ins into browser
10
- * bundler module graphs. See the note in `../index.ts`.
11
8
  */
12
9
  export function isTelemetryDisabled(): boolean {
10
+ const env = processEnv();
13
11
  return (
14
- (process.env as Record<string, string | undefined>)
15
- .COPILOTKIT_TELEMETRY_DISABLED === "true" ||
16
- (process.env as Record<string, string | undefined>)
17
- .COPILOTKIT_TELEMETRY_DISABLED === "1" ||
18
- (process.env as Record<string, string | undefined>).DO_NOT_TRACK ===
19
- "true" ||
20
- (process.env as Record<string, string | undefined>).DO_NOT_TRACK === "1"
12
+ env.COPILOTKIT_TELEMETRY_DISABLED === "true" ||
13
+ env.COPILOTKIT_TELEMETRY_DISABLED === "1" ||
14
+ env.DO_NOT_TRACK === "true" ||
15
+ env.DO_NOT_TRACK === "1"
21
16
  );
22
17
  }
@@ -1,4 +1,4 @@
1
- import * as agui from "@ag-ui/core";
1
+ import type * as agui from "@ag-ui/core";
2
2
 
3
3
  // Re-export AG-UI multimodal input types.
4
4
  // Note: AG-UI names the text variant TextInputContent; we export it as TextInputPart for consistency.
@@ -14,18 +14,6 @@ export type {
14
14
  DocumentInputPart,
15
15
  } from "@ag-ui/core";
16
16
 
17
- /**
18
- * @deprecated Use `InputContentSource` from `@ag-ui/core` (re-exported from `@copilotkit/shared`) instead.
19
- * `ImageData` only described base64 image payloads. `InputContentSource` supports
20
- * data and URL sources for images, audio, video, and documents.
21
- * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
22
- * @since 1.56.0
23
- */
24
- export interface ImageData {
25
- format: string;
26
- bytes: string;
27
- }
28
-
29
17
  // Pass through types
30
18
  export type Role = agui.Role;
31
19
  export type SystemMessage = agui.SystemMessage;
@@ -44,12 +32,6 @@ export type AIMessage = agui.AssistantMessage & {
44
32
  generativeUIPosition?: "before" | "after";
45
33
  agentName?: string;
46
34
  state?: any;
47
- /**
48
- * @deprecated Use multimodal `content` array with `InputContent` parts instead.
49
- * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
50
- * @since 1.56.0
51
- */
52
- image?: ImageData;
53
35
  runId?: string;
54
36
  };
55
37
 
@@ -0,0 +1,44 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import {
3
+ CopilotKitError,
4
+ CopilotKitErrorCode,
5
+ ConfigurationError,
6
+ ErrorVisibility,
7
+ Severity,
8
+ } from "../errors";
9
+
10
+ describe("CopilotKitError", () => {
11
+ it("is a plain Error that keeps the structured extensions", () => {
12
+ const error = new CopilotKitError({
13
+ message: "boom",
14
+ code: CopilotKitErrorCode.NOT_FOUND,
15
+ });
16
+
17
+ expect(error).toBeInstanceOf(Error);
18
+ expect(error.message).toBe("boom");
19
+ expect(error.name).toBe("CopilotError");
20
+ expect(error.extensions).toMatchObject({
21
+ name: "CopilotError",
22
+ code: CopilotKitErrorCode.NOT_FOUND,
23
+ statusCode: 404,
24
+ visibility: ErrorVisibility.BANNER,
25
+ severity: Severity.CRITICAL,
26
+ originalError: { message: "boom" },
27
+ });
28
+ expect(error.extensions.troubleshootingUrl).toContain(
29
+ "network-errors-api-not-found",
30
+ );
31
+ });
32
+
33
+ it("sets troubleshootingUrl to null when the code has none", () => {
34
+ const error = new CopilotKitError({ code: CopilotKitErrorCode.UNKNOWN });
35
+ expect(error.extensions.troubleshootingUrl).toBeNull();
36
+ });
37
+
38
+ it("keeps subclasses instanceof both the subclass and CopilotKitError", () => {
39
+ const error = new ConfigurationError("bad config");
40
+ expect(error).toBeInstanceOf(ConfigurationError);
41
+ expect(error).toBeInstanceOf(CopilotKitError);
42
+ expect(error.extensions.code).toBe(CopilotKitErrorCode.CONFIGURATION_ERROR);
43
+ });
44
+ });