@copilotkit/shared 1.79.2-canary.1792172552 → 1.81.0

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 (156) hide show
  1. package/dist/a2ui-envelope.cjs +154 -0
  2. package/dist/a2ui-envelope.cjs.map +1 -0
  3. package/dist/a2ui-envelope.d.cts +101 -0
  4. package/dist/a2ui-envelope.d.cts.map +1 -0
  5. package/dist/a2ui-envelope.d.mts +101 -0
  6. package/dist/a2ui-envelope.d.mts.map +1 -0
  7. package/dist/a2ui-envelope.mjs +151 -0
  8. package/dist/a2ui-envelope.mjs.map +1 -0
  9. package/dist/a2ui-prompts.cjs +139 -0
  10. package/dist/a2ui-prompts.cjs.map +1 -1
  11. package/dist/a2ui-prompts.d.cts +60 -1
  12. package/dist/a2ui-prompts.d.cts.map +1 -1
  13. package/dist/a2ui-prompts.d.mts +60 -1
  14. package/dist/a2ui-prompts.d.mts.map +1 -1
  15. package/dist/a2ui-prompts.mjs +134 -1
  16. package/dist/a2ui-prompts.mjs.map +1 -1
  17. package/dist/constants/index.cjs +7 -0
  18. package/dist/constants/index.cjs.map +1 -1
  19. package/dist/constants/index.d.cts +7 -1
  20. package/dist/constants/index.d.cts.map +1 -1
  21. package/dist/constants/index.d.mts +7 -1
  22. package/dist/constants/index.d.mts.map +1 -1
  23. package/dist/constants/index.mjs +7 -1
  24. package/dist/constants/index.mjs.map +1 -1
  25. package/dist/event-transforms/open-generative-ui-middleware.cjs +7 -6
  26. package/dist/event-transforms/open-generative-ui-middleware.cjs.map +1 -1
  27. package/dist/event-transforms/open-generative-ui-middleware.d.cts.map +1 -1
  28. package/dist/event-transforms/open-generative-ui-middleware.d.mts.map +1 -1
  29. package/dist/event-transforms/open-generative-ui-middleware.mjs +7 -6
  30. package/dist/event-transforms/open-generative-ui-middleware.mjs.map +1 -1
  31. package/dist/generative-ui/basic-functions.cjs +177 -0
  32. package/dist/generative-ui/basic-functions.cjs.map +1 -0
  33. package/dist/generative-ui/basic-functions.d.cts +108 -0
  34. package/dist/generative-ui/basic-functions.d.cts.map +1 -0
  35. package/dist/generative-ui/basic-functions.d.mts +108 -0
  36. package/dist/generative-ui/basic-functions.d.mts.map +1 -0
  37. package/dist/generative-ui/basic-functions.mjs +167 -0
  38. package/dist/generative-ui/basic-functions.mjs.map +1 -0
  39. package/dist/generative-ui/child-refs.cjs +161 -0
  40. package/dist/generative-ui/child-refs.cjs.map +1 -0
  41. package/dist/generative-ui/child-refs.d.cts +68 -0
  42. package/dist/generative-ui/child-refs.d.cts.map +1 -0
  43. package/dist/generative-ui/child-refs.d.mts +68 -0
  44. package/dist/generative-ui/child-refs.d.mts.map +1 -0
  45. package/dist/generative-ui/child-refs.mjs +152 -0
  46. package/dist/generative-ui/child-refs.mjs.map +1 -0
  47. package/dist/generative-ui/is-record.cjs +10 -0
  48. package/dist/generative-ui/is-record.cjs.map +1 -0
  49. package/dist/generative-ui/is-record.mjs +9 -0
  50. package/dist/generative-ui/is-record.mjs.map +1 -0
  51. package/dist/generative-ui/prompt.cjs +91 -0
  52. package/dist/generative-ui/prompt.cjs.map +1 -0
  53. package/dist/generative-ui/prompt.d.cts +13 -0
  54. package/dist/generative-ui/prompt.d.cts.map +1 -0
  55. package/dist/generative-ui/prompt.d.mts +13 -0
  56. package/dist/generative-ui/prompt.d.mts.map +1 -0
  57. package/dist/generative-ui/prompt.mjs +90 -0
  58. package/dist/generative-ui/prompt.mjs.map +1 -0
  59. package/dist/generative-ui/render-ui-args.cjs +160 -0
  60. package/dist/generative-ui/render-ui-args.cjs.map +1 -0
  61. package/dist/generative-ui/render-ui-args.d.cts +40 -0
  62. package/dist/generative-ui/render-ui-args.d.cts.map +1 -0
  63. package/dist/generative-ui/render-ui-args.d.mts +40 -0
  64. package/dist/generative-ui/render-ui-args.d.mts.map +1 -0
  65. package/dist/generative-ui/render-ui-args.mjs +159 -0
  66. package/dist/generative-ui/render-ui-args.mjs.map +1 -0
  67. package/dist/generative-ui/types.cjs +101 -0
  68. package/dist/generative-ui/types.cjs.map +1 -0
  69. package/dist/generative-ui/types.d.cts +270 -0
  70. package/dist/generative-ui/types.d.cts.map +1 -0
  71. package/dist/generative-ui/types.d.mts +270 -0
  72. package/dist/generative-ui/types.d.mts.map +1 -0
  73. package/dist/generative-ui/types.mjs +86 -0
  74. package/dist/generative-ui/types.mjs.map +1 -0
  75. package/dist/generative-ui/validate-operation.cjs +405 -0
  76. package/dist/generative-ui/validate-operation.cjs.map +1 -0
  77. package/dist/generative-ui/validate-operation.d.cts +86 -0
  78. package/dist/generative-ui/validate-operation.d.cts.map +1 -0
  79. package/dist/generative-ui/validate-operation.d.mts +86 -0
  80. package/dist/generative-ui/validate-operation.d.mts.map +1 -0
  81. package/dist/generative-ui/validate-operation.mjs +399 -0
  82. package/dist/generative-ui/validate-operation.mjs.map +1 -0
  83. package/dist/index.cjs +64 -0
  84. package/dist/index.cjs.map +1 -1
  85. package/dist/index.d.cts +11 -4
  86. package/dist/index.d.cts.map +1 -1
  87. package/dist/index.d.mts +11 -4
  88. package/dist/index.d.mts.map +1 -1
  89. package/dist/index.mjs +10 -3
  90. package/dist/index.mjs.map +1 -1
  91. package/dist/index.umd.js +1466 -29
  92. package/dist/index.umd.js.map +1 -1
  93. package/dist/package.cjs +1 -1
  94. package/dist/package.mjs +1 -1
  95. package/dist/telemetry/lambda-client.cjs.map +1 -1
  96. package/dist/telemetry/lambda-client.mjs.map +1 -1
  97. package/dist/telemetry/utils.cjs +0 -2
  98. package/dist/telemetry/utils.cjs.map +1 -1
  99. package/dist/telemetry/utils.mjs +0 -2
  100. package/dist/telemetry/utils.mjs.map +1 -1
  101. package/dist/utils/dashboard-url.cjs +19 -0
  102. package/dist/utils/dashboard-url.cjs.map +1 -0
  103. package/dist/utils/dashboard-url.mjs +18 -0
  104. package/dist/utils/dashboard-url.mjs.map +1 -0
  105. package/dist/utils/index.cjs +2 -1
  106. package/dist/utils/index.cjs.map +1 -1
  107. package/dist/utils/index.d.cts +1 -1
  108. package/dist/utils/index.d.cts.map +1 -1
  109. package/dist/utils/index.d.mts +1 -1
  110. package/dist/utils/index.d.mts.map +1 -1
  111. package/dist/utils/index.mjs +2 -1
  112. package/dist/utils/index.mjs.map +1 -1
  113. package/dist/utils/inspector-learning.cjs +48 -16
  114. package/dist/utils/inspector-learning.cjs.map +1 -1
  115. package/dist/utils/inspector-learning.d.cts +14 -1
  116. package/dist/utils/inspector-learning.d.cts.map +1 -1
  117. package/dist/utils/inspector-learning.d.mts +14 -1
  118. package/dist/utils/inspector-learning.d.mts.map +1 -1
  119. package/dist/utils/inspector-learning.mjs +49 -16
  120. package/dist/utils/inspector-learning.mjs.map +1 -1
  121. package/dist/utils/inspector-metadata.cjs +2 -3
  122. package/dist/utils/inspector-metadata.cjs.map +1 -1
  123. package/dist/utils/inspector-metadata.d.cts.map +1 -1
  124. package/dist/utils/inspector-metadata.d.mts.map +1 -1
  125. package/dist/utils/inspector-metadata.mjs +3 -3
  126. package/dist/utils/inspector-metadata.mjs.map +1 -1
  127. package/package.json +3 -4
  128. package/src/__tests__/a2ui-envelope.test.ts +434 -0
  129. package/src/__tests__/a2ui-prompts.test.ts +362 -0
  130. package/src/a2ui-envelope.ts +309 -0
  131. package/src/a2ui-prompts.ts +207 -0
  132. package/src/constants/index.ts +7 -0
  133. package/src/event-transforms/open-generative-ui-middleware.ts +19 -10
  134. package/src/generative-ui/__tests__/render-ui-args.test.ts +175 -0
  135. package/src/generative-ui/__tests__/validate-operation.test.ts +977 -0
  136. package/src/generative-ui/basic-functions.ts +282 -0
  137. package/src/generative-ui/child-refs.ts +210 -0
  138. package/src/generative-ui/index.ts +6 -0
  139. package/src/generative-ui/is-record.ts +4 -0
  140. package/src/generative-ui/prompt.ts +174 -0
  141. package/src/generative-ui/render-ui-args.ts +199 -0
  142. package/src/generative-ui/types.ts +314 -0
  143. package/src/generative-ui/validate-operation.ts +723 -0
  144. package/src/index.ts +15 -0
  145. package/src/telemetry/lambda-client.ts +3 -3
  146. package/src/telemetry/utils.ts +0 -28
  147. package/src/utils/dashboard-url.ts +17 -0
  148. package/src/utils/index.ts +7 -1
  149. package/src/utils/inspector-learning.test.ts +210 -0
  150. package/src/utils/inspector-learning.ts +117 -17
  151. package/src/utils/inspector-metadata.test.ts +2 -1
  152. package/src/utils/inspector-metadata.ts +3 -13
  153. package/src/utils.test.ts +71 -0
  154. package/tsdown.config.ts +0 -1
  155. package/src/telemetry/scarf-client.ts +0 -39
  156. package/src/telemetry/security-check.ts +0 -0
