@zeyos/zx 5.6.0 → 5.7.1

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 (227) hide show
  1. package/CHANGELOG.md +188 -0
  2. package/README.md +73 -7
  3. package/bin/zx-css.js +328 -0
  4. package/dist/types/components/account-menu/account-menu.d.ts +4 -2
  5. package/dist/types/components/activity-list/activity-list.d.ts +14 -8
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +142 -14
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
  9. package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
  10. package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
  11. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  12. package/dist/types/components/calendar/calendar.d.ts +12 -4
  13. package/dist/types/components/chart/chart.d.ts +25 -13
  14. package/dist/types/components/checklist/checklist.d.ts +29 -0
  15. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  16. package/dist/types/components/composer/composer.d.ts +206 -4
  17. package/dist/types/components/composer/queue.d.ts +76 -0
  18. package/dist/types/components/copy/copy-button.d.ts +6 -4
  19. package/dist/types/components/copy/copy-input.d.ts +10 -6
  20. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  21. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  22. package/dist/types/components/dialog/dialog.d.ts +2 -2
  23. package/dist/types/components/dock/dock.d.ts +12 -3
  24. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  25. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  26. package/dist/types/components/file-item/file-item.d.ts +3 -2
  27. package/dist/types/components/file-list/file-list.d.ts +14 -8
  28. package/dist/types/components/filter/filter-model.d.ts +31 -1
  29. package/dist/types/components/filter/filter.d.ts +20 -2
  30. package/dist/types/components/finder/finder.d.ts +14 -6
  31. package/dist/types/components/flag/flag.d.ts +99 -0
  32. package/dist/types/components/grid/grid.d.ts +1 -1
  33. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  34. package/dist/types/components/launcher/launcher.d.ts +2 -0
  35. package/dist/types/components/modal/modal.d.ts +34 -8
  36. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  37. package/dist/types/components/number-field/number-field.d.ts +41 -7
  38. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  39. package/dist/types/components/prose/prose.d.ts +9 -6
  40. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  41. package/dist/types/components/questionnaire/items.d.ts +52 -30
  42. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  43. package/dist/types/components/rating/rating.d.ts +5 -3
  44. package/dist/types/components/select/country.d.ts +106 -0
  45. package/dist/types/components/select/field-adapter.d.ts +2 -1
  46. package/dist/types/components/select/locale.d.ts +102 -0
  47. package/dist/types/components/select/select.d.ts +41 -2
  48. package/dist/types/components/sheet/sheet.d.ts +2 -2
  49. package/dist/types/components/slider/slider.d.ts +1 -0
  50. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  51. package/dist/types/components/source-list/source-list.d.ts +7 -5
  52. package/dist/types/components/split-view/split-view.d.ts +5 -3
  53. package/dist/types/components/surface/catalog.d.ts +260 -0
  54. package/dist/types/components/surface/elicit.d.ts +81 -0
  55. package/dist/types/components/surface/mcp.d.ts +165 -0
  56. package/dist/types/components/surface/schema.d.ts +314 -0
  57. package/dist/types/components/surface/stream.d.ts +118 -0
  58. package/dist/types/components/surface/surface.d.ts +718 -0
  59. package/dist/types/components/surface/text.d.ts +277 -0
  60. package/dist/types/components/surface/validate.d.ts +339 -0
  61. package/dist/types/components/table/table.d.ts +55 -3
  62. package/dist/types/components/table/window.d.ts +203 -0
  63. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  64. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  65. package/dist/types/components/tree/tree.d.ts +20 -13
  66. package/dist/types/core/component.d.ts +10 -0
  67. package/dist/types/core/date.d.ts +8 -1
  68. package/dist/types/core/dom.d.ts +15 -0
  69. package/dist/types/core/http.d.ts +10 -0
  70. package/dist/types/core/i18n.d.ts +38 -0
  71. package/dist/types/core/messages.d.ts +344 -1
  72. package/dist/types/core/storage.d.ts +7 -2
  73. package/dist/types/elements/define.d.ts +21 -46
  74. package/dist/types/elements/definitions.d.ts +147 -0
  75. package/dist/types/elements/kit.d.ts +7 -0
  76. package/dist/types/elements/reflect.d.ts +6 -3
  77. package/dist/types/index.d.ts +10 -1
  78. package/dist/types/internal/date-locale.d.ts +7 -0
  79. package/dist/types/internal/json-patch.d.ts +146 -0
  80. package/dist/types/locales/de.d.ts +13 -0
  81. package/dist/types/locales/en.d.ts +2 -0
  82. package/dist/types/locales/index.d.ts +823 -0
  83. package/dist/types/zeyos/view.d.ts +8 -1
  84. package/dist/zx-zeyos.esm.js +16852 -15131
  85. package/dist/zx-zeyos.esm.min.js +5 -5
  86. package/dist/zx.core.css +1276 -0
  87. package/dist/zx.core.min.css +1 -0
  88. package/dist/zx.css +520 -143
  89. package/dist/zx.esm.js +40940 -29684
  90. package/dist/zx.esm.min.js +36 -23
  91. package/dist/zx.global.js +40940 -29684
  92. package/dist/zx.global.min.js +36 -23
  93. package/dist/zx.layered.css +17315 -0
  94. package/dist/zx.layered.min.css +1 -0
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +12501 -0
  97. package/docs/agent-surfaces.md +340 -0
  98. package/docs/api.json +909 -137
  99. package/docs/llms.md +1046 -80
  100. package/docs/llms.txt +30 -9
  101. package/package.json +29 -6
  102. package/src/components/account-menu/account-menu.js +6 -3
  103. package/src/components/activity-item/activity-item.js +2 -1
  104. package/src/components/activity-list/activity-list.js +16 -10
  105. package/src/components/agent-thread/ag-ui.js +1439 -0
  106. package/src/components/agent-thread/agent-thread.js +359 -54
  107. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  108. package/src/components/app-sidebar/app-sidebar.js +18 -8
  109. package/src/components/approval-card/approval-card.js +3 -2
  110. package/src/components/block-view/block-view.js +7 -6
  111. package/src/components/breadcrumb/breadcrumb.js +8 -5
  112. package/src/components/button/button.css +24 -11
  113. package/src/components/calendar/calendar-model.js +8 -2
  114. package/src/components/calendar/calendar.js +53 -18
  115. package/src/components/chart/chart.js +54 -23
  116. package/src/components/checklist/checklist.css +9 -1
  117. package/src/components/checklist/checklist.js +59 -3
  118. package/src/components/checklist/field-adapter.js +2 -11
  119. package/src/components/code-editor/code-editor.js +45 -8
  120. package/src/components/code-editor/field-adapter.js +1 -1
  121. package/src/components/composer/composer.css +80 -1
  122. package/src/components/composer/composer.js +390 -16
  123. package/src/components/composer/queue.js +78 -0
  124. package/src/components/context-menu/context-menu.js +12 -1
  125. package/src/components/copy/copy-button.js +9 -7
  126. package/src/components/copy/copy-input.js +10 -6
  127. package/src/components/date-picker/date-picker.js +2 -1
  128. package/src/components/date-picker/date-range-picker.js +8 -7
  129. package/src/components/datebox/date-range-box.js +3 -9
  130. package/src/components/datebox/datebox.js +18 -21
  131. package/src/components/datebox/placeholder.js +18 -0
  132. package/src/components/dialog/dialog.js +4 -5
  133. package/src/components/dock/dock.js +34 -13
  134. package/src/components/entity-ref/entity-ref.js +16 -5
  135. package/src/components/field-upload/field-upload.js +81 -38
  136. package/src/components/file-item/file-item.js +70 -40
  137. package/src/components/file-list/file-list.js +15 -9
  138. package/src/components/filter/filter-model.js +46 -8
  139. package/src/components/filter/filter.css +3 -3
  140. package/src/components/filter/filter.js +29 -10
  141. package/src/components/filter-panel/filter-panel.js +13 -5
  142. package/src/components/finder/finder.js +50 -26
  143. package/src/components/flag/flag.css +40 -0
  144. package/src/components/flag/flag.js +177 -0
  145. package/src/components/form/form.js +1 -1
  146. package/src/components/grid/grid.js +22 -8
  147. package/src/components/kanban-view/kanban-view.js +51 -81
  148. package/src/components/launcher/launcher.js +17 -2
  149. package/src/components/list-toolbar/list-toolbar.js +2 -1
  150. package/src/components/master-panel/master-panel.js +1 -1
  151. package/src/components/menu-button/menu-button.js +4 -0
  152. package/src/components/message/message.js +3 -0
  153. package/src/components/modal/modal.js +62 -8
  154. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  155. package/src/components/navigation-bar/navigation-bar.js +3 -3
  156. package/src/components/number-field/number-field.js +98 -29
  157. package/src/components/prompt-starters/prompt-starters.css +91 -0
  158. package/src/components/prompt-starters/prompt-starters.js +206 -0
  159. package/src/components/prose/prose.js +14 -10
  160. package/src/components/questionnaire/conditions.js +666 -0
  161. package/src/components/questionnaire/items.js +150 -41
  162. package/src/components/questionnaire/questionnaire.js +126 -32
  163. package/src/components/rating/rating.js +5 -4
  164. package/src/components/run-status/run-status.js +2 -2
  165. package/src/components/select/country.js +136 -0
  166. package/src/components/select/field-adapter.js +7 -2
  167. package/src/components/select/locale.js +219 -0
  168. package/src/components/select/select.css +20 -22
  169. package/src/components/select/select.js +94 -12
  170. package/src/components/sheet/sheet-stack.js +10 -1
  171. package/src/components/sheet/sheet.js +12 -5
  172. package/src/components/slider/slider.js +7 -2
  173. package/src/components/sort-control/sort-control.js +15 -5
  174. package/src/components/source-list/source-list.js +7 -4
  175. package/src/components/split-view/split-view.js +5 -3
  176. package/src/components/surface/catalog.js +1334 -0
  177. package/src/components/surface/elicit.js +107 -0
  178. package/src/components/surface/mcp.js +243 -0
  179. package/src/components/surface/schema.js +644 -0
  180. package/src/components/surface/stream.js +245 -0
  181. package/src/components/surface/surface.css +308 -0
  182. package/src/components/surface/surface.js +2291 -0
  183. package/src/components/surface/text.js +513 -0
  184. package/src/components/surface/validate.js +2218 -0
  185. package/src/components/tabbox/tabbox.js +9 -0
  186. package/src/components/table/table.css +63 -3
  187. package/src/components/table/table.js +167 -28
  188. package/src/components/table/window.js +317 -0
  189. package/src/components/toolbar/toolbar.js +12 -7
  190. package/src/components/tooltip/tooltip.css +2 -3
  191. package/src/components/tooltip/tooltip.js +32 -5
  192. package/src/components/tree/tree.js +53 -23
  193. package/src/core/component.js +25 -1
  194. package/src/core/date.js +62 -16
  195. package/src/core/dom.js +67 -4
  196. package/src/core/format.js +15 -13
  197. package/src/core/http.js +29 -20
  198. package/src/core/i18n.js +83 -10
  199. package/src/core/icons.js +13 -2
  200. package/src/core/keyboard.js +79 -8
  201. package/src/core/messages.js +376 -2
  202. package/src/core/overlay-host.js +1 -0
  203. package/src/core/position.js +3 -2
  204. package/src/core/storage.js +59 -6
  205. package/src/elements/define.js +178 -130
  206. package/src/elements/definitions.js +229 -0
  207. package/src/elements/kit.js +444 -0
  208. package/src/elements/reflect.js +8 -3
  209. package/src/index.js +10 -1
  210. package/src/internal/date-locale.js +11 -0
  211. package/src/internal/json-patch.js +405 -0
  212. package/src/locales/de.js +911 -0
  213. package/src/locales/en.js +2 -0
  214. package/src/locales/index.js +7 -0
  215. package/src/zeyos/calendar.js +2 -1
  216. package/src/zeyos/form.js +2 -1
  217. package/src/zeyos/launcher.js +7 -6
  218. package/src/zeyos/module-bar.js +2 -1
  219. package/src/zeyos/schema.js +37 -23
  220. package/src/zeyos/select.js +4 -3
  221. package/src/zeyos/table.js +2 -13
  222. package/src/zeyos/view.js +57 -17
  223. package/styles/core.css +11 -0
  224. package/styles/tokens/semantic.css +1 -0
  225. package/styles/zeyos.css +2 -0
  226. package/styles/zx.css +4 -8
  227. package/styles/zx.layered.css +1 -0
