@zeyos/zx 5.4.0 → 5.6.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 (145) hide show
  1. package/CHANGELOG.md +136 -0
  2. package/README.md +23 -16
  3. package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
  4. package/dist/types/components/app-sidebar/app-sidebar.d.ts +33 -0
  5. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  6. package/dist/types/components/avatar/avatar.d.ts +91 -4
  7. package/dist/types/components/badge/badge.d.ts +5 -4
  8. package/dist/types/components/block-view/block-view.d.ts +205 -0
  9. package/dist/types/components/composer/composer.d.ts +736 -0
  10. package/dist/types/components/datebox/date-range-box.d.ts +15 -2
  11. package/dist/types/components/datebox/datebox.d.ts +37 -3
  12. package/dist/types/components/kbd/kbd.d.ts +41 -0
  13. package/dist/types/components/launcher/launcher.d.ts +4 -2
  14. package/dist/types/components/prose/prose.d.ts +69 -0
  15. package/dist/types/components/questionnaire/questionnaire.d.ts +0 -36
  16. package/dist/types/components/run-status/run-status.d.ts +393 -0
  17. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  18. package/dist/types/components/source-list/source-list.d.ts +177 -0
  19. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -0
  20. package/dist/types/components/tag-picker/tag-picker.d.ts +11 -5
  21. package/dist/types/components/tree/tree.d.ts +44 -3
  22. package/dist/types/core/icons.d.ts +22 -1
  23. package/dist/types/core/messages.d.ts +135 -0
  24. package/dist/types/index.d.ts +12 -2
  25. package/dist/types/internal/agent-model.d.ts +587 -0
  26. package/dist/types/internal/app-rail.d.ts +10 -3
  27. package/dist/types/internal/highlight.d.ts +24 -0
  28. package/dist/types/internal/presence-loop.d.ts +148 -0
  29. package/dist/types/internal/row-actions.d.ts +151 -0
  30. package/dist/zx-zeyos.esm.js +4852 -4535
  31. package/dist/zx-zeyos.esm.min.js +4 -4
  32. package/dist/zx.css +3152 -434
  33. package/dist/zx.esm.js +13730 -6595
  34. package/dist/zx.esm.min.js +27 -8
  35. package/dist/zx.global.js +13730 -6595
  36. package/dist/zx.global.min.js +27 -8
  37. package/dist/zx.min.css +1 -1
  38. package/docs/api.json +1474 -205
  39. package/docs/llms.md +698 -39
  40. package/docs/llms.txt +12 -1
  41. package/package.json +1 -1
  42. package/src/components/account-menu/account-menu.js +2 -2
  43. package/src/components/agent-thread/agent-thread.css +417 -0
  44. package/src/components/agent-thread/agent-thread.js +1365 -0
  45. package/src/components/app-rail/app-rail.css +11 -11
  46. package/src/components/app-sidebar/app-sidebar.css +90 -17
  47. package/src/components/app-sidebar/app-sidebar.js +120 -12
  48. package/src/components/approval-card/approval-card.css +289 -0
  49. package/src/components/approval-card/approval-card.js +1377 -0
  50. package/src/components/avatar/avatar.css +56 -1
  51. package/src/components/avatar/avatar.js +148 -26
  52. package/src/components/badge/badge.css +33 -20
  53. package/src/components/badge/badge.js +5 -4
  54. package/src/components/block-view/block-view.css +300 -0
  55. package/src/components/block-view/block-view.js +523 -0
  56. package/src/components/breadcrumb/breadcrumb.css +28 -3
  57. package/src/components/breadcrumb/breadcrumb.js +2 -2
  58. package/src/components/button/button.css +24 -13
  59. package/src/components/button/button.js +20 -2
  60. package/src/components/calendar/calendar.css +14 -4
  61. package/src/components/card-view/card-view.js +2 -2
  62. package/src/components/chart/chart.js +20 -5
  63. package/src/components/check-button/check-button.css +11 -3
  64. package/src/components/check-button/check-button.js +3 -3
  65. package/src/components/composer/composer.css +403 -0
  66. package/src/components/composer/composer.js +1441 -0
  67. package/src/components/context-menu/context-menu.css +7 -1
  68. package/src/components/date-picker/date-picker.css +6 -0
  69. package/src/components/date-picker/date-picker.js +5 -5
  70. package/src/components/date-picker/date-range-picker.css +6 -0
  71. package/src/components/date-picker/date-range-picker.js +3 -3
  72. package/src/components/date-picker/month-picker.js +3 -3
  73. package/src/components/date-picker/time-picker.css +6 -0
  74. package/src/components/datebox/date-range-box.js +30 -6
  75. package/src/components/datebox/datebox.js +44 -7
  76. package/src/components/dialog/dialog.css +0 -1
  77. package/src/components/dialog/dialog.js +2 -1
  78. package/src/components/dock/dock.js +2 -2
  79. package/src/components/dropdown/dropdown.css +2 -1
  80. package/src/components/entity-ref/entity-ref.css +8 -1
  81. package/src/components/file-item/file-item.css +1 -1
  82. package/src/components/finder/finder.js +2 -2
  83. package/src/components/groupbox/groupbox.js +2 -2
  84. package/src/components/kanban-view/kanban-view.css +8 -4
  85. package/src/components/kanban-view/kanban-view.js +3 -3
  86. package/src/components/kbd/kbd.css +64 -0
  87. package/src/components/kbd/kbd.js +121 -0
  88. package/src/components/launcher/launcher.css +30 -25
  89. package/src/components/launcher/launcher.js +15 -21
  90. package/src/components/list-toolbar/list-toolbar.css +7 -1
  91. package/src/components/menu-button/menu-button.css +9 -2
  92. package/src/components/message/message.js +2 -2
  93. package/src/components/module-bar/module-bar.css +11 -1
  94. package/src/components/multi-value-editor/multi-value-editor.js +4 -4
  95. package/src/components/navigation-bar/navigation-bar.css +3 -2
  96. package/src/components/pagination/pagination.js +2 -2
  97. package/src/components/panel/panel.js +2 -2
  98. package/src/components/prose/prose.css +53 -0
  99. package/src/components/prose/prose.js +152 -0
  100. package/src/components/questionnaire/questionnaire.css +7 -17
  101. package/src/components/questionnaire/questionnaire.js +16 -1
  102. package/src/components/rating/rating.css +3 -1
  103. package/src/components/run-status/run-status.css +208 -0
  104. package/src/components/run-status/run-status.js +782 -0
  105. package/src/components/run-trace/run-trace.css +443 -0
  106. package/src/components/run-trace/run-trace.js +1209 -0
  107. package/src/components/search/search.js +2 -2
  108. package/src/components/select/glyphs.js +3 -3
  109. package/src/components/select/select.css +35 -7
  110. package/src/components/select/select.js +4 -4
  111. package/src/components/source-list/source-list.css +208 -0
  112. package/src/components/source-list/source-list.js +355 -0
  113. package/src/components/stat-tile/stat-tile.css +56 -2
  114. package/src/components/stat-tile/stat-tile.js +25 -2
  115. package/src/components/stepper/stepper.css +2 -1
  116. package/src/components/stepper/stepper.js +3 -3
  117. package/src/components/tabbox/tabbox.css +2 -2
  118. package/src/components/tabbox/tabbox.js +2 -2
  119. package/src/components/table/table.css +52 -16
  120. package/src/components/table/table.js +7 -5
  121. package/src/components/tag-picker/tag-picker.css +56 -43
  122. package/src/components/tag-picker/tag-picker.js +21 -16
  123. package/src/components/tree/tree.css +44 -0
  124. package/src/components/tree/tree.js +97 -9
  125. package/src/components/value-list/value-list.css +25 -4
  126. package/src/components/value-list/value-list.js +2 -1
  127. package/src/components/view/record-view.js +3 -3
  128. package/src/components/view-settings/view-settings.css +2 -1
  129. package/src/components/workspace-switcher/workspace-switcher.js +3 -3
  130. package/src/core/icons.js +34 -3
  131. package/src/core/messages.js +143 -0
  132. package/src/elements/define.js +1 -0
  133. package/src/index.js +12 -2
  134. package/src/internal/agent-model.js +488 -0
  135. package/src/internal/app-rail.js +5 -1
  136. package/src/internal/highlight.js +104 -0
  137. package/src/internal/presence-loop.js +343 -0
  138. package/src/internal/row-actions.js +203 -0
  139. package/styles/base.css +26 -1
  140. package/styles/prose.css +306 -0
  141. package/styles/tokens/dark.css +97 -120
  142. package/styles/tokens/global.css +24 -9
  143. package/styles/tokens/semantic.css +464 -184
  144. package/styles/tokens/themes.css +9 -0
  145. package/styles/zx.css +10 -0