@@ -1,3 +1,7 @@
1
+ import { isA2UIBasicFunction } from "./generative-ui/basic-functions";
2
+ import { A2UI_CHILD_LIST_REF } from "./generative-ui/child-refs";
3
+ import { GENERATIVE_UI_AGENT_FUNCTION_CALLS } from "./generative-ui/types";
4
+ import type { GenerativeUIManifest } from "./generative-ui/types";
1
5
  /**
2
6
  * Default A2UI generation and design guideline prompts.
3
7
  *
@@ -113,3 +117,206 @@ Design principles:
113
117
  action context should reference the same paths to capture user input.
114
118
 
115
119
  Use the SAME surfaceId as the main surface. Match action names to button action event names.`;
120
+
121
+ /**
122
+ * When UI helps the user, for both transports: a light nudge to reach for UI
123
+ * where it conveys the answer better than prose, and to stay in prose
124
+ * otherwise.
125
+ */
126
+ export const GENERATIVE_UI_WHEN_TO_SHOW =
127
+ "Show UI when it conveys the answer better than prose: to illustrate a concept (a diagram, a chart of how something changes), to compare options side by side, to let the user explore or adjust values, or to collect input. A small, focused surface next to your explanation often lands better than a long description. Reply in prose alone for a quick fact, a short answer, or conversation, and never add UI only as decoration.";
128
+
129
+ /** Description of the context entry that carries `GENERATIVE_UI_MARKDOWN_GUIDELINES`. */
130
+ export const GENERATIVE_UI_MARKDOWN_GUIDELINES_DESCRIPTION =
131
+ "Generative UI markdown guide: how to write UI surfaces inside ```a2ui code fences in a normal markdown reply.";
132
+
133
+ /**
134
+ * Description of the context entry that carries the compact component schema
135
+ * in the markdown transport.
136
+ *
137
+ * It must not equal `A2UI_SCHEMA_CONTEXT_DESCRIPTION` (the key that
138
+ * `@ag-ui/a2ui-middleware` stamps for tool mode). The LangGraph and Strands
139
+ * adapters find that exact string and move the entry into
140
+ * `state["ag-ui"]["a2ui_schema"]` for the `render_a2ui` tool, so it never
141
+ * gets to the system prompt. The markdown transport has no tool, so the
142
+ * schema must stay ordinary context that the model reads as App Context.
143
+ */
144
+ export const GENERATIVE_UI_MARKDOWN_SCHEMA_CONTEXT_DESCRIPTION =
145
+ "Generative UI component schema: the components, props, events, slots, functions, and targets that ```a2ui code fences can use, and the surfaces that already exist.";
146
+
147
+ /** Which optional parts of A2UI a manifest uses. The guides leave out the rules for the others. */
148
+ export interface GenerativeUIGuideFeatures {
149
+ /** A function is mounted: function calls and callRendererFunction. */
150
+ functions: boolean;
151
+ /** A component has an event prop. */
152
+ events: boolean;
153
+ /** A component has a "multiple" slot, which takes templates and @index. */
154
+ templates: boolean;
155
+ /** A component has a "checks" prop: validation rules on inputs. */
156
+ checks: boolean;
157
+ }
158
+
159
+ /** Every optional rule group. Use it when the manifest is not known. */
160
+ export const ALL_GENERATIVE_UI_GUIDE_FEATURES: GenerativeUIGuideFeatures = {
161
+ functions: true,
162
+ events: true,
163
+ templates: true,
164
+ checks: true,
165
+ };
166
+
167
+ /**
168
+ * The optional parts of A2UI that a manifest uses, so that a guide sends only
169
+ * the rules that the model can apply.
170
+ *
171
+ * @param manifest - The components and the mounted functions of a run.
172
+ * @returns Which optional rule groups the guides include.
173
+ *
174
+ * @example
175
+ * ```ts
176
+ * const guide = buildGenerativeUIMarkdownGuidelines(
177
+ * generativeUIGuideFeatures(manifest),
178
+ * );
179
+ * ```
180
+ */
181
+ export function generativeUIGuideFeatures(
182
+ manifest: Pick<GenerativeUIManifest, "components" | "functions">,
183
+ ): GenerativeUIGuideFeatures {
184
+ const components = Object.values(manifest.components);
185
+ const hasChildList = (schema: unknown): boolean => {
186
+ if (Array.isArray(schema)) return schema.some(hasChildList);
187
+ if (typeof schema !== "object" || schema === null) return false;
188
+ const node = schema as Record<string, unknown>;
189
+ if (node.$ref === A2UI_CHILD_LIST_REF) return true;
190
+ return Object.values(node).some(hasChildList);
191
+ };
192
+ return {
193
+ // App functions only: the built-in ones are always there and have
194
+ // their own rules.
195
+ functions: Object.keys(manifest.functions).some(
196
+ (name) => !isA2UIBasicFunction(name),
197
+ ),
198
+ events: components.some((c) => Object.keys(c.events ?? {}).length > 0),
199
+ templates: components.some(
200
+ (c) =>
201
+ Object.values(c.slots ?? {}).includes("multiple") ||
202
+ hasChildList(c.props),
203
+ ),
204
+ checks: components.some((c) => {
205
+ const properties = c.props.properties;
206
+ return (
207
+ typeof properties === "object" &&
208
+ properties !== null &&
209
+ Object.prototype.hasOwnProperty.call(properties, "checks")
210
+ );
211
+ }),
212
+ };
213
+ }
214
+
215
+ /** The first rules of every markdown guideline, before the optional groups. */
216
+ const MARKDOWN_BASE_RULES = [
217
+ "Write explanations as normal markdown prose outside the fences.",
218
+ "Open a fence with ```a2ui to show the surface in the chat, at the place of the fence.",
219
+ 'Open a fence with ```a2ui target=<id> to show the surface in a named target. Use only target ids from the schema. When a target has "components", its surfaces can use only those components.',
220
+ "Inside a fence, write one JSON object per line and nothing else. No comments, no trailing commas, no pretty-printing.",
221
+ "Keep each operation whole on its line.",
222
+ 'Give every operation "version":"v1.0".',
223
+ `Start a surface with one createSurface. Put all the initial data in "dataModel" and the "root" component in "components". Then write the children in updateComponents lines, so that they show while you write:
224
+ \`\`\`a2ui
225
+ {"version":"v1.0","createSurface":{"surfaceId":"plan-picker","dataModel":{ ...initial data... },"components":[{"id":"root","component":"<Name>","children":["seats","pick"]}]}}
226
+ {"version":"v1.0","updateComponents":{"surfaceId":"plan-picker","components":[ ...the children... ]}}
227
+ \`\`\``,
228
+ 'Keep "dataModel" flat: top-level keys such as "seats" or "form", never one wrapper object around everything. Check that every { and [ you open in a line is closed.',
229
+ 'Every surface renders from the component with id "root". Make every other component reachable from "root" through slots.',
230
+ "Use unique ids. Do not make cycles. A component cannot be its own child.",
231
+ 'Write a component as one flat object: {"id":"title","component":"<Name>","text":"Hello"}.',
232
+ 'Put the component name in "component" (never "type"). Put props next to it, never inside a "props" object.',
233
+ 'A component may take "accessibility":{"label":"<1 to 3 words>","description":"<what it does>"} for screen readers: on the component it describes, when nothing visible names it. Not on every component, and "live":"polite" only on text that changes by itself.',
234
+ 'Use only the components, props, events, and slots in the schema. A component with "includesCommonProps" also takes every prop in "commonProps".',
235
+ 'Give a prop a literal value, or bind it to the data model with {"@path":"/x"}. Never write {"path":"/x"} as a binding.',
236
+ 'A prop can also be a function value that updates with the data: {"@call":"formatCurrency","args":{"value":{"@path":"/total"},"currency":"EUR"}}. Use only the functions under "functions" in the schema. Write a literal when the value never changes.',
237
+ 'formatString interpolates ${...}: {"@call":"formatString","args":{"value":"${/qty} × ${formatCurrency(value: /price, currency: \'EUR\')}"}}. Inside ${...}, a path has no quotes, a string has single quotes, and a function takes named args.',
238
+ '${...} is evaluated only in the value of formatString and in the item of series; in other strings it stays literal text. Inside formatString, ${...} does not support operators. For arithmetic use calc, with the values as named args: {"@call":"calc","args":{"expression":"seats * 29 * (annual ? 0.8 : 1)","seats":{"@path":"/seats"},"annual":{"@path":"/annual"}}}. Inside formatString: ${formatCurrency(value: calc(expression: \'seats * 29\', seats: /seats), currency: \'USD\')}. The UI then follows the user\'s input with no round trip.',
239
+ 'For a computed list (chart data, template items) use series. Its description under "functions" in the schema gives the rules and an example. Bind the "data" of a Chart or the "items" of a List to it; a template path stays a literal path.',
240
+ 'Bind a writable prop to let the user edit it: "value":{"@path":"/form/email"}. The user\'s input goes to that path.',
241
+ 'To change data, write updateDataModel with a "path" and a "value": {"version":"v1.0","updateDataModel":{"surfaceId":"plan-picker","path":"/seats","value":12}}. Always give "value".',
242
+ 'Set "value":null to delete the key at "path".',
243
+ ];
244
+
245
+ /** The last rules of every markdown guideline, after the optional groups. */
246
+ const MARKDOWN_CLOSING_RULES = [
247
+ 'The schema lists the surfaces that already exist under "surfaces". "dataModel" holds the values that the user entered: read them, and do not write those paths. "rejected" lists operations that the client dropped: send corrected operations in a new fence for that surfaceId. "status":"deleted" means the surface is gone: never use its id again. "status":"failed" means its createSurface was rejected: send a corrected createSurface with that id.',
248
+ "Never make a surface that is only prose. Write headings, paragraphs, lists of text, intros, and summaries as markdown outside the fences, also between two fences.",
249
+ "Put in a fence only what markdown cannot show: charts, tables, maps, images, badges, inputs, buttons, cards with controls.",
250
+ "Use Card only for an interactive panel (controls, a form, a configurator). Put everything else in a plain layout component.",
251
+ "Never wrap the whole reply in a fence.",
252
+ ];
253
+
254
+ /**
255
+ * Builds the markdown-transport guideline. The model writes A2UI v1.0
256
+ * operations inside ```a2ui fences between normal markdown prose. The rules
257
+ * for functions, events, and templates are left out when the manifest has
258
+ * none of them, so the guideline stays small.
259
+ *
260
+ * @param features - The optional rule groups to include. Defaults to all.
261
+ * @returns The guideline text, one rule per line.
262
+ */
263
+ export function buildGenerativeUIMarkdownGuidelines(
264
+ features: GenerativeUIGuideFeatures = ALL_GENERATIVE_UI_GUIDE_FEATURES,
265
+ ) {
266
+ const { functions, events, templates, checks } = features;
267
+ const rules = [...MARKDOWN_BASE_RULES];
268
+ if (events) {
269
+ rules.push(
270
+ 'Give an event prop an object: {"event":{"name":"<name>","userMessage":"<text>","context":{...}}} or {"functionCall":{"@call":"<function>","args":{...}}}. Never a flat {"event":"<name>"}.',
271
+ functions
272
+ ? 'Use {"functionCall": ...} to run a function in the browser when the user clicks: an app function from the schema, or openUrl: {"functionCall":{"@call":"openUrl","args":{"url":"https://example.com"}}}. You are not told about the call.'
273
+ : 'Use {"functionCall": ...} to open a URL when the user clicks: {"functionCall":{"@call":"openUrl","args":{"url":"https://example.com"}}}. You are not told about the call.',
274
+ 'Use {"event": ...} to send the interaction back to you as a user message. Put the text of that message in "userMessage": {"event":{"name":"choose","userMessage":"Show me the Team plan"}}. "userMessage" is plain text: ${...} is not interpolated in it; put values in "context".',
275
+ 'To send input values with an event, bind them in the context: "context":{"email":{"@path":"/form/email"}}.',
276
+ "A button or other event prop without an event or functionCall does nothing.",
277
+ );
278
+ }
279
+ if (checks) {
280
+ rules.push(
281
+ 'Validate an input with "checks": [{"condition":{"@call":"email","args":{"value":{"@path":"/form/email"}}},"message":"Enter a valid email"}]. The check functions are required, regex, length, numeric and email; a condition can also be a boolean {"@path"}. A failed check shows the message under the input and disables a Button that has the same checks.',
282
+ );
283
+ }
284
+ rules.push(
285
+ 'A prop typed componentId takes the id of another component, and a childList takes ids ["a","b"]: "child":"card", "children":["a","b"], "tabs":[{"title":"Specs","child":"specs"}].',
286
+ );
287
+ if (templates) {
288
+ rules.push(
289
+ 'To repeat a component for each item of a list, give a childList a template: "children":{"componentId":"row","path":"/items"}.',
290
+ 'Inside a template, paths are relative to the item ("name", not "/name").',
291
+ 'Inside a template, {"@call":"@index"} gives the position of the item, from 0. To count from 1, write {"@call":"@index","args":{"offset":1}}.',
292
+ );
293
+ }
294
+ rules.push(
295
+ "Updating a component replaces all of its props. Send every prop again.",
296
+ "To change a surface in this reply, write another fence with the same surfaceId. Do not send createSurface again. The surface changes where it already is. A surface in a target can also be changed from a later reply; a chat surface cannot, because the chat is a transcript: a later reply with the same surfaceId makes a new surface.",
297
+ "Use a new surfaceId for a different view. Never use a surfaceId again, also after the surface is deleted.",
298
+ );
299
+ if (functions && GENERATIVE_UI_AGENT_FUNCTION_CALLS) {
300
+ rules.push(
301
+ 'To run an app function now, with no click, write a callRendererFunction line in a fence: {"version":"v1.0","callRendererFunction":{"functionCallId":"<unique id>","callFunction":{"@call":"<function>","args":{...}}}}. It needs no surface.',
302
+ 'Give every callRendererFunction a new functionCallId. Call only a function from the schema with "callers": "UI or agent" or "agent only"; a function without "callers" is for the UI only. A function with "callers": "agent only" is only for callRendererFunction: do not bind an event to it.',
303
+ 'The result of a callRendererFunction comes back to you as a developer message: {"version":"v1.0","rendererFunctionResponse":{"functionCallId":"<id>","value":...}}. If the call failed, it has "error" in place of "value". Then you get a new turn.',
304
+ "Do not guess the result of a callRendererFunction. Wait for the developer message.",
305
+ );
306
+ }
307
+ rules.push(...MARKDOWN_CLOSING_RULES);
308
+ return `You can show interactive UI in your reply. Write A2UI operations inside a fenced code block tagged a2ui.
309
+
310
+ ${GENERATIVE_UI_WHEN_TO_SHOW}
311
+
312
+ RULES
313
+ ${rules.map((rule) => `- ${rule}`).join("\n")}
314
+ `;
315
+ }
316
+
317
+ /**
318
+ * The markdown-transport guideline with every rule group. A run sends
319
+ * `buildGenerativeUIMarkdownGuidelines` for its own manifest instead.
320
+ */
321
+ export const GENERATIVE_UI_MARKDOWN_GUIDELINES =
322
+ buildGenerativeUIMarkdownGuidelines();
@@ -6,5 +6,12 @@ export const COPILOT_CLOUD_PUBLIC_API_KEY_HEADER =
6
6
 