@@ -0,0 +1,340 @@
1
+ import { inlineSplitter } from '../surface/stream.js';
2
+ export type AgentThread = import('./agent-thread.js').AgentThread;
3
+ export type ThreadItem = import('../../internal/agent-model.js').ThreadItem;
4
+ export type TraceStep = import('../../internal/agent-model.js').TraceStep;
5
+ export type RunState = import('../../internal/agent-model.js').RunState;
6
+ export type Author = import('../../internal/agent-model.js').Author;
7
+ export type SurfaceCatalog = import('../surface/catalog.js').SurfaceCatalog;
8
+ export type SurfaceError = import('../surface/validate.js').SurfaceError;
9
+ export type SurfaceReply = import('../surface/text.js').SurfaceReply;
10
+ /** @typedef {import('./agent-thread.js').AgentThread} AgentThread */
11
+ /** @typedef {import('../../internal/agent-model.js').ThreadItem} ThreadItem */
12
+ /** @typedef {import('../../internal/agent-model.js').TraceStep} TraceStep */
13
+ /** @typedef {import('../../internal/agent-model.js').RunState} RunState */
14
+ /** @typedef {import('../../internal/agent-model.js').Author} Author */
15
+ /** @typedef {import('../surface/catalog.js').SurfaceCatalog} SurfaceCatalog */
16
+ /** @typedef {import('../surface/validate.js').SurfaceError} SurfaceError */
17
+ /** @typedef {import('../surface/text.js').SurfaceReply} SurfaceReply */
18
+ /** The AG-UI protocol version the adapter implements. */
19
+ export declare const AG_UI_VERSION = "1.0";
20
+ export type AgUiEvent = {
21
+ type: string;
22
+ timestamp?: number;
23
+ [key: string]: unknown;
24
+ };
25
+ export type ToolCall = {
26
+ /**
27
+ * The call's `toolCallId`.
28
+ */
29
+ id: string;
30
+ /**
31
+ * The tool's name.
32
+ */
33
+ name: string;
34
+ /**
35
+ * The parsed arguments once they are complete; `null` before, and when
36
+ * they are not JSON.
37
+ */
38
+ args: unknown;
39
+ /**
40
+ * The arguments as they arrived.
41
+ */
42
+ argsText: string;
43
+ /**
44
+ * The `content` of the call's result event, unchanged (a string, or a
45
+ * list of content parts); for a surface tool, what `ontoolresult` received.
46
+ */
47
+ result?: unknown;
48
+ /**
49
+ * Why the call failed.
50
+ */
51
+ error?: string;
52
+ /**
53
+ * `queued` while the arguments arrive, `waiting` for an approval or an
54
+ * answer, `running` until the result, then `done`, `failed`, `skipped` when the approval was
55
+ * rejected, or `stopped` when the run ended without it.
56
+ */
57
+ status: RunState;
58
+ };
59
+ export type ToolTileRenderer = (call: ToolCall) => ThreadItem | null;
60
+ export type AgUiProblem = {
61
+ /**
62
+ * What went wrong.
63
+ */
64
+ code: string;
65
+ /**
66
+ * What went wrong, in English.
67
+ */
68
+ message: string;
69
+ /**
70
+ * The event it concerns.
71
+ */
72
+ event?: AgUiEvent;
73
+ /**
74
+ * The error thrown, for `renderer`, `approval-check` and `state`.
75
+ */
76
+ cause?: unknown;
77
+ /**
78
+ * The surface's problems, for a surface tool's document.
79
+ */
80
+ errors?: SurfaceError[];
81
+ };
82
+ export type AgUiOptions = {
83
+ /**
84
+ * A
85
+ * RunStatus the run's lifecycle drives: `running` when it starts, `done`, `waiting` (an
86
+ * interrupt, or calls of the run still without a result), `stopped` (cancelled) or `failed`.
87
+ */
88
+ runStatus?: {
89
+ update: (values: Record<string, unknown>) => unknown;
90
+ } | null;
91
+ /**
92
+ * The thread's authors. A text message whose
93
+ * `name` is one of their keys is written by that author; every other item by `agent`.
94
+ */
95
+ authors?: Record<string, Author>;
96
+ /**
97
+ * The author key of the agent's output; the thread's first
98
+ * agent when null.
99
+ */
100
+ agent?: string | null;
101
+ /**
102
+ * Asked once a call's
103
+ * arguments are complete: any truthy answer holds the call at an ApprovalCard until the person
104
+ * decides. Nothing is approved by default: a check that throws holds the call too, and so does a
105
+ * Promise, whatever it resolves to, so an asynchronous check never lets a call through. Not asked
106
+ * for surface tools, whose surface is the person's say.
107
+ */
108
+ requiresApproval?: ((call: ToolCall) => unknown) | null;
109
+ /**
110
+ * What
111
+ * the person decided, for the application to send back to the agent. An approval answers
112
+ * `{approved: true}` or `{approved: false, reason?}`; a surface tool its reply, with `errors`
113
+ * when the surface had any; a `show` surface with no actions answers at once with
114
+ * `{shown: true, surface, errors?}` and stays on screen; a surface tool whose arguments are not a
115
+ * surface answers at once with `{error: 'invalid-arguments'}`, and one the thread cannot draw
116
+ * with `{error: 'surface-unavailable'}`. It fires once for a call. In AG-UI 1.0 the application turns it into a `resume`
117
+ * entry (`{interruptId, status: 'resolved', payload}`) when the run ended with an interrupt for
118
+ * the call, or into a tool message (`{role: 'tool', toolCallId, content}`) when it ended with
119
+ * the call among its `pendingToolCallIds`; either goes in the next run's input.
120
+ */
121
+ ontoolresult?: ((id: string, result: Record<string, unknown>) => void) | null;
122
+ /**
123
+ * The application state after each
124
+ * snapshot or delta.
125
+ */
126
+ onstate?: ((state: unknown) => void) | null;
127
+ /**
128
+ * Every event the adapter does not
129
+ * draw: unknown types, and known ones without a place in the thread (steps, message snapshots,
130
+ * activities, raw and encrypted values, subagents, custom events of another name).
131
+ */
132
+ onunknown?: ((event: AgUiEvent) => void) | null;
133
+ /**
134
+ * Problems found in the stream.
135
+ */
136
+ onerror?: ((problem: AgUiProblem) => void) | null;
137
+ /**
138
+ * Show the reasoning text in its trace step. Without
139
+ * it, reasoning is one collapsed "Thought for 12 s" step.
140
+ */
141
+ showReasoning?: boolean;
142
+ /**
143
+ * The name of the custom event that carries
144
+ * surface operations: its `value` is one operation, or `{ops: [...], token?}`. The token of the
145
+ * event that opens a surface is kept; later ones are ignored. Give these surfaces ids a model
146
+ * cannot predict: a surface belongs to the source that opened it, and a `begin` for an id the
147
+ * model already took is refused.
148
+ */
149
+ surfaceEvent?: string;
150
+ /**
151
+ * The tools whose calls the application
152
+ * draws itself, by name. The renderer is called at each status change of the call, never while
153
+ * its arguments stream; its first item that is not `null` is inserted after the call's step,
154
+ * later ones replace it where it stands, and the step links to it.
155
+ */
156
+ tools?: Record<string, ToolTileRenderer>;
157
+ /**
158
+ * The tools whose arguments are a
159
+ * whole surface document. The surface is drawn once the arguments are complete, and its reply is
160
+ * the call's result.
161
+ */
162
+ surfaceTools?: string[];
163
+ /**
164
+ * Split surface fences out of answer text.
165
+ */
166
+ inlineSurfaces?: boolean;
167
+ /**
168
+ * A narrowed catalog, given to every surface the adapter
169
+ * creates.
170
+ */
171
+ catalog?: SurfaceCatalog;
172
+ };
173
+ export type AgUiConnection = {
174
+ /**
175
+ * Takes the next event, in stream order.
176
+ */
177
+ handle: (event: AgUiEvent) => void;
178
+ /**
179
+ * The application state as it stands: a copy of the last
180
+ * snapshot with every delta since applied, `null` before the first.
181
+ */
182
+ state: () => unknown;
183
+ /**
184
+ * Ends the connection without leaving anyone waiting: a run still
185
+ * open is closed as stopped, every unanswered surface-tool surface is cancelled (its reply, with
186
+ * `reason: 'stopped'`, still reaches `ontoolresult`), every undecided approval card expires, and
187
+ * then the thread is no longer listened to. Nothing of this is reported through `onerror`. Later
188
+ * events are ignored; the items stay.
189
+ */
190
+ destroy: () => void;
191
+ };
192
+ export type Run = {
193
+ id: string;
194
+ /**
195
+ * The trace its steps go into now.
196
+ */
197
+ traceId: string | null;
198
+ traces: number;
199
+ errors: number;
200
+ /**
201
+ * Surface items created in the run.
202
+ */
203
+ surfaces: Set<string>;
204
+ /**
205
+ * Surfaces an unterminated fence left open, already reported.
206
+ */
207
+ cancelAtEnd: Set<string>;
208
+ };
209
+ export type Message = {
210
+ id: string;
211
+ run: Run;
212
+ open: boolean;
213
+ /**
214
+ * A message of a role the thread does not draw.
215
+ */
216
+ ignored: boolean;
217
+ author: string | null;
218
+ /**
219
+ * Its answer items: the message id, then `<id>#2`, `<id>#3`…
220
+ */
221
+ segments: string[];
222
+ /**
223
+ * Segments that received text.
224
+ */
225
+ written: Set<string>;
226
+ /**
227
+ * A fence's lines came since the last prose.
228
+ */
229
+ afterFence: boolean;
230
+ /**
231
+ * Surfaces its fences began and did not end.
232
+ */
233
+ pending: Set<string>;
234
+ /**
235
+ * Surfaces its fences began.
236
+ */
237
+ surfaces: number;
238
+ splitter: ReturnType<typeof inlineSplitter> | null;
239
+ };
240
+ export type Call = {
241
+ call: ToolCall;
242
+ kind: 'step' | 'tile' | 'surface';
243
+ run: Run;
244
+ traceId: string;
245
+ /**
246
+ * Its arguments are still arriving.
247
+ */
248
+ open: boolean;
249
+ startedAt: {
250
+ source: boolean;
251
+ value: number;
252
+ };
253
+ gated: boolean;
254
+ decided: boolean;
255
+ tileId: string | null;
256
+ placeholder: string | null;
257
+ surfaceId: string | null;
258
+ /**
259
+ * The items drawn for the call — its approval, tile, stand-in or
260
+ * surface — in thread order.
261
+ */
262
+ items: string[];
263
+ };
264
+ /**
265
+ * @typedef {Object} Run
266
+ * @property {string} id
267
+ * @property {string|null} traceId The trace its steps go into now.
268
+ * @property {number} traces
269
+ * @property {number} errors
270
+ * @property {Set<string>} surfaces Surface items created in the run.
271
+ * @property {Set<string>} cancelAtEnd Surfaces an unterminated fence left open, already reported.
272
+ */
273
+ /**
274
+ * @typedef {Object} Message
275
+ * @property {string} id
276
+ * @property {Run} run
277
+ * @property {boolean} open
278
+ * @property {boolean} ignored A message of a role the thread does not draw.
279
+ * @property {string|null} author
280
+ * @property {string[]} segments Its answer items: the message id, then `<id>#2`, `<id>#3`…
281
+ * @property {Set<string>} written Segments that received text.
282
+ * @property {boolean} afterFence A fence's lines came since the last prose.
283
+ * @property {Set<string>} pending Surfaces its fences began and did not end.
284
+ * @property {number} surfaces Surfaces its fences began.
285
+ * @property {ReturnType<typeof inlineSplitter>|null} splitter
286
+ */
287
+ /**
288
+ * @typedef {Object} Call
289
+ * @property {ToolCall} call
290
+ * @property {'step'|'tile'|'surface'} kind
291
+ * @property {Run} run
292
+ * @property {string} traceId
293
+ * @property {boolean} open Its arguments are still arriving.
294
+ * @property {{source:boolean, value:number}} startedAt
295
+ * @property {boolean} gated
296
+ * @property {boolean} decided
297
+ * @property {string|null} tileId
298
+ * @property {string|null} placeholder
299
+ * @property {string|null} surfaceId
300
+ * @property {string[]} items The items drawn for the call — its approval, tile, stand-in or
301
+ * surface — in thread order.
302
+ */
303
+ /**
304
+ * Connects an AG-UI 1.0 event stream to an AgentThread.
305
+ *
306
+ * - Run start, finish and error drive `runStatus`; an error also adds a `notice`. An error outside
307
+ * an open run closes nothing: an approval or a surface still waiting for a person stays open.
308
+ * - A text message is an `answer` streamed with `appendText()`; with `inlineSurfaces`, its
309
+ * surface fences become surfaces after the prose before them, and the prose after a fence
310
+ * continues in the answer `<messageId>#2` (then `#3`…), by the same author.
311
+ * - A tool call is a trace step: its arguments show once complete, its result fills it. A call in
312
+ * `tools` is also the application's tile `tool:<toolCallId>`; a call in `surfaceTools` is an
313
+ * `ask` step and a surface, a Skeleton while its arguments arrive.
314
+ * - Calls `requiresApproval` holds wait at an ApprovalCard (`approval:<toolCallId>`). AG-UI 1.0
315
+ * asks for approval by ending the run with an `interrupt` outcome, or with the call among the
316
+ * `pendingToolCallIds` of a frontend tool; either way the decision reaches the application
317
+ * through `ontoolresult` for its next run, and a later run's result for the call fills the step.
318
+ * A `tool_call` interrupt for a call `requiresApproval` let through gates it too; the
319
+ * application keeps each `interrupt.id` from the event for its `resume` entry. Every other
320
+ * interrupt is the application's: the event goes to `onunknown`. A result that arrives before
321
+ * the decision is drawn as it is, the card expires, and no decision is sent for that call; a
322
+ * surface still waiting is cancelled the same way.
323
+ * - A message id is the answer's item id. A start for a closed message or call reopens it, in this
324
+ * run or a later one, and its content continues: a reopened call is asked about again once its
325
+ * arguments are complete. A start for an id still open, or for a call already decided or
326
+ * answered, is ignored and reported: `ontoolresult` fires once for a call, and a receipt stays.
327
+ * - A surface is the thread item `surface:<runId>/<surface>`, so a model reusing `s1` in every
328
+ * run gets a new surface each run. Its token is the application's for a custom event, the tool
329
+ * call id for a surface tool, and the run id for an inline surface.
330
+ * - A state snapshot and its deltas keep the application state, reported through `onstate`.
331
+ * - Reasoning is one collapsed "Thought for N s" step, its text shown only with `showReasoning`.
332
+ * - `*_CHUNK` events are expanded into their start, content and end events.
333
+ * - Out of order: content, arguments or an end for something never started is dropped, not
334
+ * drawn; a second start for an open id is ignored. Both are reported through `onerror`.
335
+ *
336
+ * @param {AgentThread} thread The thread to draw in.
337
+ * @param {AgUiOptions} [options]
338
+ * @returns {AgUiConnection}
339
+ */
340
+ export declare function connectAgUi(thread: AgentThread, options?: AgUiOptions): AgUiConnection;
@@ -3,12 +3,54 @@ import { ApprovalCard } from '../approval-card/approval-card.js';
3
3
  import { BlockView } from '../block-view/block-view.js';