@@ -0,0 +1,624 @@
1
+ import { Component } from '../../core/component.js';
2
+ import { Avatar } from '../avatar/avatar.js';
3
+ export type TraceStep = import('../../internal/agent-model.js').TraceStep;
4
+ export type Author = import('../../internal/agent-model.js').Author;
5
+ export type ItemRef = import('../../internal/agent-model.js').ItemRef;
6
+ export type RunState = import('../../internal/agent-model.js').RunState;
7
+ export type AvatarTone = import('../avatar/avatar.js').AvatarTone;
8
+ export type TraceKind = 'search' | 'read' | 'query' | 'write' | 'run' | 'call' | 'handoff' | 'think' | 'task' | 'ask' | 'decision';
9
+ export type RowKind = 'disclosure' | 'select' | 'static';
10
+ export type MetaPart = {
11
+ /**
12
+ * What the piece is: a
13
+ * hand-off's own label, the count, a search's sources, who took the step, when it started, the
14
+ * tokens it used.
15
+ */
16
+ part: 'label' | 'count' | 'sources' | 'actor' | 'time' | 'tokens';
17
+ /**
18
+ * The words shown.
19
+ */
20
+ text: string;
21
+ };
22
+ export type RunTraceOptions = {
23
+ /**
24
+ * The steps the run took, in the order they started. A step
25
+ * with `retryOf` is drawn under the step it repeats. Model text is data: every string reaches the
26
+ * page as text.
27
+ */
28
+ steps?: TraceStep[];
29
+ /**
30
+ * Whether the step list starts open under its summary.
31
+ */
32
+ open?: boolean;
33
+ /**
34
+ * Text the summary reads instead of the computed "Worked for
35
+ * …" line — a plan's title, "Plan · 5 of 6 done". Any state but done still follows it as a word
36
+ * ("· Running"). `setLabel()` changes it.
37
+ */
38
+ label?: string | null;
39
+ /**
40
+ * Who the `actor` and `to` keys of the steps name;
41
+ * a hand-off draws both authors' avatars, round for a `person` and rounded squares otherwise. A key
42
+ * with no entry is shown as written.
43
+ */
44
+ authors?: Record<string, Author>;
45
+ /**
46
+ * Whether a step's disclosure shows the arguments its call
47
+ * was made with.
48
+ */
49
+ showArguments?: boolean;
50
+ /**
51
+ * Characters of a result shown before it is cut, with a
52
+ * "Show all" button for the rest. Zero or a non-finite value shows every result whole.
53
+ */
54
+ maxResult?: number;
55
+ /**
56
+ * Whether the steps fold into a summary line. Without it the
57
+ * list always shows — for a run panel whose state is already told beside it.
58
+ */
59
+ summary?: boolean;
60
+ /**
61
+ * Whether each step leads with its kind's glyph. Without
62
+ * them a step shows only its status. `null` decides by the steps: a plan, where every step is a
63
+ * `task`, shows none; anything else shows them.
64
+ */
65
+ kindIcons?: boolean | null;
66
+ /**
67
+ * Whether every step can be chosen: a row with nothing to
68
+ * open becomes a button, and a disclosure also reports the step as it opens. Both emit `select`.
69
+ */
70
+ selectable?: boolean;
71
+ /**
72
+ * Whether a running step that has `at` shows how long it has
73
+ * run, counting once a second. One interval serves the whole trace; it runs only while such a step
74
+ * is on screen in the open list, and sleeps while the page is hidden.
75
+ */
76
+ ticking?: boolean;
77
+ /**
78
+ * The clock `ticking` counts against, for an application
79
+ * whose world is fixed on another date; real time when null.
80
+ */
81
+ now?: (() => Date) | null;
82
+ /**
83
+ * Writes a step's `at` for its meta
84
+ * line; "10:31:05" (the local ISO time as given) when null.
85
+ */
86
+ formatTime?: ((at: string) => string) | null;
87
+ /**
88
+ * Icon names per step kind, over the
89
+ * built-in `STEP_ICONS`.
90
+ */
91
+ icons?: Partial<Record<TraceKind, string>>;
92
+ /**
93
+ * Localized
94
+ * messages: the `runTrace.*` keys and the `agent.status.*` words.
95
+ */
96
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
97
+ /**
98
+ * Disclosure
99
+ * listener.
100
+ */
101
+ ontoggle?: (event: CustomEvent<{
102
+ id: string | null;
103
+ open: boolean;
104
+ }>) => void;
105
+ /**
106
+ * Reveal listener.
107
+ */
108
+ onreveal?: (event: CustomEvent<{
109
+ id: string;
110
+ }>) => void;
111
+ /**
112
+ * Selection listener
113
+ * (`selectable` traces).
114
+ */
115
+ onselect?: (event: CustomEvent<{
116
+ id: string;
117
+ }>) => void;
118
+ /**
119
+ * Listener for
120
+ * a step's links.
121
+ */
122
+ onopen?: (event: CustomEvent<{
123
+ step: TraceStep;
124
+ ref: ItemRef;
125
+ }>) => void;
126
+ };
127
+ export type StepEntry = {
128
+ /**
129
+ * The step as last given.
130
+ */
131
+ step: TraceStep & {
132
+ id: string;
133
+ };
134
+ /**
135
+ * Its list item; it outlives redraws of the step.
136
+ */
137
+ li: HTMLElement;
138
+ /**
139
+ * The row: a disclosure button, a select button, or a plain row.
140
+ */
141
+ row: HTMLElement | null;
142
+ /**
143
+ * The step's links, after its row.
144
+ */
145
+ refs: HTMLElement | null;
146
+ /**
147
+ * The disclosure's content, when the step has any.
148
+ */
149
+ body: HTMLElement | null;
150
+ /**
151
+ * The nested list of the steps that repeat this one.
152
+ */
153
+ retries: HTMLElement | null;
154
+ /**
155
+ * Avatars the row owns.
156
+ */
157
+ avatars: Avatar[];
158
+ /**
159
+ * The top-level step a retry is drawn under; null for a top-level step.
160
+ */
161
+ rootId: string | null;
162
+ /**
163
+ * Id of the disclosure content.
164
+ */
165
+ bodyId: string | null;
166
+ };
167
+ export type TraceLabel = {
168
+ /**
169
+ * `running`, `waiting`, `blocked`, `paused`, `stopped`, `failed`,
170
+ * `queued` (no step has started), or `done`.
171
+ */
172
+ state: RunState;
173
+ /**
174
+ * The summary line: "Worked for 41 s · 5 tool calls · 1 retry".
175
+ */
176
+ label: string;
177
+ /**
178
+ * What the running step is doing, or which step is waiting or
179
+ * blocked, without an ellipsis.
180
+ */
181
+ doing: string | null;
182
+ };
183
+ /** @typedef {import('../../internal/agent-model.js').TraceStep} TraceStep */
184
+ /** @typedef {import('../../internal/agent-model.js').Author} Author */
185
+ /** @typedef {import('../../internal/agent-model.js').ItemRef} ItemRef */
186
+ /** @typedef {import('../../internal/agent-model.js').RunState} RunState */
187
+ /** @typedef {import('../avatar/avatar.js').AvatarTone} AvatarTone */
188
+ /**
189
+ * What kind of step a trace step is: it picks the glyph, and whether the summary counts it as a
190
+ * tool call. `task` is a planned step, `ask` a request a person made, `decision` a person's
191
+ * answer; with `think` and `handoff` they are not tool calls.
192
+ * @typedef {'search'|'read'|'query'|'write'|'run'|'call'|'handoff'|'think'|'task'|'ask'|'decision'} TraceKind
193
+ */
194
+ /**
195
+ * How a step's row behaves: a disclosure button when the step has something to open, a plain
196
+ * button when the trace is `selectable`, otherwise a static row.
197
+ * @typedef {'disclosure'|'select'|'static'} RowKind
198
+ */
199
+ /**
200
+ * One piece of a step's muted meta line, in the order drawn.
201
+ * @typedef {Object} MetaPart
202
+ * @property {'label'|'count'|'sources'|'actor'|'time'|'tokens'} part What the piece is: a
203
+ * hand-off's own label, the count, a search's sources, who took the step, when it started, the
204
+ * tokens it used.
205
+ * @property {string} text The words shown.
206
+ */
207
+ /**
208
+ * @typedef {Object} RunTraceOptions
209
+ * @property {TraceStep[]} [steps=[]] The steps the run took, in the order they started. A step
210
+ * with `retryOf` is drawn under the step it repeats. Model text is data: every string reaches the
211
+ * page as text.
212
+ * @property {boolean} [open=false] Whether the step list starts open under its summary.
213
+ * @property {string|null} [label=null] Text the summary reads instead of the computed "Worked for
214
+ * …" line — a plan's title, "Plan · 5 of 6 done". Any state but done still follows it as a word
215
+ * ("· Running"). `setLabel()` changes it.
216
+ * @property {Record<string, Author>} [authors={}] Who the `actor` and `to` keys of the steps name;
217
+ * a hand-off draws both authors' avatars, round for a `person` and rounded squares otherwise. A key
218
+ * with no entry is shown as written.
219
+ * @property {boolean} [showArguments=true] Whether a step's disclosure shows the arguments its call
220
+ * was made with.
221
+ * @property {number} [maxResult=4000] Characters of a result shown before it is cut, with a
222
+ * "Show all" button for the rest. Zero or a non-finite value shows every result whole.
223
+ * @property {boolean} [summary=true] Whether the steps fold into a summary line. Without it the
224
+ * list always shows — for a run panel whose state is already told beside it.
225
+ * @property {boolean|null} [kindIcons=null] Whether each step leads with its kind's glyph. Without
226
+ * them a step shows only its status. `null` decides by the steps: a plan, where every step is a
227
+ * `task`, shows none; anything else shows them.
228
+ * @property {boolean} [selectable=false] Whether every step can be chosen: a row with nothing to
229
+ * open becomes a button, and a disclosure also reports the step as it opens. Both emit `select`.
230
+ * @property {boolean} [ticking=false] Whether a running step that has `at` shows how long it has
231
+ * run, counting once a second. One interval serves the whole trace; it runs only while such a step
232
+ * is on screen in the open list, and sleeps while the page is hidden.
233
+ * @property {(() => Date)|null} [now=null] The clock `ticking` counts against, for an application
234
+ * whose world is fixed on another date; real time when null.
235
+ * @property {((at: string) => string)|null} [formatTime=null] Writes a step's `at` for its meta
236
+ * line; "10:31:05" (the local ISO time as given) when null.
237
+ * @property {Partial<Record<TraceKind, string>>} [icons={}] Icon names per step kind, over the
238
+ * built-in `STEP_ICONS`.
239
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized
240
+ * messages: the `runTrace.*` keys and the `agent.status.*` words.
241
+ * @property {(event: CustomEvent<{id: string|null, open: boolean}>) => void} [ontoggle] Disclosure
242
+ * listener.
243
+ * @property {(event: CustomEvent<{id: string}>) => void} [onreveal] Reveal listener.
244
+ * @property {(event: CustomEvent<{id: string}>) => void} [onselect] Selection listener
245
+ * (`selectable` traces).
246
+ * @property {(event: CustomEvent<{step: TraceStep, ref: ItemRef}>) => void} [onopen] Listener for
247
+ * a step's links.
248
+ */
249
+ /**
250
+ * One drawn step.
251
+ * @typedef {Object} StepEntry
252
+ * @property {TraceStep & {id: string}} step The step as last given.
253
+ * @property {HTMLElement} li Its list item; it outlives redraws of the step.
254
+ * @property {HTMLElement|null} row The row: a disclosure button, a select button, or a plain row.
255
+ * @property {HTMLElement|null} refs The step's links, after its row.
256
+ * @property {HTMLElement|null} body The disclosure's content, when the step has any.
257
+ * @property {HTMLElement|null} retries The nested list of the steps that repeat this one.
258
+ * @property {Avatar[]} avatars Avatars the row owns.
259
+ * @property {string|null} rootId The top-level step a retry is drawn under; null for a top-level step.
260
+ * @property {string|null} bodyId Id of the disclosure content.
261
+ */
262
+ /**
263
+ * The trace's overall state and its one-line summary.
264
+ * @typedef {Object} TraceLabel
265
+ * @property {RunState} state `running`, `waiting`, `blocked`, `paused`, `stopped`, `failed`,
266
+ * `queued` (no step has started), or `done`.
267
+ * @property {string} label The summary line: "Worked for 41 s · 5 tool calls · 1 retry".
268
+ * @property {string|null} doing What the running step is doing, or which step is waiting or
269
+ * blocked, without an ellipsis.
270
+ */
271
+ /** Built-in glyph per step kind. */
272
+ export declare const STEP_ICONS: Readonly<{
273
+ search: "search";
274
+ read: "file";
275
+ query: "table";
276
+ write: "type";
277
+ run: "code";
278
+ call: "gear";
279
+ handoff: "link-2";
280
+ think: "dots";
281
+ task: "list";
282
+ ask: "mail";
283
+ decision: "check";
284
+ }>;
285
+ /**
286
+ * What an agent did during a run: a one-line summary ("Worked for 41 s · 5 tool calls") that
287
+ * opens into a timeline of its steps. A tool call opens in turn to the arguments it was made with
288
+ * and what came back; a retry is drawn under the call it repeats; a hand-off shows both agents.
289
+ *
290
+ * The trace renders the steps it is given and changes only when the application calls
291
+ * `setSteps()` or `upsert()`; a live run upserts each step as it starts and again as it ends, and
292
+ * only that step is redrawn. The same component draws a plan: `task` steps under a `label` of the
293
+ * plan's own, chosen one at a time with `selectable`.
294
+ *
295
+ * @fires RunTrace#toggle
296
+ * @fires RunTrace#reveal
297
+ * @fires RunTrace#select
298
+ * @fires RunTrace#open
299
+ * @extends {Component<RunTraceOptions>}
300
+ */
301
+ export declare class RunTrace extends Component<RunTraceOptions> {
302
+ _original: import("../../core/dom.js").TargetSnapshot;
303
+ _destroyed: boolean;
304
+ _open: any;
305
+ /** @type {string|null} The summary text set by `label` or `setLabel()`. */
306
+ _label: string | null;
307
+ /** @type {Array<TraceStep & {id: string}>} */
308
+ _steps: Array<TraceStep & {
309
+ id: string;
310
+ }>;
311
+ /** @type {Map<string, StepEntry>} */
312
+ _entries: Map<string, StepEntry>;
313
+ /** @type {Set<string>} Steps whose disclosure is open. */
314
+ _expanded: Set<string>;
315
+ /** @type {Set<string>} Steps whose long result is shown whole. */
316
+ _whole: Set<string>;
317
+ /** @type {ReturnType<typeof setTimeout>|null} */
318
+ _revealTimer: ReturnType<typeof setTimeout> | null;
319
+ /** @type {ReturnType<typeof setInterval>|null} The one clock every running step counts by. */
320
+ _clock: ReturnType<typeof setInterval> | null;
321
+ _summaryState: HTMLElement;
322
+ _summaryText: HTMLElement;
323
+ _summaryDoing: HTMLElement;
324
+ _summary: HTMLElement;
325
+ _list: HTMLElement;
326
+ static cssName: string;
327
+ /** @type {Readonly<RunTraceOptions>} */
328
+ static defaults: Readonly<RunTraceOptions>;
329
+ /** @returns {HTMLElement} */
330
+ render(): HTMLElement;
331
+ /**
332
+ * Sets the text the summary reads instead of the computed line; null or an empty string goes
333
+ * back to "Worked for …". Any state but done still follows it as a word.
334
+ * @param {string|null} label
335
+ * @returns {this}
336
+ */
337
+ setLabel(label: string | null): this;
338
+ /**
339
+ * Replaces every step. Open steps stay open, and focus on a step's row stays on that step.
340
+ * @param {TraceStep[]} steps
341
+ * @returns {this}
342
+ */
343
+ setSteps(steps: TraceStep[]): this;
344
+ /**
345
+ * Adds a step, or replaces the step with the same `id`. A replaced step is redrawn on its own,
346
+ * keeping its place, its open state, and the retries under it; a new step is appended, under
347
+ * the step it repeats when it has `retryOf`.
348
+ * @param {TraceStep} step
349
+ * @returns {this}
350
+ */
351
+ upsert(step: TraceStep): this;
352
+ /**
353
+ * Opens the step list, and the disclosure of the step `id` when one is given.
354
+ * @param {string|null} [id=null]
355
+ * @returns {this}
356
+ */
357
+ expand(id?: string | null): this;
358
+ /**
359
+ * Closes the step list, or only the disclosure of the step `id` when one is given.
360
+ * @param {string|null} [id=null]
361
+ * @returns {this}
362
+ */
363
+ collapse(id?: string | null): this;
364
+ /**
365
+ * Shows one step: opens the list and the step, scrolls it into view, puts focus on its row, and
366
+ * marks it with `data-state="revealed"` for two seconds. Under reduced motion the scroll jumps.
367
+ * An unknown id does nothing.
368
+ * @param {string} id
369
+ * @returns {this}
370
+ * @fires RunTrace#reveal
371
+ */
372
+ reveal(id: string): this;
373
+ /** @returns {TraceStep[]} Copies of the steps, in the order they were given. */
374
+ getSteps(): TraceStep[];
375
+ /** @returns {boolean} Whether the step list is open. */
376
+ isOpen(): boolean;
377
+ /** @returns {void} */
378
+ destroy(): void;
379
+ /**
380
+ * @private
381
+ * @param {unknown} steps
382
+ * @returns {void}
383
+ */
384
+ private _build;
385
+ /**
386
+ * @private
387
+ * @param {TraceStep & {id: string}} step
388
+ * @param {string|null} rootId
389
+ * @returns {HTMLElement}
390
+ */
391
+ private _createEntry;
392
+ /**
393
+ * @private
394
+ * @param {string} rootId
395
+ * @param {TraceStep & {id: string}} step
396
+ * @returns {void}
397
+ */
398
+ private _appendRetry;
399
+ /**
400
+ * The top-level step a new step is drawn under, or null when it repeats nothing drawn.
401
+ * @private
402
+ * @param {TraceStep} step
403
+ * @returns {string|null}
404
+ */
405
+ private _rootOf;
406
+ /**
407
+ * Draws a step's row, links, and disclosure, replacing the ones it had. The list item, its
408
+ * marks, and the retries under it stay; focus on the row, a link, or the disclosure stays on
409
+ * the step.
410
+ * @private
411
+ * @param {StepEntry} entry
412
+ * @returns {void}
413
+ */
414
+ private _paint;
415
+ /**
416
+ * The step's links to the application's own things, as a list of quiet buttons, or null when it
417
+ * has none.
418
+ * @private
419
+ * @param {TraceStep} step
420
+ * @returns {HTMLElement|null}
421
+ */
422
+ private _refs;
423
+ /**
424
+ * The step's words: what it did (or is doing), a "Retried" tag, a hand-off's two avatars, and a
425
+ * muted line of its count, who took it, when, and the tokens it used.
426
+ * @private
427
+ * @param {StepEntry} entry
428
+ * @param {TraceKind} kind
429
+ * @param {RunState} status
430
+ * @returns {HTMLElement}
431
+ */
432
+ private _text;
433
+ /**
434
+ * The step's state: always a glyph and a word. The word is visible for the states a reader has
435
+ * to notice; a finished step shows its duration instead, and a running one says what it is doing
436
+ * and, with `ticking`, how long it has run.
437
+ * @private
438
+ * @param {TraceStep} step
439
+ * @param {RunState} status
440
+ * @returns {HTMLElement}
441
+ */
442
+ private _end;
443
+ /**
444
+ * A step's disclosure: the tool, the detail, the arguments, and the result or the error. Who
445
+ * took the step and when are on its row.
446
+ * @private
447
+ * @param {TraceStep & {id: string}} step
448
+ * @param {string} id
449
+ * @param {boolean} open
450
+ * @returns {HTMLElement}
451
+ */
452
+ private _body;
453
+ /**
454
+ * One block of a disclosure: its title, a copy button, and the text in a `<pre>`. A result
455
+ * longer than `maxResult` is cut, with a button that shows the rest.
456
+ * @private
457
+ * @param {'arguments'|'result'|'error'} kind
458
+ * @param {string} full
459
+ * @param {string} stepId
460
+ * @returns {HTMLElement}
461
+ */
462
+ private _section;
463
+ /**
464
+ * @private
465
+ * @param {boolean} open
466
+ * @returns {void}
467
+ */
468
+ private _setOpen;
469
+ /**
470
+ * @private
471
+ * @param {string} id
472
+ * @param {boolean} open
473
+ * @returns {void}
474
+ */
475
+ private _setStep;
476
+ /**
477
+ * Redraws the summary from the steps.
478
+ * @private
479
+ * @returns {void}
480
+ */
481
+ private _sync;
482
+ /**
483
+ * Starts the one clock while a running step's time is on screen, and stops it otherwise: when
484
+ * no step is running, the list is closed, the page is hidden, or the trace is destroyed.
485
+ * @private
486
+ * @returns {void}
487
+ */
488
+ private _syncClock;
489
+ /**
490
+ * Moves every running step's time to the clock's now.
491
+ * @private
492
+ * @returns {void}
493
+ */
494
+ private _tick;
495
+ /**
496
+ * The time `ticking` counts against: the `now` option's, or real time.
497
+ * @private
498
+ * @returns {number} Milliseconds since the epoch.
499
+ */
500
+ private _now;
501
+ /**
502
+ * @private
503
+ * @param {HTMLElement} li
504
+ * @returns {void}
505
+ */
506
+ private _mark;
507
+ /** @private @param {TraceKind} kind @returns {string} */
508
+ private _icon;
509
+ /**
510
+ * @private
511
+ * @param {unknown} key
512
+ * @returns {{name: string, initials: string, tone: AvatarTone|null, person: boolean}}
513
+ */
514
+ private _author;
515
+ /**
516
+ * A hand-off avatar, shaped like the author's avatar everywhere else: round for a person, a
517
+ * rounded square for an agent or a model.
518
+ * @private
519
+ * @param {unknown} key
520
+ * @returns {Avatar}
521
+ */
522
+ private _avatar;
523
+ /** @private @param {StepEntry} entry @returns {void} */
524
+ private _releaseAvatars;
525
+ /** @private @returns {string|null} The step whose row or disclosure has focus. */
526
+ private _focusedStep;
527
+ /**
528
+ * @private
529
+ * @param {MouseEvent} event
530
+ * @returns {void}
531
+ */
532
+ private _onClick;
533
+ }
534
+ /**
535
+ * How long something has run, from when it started to now, in whole units: "41 s". A start in
536
+ * the future reads "0 s".
537
+ * @param {number} since Start, in milliseconds since the epoch.
538
+ * @param {number} now
539
+ * @returns {string}
540
+ */
541
+ export declare function elapsedSince(since: number, now: number): string;
542
+ /**
543
+ * The glyph a step kind draws: the application's from `icons`, else the built-in one. An unknown
544
+ * kind draws as a `call`.
545
+ * @param {unknown} kind
546
+ * @param {Partial<Record<TraceKind, string>>|null} [icons]
547
+ * @returns {string}
548
+ */
549
+ export declare function stepIcon(kind: unknown, icons?: Partial<Record<TraceKind, string>> | null): string;
550
+ /**
551
+ * How a step's row behaves: a disclosure when it has something to open, a button that selects
552
+ * the step when the trace is `selectable`, otherwise a static row.
553
+ * @param {TraceStep} step
554
+ * @param {{selectable?: boolean, showArguments?: boolean}} [options]
555
+ * @returns {RowKind}
556
+ */
557
+ export declare function rowKind(step: TraceStep, options?: {
558
+ selectable?: boolean;
559
+ showArguments?: boolean;
560
+ }): RowKind;
561
+ /**
562
+ * A step's muted meta line, in reading order: a hand-off's own label (when the "handed over"
563
+ * words replace it), the count, a search's sources, who took the step (not for a hand-off, whose
564
+ * words name both sides), the clock time it started, and the tokens it used. Each piece only when
565
+ * the step has it.
566
+ * @param {TraceStep} step
567
+ * @param {{msg?: (key: string, ...args: unknown[]) => string, name?: (key: string) => string,
568
+ * formatTime?: ((at: string) => string)|null}} [context] Message lookup (English by default),
569
+ * author key → display name (the key itself by default), and a writer for `at`.
570
+ * @returns {MetaPart[]}
571
+ */
572
+ export declare function stepMeta(step: TraceStep, context?: {
573
+ msg?: (key: string, ...args: unknown[]) => string;
574
+ name?: (key: string) => string;
575
+ formatTime?: ((at: string) => string) | null;
576
+ }): MetaPart[];
577
+ /**
578
+ * Arguments for display: JSON objects and arrays pretty-printed with two spaces, anything else
579
+ * exactly as given.
580
+ * @param {unknown} value
581
+ * @returns {string}
582
+ */
583
+ export declare function prettyArguments(value: unknown): string;
584
+ /**
585
+ * Cuts a text to at most `max` characters plus an ellipsis, never inside a surrogate pair. Zero, a
586
+ * negative, or a non-finite `max` keeps the whole text.
587
+ * @param {unknown} value
588
+ * @param {unknown} max
589
+ * @returns {{text: string, cut: boolean, length: number}} The text to show, whether it was cut,
590
+ * and the length of the whole.
591
+ */
592
+ export declare function truncateText(value: unknown, max: unknown): {
593
+ text: string;
594
+ cut: boolean;
595
+ length: number;
596
+ };
597
+ /**
598
+ * Groups steps for drawing: every step that repeats another (`retryOf`, followed through retries
599
+ * of retries) goes under the first step of its chain. Top-level steps keep their order, and so do
600
+ * the retries under each. A `retryOf` naming no step, or a loop, leaves the step at the top level.
601
+ * @param {TraceStep[]} steps
602
+ * @returns {Array<{step: TraceStep, retries: TraceStep[]}>}
603
+ */
604
+ export declare function groupRetries(steps: TraceStep[]): Array<{
605
+ step: TraceStep;
606
+ retries: TraceStep[];
607
+ }>;
608
+ /**
609
+ * The trace's state and its summary line. While a step runs it reads "Working…" and names what
610
+ * the step is doing; a run waiting for a person, or blocked, says so and names the step ("Blocked
611
+ * after 12 s · 3 tool calls"); a paused, stopped, or failed run says so before its counts; a run
612
+ * no step of which has started reads "Not started · 6 steps"; once the run ends it reads "Worked
613
+ * for 41 s · 5 tool calls · 9 sources · 1 retry", each count only when it is not zero.
614
+ *
615
+ * With `label`, the line is that text instead — a plan's title — followed by the state's word for
616
+ * every state but done: "Close September · 2 of 5 done · Running".
617
+ * @param {TraceStep[]} steps
618
+ * @param {(key: string, ...args: unknown[]) => string} [msg] Message lookup; English by default.
619
+ * @param {{label?: string|null}} [options]
620
+ * @returns {TraceLabel}
621
+ */
622
+ export declare function traceLabel(steps: TraceStep[], msg?: (key: string, ...args: unknown[]) => string, options?: {
623
+ label?: string | null;
624
+ }): TraceLabel;