@zeyos/zx 5.5.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 (48) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
  3. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  4. package/dist/types/components/avatar/avatar.d.ts +91 -4
  5. package/dist/types/components/block-view/block-view.d.ts +205 -0
  6. package/dist/types/components/composer/composer.d.ts +736 -0
  7. package/dist/types/components/run-status/run-status.d.ts +393 -0
  8. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  9. package/dist/types/components/source-list/source-list.d.ts +177 -0
  10. package/dist/types/core/messages.d.ts +135 -0
  11. package/dist/types/index.d.ts +8 -0
  12. package/dist/types/internal/agent-model.d.ts +587 -0
  13. package/dist/types/internal/highlight.d.ts +24 -0
  14. package/dist/types/internal/presence-loop.d.ts +148 -0
  15. package/dist/zx-zeyos.esm.js +4648 -4513
  16. package/dist/zx-zeyos.esm.min.js +2 -2
  17. package/dist/zx.css +1927 -1
  18. package/dist/zx.esm.js +15769 -9194
  19. package/dist/zx.esm.min.js +27 -8
  20. package/dist/zx.global.js +15769 -9194
  21. package/dist/zx.global.min.js +27 -8
  22. package/dist/zx.min.css +1 -1
  23. package/docs/api.json +1166 -5
  24. package/docs/llms.md +455 -2
  25. package/docs/llms.txt +10 -1
  26. package/package.json +1 -1
  27. package/src/components/agent-thread/agent-thread.css +417 -0
  28. package/src/components/agent-thread/agent-thread.js +1365 -0
  29. package/src/components/approval-card/approval-card.css +289 -0
  30. package/src/components/approval-card/approval-card.js +1377 -0
  31. package/src/components/avatar/avatar.css +56 -1
  32. package/src/components/avatar/avatar.js +148 -26
  33. package/src/components/block-view/block-view.css +300 -0
  34. package/src/components/block-view/block-view.js +523 -0
  35. package/src/components/composer/composer.css +403 -0
  36. package/src/components/composer/composer.js +1441 -0
  37. package/src/components/run-status/run-status.css +208 -0
  38. package/src/components/run-status/run-status.js +782 -0
  39. package/src/components/run-trace/run-trace.css +443 -0
  40. package/src/components/run-trace/run-trace.js +1209 -0
  41. package/src/components/source-list/source-list.css +208 -0
  42. package/src/components/source-list/source-list.js +355 -0
  43. package/src/core/messages.js +143 -0
  44. package/src/index.js +8 -0
  45. package/src/internal/agent-model.js +488 -0
  46. package/src/internal/highlight.js +104 -0
  47. package/src/internal/presence-loop.js +343 -0
  48. package/styles/zx.css +7 -0