4
4
  import { RunTrace } from '../run-trace/run-trace.js';
5
5
  import { SourceList } from '../source-list/source-list.js';
6
+ import { Surface } from '../surface/surface.js';
6
7
  export type ThreadItem = import('../../internal/agent-model.js').ThreadItem;
7
8
  export type Author = import('../../internal/agent-model.js').Author;
8
9
  export type Source = import('../../internal/agent-model.js').Source;
9
10
  export type Block = import('../../internal/agent-model.js').Block;
10
11
  export type EmptyStateOptions = import('../empty-state/empty-state.js').EmptyStateOptions;
11
12
  export type AnswerAction = 'copy' | 'regenerate' | 'branch' | 'rate';
13
+ export type SurfaceOptions = import('../surface/surface.js').SurfaceOptions;
14
+ export type SurfaceReply = import('../surface/text.js').SurfaceReply;
15
+ export type PlaceholderItem = {
16
+ id: string;
17
+ type: 'zx-placeholder';
18
+ at?: string;
19
+ author?: string;
20
+ /**
21
+ * Skeleton lines.
22
+ */
23
+ lines?: number;
24
+ };
25
+ export type UpsertOptions = {
26
+ /**
27
+ * The id of the item to insert the new item right after;
28
+ * the end of the thread when null or unknown. An item already in the thread stays where it is.
29
+ */
30
+ after?: string | null;
31
+ };
32
+ export type SurfaceItem = {
33
+ id: string;
34
+ type: 'surface';
35
+ at?: string;
36
+ author?: string;
37
+ /**
38
+ * The whole surface.
39
+ */
40
+ document?: import('../surface/validate.js').SurfaceDocument | null;
41
+ /**
42
+ * The application's token, copied into the reply.
43
+ */
44
+ token?: string | null;
45
+ /**
46
+ * A narrowed catalog.
47
+ */
48
+ catalog?: import('../surface/catalog.js').SurfaceCatalog;
49
+ /**
50
+ * The reply it gave; the surface is drawn as its receipt.
51
+ */
52
+ reply?: SurfaceReply | null;
53
+ };
12
54
  export type ThreadRenderContext = {
13
55
  /**
14
56
  * The thread drawing the item.
@@ -101,6 +143,12 @@ export type AgentThreadOptions = {
101
143
  * Locale for times.
102
144
  */
103
145
  locale?: string;
146
+ /**
147
+ * Options
148
+ * handed to every Surface the thread draws: the application's `policy`, `resolve`, `chartAdapter`
149
+ * and `msg`. Its authors, heading level and locale are the thread's unless given here.
150
+ */
151
+ surfaceOptions?: Omit<SurfaceOptions, 'document' | 'token' | 'catalog' | 'reply'>;
104
152
  /**
105
153
  * Localized messages.
106
154
  */
@@ -113,6 +161,13 @@ export type AgentThreadOptions = {
113
161
  action: string;
114
162
  value?: unknown;
115
163
  }>) => void;