7
7
  export const DEFAULT_AGENT_ID = "default";
8
8
 
9
+ /**
10
+ * `RUN_ERROR` code the runtime sends when a run is rejected because the
11
+ * thread already has one in flight. CopilotKit core reports it as
12
+ * `agent_thread_locked`.
13
+ */
14
+ export const THREAD_ALREADY_RUNNING_ERROR_CODE = "THREAD_ALREADY_RUNNING";
15
+
9
16
  /** Phoenix channel event name used for all AG-UI events. */
10
17
  export const AG_UI_CHANNEL_EVENT = "ag-ui";
@@ -251,16 +251,23 @@ export class ArgsParser {
251
251
  }
252
252
  }
253
253
 
254
+ /**
255
+ * Extract EventWithState type from Middleware.runNextWithState return type
256
+ */
257
+ type ExtractObservableType<T> = T extends Observable<infer U> ? U : never;
258
+ type RunNextWithStateReturn = ReturnType<Middleware["runNextWithState"]>;
259
+ type EventWithState = ExtractObservableType<RunNextWithStateReturn>;
260
+
254
261
  export class OpenGenerativeUIMiddleware extends Middleware {
255
262
  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
256
- // Only the events are read, so `runNext`: `runNextWithState` copies the
257
- // messages and state on every event for a consumer that never looks.
258
- return this.processStream(this.runNext(input, next));
263
+ return this.processStream(this.runNextWithState(input, next));
259
264
  }