@@ -0,0 +1,393 @@
1
+ import { Component } from '../../core/component.js';
2
+ export type RunState = import('../../internal/agent-model.js').RunState;
3
+ export type RunStatusAction = {
4
+ /**
5
+ * Visible label.
6
+ */
7
+ label: string;
8
+ /**
9
+ * Visual intent.
10
+ */
11
+ kind?: 'default' | 'primary' | 'danger' | 'ghost';
12
+ /**
13
+ * Icon name.
14
+ */
15
+ icon?: string | null;
16
+ /**
17
+ * Called on activation, before the `action` event.
18
+ */
19
+ onclick?: (event: MouseEvent) => void;
20
+ };
21
+ export type RunCost = {
22
+ /**
23
+ * Spent so far.
24
+ */
25
+ amount: number;
26
+ /**
27
+ * The most it may spend. With a budget the cost is a meter that
28
+ * turns to the warning tone from 80% and to the danger tone at 100%.
29
+ */
30
+ budget?: number | null;
31
+ /**
32
+ * ISO 4217 code, such as `EUR`.
33
+ */
34
+ currency?: string;
35
+ };
36
+ export type RunSteps = {
37
+ done: number;
38
+ total: number;
39
+ };
40
+ export type RunTokens = [number, number] | number;
41
+ export type RunCompactMode = 'word' | 'icon';
42
+ export type RunTokenMeter = {
43
+ /**
44
+ * Tokens used.
45
+ */
46
+ total: number;
47
+ /**
48
+ * The most the run may use.
49
+ */
50
+ budget: number;
51
+ /**
52
+ * `warning` from 80%, `danger` at 100%.
53
+ */
54
+ level: 'normal' | 'warning' | 'danger';
55
+ /**
56
+ * "22.8K of 60K tokens".
57
+ */
58
+ text: string;
59
+ };
60
+ export type RunTime = string | Date;
61
+ export type RunStatusOptions = {
62
+ /**
63
+ * Where the run stands. Also the root's `data-state`. A
64
+ * `blocked` run is not over: it shows since when it is blocked, never a finished time.
65
+ */
66
+ state?: RunState;
67
+ /**
68
+ * One sentence on what is happening: "Step 3 of 6 needs your
69
+ * approval." Text only.
70
+ */
71
+ summary?: string;
72
+ /**
73
+ * Steps done out of the total, drawn as a progressbar.
74
+ */
75
+ steps?: RunSteps | null;
76
+ /**
77
+ * When the run started.
78
+ */
79
+ started?: RunTime | null;
80
+ /**
81
+ * When it finished, failed, or was stopped. Shown once
82
+ * the run is over.
83
+ */
84
+ finished?: RunTime | null;
85
+ /**
86
+ * How long the agent has worked, in milliseconds. Waiting
87
+ * for a person is not work. The row shows only when this is a number.
88
+ */
89
+ workMs?: number | null;
90
+ /**
91
+ * Since when the run has waited for a person, or been
92
+ * blocked. Shown as "Waiting since" while the state is `waiting` and "Blocked since" while it is
93
+ * `blocked`.
94
+ */
95
+ waitingSince?: RunTime | null;
96
+ /**
97
+ * Input and output tokens as `[in, out]`, or the total as
98
+ * one number.
99
+ */
100
+ tokens?: RunTokens | null;
101
+ /**
102
+ * The most tokens the run may use. With a budget the
103
+ * tokens are a meter, read in compact figures ("22.8K of 60K tokens"), that turns to the warning
104
+ * tone from 80% and to the danger tone at 100%. Without one they stay text.
105
+ */
106
+ tokenBudget?: number | null;
107
+ /**
108
+ * What the run has cost, against its budget.
109
+ */
110
+ cost?: RunCost | null;
111
+ /**
112
+ * The model the agent runs on.
113
+ */
114
+ model?: string | null;
115
+ /**
116
+ * Buttons under the summary.
117
+ */
118
+ actions?: RunStatusAction[];
119
+ /**
120
+ * While the state is `running`, the working time counts on
121
+ * once a second from `workMs` and the moment of the last `update()`. One interval, which sleeps
122
+ * while the page is hidden.
123
+ */
124
+ ticking?: boolean;
125
+ /**
126
+ * Draws only the state: `true` as a pill of glyph and
127
+ * word for a narrow header, `'icon'` as the glyph alone, its word visually hidden but still the
128
+ * accessible text, and shown as the pill's tooltip.
129
+ */
130
+ compact?: boolean | 'icon';
131
+ /**
132
+ * The clock: what decides whether a time is today (a
133
+ * time on another day shows its date too) and what the working time counts against while
134
+ * `ticking`. Null is real time. Fixed at construction.
135
+ */
136
+ now?: (() => Date) | null;
137
+ /**
138
+ * BCP 47 tag for numbers and amounts; defaults to the active language.
139
+ */
140
+ locale?: string;
141
+ /**
142
+ * Localized
143
+ * messages: the state words (`agent.status.*`) and the `runStatus.*` labels.
144
+ */
145
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
146
+ /**
147
+ * Action listener.
148
+ */
149
+ onaction?: (event: CustomEvent<{
150
+ index: number;
151
+ action: RunStatusAction;
152
+ }>) => void;
153
+ };
154
+ export type RunStatusState = {
155
+ state: RunState;
156
+ summary: string;
157
+ steps: RunSteps | null;
158
+ started: RunTime | null;
159
+ finished: RunTime | null;
160
+ workMs: number | null;
161
+ waitingSince: RunTime | null;
162
+ tokens: RunTokens | null;
163
+ tokenBudget: number | null;
164
+ cost: RunCost | null;
165
+ model: string | null;
166
+ actions: RunStatusAction[];
167
+ };
168
+ /**
169
+ * Where an agent's run stands: its state in a glyph and a word, a sentence on what is happening,
170
+ * its steps as a progressbar, when it started and how long the agent has worked, what it has cost
171
+ * against its budget, and the buttons for what the reader can do about it now. `compact` draws the
172
+ * state alone, for a header.
173
+ *
174
+ * It announces nothing itself: the conversation the run belongs to says when it starts, waits,
175
+ * fails, or finishes.
176
+ *
177
+ * @fires RunStatus#action
178
+ * @extends {Component<RunStatusOptions>}
179
+ */
180
+ export declare class RunStatus extends Component<RunStatusOptions> {
181
+ _original: import("../../core/dom.js").TargetSnapshot;
182
+ /** @type {Record<string, any>} */
183
+ _values: Record<string, any>;
184
+ _workBase: number;
185
+ _workAt: number;
186
+ /** @type {HTMLElement|null} */
187
+ _elapsed: HTMLElement | null;
188
+ /** @type {HTMLElement|null} The action row as drawn, kept across updates that leave it unchanged. */
189
+ _actionsEl: HTMLElement | null;
190
+ _actionsKey: string;
191
+ /** Whether the root took `tabindex="-1"` to hold focus that had nowhere else to go. */
192
+ _heldFocus: boolean;
193
+ /** @type {ReturnType<typeof setInterval>|0} */
194
+ _interval: ReturnType<typeof setInterval> | 0;
195
+ _destroyed: boolean;
196
+ static cssName: string;
197
+ /** @type {Readonly<RunStatusOptions>} */
198
+ static defaults: Readonly<RunStatusOptions>;
199
+ /** @returns {HTMLElement} */
200
+ render(): HTMLElement;
201
+ /**
202
+ * Merges new values and redraws. The working time carries on from where it stood unless the
203
+ * update brings a new `workMs`. Focus inside the panel stays where it was: an action row that
204
+ * did not change is kept as it is, and otherwise focus moves to the action at the same index (or
205
+ * the nearest one left), or to the panel itself when no action is left.
206
+ * @param {Partial<Omit<RunStatusOptions, 'locale'|'msg'|'onaction'|'now'>>} values
207
+ * @returns {this}
208
+ */
209
+ update(values?: Partial<Omit<RunStatusOptions, 'locale' | 'msg' | 'onaction' | 'now'>>): this;
210
+ /** @returns {RunStatusState} The run's values as they stand, as copies. */
211
+ getState(): RunStatusState;
212
+ /** Stops the clock, removes what the component drew, and restores an enhanced target. @returns {void} */
213
+ destroy(): void;
214
+ /** @private @returns {number} Milliseconds on the clock the working time counts against. */
215
+ private _clock;
216
+ /** @private @returns {number|null} Milliseconds worked, including the time counted since the last update. */
217
+ private _workTime;
218
+ /** @private @returns {void} */
219
+ private _draw;
220
+ /**
221
+ * Puts the drawn parts in the root in order. A part kept from the last draw stays where it is
222
+ * rather than being taken out and put back, so focus inside it survives.
223
+ * @private
224
+ * @param {Array<Node|null>} parts
225
+ * @returns {void}
226
+ */
227
+ private _place;
228
+ /**
229
+ * The action row: the one already drawn when the actions read the same, a new one otherwise.
230
+ * @private
231
+ * @returns {HTMLElement|null}
232
+ */
233
+ private _actions;
234
+ /**
235
+ * Where focus is inside the panel, in terms that survive a redraw: the index of an action, or
236
+ * of a focusable element among all of them.
237
+ * @private
238
+ * @returns {{action: number}|{focusable: number}|null} Null when focus is elsewhere, or on the root.
239
+ */
240
+ private _focusKey;
241
+ /**
242
+ * Puts focus back after a redraw when the element that had it is gone: on the action at the same
243
+ * index or the nearest one left, else on the focusable at the same index, else on the root.
244
+ * @private
245
+ * @param {{action: number}|{focusable: number}|null} key What `_focusKey()` returned before the draw.
246
+ * @returns {void}
247
+ */
248
+ private _restoreFocus;
249
+ /** @private Gives back the `tabindex` the root took to hold focus. @returns {void} */
250
+ private _releaseFocus;
251
+ /** @private @param {RunState} state @returns {Node[]} The state's glyph and its word. */
252
+ private _stateParts;
253
+ /** @private @param {{done: number, total: number, percent: number}} steps @returns {HTMLElement} */
254
+ private _steps;
255
+ /**
256
+ * The property rows that apply to the state: started, working time, waiting or blocked since,
257
+ * or finished, then model, tokens, and cost.
258
+ * @private
259
+ * @param {RunState} state
260
+ * @returns {Array<[string, Node|string|Array<Node>]>}
261
+ */
262
+ private _rows;
263
+ /** @private @param {unknown} value @returns {HTMLElement|null} A `<time>` with the clock time, and the date when it is not today. */
264
+ private _time;
265
+ /** @private @param {unknown} cost @returns {Node[]|null} The cost, and a meter against the budget when there is one. */
266
+ private _cost;
267
+ /**
268
+ * A thin `role="meter"` bar of a value against its limit, toned by how close it is.
269
+ * @private
270
+ * @param {string} label
271
+ * @param {number} value
272
+ * @param {number} limit
273
+ * @param {string} text The value in words, its `aria-valuetext`.
274
+ * @returns {HTMLElement}
275
+ */
276
+ private _meter;
277
+ /** @private @returns {boolean} Whether the working time should count on screen now. */
278
+ private _shouldTick;
279
+ /** @private @returns {void} */
280
+ private _syncTicker;
281
+ /** @private @returns {void} */
282
+ private _stopTicker;
283
+ /** @private @returns {void} */
284
+ private _tick;
285
+ /** @private @param {MouseEvent} event @returns {void} */
286
+ private _onClick;
287
+ }
288
+ /**
289
+ * How close a run's cost is to its budget: `'warning'` from 80%, `'danger'` at 100% and over,
290
+ * `'normal'` below, and without a budget.
291
+ * @param {number} amount
292
+ * @param {number|null|undefined} budget
293
+ * @returns {'normal'|'warning'|'danger'}
294
+ */
295
+ export declare function costLevel(amount: number, budget: number | null | undefined): 'normal' | 'warning' | 'danger';
296
+ /**
297
+ * Reads a steps count: whole numbers, the done count kept within the total. Null for no steps.
298
+ * @param {unknown} steps `{done, total}`.
299
+ * @returns {{done: number, total: number, percent: number}|null}
300
+ */
301
+ export declare function stepProgress(steps: unknown): {
302
+ done: number;
303
+ total: number;
304
+ percent: number;
305
+ } | null;
306
+ /**
307
+ * Token counts in words: "18,420 in · 1,236 out" for a pair, "22,840" for a total. Empty without
308
+ * counts.
309
+ * @param {unknown} tokens `[input, output]`, or the total as one number.
310
+ * @param {{locale?: string, template?: string}} [options={}] `template` takes the two formatted
311
+ * counts of a pair as `%1` and `%2`.
312
+ * @returns {string}
313
+ */
314
+ export declare function formatTokens(tokens: unknown, options?: {
315
+ locale?: string;
316
+ template?: string;
317
+ }): string;
318
+ /**
319
+ * How many tokens a run has used in all: the number itself, or input and output added up.
320
+ * @param {unknown} tokens `[input, output]`, or the total as one number.
321
+ * @returns {number|null} Null without counts.
322
+ */
323
+ export declare function tokenTotal(tokens: unknown): number | null;
324
+ /**
325
+ * A count in the locale's compact notation (`Intl.NumberFormat` with `notation: 'compact'`) and at
326
+ * most one decimal: "22.8K", "60K", "1.2M" in English, "22.840" in German, which has no compact
327
+ * form for thousands.
328
+ * @param {number} value
329
+ * @param {{locale?: string}} [options={}]
330
+ * @returns {string} Empty for anything that is not a finite number.
331
+ */
332
+ export declare function formatCompactNumber(value: number, options?: {
333
+ locale?: string;
334
+ }): string;
335
+ /**
336
+ * The tokens as a meter against their budget: the total, the budget, the level (`warning` from
337
+ * 80%, `danger` at 100%, as for the cost), and the words "22.8K of 60K tokens". Null without
338
+ * counts or without a budget above zero, when the tokens stay text.
339
+ * @param {unknown} tokens `[input, output]`, or the total as one number.
340
+ * @param {unknown} budget The most tokens the run may use.
341
+ * @param {{locale?: string, template?: string}} [options={}] `template` takes the compact total and
342
+ * budget as `%1` and `%2`.
343
+ * @returns {RunTokenMeter|null}
344
+ */
345
+ export declare function tokenMeter(tokens: unknown, budget: unknown, options?: {
346
+ locale?: string;
347
+ template?: string;
348
+ }): RunTokenMeter | null;
349
+ /**
350
+ * Reads the `compact` option: `'icon'` for the glyph alone, `'word'` for any other truthy value
351
+ * (the pill of glyph and word), null for the full panel.
352
+ * @param {unknown} value
353
+ * @returns {RunCompactMode|null}
354
+ */
355
+ export declare function compactMode(value: unknown): RunCompactMode | null;
356
+ /**
357
+ * The message keys of the time rows a state shows besides "Started": the "since" row while the
358
+ * run is held (`waiting`: "Waiting since", `blocked`: "Blocked since"), and the "finished" row
359
+ * once it is over ("Finished", "Failed at", "Stopped at"). A blocked run is not over, so it never
360
+ * shows a finished row.
361
+ * @param {unknown} state
362
+ * @returns {{since: string|null, finished: string|null}}
363
+ */
364
+ export declare function runTimeKeys(state: unknown): {
365
+ since: string | null;
366
+ finished: string | null;
367
+ };
368
+ /**
369
+ * Reads the `now` option: the date its function returns (a `Date` or a millisecond timestamp),
370
+ * or the real time when there is no function or it returns nothing usable.
371
+ * @param {unknown} now
372
+ * @returns {Date}
373
+ */
374
+ export declare function currentTime(now: unknown): Date;
375
+ /**
376
+ * A run's cost in words: "€0.14 of €2.00" against a budget, "€0.14" without one. Empty without a
377
+ * cost.
378
+ * @param {unknown} cost `{amount, budget?, currency?}`.
379
+ * @param {{locale?: string, template?: string}} [options={}] `template` takes the amount and the
380
+ * budget as `%1` and `%2`.
381
+ * @returns {string}
382
+ */
383
+ export declare function formatRunCost(cost: unknown, options?: {
384
+ locale?: string;
385
+ template?: string;
386
+ }): string;
387
+ /**
388
+ * Reads a run time: a `Date`, or a local ISO date-time string (`2026-09-29T11:20:04`; a bare date
389
+ * is midnight local time). Null for anything else.
390
+ * @param {unknown} value
391
+ * @returns {Date|null}
392
+ */
393
+ export declare function runDate(value: unknown): Date | null;