164
+ /**
165
+ * Surface reply listener.
166
+ */
167
+ onreply?: (event: CustomEvent<{
168
+ item: ThreadItem;
169
+ reply: SurfaceReply;
170
+ }>) => void;
116
171
  /**
117
172
  * Approval listener.
118
173
  */
@@ -192,6 +247,10 @@ export type ThreadEntry = {
192
247
  * An approval.
193
248
  */
194
249
  card: ApprovalCard | null;
250
+ /**
251
+ * A surface.
252
+ */
253
+ surface?: Surface | null;
195
254
  };
196
255
  /**
197
256
  * A conversation with one or more agents: the person's messages, the agents' answers as they
@@ -212,6 +271,7 @@ export type ThreadEntry = {
212
271
  * @fires AgentThread#artifact
213
272
  * @fires AgentThread#reveal
214
273
  * @fires AgentThread#open
274
+ * @fires AgentThread#reply
215
275
  * @extends {Component<AgentThreadOptions>}
216
276
  */
217
277
  export declare class AgentThread extends Component<AgentThreadOptions> {
@@ -223,8 +283,12 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
223
283
  /** @type {string[]} */
224
284
  _order: string[];
225
285
  _announceTimer: number;
286
+ _askingPerson: boolean;
226
287
  /** @type {Element|null} */
227
288
  _scrollHost: Element | null;
289
+ /** @type {EventTarget|null} */
290
+ _scrollTarget: EventTarget | null;
291
+ _onScroll: () => void;
228
292
  /** @type {string|null} */
229
293
  _latestAnswer: string | null;
230
294
  /** @type {Map<string, {expanded?: boolean|null, controls?: string|null}>} Artifact open states, for answers drawn later. */
@@ -232,6 +296,8 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
232
296
  expanded?: boolean | null;
233
297
  controls?: string | null;
234
298
  }>;