260
265
 
261
- private processStream(source: Observable<BaseEvent>): Observable<BaseEvent> {
266
+ private processStream(
267
+ source: Observable<EventWithState>,
268
+ ): Observable<BaseEvent> {
262
269
  return new Observable<BaseEvent>((subscriber) => {
263
- let heldRunFinished: BaseEvent | null = null;
270
+ let heldRunFinished: EventWithState | null = null;
264
271
  // Track active generateSandboxedUi tool call IDs → their streaming parser
265
272
  const activeParsers = new Map<string, ArgsParser>();
266
273
  // Hold genui tool call events until the first activity event is emitted
@@ -280,14 +287,16 @@ export class OpenGenerativeUIMiddleware extends Middleware {
280
287
  };
281
288
 
282
289
  const subscription = source.subscribe({
283
- next: (event) => {
290
+ next: (eventWithState) => {
291
+ const event = eventWithState.event;
292
+
284
293
  if (heldRunFinished) {
285
- subscriber.next(heldRunFinished);
294
+ subscriber.next(heldRunFinished.event);
286
295
  heldRunFinished = null;
287
296
  }
288
297
 
289
298
  if (event.type === EventType.RUN_FINISHED) {
290
- heldRunFinished = event;
299
+ heldRunFinished = eventWithState;
291
300
  return;
292
301
  }
293
302
 
@@ -357,7 +366,7 @@ export class OpenGenerativeUIMiddleware extends Middleware {
357
366
  heldToolCallEvents.clear();
358
367
 
359
368
  if (heldRunFinished) {
360
- subscriber.next(heldRunFinished);
369
+ subscriber.next(heldRunFinished.event);
361
370
  heldRunFinished = null;
362
371
  }
363
372
  subscriber.error(err);
@@ -369,7 +378,7 @@ export class OpenGenerativeUIMiddleware extends Middleware {
369
378
  });
370
379
 
371
380
  if (heldRunFinished) {
372
- subscriber.next(heldRunFinished);
381
+ subscriber.next(heldRunFinished.event);
373
382
  heldRunFinished = null;
374
383
  }
375
384
  activeParsers.clear();
@@ -0,0 +1,175 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { RenderUIArgsStream, extractRenderUIArgs } from "../render-ui-args";
3
+
4
+ const opA = {
5
+ version: "v1.0",
6
+ createSurface: { surfaceId: "s" },
7
+ };
8
+ const opB = {
9
+ version: "v1.0",
10
+ updateComponents: {
11
+ surfaceId: "s",
12
+ components: [
13
+ {
14
+ id: "root",
15
+ component: "Grid",
16
+ children: ["c1"],
17
+ title: 'He said "}{" ok',
18
+ },
19
+ ],
20
+ },
21
+ };
22
+ const opC = {
23
+ version: "v1.0",
24
+ updateDataModel: { surfaceId: "s", path: "/a", value: [1, { b: "]" }] },
25
+ };
26
+ /** One createSurface with the data model and the root inline. */
27
+ const inlineCreate = {
28
+ version: "v1.0",
29
+ createSurface: {
30
+ surfaceId: "plan",
31
+ dataModel: { seats: 10, plans: [{ name: "Team" }] },
32
+ components: [
33
+ {
34
+ id: "root",
35
+ component: "Column",
36
+ children: { componentId: "row", path: "/plans" },
37
+ },
38
+ { id: "row", component: "Text", text: { "@call": "@index" } },
39
+ ],
40
+ },
41
+ };
42
+ const functionCall = {
43
+ version: "v1.0",
44
+ callRendererFunction: {
45
+ functionCallId: "f1",
46
+ callFunction: { "@call": "addToCart", args: { productId: "p{1}" } },
47
+ },
48
+ };
49
+
50
+ describe("extractRenderUIArgs", () => {
51
+ it("extracts target and every complete operation from a full payload", () => {
52
+ const text = JSON.stringify({
53
+ target: "recommendations",
54
+ operations: [opA, opB, opC],
55
+ });
56
+ expect(extractRenderUIArgs(text)).toEqual({
57
+ target: "recommendations",
58
+ operations: [opA, opB, opC],
59
+ });
60
+ });
61
+
62
+ it("does not return an operation until its closing brace has arrived", () => {
63
+ const text = JSON.stringify({ target: "chat", operations: [opA, opB] });
64
+ const cut = text.indexOf("updateComponents") + 5;
65
+ expect(extractRenderUIArgs(text.slice(0, cut)).operations).toEqual([opA]);
66
+ });
67
+
68
+ it("finds operations that precede the target key", () => {
69
+ const text = JSON.stringify({ operations: [opA], target: "chat" });
70
+ expect(extractRenderUIArgs(text)).toEqual({
71
+ target: "chat",
72
+ operations: [opA],
73
+ });
74
+ });
75
+
76
+ it("returns null for a balanced element that is not valid JSON", () => {
77
+ const text =
78
+ '{"target":"chat","operations":[{"version":"v1.0", bad},' +
79
+ JSON.stringify(opA) +
80
+ "]}";
81
+ expect(extractRenderUIArgs(text).operations).toEqual([null, opA]);
82
+ });
83
+
84
+ it("flags an operation that was opened but never closed", () => {
85
+ const text = JSON.stringify({ target: "chat", operations: [opA, opB] });
86
+ const cut = text.indexOf("updateComponents") + 5;
87
+ expect(extractRenderUIArgs(text.slice(0, cut)).incompleteOperation).toBe(
88
+ true,
89
+ );
90
+ expect(extractRenderUIArgs(text).incompleteOperation).toBeUndefined();
91
+ });
92
+
93
+ it("ignores string values that look like keys", () => {
94
+ const text = JSON.stringify({
95
+ note: "target",
96
+ target: "chat",
97
+ operations: [],
98
+ });
99
+ expect(extractRenderUIArgs(text).target).toBe("chat");
100
+ });
101
+ });
102
+
103
+ describe("RenderUIArgsStream", () => {
104
+ it("emits each operation exactly once when streamed one character at a time", () => {
105
+ const text = JSON.stringify({
106
+ target: "recommendations",
107
+ operations: [opA, opB, opC],
108
+ });
109
+ const stream = new RenderUIArgsStream();
110
+ const emitted: unknown[] = [];
111
+ let target: string | undefined;
112
+ for (const ch of text) {
113
+ const update = stream.push(ch);
114
+ target = update.target ?? target;
115
+ emitted.push(...update.newOperations);
116
+ }
117
+ expect(target).toBe("recommendations");
118
+ expect(emitted).toEqual([opA, opB, opC]);
119
+ });
120
+
121
+ it("emits an inline createSurface and a callRendererFunction once each", () => {
122
+ const text = JSON.stringify({
123
+ target: "chat",
124
+ operations: [inlineCreate, functionCall],
125
+ });
126
+ const stream = new RenderUIArgsStream();
127
+ const emitted: unknown[] = [];
128
+ for (const ch of text) emitted.push(...stream.push(ch).newOperations);
129
+ expect(emitted).toEqual([inlineCreate, functionCall]);
130
+ });
131
+
132
+ it("holds back an inline createSurface until its components array closes", () => {
133
+ const text = JSON.stringify({ target: "chat", operations: [inlineCreate] });
134
+ const cut = text.indexOf('"row","component"');
135
+ const stream = new RenderUIArgsStream();
136
+ expect(stream.push(text.slice(0, cut)).newOperations).toEqual([]);
137
+ expect(stream.hasIncompleteOperation).toBe(true);
138
+ expect(stream.push(text.slice(cut)).newOperations).toEqual([inlineCreate]);
139
+ });
140
+
141
+ it("keeps the parser state across deltas that split strings, escapes and braces", () => {
142
+ const tricky = {
143
+ version: "v1.0",
144
+ updateDataModel: { surfaceId: "s", path: "/q", value: 'a "}{" \\ ]' },
145
+ };
146
+ const text = JSON.stringify({
147
+ operations: [opA, tricky, opB],
148
+ target: 'chat "x"',
149
+ });
150
+ for (const size of [1, 2, 3, 7]) {
151
+ const stream = new RenderUIArgsStream();
152
+ const emitted: unknown[] = [];
153
+ let target: string | undefined;
154
+ for (let i = 0; i < text.length; i += size) {
155
+ const step = stream.push(text.slice(i, i + size));
156
+ emitted.push(...step.newOperations);
157
+ target = step.target;
158
+ }
159
+ expect(emitted).toEqual([opA, tricky, opB]);
160
+ expect(target).toBe('chat "x"');
161
+ expect(stream.hasIncompleteOperation).toBe(false);
162
+ }
163
+ });
164
+
165
+ it("exposes the accumulated text and whether it ends mid-operation", () => {
166
+ const text = JSON.stringify({ target: "chat", operations: [opA, opB] });
167
+ const cut = text.indexOf("updateComponents");
168
+ const stream = new RenderUIArgsStream();
169
+ stream.push(text.slice(0, cut));
170
+ expect(stream.text).toBe(text.slice(0, cut));
171
+ expect(stream.hasIncompleteOperation).toBe(true);
172
+ stream.push(text.slice(cut));
173
+ expect(stream.hasIncompleteOperation).toBe(false);
174
+ });
175
+ });