299
+ /** @type {WeakSet<Surface>} Surfaces answered elsewhere, whose going is no reply. */
300
+ _answeredElsewhere: WeakSet<Surface>;
235
301
  _feed: HTMLElement;
236
302
  _empty: HTMLElement;
237
303
  _latestButton: HTMLButtonElement;
@@ -241,15 +307,17 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
241
307
  /** @type {Readonly<AgentThreadOptions>} */
242
308
  static defaults: Readonly<AgentThreadOptions>;
243
309
  /**
244
- * Registers how items of another type are drawn — an application's own, or a surface. A
245
- * built-in type cannot be replaced.
310
+ * Registers how items of another type are drawn. An application's own renderer for `surface`
311
+ * replaces the library's drawing of that type; the types the library always draws cannot be
312
+ * replaced.
246
313
  * @param {string} type Item type.
247
314
  * @param {ThreadItemRenderer} render Draws the item's content.
248
315
  * @returns {typeof AgentThread}
249
316
  */
250
317
  static register(type: string, render: ThreadItemRenderer): typeof AgentThread;
251
318
  /**
252
- * Reports whether a type has a registered renderer.
319
+ * Reports whether a type has a registered renderer. `surface` answers false until an
320
+ * application registers its own, so a guarded `register()` still takes effect.
253
321
  * @param {string} type
254
322
  * @returns {boolean}
255
323
  */
@@ -257,21 +325,25 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
257
325
  /** @returns {HTMLElement} */
258
326
  render(): HTMLElement;
259
327
  /**
260
- * Replaces the conversation.
328
+ * Replaces the conversation. Everything is dropped and then drawn anew, except a surface already
329
+ * drawn, which stays so that one still matching keeps answering.
261
330
  * @param {ThreadItem[]} items
262
331
  * @returns {this}
263
332
  */
264
333
  setItems(items: ThreadItem[]): this;
265
334
  /**
266
- * Adds an item, or replaces the item with the same id where it stands.
335
+ * Adds an item, or replaces the item with the same id where it stands. A new item goes at the
336
+ * end, or right after the item `options.after` names.
267
337
  * @param {ThreadItem} item
338
+ * @param {UpsertOptions} [options]
268
339
  * @returns {this}
269
340
  */
270
- upsert(item: ThreadItem): this;
341
+ upsert(item: ThreadItem, options?: UpsertOptions): this;
271
342
  /**
272
- * Changes part of an item. The common changes are made in place — an answer finishing or
273
- * stopping, a trace's steps, an approval's status — so focus and selection inside the item
274
- * survive; anything else redraws the item.
343
+ * Changes part of an item. The common changes are made in place — an answer finishing, stopping
344
+ * or writing on, a trace's steps, an approval's status — so what the reader opened, and focus and
345
+ * selection where the blocks stay, survive; anything else redraws the item. Metadata patches
346
+ * retain an answer's live blocks; explicit `blocks` or `versions` remain authoritative.
275
347
  * @param {string} id
276
348
  * @param {Record<string, unknown>} partial
277
349
  * @returns {this}
@@ -301,7 +373,8 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
301
373
  */
302
374
  announce(text: string): this;
303
375
  /**
304
- * Removes an item.
376
+ * Removes an item. Focus inside it moves to the item above, or the one below when it was the
377
+ * first, so that a keyboard user is not thrown back to the top of the page.
305
378
  * @param {string} id
306
379
  * @returns {this}
307
380
  */
@@ -321,9 +394,17 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
321
394
  * @returns {Component|null}
322
395
  */
323
396
  getComponent(id: string): Component | null;
397
+ /**
398
+ * The Surface drawn for a `surface` item, to stream its operations into with `apply()` or
399
+ * `write()`.
400
+ * @param {string} id
401
+ * @returns {Surface|null}
402
+ */
403
+ surface(id: string): Surface | null;
324
404
  /**
325
405
  * Brings something into view and moves focus to it: `item:<id>` an item, `step:<id>` a trace
326
- * step (in whichever trace holds it), `source:<n>` a source of the latest answer that has one.
406
+ * step (in whichever trace holds it), `source:<n>` a source of the latest answer that has one,
407
+ * `source:<n>:<id>` a source in the list of the answer `id`.
327
408
  * @param {string} target
328
409
  * @returns {boolean} Whether the target was found.
329
410
  */
@@ -349,7 +430,7 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
349
430
  /**
350
431
  * @private
351
432
  * @param {ThreadItem} item
352
- * @param {{announce?: boolean}} [options]
433
+ * @param {{announce?: boolean, after?: string|null}} [options]
353
434
  * @returns {void}
354
435
  */
355
436
  private _add;
@@ -360,6 +441,14 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
360
441
  * @returns {void}
361
442
  */
362
443
  private _replace;
444
+ /**
445
+ * Puts the feed in the order given, moving only what stands elsewhere. Anything a listener added
446
+ * meanwhile stays, after what was asked for.
447
+ * @private
448
+ * @param {string[]} ids
449
+ * @returns {void}
450
+ */
451
+ private _arrange;
363
452
  /** @private @param {string} id @returns {void} */
364
453
  private _drop;
365
454
  /**
@@ -382,6 +471,7 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
382
471
  * Draws one item into its article.
383
472
  * @private
384
473
  * @param {ThreadItem} item
474
+ * @param {Surface|null} [surface=null] A surface to keep rather than draw anew.
385
475
  * @returns {ThreadEntry}
386
476
  */
387
477
  private _build;
@@ -454,6 +544,16 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
454
544
  * @returns {void}
455
545
  */
456
546
  private _buildApproval;
547
+ /**
548
+ * A surface item: the Surface, its reply re-emitted as the thread's `reply` and kept on the item.
549
+ * @private
550
+ * @param {ThreadEntry} entry
551
+ * @param {HTMLElement} body
552
+ * @param {<T extends Component>(component: T) => T} own
553
+ * @param {Surface|null} kept A surface carried over from the item's earlier drawing.
554
+ * @returns {void}
555
+ */
556
+ private _buildSurface;
457
557
  /**
458
558
  * The author's avatar, beside the byline and the content. Decorative: the byline names them.
459
559
  * @private
@@ -485,6 +585,25 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
485
585
  private _time;
486
586
  /** @private @param {Extract<ThreadItem, {type: 'answer'}>} answer @returns {number} */
487
587
  private _versionIndex;
588
+ /**
589
+ * An answer with versions shows its chosen version, so what changes in it belongs there too: the
590
+ * item's own fields are only what it would show without them.
591
+ * @private
592
+ * @template {ThreadItem} T
593
+ * @param {T} item
594
+ * @param {Record<string, unknown>} partial What changed.
595
+ * @returns {T}
596
+ */
597
+ private _intoVersion;
598
+ /**
599
+ * Streamed text lives in the view, so an answer drawn anew from the same versions takes it along
600
+ * into the version it was streamed into.
601
+ * @private
602
+ * @param {ThreadEntry} old
603
+ * @param {ThreadItem} item
604
+ * @returns {ThreadItem}
605
+ */
606
+ private _keepStreamed;
488
607
  /**
489
608
  * The blocks, sources, and steps an answer shows: its chosen version's when it has several.
490
609
  * @private
@@ -509,9 +628,11 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
509
628
  private _announceItem;
510
629
  /**
511
630
  * Says a milestone once. The region is cleared first so the same words said twice are heard
512
- * twice.
631
+ * twice. Words still waiting to be said give way only to words that must be heard: what asks
632
+ * something of the person is not overtaken by what has just finished.
513
633
  * @private
514
634
  * @param {string} text
635
+ * @param {boolean} [urgent=false] Whether it must be heard.
515
636
  * @returns {void}
516
637
  */
517
638
  private _announce;
@@ -532,7 +653,7 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
532
653
  private _onClick;
533
654
  /**
534
655
  * APG feed keys: PageDown and PageUp move between articles; Ctrl+End and Ctrl+Home move focus
535
- * past the end or before the start of the feed.
656
+ * past the end or before the start of the feed. A control inside an item keeps them.
536
657
  * @private
537
658
  * @param {KeyboardEvent} event
538
659
  * @returns {void}
@@ -581,3 +702,10 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
581
702
  * @event AgentThread#open
582
703
  * @type {CustomEvent<{item: ThreadItem, ref: import('../../internal/agent-model.js').ItemRef, step?: import('../../internal/agent-model.js').TraceStep}>}
583
704
  */
705
+ /**
706
+ * A surface in the thread replied: its one reply, with the item as it now stands. Also sent when
707
+ * an unanswered surface is superseded by a new one under the same id, removed, or destroyed with
708
+ * the thread.
709
+ * @event AgentThread#reply
710
+ * @type {CustomEvent<{item: ThreadItem, reply: SurfaceReply}>}
711
+ */