@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,1209 @@
1
+ // @ts-check
2
+ import { Component } from '../../core/component.js';
3
+ import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
4
+ import { icon } from '../../core/icons.js';
5
+ import { formatNumber } from '../../core/format.js';
6
+ import { prefersReducedMotion } from '../../core/motion.js';
7
+ import { uid } from '../../core/util.js';
8
+ import {
9
+ AGENT_MESSAGES, STATUS, formatDuration, formatElapsed, initialsOf, normalizeRunState, traceSummary
10
+ } from '../../internal/agent-model.js';
11
+ import { Avatar } from '../avatar/avatar.js';
12
+ import { copyButton } from '../copy/copy-button.js';
13
+ import { statusIcon } from '../select/glyphs.js';
14
+
15
+ /** @typedef {import('../../internal/agent-model.js').TraceStep} TraceStep */
16
+ /** @typedef {import('../../internal/agent-model.js').Author} Author */
17
+ /** @typedef {import('../../internal/agent-model.js').ItemRef} ItemRef */
18
+ /** @typedef {import('../../internal/agent-model.js').RunState} RunState */
19
+ /** @typedef {import('../avatar/avatar.js').AvatarTone} AvatarTone */
20
+
21
+ /**
22
+ * What kind of step a trace step is: it picks the glyph, and whether the summary counts it as a
23
+ * tool call. `task` is a planned step, `ask` a request a person made, `decision` a person's
24
+ * answer; with `think` and `handoff` they are not tool calls.
25
+ * @typedef {'search'|'read'|'query'|'write'|'run'|'call'|'handoff'|'think'|'task'|'ask'|'decision'} TraceKind
26
+ */
27
+
28
+ /**
29
+ * How a step's row behaves: a disclosure button when the step has something to open, a plain
30
+ * button when the trace is `selectable`, otherwise a static row.
31
+ * @typedef {'disclosure'|'select'|'static'} RowKind
32
+ */
33
+
34
+ /**
35
+ * One piece of a step's muted meta line, in the order drawn.
36
+ * @typedef {Object} MetaPart
37
+ * @property {'label'|'count'|'sources'|'actor'|'time'|'tokens'} part What the piece is: a
38
+ * hand-off's own label, the count, a search's sources, who took the step, when it started, the
39
+ * tokens it used.
40
+ * @property {string} text The words shown.
41
+ */
42
+
43
+ /**
44
+ * @typedef {Object} RunTraceOptions
45
+ * @property {TraceStep[]} [steps=[]] The steps the run took, in the order they started. A step
46
+ * with `retryOf` is drawn under the step it repeats. Model text is data: every string reaches the
47
+ * page as text.
48
+ * @property {boolean} [open=false] Whether the step list starts open under its summary.
49
+ * @property {string|null} [label=null] Text the summary reads instead of the computed "Worked for
50
+ * …" line — a plan's title, "Plan · 5 of 6 done". Any state but done still follows it as a word
51
+ * ("· Running"). `setLabel()` changes it.
52
+ * @property {Record<string, Author>} [authors={}] Who the `actor` and `to` keys of the steps name;
53
+ * a hand-off draws both authors' avatars, round for a `person` and rounded squares otherwise. A key
54
+ * with no entry is shown as written.
55
+ * @property {boolean} [showArguments=true] Whether a step's disclosure shows the arguments its call
56
+ * was made with.
57
+ * @property {number} [maxResult=4000] Characters of a result shown before it is cut, with a
58
+ * "Show all" button for the rest. Zero or a non-finite value shows every result whole.
59
+ * @property {boolean} [summary=true] Whether the steps fold into a summary line. Without it the
60
+ * list always shows — for a run panel whose state is already told beside it.
61
+ * @property {boolean|null} [kindIcons=null] 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
+ * @property {boolean} [selectable=false] Whether every step can be chosen: a row with nothing to
65
+ * open becomes a button, and a disclosure also reports the step as it opens. Both emit `select`.
66
+ * @property {boolean} [ticking=false] Whether a running step that has `at` shows how long it has
67
+ * run, counting once a second. One interval serves the whole trace; it runs only while such a step
68
+ * is on screen in the open list, and sleeps while the page is hidden.
69
+ * @property {(() => Date)|null} [now=null] The clock `ticking` counts against, for an application
70
+ * whose world is fixed on another date; real time when null.
71
+ * @property {((at: string) => string)|null} [formatTime=null] Writes a step's `at` for its meta
72
+ * line; "10:31:05" (the local ISO time as given) when null.
73
+ * @property {Partial<Record<TraceKind, string>>} [icons={}] Icon names per step kind, over the
74
+ * built-in `STEP_ICONS`.
75
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized
76
+ * messages: the `runTrace.*` keys and the `agent.status.*` words.
77
+ * @property {(event: CustomEvent<{id: string|null, open: boolean}>) => void} [ontoggle] Disclosure
78
+ * listener.
79
+ * @property {(event: CustomEvent<{id: string}>) => void} [onreveal] Reveal listener.
80
+ * @property {(event: CustomEvent<{id: string}>) => void} [onselect] Selection listener
81
+ * (`selectable` traces).
82
+ * @property {(event: CustomEvent<{step: TraceStep, ref: ItemRef}>) => void} [onopen] Listener for
83
+ * a step's links.
84
+ */
85
+
86
+ /**
87
+ * One drawn step.
88
+ * @typedef {Object} StepEntry
89
+ * @property {TraceStep & {id: string}} step The step as last given.
90
+ * @property {HTMLElement} li Its list item; it outlives redraws of the step.
91
+ * @property {HTMLElement|null} row The row: a disclosure button, a select button, or a plain row.
92
+ * @property {HTMLElement|null} refs The step's links, after its row.
93
+ * @property {HTMLElement|null} body The disclosure's content, when the step has any.
94
+ * @property {HTMLElement|null} retries The nested list of the steps that repeat this one.
95
+ * @property {Avatar[]} avatars Avatars the row owns.
96
+ * @property {string|null} rootId The top-level step a retry is drawn under; null for a top-level step.
97
+ * @property {string|null} bodyId Id of the disclosure content.
98
+ */
99
+
100
+ /**
101
+ * The trace's overall state and its one-line summary.
102
+ * @typedef {Object} TraceLabel
103
+ * @property {RunState} state `running`, `waiting`, `blocked`, `paused`, `stopped`, `failed`,
104
+ * `queued` (no step has started), or `done`.
105
+ * @property {string} label The summary line: "Worked for 41 s · 5 tool calls · 1 retry".
106
+ * @property {string|null} doing What the running step is doing, or which step is waiting or
107
+ * blocked, without an ellipsis.
108
+ */
109
+
110
+ /** Built-in glyph per step kind. */
111
+ export const STEP_ICONS = Object.freeze({
112
+ search: 'search',
113
+ read: 'file',
114
+ query: 'table',
115
+ write: 'type',
116
+ run: 'code',
117
+ call: 'gear',
118
+ handoff: 'link-2',
119
+ think: 'dots',
120
+ task: 'list',
121
+ ask: 'mail',
122
+ decision: 'check'
123
+ });
124
+
125
+ const MESSAGES = Object.freeze({
126
+ ...AGENT_MESSAGES,
127
+ 'runTrace.label': 'Steps',
128
+ 'runTrace.worked': 'Worked for %1',
129
+ 'runTrace.stoppedAfter': 'Stopped after %1',
130
+ 'runTrace.failedAfter': 'Failed after %1',
131
+ 'runTrace.blockedAfter': 'Blocked after %1',
132
+ 'runTrace.working': 'Working…',
133
+ 'runTrace.step': '1 step',
134
+ 'runTrace.steps': '%1 steps',
135
+ 'runTrace.call': '1 tool call',
136
+ 'runTrace.calls': '%1 tool calls',
137
+ 'runTrace.source': '1 source',
138
+ 'runTrace.sources': '%1 sources',
139
+ 'runTrace.retry': '1 retry',
140
+ 'runTrace.retries': '%1 retries',
141
+ 'runTrace.token': '1 token',
142
+ 'runTrace.tokens': '%1 tokens',
143
+ 'runTrace.doing': '%1…',
144
+ 'runTrace.retried': 'Retried',
145
+ 'runTrace.handoff': '%1 handed over to %2',
146
+ 'runTrace.arguments': 'Arguments',
147
+ 'runTrace.result': 'Result',
148
+ 'runTrace.error': 'Error',
149
+ 'runTrace.copyArguments': 'Copy arguments',
150
+ 'runTrace.copyResult': 'Copy result',
151
+ 'runTrace.copyError': 'Copy error',
152
+ 'runTrace.copied': 'Copied',
153
+ 'runTrace.showAll': 'Show all',
154
+ 'runTrace.awaiting': 'Waiting for the result…'
155
+ });
156
+
157
+ /** How long a revealed step stays marked, in milliseconds. */
158
+ const REVEAL_MS = 2000;
159
+
160
+ /** How often a running step's clock counts, in milliseconds. */
161
+ const TICK_MS = 1000;
162
+
163
+ /** Sections of a step's disclosure, with their title and copy-button message keys. */
164
+ const SECTIONS = Object.freeze({
165
+ arguments: { title: 'runTrace.arguments', copy: 'runTrace.copyArguments' },
166
+ result: { title: 'runTrace.result', copy: 'runTrace.copyResult' },
167
+ error: { title: 'runTrace.error', copy: 'runTrace.copyError' }
168
+ });
169
+
170
+ /**
171
+ * What an agent did during a run: a one-line summary ("Worked for 41 s · 5 tool calls") that
172
+ * opens into a timeline of its steps. A tool call opens in turn to the arguments it was made with
173
+ * and what came back; a retry is drawn under the call it repeats; a hand-off shows both agents.
174
+ *
175
+ * The trace renders the steps it is given and changes only when the application calls
176
+ * `setSteps()` or `upsert()`; a live run upserts each step as it starts and again as it ends, and
177
+ * only that step is redrawn. The same component draws a plan: `task` steps under a `label` of the
178
+ * plan's own, chosen one at a time with `selectable`.
179
+ *
180
+ * @fires RunTrace#toggle
181
+ * @fires RunTrace#reveal
182
+ * @fires RunTrace#select
183
+ * @fires RunTrace#open
184
+ * @extends {Component<RunTraceOptions>}
185
+ */
186
+ export class RunTrace extends Component {
187
+ static cssName = 'run-trace';
188
+
189
+ /** @type {Readonly<RunTraceOptions>} */
190
+ static defaults = {
191
+ steps: [],
192
+ open: false,
193
+ label: null,
194
+ authors: {},
195
+ showArguments: true,
196
+ maxResult: 4000,
197
+ summary: true,
198
+ kindIcons: null,
199
+ selectable: false,
200
+ ticking: false,
201
+ now: null,
202
+ formatTime: null,
203
+ icons: {},
204
+ msg: MESSAGES
205
+ };
206
+
207
+ /** @returns {HTMLElement} */
208
+ render() {
209
+ const created = !this.el;
210
+ const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
211
+ this.el = root;
212
+ this._original = created ? null : snapshotTarget(root);
213
+ if (!created) root.replaceChildren();
214
+ this._destroyed = false;
215
+ this._open = Boolean(this.options.open);
216
+ /** @type {string|null} The summary text set by `label` or `setLabel()`. */
217
+ this._label = ownLabel(this.options.label);
218
+ /** @type {Array<TraceStep & {id: string}>} */
219
+ this._steps = [];
220
+ /** @type {Map<string, StepEntry>} */
221
+ this._entries = new Map();
222
+ /** @type {Set<string>} Steps whose disclosure is open. */
223
+ this._expanded = new Set();
224
+ /** @type {Set<string>} Steps whose long result is shown whole. */
225
+ this._whole = new Set();
226
+ /** @type {ReturnType<typeof setTimeout>|null} */
227
+ this._revealTimer = null;
228
+ /** @type {ReturnType<typeof setInterval>|null} The one clock every running step counts by. */
229
+ this._clock = null;
230
+
231
+ const listId = uid('zx-run-trace');
232
+ this._summaryState = h('span', { class: 'zx-run-trace__summary-state', hidden: true });
233
+ this._summaryText = h('span', { class: 'zx-run-trace__summary-text' });
234
+ this._summaryDoing = h('span', { class: 'zx-run-trace__summary-doing', hidden: true });
235
+ this._summary = h('button', {
236
+ type: 'button',
237
+ class: 'zx-run-trace__summary',
238
+ 'aria-expanded': String(this._open),
239
+ 'aria-controls': listId,
240
+ dataset: { action: 'summary' }
241
+ },
242
+ h('span', { class: 'zx-run-trace__chevron', 'aria-hidden': 'true' }, icon('chevron-right', { size: 14 })),
243
+ this._summaryState, this._summaryText, this._summaryDoing);
244
+ this._list = h('ol', {
245
+ class: 'zx-run-trace__steps', id: listId, 'aria-label': this.msg('runTrace.label'), hidden: !this._open
246
+ });
247
+ root.append(this._summary, this._list);
248
+ if (this.options.summary === false) {
249
+ this._summary.hidden = true;
250
+ this._list.hidden = false;
251
+ this._open = true;
252
+ }
253
+
254
+ this.listen(root, 'click', (event) => this._onClick(/** @type {MouseEvent} */ (event)));
255
+ this.listen(root, 'focusout', (event) => {
256
+ // A plain row is focusable only while a reveal has put focus on it.
257
+ const target = /** @type {HTMLElement|null} */ (event.target instanceof HTMLElement ? event.target : null);
258
+ if (target?.dataset.revealFocus !== undefined) {
259
+ target.removeAttribute('tabindex');
260
+ delete target.dataset.revealFocus;
261
+ }
262
+ });
263
+ if (this.options.ticking) this.listen(root.ownerDocument, 'visibilitychange', () => this._syncClock());
264
+ this._build(this.options.steps);
265
+ return root;
266
+ }
267
+
268
+ /**
269
+ * Sets the text the summary reads instead of the computed line; null or an empty string goes
270
+ * back to "Worked for …". Any state but done still follows it as a word.
271
+ * @param {string|null} label
272
+ * @returns {this}
273
+ */
274
+ setLabel(label) {
275
+ this._label = ownLabel(label);
276
+ this._sync();
277
+ return this;
278
+ }
279
+
280
+ /**
281
+ * Replaces every step. Open steps stay open, and focus on a step's row stays on that step.
282
+ * @param {TraceStep[]} steps
283
+ * @returns {this}
284
+ */
285
+ setSteps(steps) {
286
+ this._build(steps);
287
+ return this;
288
+ }
289
+
290
+ /**
291
+ * Adds a step, or replaces the step with the same `id`. A replaced step is redrawn on its own,
292
+ * keeping its place, its open state, and the retries under it; a new step is appended, under
293
+ * the step it repeats when it has `retryOf`.
294
+ * @param {TraceStep} step
295
+ * @returns {this}
296
+ */
297
+ upsert(step) {
298
+ if (!step || typeof step !== 'object' || step.id == null || step.id === '') return this;
299
+ const next = { ...step, id: String(step.id) };
300
+ const entry = this._entries.get(next.id);
301
+ if (entry) {
302
+ if (String(entry.step.retryOf ?? '') !== String(next.retryOf ?? '')) {
303
+ // It moved under another step: regroup the whole trace.
304
+ this._build(this._steps.map((current) => (current.id === next.id ? next : current)));
305
+ return this;
306
+ }
307
+ this._steps[this._steps.indexOf(entry.step)] = next;
308
+ entry.step = next;
309
+ this._paint(entry);
310
+ } else {
311
+ this._steps.push(next);
312
+ const rootId = this._rootOf(next);
313
+ if (rootId) this._appendRetry(rootId, next);
314
+ else this._list.append(this._createEntry(next, null));
315
+ }
316
+ this._sync();
317
+ return this;
318
+ }
319
+
320
+ /**
321
+ * Opens the step list, and the disclosure of the step `id` when one is given.
322
+ * @param {string|null} [id=null]
323
+ * @returns {this}
324
+ */
325
+ expand(id = null) {
326
+ this._setOpen(true);
327
+ if (id != null) this._setStep(String(id), true);
328
+ return this;
329
+ }
330
+
331
+ /**
332
+ * Closes the step list, or only the disclosure of the step `id` when one is given.
333
+ * @param {string|null} [id=null]
334
+ * @returns {this}
335
+ */
336
+ collapse(id = null) {
337
+ if (id == null) this._setOpen(false);
338
+ else this._setStep(String(id), false);
339
+ return this;
340
+ }
341
+
342
+ /**
343
+ * Shows one step: opens the list and the step, scrolls it into view, puts focus on its row, and
344
+ * marks it with `data-state="revealed"` for two seconds. Under reduced motion the scroll jumps.
345
+ * An unknown id does nothing.
346
+ * @param {string} id
347
+ * @returns {this}
348
+ * @fires RunTrace#reveal
349
+ */
350
+ reveal(id) {
351
+ const entry = this._entries.get(String(id));
352
+ if (!entry?.row) return this;
353
+ this.expand(entry.step.id);
354
+ const row = entry.row;
355
+ for (const other of /** @type {NodeListOf<HTMLElement>} */ (this._list.querySelectorAll('[data-reveal-focus]'))) {
356
+ if (other === row) continue;
357
+ other.removeAttribute('tabindex');
358
+ delete other.dataset.revealFocus;
359
+ }
360
+ const smooth = !prefersReducedMotion(this.el);
361
+ if (typeof entry.li.scrollIntoView === 'function') {
362
+ entry.li.scrollIntoView({ block: 'nearest', behavior: smooth ? 'smooth' : 'auto' });
363
+ }
364
+ if (row.localName !== 'button') {
365
+ row.tabIndex = -1;
366
+ row.dataset.revealFocus = '';
367
+ }
368
+ row.focus({ preventScroll: true });
369
+ this._mark(entry.li);
370
+ this.emit('reveal', { id: entry.step.id });
371
+ return this;
372
+ }
373
+
374
+ /** @returns {TraceStep[]} Copies of the steps, in the order they were given. */
375
+ getSteps() {
376
+ return this._steps.map((step) => ({ ...step }));
377
+ }
378
+
379
+ /** @returns {boolean} Whether the step list is open. */
380
+ isOpen() {
381
+ return this._open;
382
+ }
383
+
384
+ /** @returns {void} */
385
+ destroy() {
386
+ if (this._destroyed) return;
387
+ this._destroyed = true;
388
+ if (this._revealTimer) clearTimeout(this._revealTimer);
389
+ this._revealTimer = null;
390
+ if (this._clock) clearInterval(this._clock);
391
+ this._clock = null;
392
+ for (const entry of this._entries.values()) this._releaseAvatars(entry);
393
+ this._entries.clear();
394
+ super.destroy();
395
+ if (this._original) restoreTarget(this.el, this._original);
396
+ }
397
+
398
+ /* ------------------------------------------------------------------ building -- */
399
+
400
+ /**
401
+ * @private
402
+ * @param {unknown} steps
403
+ * @returns {void}
404
+ */
405
+ _build(steps) {
406
+ const focused = this._focusedStep();
407
+ for (const entry of this._entries.values()) this._releaseAvatars(entry);
408
+ this._entries.clear();
409
+ this._list.replaceChildren();
410
+ this._steps = normalizeSteps(steps);
411
+ for (const group of groupRetries(this._steps)) {
412
+ this._list.append(this._createEntry(/** @type {TraceStep & {id: string}} */ (group.step), null));
413
+ for (const retry of group.retries) this._appendRetry(String(group.step.id), /** @type {TraceStep & {id: string}} */ (retry));
414
+ }
415
+ for (const id of [...this._expanded]) if (!this._entries.has(id)) this._expanded.delete(id);
416
+ for (const id of [...this._whole]) if (!this._entries.has(id)) this._whole.delete(id);
417
+ if (focused) this._entries.get(focused)?.row?.focus({ preventScroll: true });
418
+ this._sync();
419
+ }
420
+
421
+ /**
422
+ * @private
423
+ * @param {TraceStep & {id: string}} step
424
+ * @param {string|null} rootId
425
+ * @returns {HTMLElement}
426
+ */
427
+ _createEntry(step, rootId) {
428
+ const li = h('li', { class: 'zx-run-trace__step', dataset: { step: step.id } });
429
+ /** @type {StepEntry} */
430
+ const entry = { step, li, row: null, refs: null, body: null, retries: null, avatars: [], rootId, bodyId: null };
431
+ this._entries.set(step.id, entry);
432
+ this._paint(entry);
433
+ return li;
434
+ }
435
+
436
+ /**
437
+ * @private
438
+ * @param {string} rootId
439
+ * @param {TraceStep & {id: string}} step
440
+ * @returns {void}
441
+ */
442
+ _appendRetry(rootId, step) {
443
+ const root = this._entries.get(rootId);
444
+ if (!root) {
445
+ this._list.append(this._createEntry(step, null));
446
+ return;
447
+ }
448
+ if (!root.retries) {
449
+ root.retries = h('ol', { class: 'zx-run-trace__retries' });
450
+ root.li.append(root.retries);
451
+ }
452
+ root.retries.append(this._createEntry(step, rootId));
453
+ }
454
+
455
+ /**
456
+ * The top-level step a new step is drawn under, or null when it repeats nothing drawn.
457
+ * @private
458
+ * @param {TraceStep} step
459
+ * @returns {string|null}
460
+ */
461
+ _rootOf(step) {
462
+ if (step.retryOf == null || step.retryOf === '') return null;
463
+ const parent = this._entries.get(String(step.retryOf));
464
+ if (!parent || parent.step.id === step.id) return null;
465
+ return parent.rootId ?? parent.step.id;
466
+ }
467
+
468
+ /**
469
+ * Draws a step's row, links, and disclosure, replacing the ones it had. The list item, its
470
+ * marks, and the retries under it stay; focus on the row, a link, or the disclosure stays on
471
+ * the step.
472
+ * @private
473
+ * @param {StepEntry} entry
474
+ * @returns {void}
475
+ */
476
+ _paint(entry) {
477
+ const { step, li } = entry;
478
+ const active = this.el.ownerDocument?.activeElement ?? null;
479
+ const focusedRef = active && entry.refs?.contains(active)
480
+ ? /** @type {HTMLElement|null} */ (active.closest('[data-ref-index]'))?.dataset.refIndex ?? null
481
+ : null;
482
+ const hadFocus = Boolean(active && (entry.row?.contains(active) || entry.refs?.contains(active) || entry.body?.contains(active)));
483
+ this._releaseAvatars(entry);
484
+
485
+ const status = normalizeRunState(step.status);
486
+ const kind = normalizeKind(step.kind);
487
+ li.dataset.kind = kind;
488
+ li.dataset.status = status;
489
+ if (status === 'running') li.setAttribute('aria-current', 'step');
490
+ else li.removeAttribute('aria-current');
491
+
492
+ const mode = rowKind(step, this.options);
493
+ const disclosure = mode === 'disclosure';
494
+ if (disclosure && !entry.bodyId) entry.bodyId = uid('zx-run-trace-step');
495
+ const open = disclosure && this._expanded.has(step.id);
496
+ if (!disclosure) this._expanded.delete(step.id);
497
+
498
+ const content = [
499
+ h('span', { class: 'zx-run-trace__tile', 'aria-hidden': 'true' }, icon(this._icon(kind), { size: 14 })),
500
+ this._text(entry, kind, status),
501
+ this._end(step, status),
502
+ h('span', { class: 'zx-run-trace__chevron', 'aria-hidden': 'true' },
503
+ disclosure ? icon('chevron-down', { size: 14 }) : null)
504
+ ];
505
+ let row;
506
+ if (disclosure) {
507
+ row = h('button', {
508
+ type: 'button',
509
+ class: 'zx-run-trace__row',
510
+ 'aria-expanded': String(open),
511
+ 'aria-controls': entry.bodyId,
512
+ dataset: { action: 'step' }
513
+ }, content);
514
+ } else if (mode === 'select') {
515
+ row = h('button', { type: 'button', class: 'zx-run-trace__row', dataset: { action: 'select' } }, content);
516
+ } else {
517
+ row = h('div', { class: 'zx-run-trace__row' }, content);
518
+ }
519
+ // The links sit beside the row, never inside it: a button holds no other controls.
520
+ const refs = this._refs(step);
521
+ const body = disclosure ? this._body(step, /** @type {string} */ (entry.bodyId), open) : null;
522
+
523
+ if (entry.row) entry.row.replaceWith(row);
524
+ else li.prepend(row);
525
+ entry.refs?.remove();
526
+ entry.body?.remove();
527
+ if (refs) row.after(refs);
528
+ if (body) (refs ?? row).after(body);
529
+ entry.row = row;
530
+ entry.refs = refs;
531
+ entry.body = body;
532
+ const again = focusedRef === null ? null
533
+ : /** @type {HTMLElement|null} */ (refs?.querySelector(`[data-ref-index="${focusedRef}"]`) ?? null);
534
+ if (again) again.focus({ preventScroll: true });
535
+ else if (hadFocus) row.focus({ preventScroll: true });
536
+ }
537
+
538
+ /**
539
+ * The step's links to the application's own things, as a list of quiet buttons, or null when it
540
+ * has none.
541
+ * @private
542
+ * @param {TraceStep} step
543
+ * @returns {HTMLElement|null}
544
+ */
545
+ _refs(step) {
546
+ const list = stepRefs(step);
547
+ if (!list.length) return null;
548
+ return h('ul', { class: 'zx-run-trace__refs' }, list.map(({ ref, index }) => h('li', {},
549
+ h('button', { type: 'button', class: 'zx-run-trace__ref', dataset: { action: 'ref', refIndex: String(index) } },
550
+ text(ref.icon) ? h('span', { class: 'zx-run-trace__ref-icon', 'aria-hidden': 'true' }, icon(text(ref.icon), { size: 14 })) : null,
551
+ h('span', { class: 'zx-run-trace__ref-label' }, text(ref.label))))));
552
+ }
553
+
554
+ /**
555
+ * The step's words: what it did (or is doing), a "Retried" tag, a hand-off's two avatars, and a
556
+ * muted line of its count, who took it, when, and the tokens it used.
557
+ * @private
558
+ * @param {StepEntry} entry
559
+ * @param {TraceKind} kind
560
+ * @param {RunState} status
561
+ * @returns {HTMLElement}
562
+ */
563
+ _text(entry, kind, status) {
564
+ const { step } = entry;
565
+ const label = text(step.label);
566
+ const handoff = kind === 'handoff' && (step.actor || step.to);
567
+ const handoffWords = handoff ? this.msg('runTrace.handoff', this._author(step.actor).name, this._author(step.to).name) : '';
568
+ const doing = text(step.doing).replace(/(?:…|\.\.\.)\s*$/, '');
569
+ const main = status === 'running' && doing ? this.msg('runTrace.doing', doing) : handoffWords || label;
570
+ const parts = stepMeta(step, {
571
+ msg: (key, ...args) => this.msg(key, ...args),
572
+ name: (key) => this._author(key).name,
573
+ formatTime: this.options.formatTime
574
+ });
575
+ const meta = parts.length ? h('span', { class: 'zx-run-trace__meta' }, parts.flatMap((part, index) => {
576
+ const node = part.part === 'time'
577
+ ? h('time', { class: 'zx-run-trace__clock', dateTime: text(step.at) }, part.text)
578
+ : part.text;
579
+ return index ? [' · ', node] : [node];
580
+ })) : null;
581
+ let pair = null;
582
+ if (handoff) {
583
+ const from = this._avatar(step.actor);
584
+ const to = this._avatar(step.to);
585
+ entry.avatars.push(from, to);
586
+ pair = h('span', { class: 'zx-run-trace__handoff', 'aria-hidden': 'true' },
587
+ from.toElement(), h('span', { class: 'zx-run-trace__handoff-line' }), to.toElement());
588
+ }
589
+ return h('span', { class: 'zx-run-trace__text' },
590
+ h('span', { class: 'zx-run-trace__line' },
591
+ entry.rootId ? h('span', { class: 'zx-run-trace__retry' }, this.msg('runTrace.retried')) : null,
592
+ pair,
593
+ h('span', { class: 'zx-run-trace__label' }, main)),
594
+ meta);
595
+ }
596
+
597
+ /**
598
+ * The step's state: always a glyph and a word. The word is visible for the states a reader has
599
+ * to notice; a finished step shows its duration instead, and a running one says what it is doing
600
+ * and, with `ticking`, how long it has run.
601
+ * @private
602
+ * @param {TraceStep} step
603
+ * @param {RunState} status
604
+ * @returns {HTMLElement}
605
+ */
606
+ _end(step, status) {
607
+ const state = STATUS[status];
608
+ const quiet = status === 'done' || status === 'running';
609
+ const ms = typeof step.ms === 'number' && Number.isFinite(step.ms) ? step.ms : null;
610
+ // A resumed step counts on from what it had worked before (`ms`) rather than from zero.
611
+ const start = status === 'running' && this.options.ticking ? startOf(step.at) : null;
612
+ const since = start !== null ? start - (ms ?? 0) : null;
613
+ let time = null;
614
+ if (status === 'done' && ms !== null) {
615
+ time = h('span', { class: 'zx-run-trace__time' }, formatDuration(ms));
616
+ } else if (since !== null) {
617
+ time = h('span', { class: 'zx-run-trace__time', dataset: { since: String(since) } }, elapsedSince(since, this._now()));
618
+ }
619
+ return h('span', { class: 'zx-run-trace__end' },
620
+ statusIcon(state.status, { tone: state.tone }),
621
+ h('span', { class: quiet ? 'zx-run-trace__sr' : 'zx-run-trace__word' }, this.msg(state.key)),
622
+ time);
623
+ }
624
+
625
+ /**
626
+ * A step's disclosure: the tool, the detail, the arguments, and the result or the error. Who
627
+ * took the step and when are on its row.
628
+ * @private
629
+ * @param {TraceStep & {id: string}} step
630
+ * @param {string} id
631
+ * @param {boolean} open
632
+ * @returns {HTMLElement}
633
+ */
634
+ _body(step, id, open) {
635
+ const status = normalizeRunState(step.status);
636
+ const args = this.options.showArguments !== false && text(step.args) ? prettyArguments(step.args) : '';
637
+ return h('div', { class: 'zx-run-trace__body', id, hidden: !open },
638
+ text(step.tool) ? h('p', { class: 'zx-run-trace__tool' },
639
+ h('code', { class: 'zx-run-trace__tool-name' }, text(step.tool))) : null,
640
+ text(step.detail) ? h('p', { class: 'zx-run-trace__note' }, text(step.detail)) : null,
641
+ args ? this._section('arguments', args, step.id) : null,
642
+ text(step.result) ? this._section('result', text(step.result), step.id) : null,
643
+ text(step.error) ? this._section('error', text(step.error), step.id) : null,
644
+ args && status === 'running' && !text(step.result) && !text(step.error)
645
+ ? h('p', { class: 'zx-run-trace__note' }, this.msg('runTrace.awaiting')) : null);
646
+ }
647
+
648
+ /**
649
+ * One block of a disclosure: its title, a copy button, and the text in a `<pre>`. A result
650
+ * longer than `maxResult` is cut, with a button that shows the rest.
651
+ * @private
652
+ * @param {'arguments'|'result'|'error'} kind
653
+ * @param {string} full
654
+ * @param {string} stepId
655
+ * @returns {HTMLElement}
656
+ */
657
+ _section(kind, full, stepId) {
658
+ const keys = SECTIONS[kind];
659
+ const shown = kind === 'result' && !this._whole.has(stepId)
660
+ ? truncateText(full, this.options.maxResult)
661
+ : { text: full, cut: false, length: full.length };
662
+ const titleId = uid('zx-run-trace-section');
663
+ return h('div', { class: 'zx-run-trace__section', dataset: { section: kind } },
664
+ h('div', { class: 'zx-run-trace__section-head' },
665
+ h('span', { class: 'zx-run-trace__section-title', id: titleId }, this.msg(keys.title)),
666
+ copyButton({ text: full, title: this.msg(keys.copy), feedback: this.msg('runTrace.copied'), size: 'sm' })),
667
+ h('pre', {
668
+ class: 'zx-run-trace__code',
669
+ tabindex: '0',
670
+ 'aria-labelledby': titleId,
671
+ dataset: { tone: kind === 'error' ? 'danger' : null }
672
+ }, shown.text),
673
+ shown.cut ? h('button', {
674
+ type: 'button', class: 'zx-btn zx-run-trace__more', dataset: { kind: 'ghost', size: 'sm', action: 'show-all' }
675
+ }, this.msg('runTrace.showAll')) : null);
676
+ }
677
+
678
+ /* ------------------------------------------------------------------ state -- */
679
+
680
+ /**
681
+ * @private
682
+ * @param {boolean} open
683
+ * @returns {void}
684
+ */
685
+ _setOpen(open) {
686
+ if (open === this._open) return;
687
+ this._open = open;
688
+ this._summary.setAttribute('aria-expanded', String(open));
689
+ this._list.hidden = !open;
690
+ this._syncClock();
691
+ this.emit('toggle', { id: null, open });
692
+ }
693
+
694
+ /**
695
+ * @private
696
+ * @param {string} id
697
+ * @param {boolean} open
698
+ * @returns {void}
699
+ */
700
+ _setStep(id, open) {
701
+ const entry = this._entries.get(id);
702
+ if (!entry?.body || !entry.row || open === this._expanded.has(id)) return;
703
+ if (open) this._expanded.add(id);
704
+ else this._expanded.delete(id);
705
+ entry.row.setAttribute('aria-expanded', String(open));
706
+ entry.body.hidden = !open;
707
+ this.emit('toggle', { id, open });
708
+ }
709
+
710
+ /**
711
+ * Redraws the summary from the steps.
712
+ * @private
713
+ * @returns {void}
714
+ */
715
+ _sync() {
716
+ const root = /** @type {HTMLElement} */ (this.el);
717
+ // A plan — every step a task — shows each step's status alone, unless told otherwise.
718
+ const tiles = this.options.kindIcons ?? !(this._steps.length > 0 && this._steps.every((step) => step.kind === 'task'));
719
+ if (tiles) delete root.dataset.tiles;
720
+ else root.dataset.tiles = 'none';
721
+ const { state, label, doing } = traceLabel(this._steps, (key, ...args) => this.msg(key, ...args), { label: this._label });
722
+ root.dataset.state = state;
723
+ if (this._steps.length) delete root.dataset.empty;
724
+ else root.dataset.empty = '';
725
+ this._summaryText.textContent = label;
726
+ this._summaryDoing.textContent = doing ?? '';
727
+ this._summaryDoing.hidden = !doing;
728
+ const entry = STATUS[state];
729
+ this._summaryState.replaceChildren(state === 'done' ? '' : statusIcon(entry.status, { tone: entry.tone }));
730
+ this._summaryState.hidden = state === 'done';
731
+ this._syncClock();
732
+ }
733
+
734
+ /**
735
+ * Starts the one clock while a running step's time is on screen, and stops it otherwise: when
736
+ * no step is running, the list is closed, the page is hidden, or the trace is destroyed.
737
+ * @private
738
+ * @returns {void}
739
+ */
740
+ _syncClock() {
741
+ const counting = !this._destroyed
742
+ && this._open
743
+ && !this.el.ownerDocument?.hidden
744
+ && this._list.querySelector('[data-since]') !== null;
745
+ if (counting && !this._clock) {
746
+ this._tick();
747
+ this._clock = setInterval(() => this._tick(), TICK_MS);
748
+ } else if (!counting && this._clock) {
749
+ clearInterval(this._clock);
750
+ this._clock = null;
751
+ }
752
+ }
753
+
754
+ /**
755
+ * Moves every running step's time to the clock's now.
756
+ * @private
757
+ * @returns {void}
758
+ */
759
+ _tick() {
760
+ const slots = /** @type {NodeListOf<HTMLElement>} */ (this._list.querySelectorAll('[data-since]'));
761
+ if (!slots.length) return;
762
+ const now = this._now();
763
+ for (const slot of slots) {
764
+ const next = elapsedSince(Number(slot.dataset.since), now);
765
+ if (slot.textContent !== next) slot.textContent = next;
766
+ }
767
+ }
768
+
769
+ /**
770
+ * The time `ticking` counts against: the `now` option's, or real time.
771
+ * @private
772
+ * @returns {number} Milliseconds since the epoch.
773
+ */
774
+ _now() {
775
+ const clock = this.options.now;
776
+ const value = typeof clock === 'function' ? clock() : null;
777
+ const ms = value instanceof Date ? value.getTime() : Number(value ?? Number.NaN);
778
+ return Number.isFinite(ms) ? ms : Date.now();
779
+ }
780
+
781
+ /**
782
+ * @private
783
+ * @param {HTMLElement} li
784
+ * @returns {void}
785
+ */
786
+ _mark(li) {
787
+ if (this._revealTimer) clearTimeout(this._revealTimer);
788
+ for (const marked of /** @type {NodeListOf<HTMLElement>} */ (this._list.querySelectorAll('[data-state="revealed"]'))) {
789
+ delete marked.dataset.state;
790
+ }
791
+ li.dataset.state = 'revealed';
792
+ this._revealTimer = setTimeout(() => {
793
+ this._revealTimer = null;
794
+ if (li.dataset.state === 'revealed') delete li.dataset.state;
795
+ }, REVEAL_MS);
796
+ }
797
+
798
+ /* ------------------------------------------------------------------ helpers -- */
799
+
800
+ /** @private @param {TraceKind} kind @returns {string} */
801
+ _icon(kind) {
802
+ return stepIcon(kind, this.options.icons);
803
+ }
804
+
805
+ /**
806
+ * @private
807
+ * @param {unknown} key
808
+ * @returns {{name: string, initials: string, tone: AvatarTone|null, person: boolean}}
809
+ */
810
+ _author(key) {
811
+ const authors = this.options.authors && typeof this.options.authors === 'object' ? this.options.authors : {};
812
+ const id = key == null ? '' : String(key);
813
+ const author = id && Object.hasOwn(authors, id) ? authors[id] : null;
814
+ const name = text(author?.name) || id;
815
+ return {
816
+ name,
817
+ initials: text(author?.initials) || initialsOf(name),
818
+ tone: /** @type {AvatarTone|null} */ (author?.tone ?? null),
819
+ person: author?.kind === 'person'
820
+ };
821
+ }
822
+
823
+ /**
824
+ * A hand-off avatar, shaped like the author's avatar everywhere else: round for a person, a
825
+ * rounded square for an agent or a model.
826
+ * @private
827
+ * @param {unknown} key
828
+ * @returns {Avatar}
829
+ */
830
+ _avatar(key) {
831
+ const author = this._author(key);
832
+ return new Avatar(null, {
833
+ name: author.name, initials: author.initials, tone: author.tone, size: 'sm', shape: author.person ? 'circle' : 'rounded'
834
+ });
835
+ }
836
+
837
+ /** @private @param {StepEntry} entry @returns {void} */
838
+ _releaseAvatars(entry) {
839
+ for (const avatar of entry.avatars) avatar.destroy();
840
+ entry.avatars = [];
841
+ }
842
+
843
+ /** @private @returns {string|null} The step whose row or disclosure has focus. */
844
+ _focusedStep() {
845
+ const active = this.el?.ownerDocument?.activeElement ?? null;
846
+ if (!active || !this._list?.contains(active)) return null;
847
+ const item = /** @type {HTMLElement|null} */ (active.closest('[data-step]'));
848
+ return item?.dataset.step ?? null;
849
+ }
850
+
851
+ /**
852
+ * @private
853
+ * @param {MouseEvent} event
854
+ * @returns {void}
855
+ */
856
+ _onClick(event) {
857
+ const target = event.target instanceof Element ? event.target : null;
858
+ const control = /** @type {HTMLElement|null} */ (target?.closest('[data-action]') ?? null);
859
+ if (!control || !this.el.contains(control)) return;
860
+ const action = control.dataset.action;
861
+ if (action === 'summary') {
862
+ this._setOpen(!this._open);
863
+ return;
864
+ }
865
+ const id = /** @type {HTMLElement|null} */ (control.closest('[data-step]'))?.dataset.step;
866
+ const entry = id ? this._entries.get(id) : undefined;
867
+ if (!entry) return;
868
+ if (action === 'step') {
869
+ const open = !this._expanded.has(entry.step.id);
870
+ this._setStep(entry.step.id, open);
871
+ if (open && this.options.selectable) this.emit('select', { id: entry.step.id });
872
+ } else if (action === 'select') {
873
+ this.emit('select', { id: entry.step.id });
874
+ } else if (action === 'ref') {
875
+ const ref = Array.isArray(entry.step.refs) ? entry.step.refs[Number(control.dataset.refIndex)] : null;
876
+ if (ref && typeof ref === 'object') this.emit('open', { step: { ...entry.step }, ref: { ...ref } });
877
+ } else if (action === 'show-all') {
878
+ this._whole.add(entry.step.id);
879
+ this._paint(entry);
880
+ /** @type {HTMLElement|null} */ (entry.body?.querySelector('[data-section="result"] > pre') ?? null)?.focus();
881
+ }
882
+ }
883
+ }
884
+
885
+ /**
886
+ * Fired when the step list or a step's disclosure opens or closes, from a click or a method. `id`
887
+ * is null for the step list.
888
+ * @event RunTrace#toggle
889
+ * @type {CustomEvent<{id: string|null, open: boolean}>}
890
+ */
891
+ /**
892
+ * Fired when `reveal()` has shown a step.
893
+ * @event RunTrace#reveal
894
+ * @type {CustomEvent<{id: string}>}
895
+ */
896
+ /**
897
+ * Fired in a `selectable` trace when the reader chooses a step: a row with nothing to open is
898
+ * activated, or a step's disclosure is opened by the reader (not by `expand()` or `reveal()`).
899
+ * @event RunTrace#select
900
+ * @type {CustomEvent<{id: string}>}
901
+ */
902
+ /**
903
+ * Fired when one of a step's links is activated; the application opens what it names. `step` and
904
+ * `ref` are copies.
905
+ * @event RunTrace#open
906
+ * @type {CustomEvent<{step: TraceStep, ref: ItemRef}>}
907
+ */
908
+
909
+ /* ------------------------------------------------------------------ pure helpers -- */
910
+
911
+ /**
912
+ * @param {string} key
913
+ * @param {...unknown} args
914
+ * @returns {string}
915
+ */
916
+ function englishMessage(key, ...args) {
917
+ const template = MESSAGES[/** @type {keyof typeof MESSAGES} */ (key)] ?? key;
918
+ return template.replace(/%(\d+)/g, (match, index) => String(args[Number(index) - 1] ?? match));
919
+ }
920
+
921
+ /** @param {unknown} value @returns {string} */
922
+ function text(value) {
923
+ return value == null ? '' : String(value);
924
+ }
925
+
926
+ /** @param {unknown} kind @returns {TraceKind} */
927
+ function normalizeKind(kind) {
928
+ return typeof kind === 'string' && Object.hasOwn(STEP_ICONS, kind) ? /** @type {TraceKind} */ (kind) : 'call';
929
+ }
930
+
931
+ /** @param {unknown} label @returns {string|null} The label to show, or null for the computed one. */
932
+ function ownLabel(label) {
933
+ return label == null || String(label).trim() === '' ? null : String(label);
934
+ }
935
+
936
+ /**
937
+ * "10:31:05" from a local ISO date-time ("10:31:00" when it gives no seconds), or '' for
938
+ * anything else.
939
+ * @param {unknown} at
940
+ * @returns {string}
941
+ */
942
+ function clockTime(at) {
943
+ const match = /[T ](\d{2}:\d{2})(?::(\d{2}))?/.exec(text(at));
944
+ return match ? `${match[1]}:${match[2] ?? '00'}` : '';
945
+ }
946
+
947
+ /** @param {unknown} at @returns {number|null} When a step started, or null when `at` is no date. */
948
+ function startOf(at) {
949
+ const source = text(at);
950
+ if (!source) return null;
951
+ const ms = Date.parse(source);
952
+ return Number.isFinite(ms) ? ms : null;
953
+ }
954
+
955
+ /**
956
+ * How long something has run, from when it started to now, in whole units: "41 s". A start in
957
+ * the future reads "0 s".
958
+ * @param {number} since Start, in milliseconds since the epoch.
959
+ * @param {number} now
960
+ * @returns {string}
961
+ */
962
+ export function elapsedSince(since, now) {
963
+ if (!Number.isFinite(since) || !Number.isFinite(now)) return '';
964
+ return formatElapsed(Math.max(0, now - since));
965
+ }
966
+
967
+ /**
968
+ * The glyph a step kind draws: the application's from `icons`, else the built-in one. An unknown
969
+ * kind draws as a `call`.
970
+ * @param {unknown} kind
971
+ * @param {Partial<Record<TraceKind, string>>|null} [icons]
972
+ * @returns {string}
973
+ */
974
+ export function stepIcon(kind, icons = null) {
975
+ const known = normalizeKind(kind);
976
+ const custom = icons && typeof icons === 'object' ? icons[known] : null;
977
+ return typeof custom === 'string' && custom ? custom : STEP_ICONS[known];
978
+ }
979
+
980
+ /**
981
+ * Whether a step has a disclosure to open: arguments (when they are shown), a result, an error,
982
+ * or a detail.
983
+ * @param {TraceStep} step
984
+ * @param {boolean} [showArguments=true]
985
+ * @returns {boolean}
986
+ */
987
+ function hasBody(step, showArguments = true) {
988
+ return Boolean((showArguments && text(step.args)) || text(step.result) || text(step.error) || text(step.detail));
989
+ }
990
+
991
+ /**
992
+ * How a step's row behaves: a disclosure when it has something to open, a button that selects
993
+ * the step when the trace is `selectable`, otherwise a static row.
994
+ * @param {TraceStep} step
995
+ * @param {{selectable?: boolean, showArguments?: boolean}} [options]
996
+ * @returns {RowKind}
997
+ */
998
+ export function rowKind(step, options = {}) {
999
+ if (step && typeof step === 'object' && hasBody(step, options?.showArguments !== false)) return 'disclosure';
1000
+ return options?.selectable ? 'select' : 'static';
1001
+ }
1002
+
1003
+ /**
1004
+ * A step's links that can be drawn — objects with a label — with their place in `step.refs`.
1005
+ * @param {TraceStep} step
1006
+ * @returns {Array<{ref: ItemRef, index: number}>}
1007
+ */
1008
+ function stepRefs(step) {
1009
+ const refs = Array.isArray(step?.refs) ? step.refs : [];
1010
+ return refs.flatMap((ref, index) => (ref && typeof ref === 'object' && text(ref.label) ? [{ ref, index }] : []));
1011
+ }
1012
+
1013
+ /**
1014
+ * A step's muted meta line, in reading order: a hand-off's own label (when the "handed over"
1015
+ * words replace it), the count, a search's sources, who took the step (not for a hand-off, whose
1016
+ * words name both sides), the clock time it started, and the tokens it used. Each piece only when
1017
+ * the step has it.
1018
+ * @param {TraceStep} step
1019
+ * @param {{msg?: (key: string, ...args: unknown[]) => string, name?: (key: string) => string,
1020
+ * formatTime?: ((at: string) => string)|null}} [context] Message lookup (English by default),
1021
+ * author key → display name (the key itself by default), and a writer for `at`.
1022
+ * @returns {MetaPart[]}
1023
+ */
1024
+ export function stepMeta(step, context = {}) {
1025
+ if (!step || typeof step !== 'object') return [];
1026
+ const msg = context.msg ?? englishMessage;
1027
+ const name = context.name ?? ((key) => key);
1028
+ /** @type {MetaPart[]} */
1029
+ const parts = [];
1030
+ const handoff = normalizeKind(step.kind) === 'handoff' && (step.actor || step.to)
1031
+ ? msg('runTrace.handoff', name(text(step.actor)), name(text(step.to)))
1032
+ : '';
1033
+ const label = text(step.label);
1034
+ if (handoff && label && label !== handoff) parts.push({ part: 'label', text: label });
1035
+ if (text(step.count)) parts.push({ part: 'count', text: text(step.count) });
1036
+ if (typeof step.sources === 'number' && step.sources > 0) {
1037
+ parts.push({ part: 'sources', text: step.sources === 1 ? msg('runTrace.source') : msg('runTrace.sources', step.sources) });
1038
+ }
1039
+ if (!handoff && text(step.actor)) parts.push({ part: 'actor', text: name(text(step.actor)) });
1040
+ const at = text(step.at);
1041
+ const time = at ? (typeof context.formatTime === 'function' ? text(context.formatTime(at)) : clockTime(at)) : '';
1042
+ if (time) parts.push({ part: 'time', text: time });
1043
+ if (typeof step.tokens === 'number' && Number.isFinite(step.tokens) && step.tokens > 0) {
1044
+ parts.push({ part: 'tokens', text: step.tokens === 1 ? msg('runTrace.token') : msg('runTrace.tokens', formatNumber(step.tokens)) });
1045
+ }
1046
+ return parts;
1047
+ }
1048
+
1049
+ /**
1050
+ * Copies the steps, giving each a string id; a later step with an id already seen replaces the
1051
+ * earlier one in its place.
1052
+ * @param {unknown} steps
1053
+ * @returns {Array<TraceStep & {id: string}>}
1054
+ */
1055
+ function normalizeSteps(steps) {
1056
+ /** @type {Map<string, TraceStep & {id: string}>} */
1057
+ const byId = new Map();
1058
+ (Array.isArray(steps) ? steps : []).forEach((step, index) => {
1059
+ if (!step || typeof step !== 'object') return;
1060
+ const id = step.id == null || step.id === '' ? `step-${index + 1}` : String(step.id);
1061
+ byId.set(id, { ...step, id });
1062
+ });
1063
+ return [...byId.values()];
1064
+ }
1065
+
1066
+ /**
1067
+ * Arguments for display: JSON objects and arrays pretty-printed with two spaces, anything else
1068
+ * exactly as given.
1069
+ * @param {unknown} value
1070
+ * @returns {string}
1071
+ */
1072
+ export function prettyArguments(value) {
1073
+ const source = text(value);
1074
+ try {
1075
+ const parsed = JSON.parse(source);
1076
+ return parsed !== null && typeof parsed === 'object' ? JSON.stringify(parsed, null, 2) : source;
1077
+ } catch {
1078
+ return source;
1079
+ }
1080
+ }
1081
+
1082
+ /**
1083
+ * Cuts a text to at most `max` characters plus an ellipsis, never inside a surrogate pair. Zero, a
1084
+ * negative, or a non-finite `max` keeps the whole text.
1085
+ * @param {unknown} value
1086
+ * @param {unknown} max
1087
+ * @returns {{text: string, cut: boolean, length: number}} The text to show, whether it was cut,
1088
+ * and the length of the whole.
1089
+ */
1090
+ export function truncateText(value, max) {
1091
+ const source = text(value);
1092
+ const limit = Math.floor(Number(max));
1093
+ if (!Number.isFinite(limit) || limit <= 0 || source.length <= limit) {
1094
+ return { text: source, cut: false, length: source.length };
1095
+ }
1096
+ let end = limit;
1097
+ const code = source.charCodeAt(end - 1);
1098
+ if (code >= 0xd800 && code <= 0xdbff) end -= 1;
1099
+ return { text: `${source.slice(0, end)}…`, cut: true, length: source.length };
1100
+ }
1101
+
1102
+ /**
1103
+ * Groups steps for drawing: every step that repeats another (`retryOf`, followed through retries
1104
+ * of retries) goes under the first step of its chain. Top-level steps keep their order, and so do
1105
+ * the retries under each. A `retryOf` naming no step, or a loop, leaves the step at the top level.
1106
+ * @param {TraceStep[]} steps
1107
+ * @returns {Array<{step: TraceStep, retries: TraceStep[]}>}
1108
+ */
1109
+ export function groupRetries(steps) {
1110
+ const list = (Array.isArray(steps) ? steps : []).filter((step) => step && typeof step === 'object');
1111
+ /** @type {Map<string, TraceStep>} */
1112
+ const byId = new Map();
1113
+ for (const step of list) if (!byId.has(String(step.id))) byId.set(String(step.id), step);
1114
+ /** @param {TraceStep} step @returns {TraceStep} */
1115
+ const rootOf = (step) => {
1116
+ const seen = new Set();
1117
+ let current = step;
1118
+ while (current.retryOf != null && byId.has(String(current.retryOf)) && !seen.has(String(current.id))) {
1119
+ seen.add(String(current.id));
1120
+ current = /** @type {TraceStep} */ (byId.get(String(current.retryOf)));
1121
+ }
1122
+ return seen.has(String(current.id)) ? step : current;
1123
+ };
1124
+ /** @type {Map<TraceStep, {step: TraceStep, retries: TraceStep[]}>} */
1125
+ const groups = new Map();
1126
+ const roots = list.map(rootOf);
1127
+ list.forEach((step, index) => {
1128
+ if (roots[index] === step) groups.set(step, { step, retries: [] });
1129
+ });
1130
+ list.forEach((step, index) => {
1131
+ if (roots[index] !== step) groups.get(roots[index])?.retries.push(step);
1132
+ });
1133
+ return [...groups.values()];
1134
+ }
1135
+
1136
+ /**
1137
+ * The trace's state and its summary line. While a step runs it reads "Working…" and names what
1138
+ * the step is doing; a run waiting for a person, or blocked, says so and names the step ("Blocked
1139
+ * after 12 s · 3 tool calls"); a paused, stopped, or failed run says so before its counts; a run
1140
+ * no step of which has started reads "Not started · 6 steps"; once the run ends it reads "Worked
1141
+ * for 41 s · 5 tool calls · 9 sources · 1 retry", each count only when it is not zero.
1142
+ *
1143
+ * With `label`, the line is that text instead — a plan's title — followed by the state's word for
1144
+ * every state but done: "Close September · 2 of 5 done · Running".
1145
+ * @param {TraceStep[]} steps
1146
+ * @param {(key: string, ...args: unknown[]) => string} [msg] Message lookup; English by default.
1147
+ * @param {{label?: string|null}} [options]
1148
+ * @returns {TraceLabel}
1149
+ */
1150
+ export function traceLabel(steps, msg = englishMessage, options = {}) {
1151
+ const computed = computedLabel(steps, msg);
1152
+ const own = ownLabel(options?.label);
1153
+ if (own === null) return computed;
1154
+ return {
1155
+ ...computed,
1156
+ label: computed.state === 'done' ? own : `${own} · ${msg(STATUS[computed.state].key)}`
1157
+ };
1158
+ }
1159
+
1160
+ /**
1161
+ * @param {TraceStep[]} steps
1162
+ * @param {(key: string, ...args: unknown[]) => string} msg
1163
+ * @returns {TraceLabel}
1164
+ */
1165
+ function computedLabel(steps, msg) {
1166
+ const list = Array.isArray(steps) ? steps.filter((step) => step && typeof step === 'object') : [];
1167
+ const summary = traceSummary(list);
1168
+ const stateOf = (/** @type {TraceStep} */ step) => normalizeRunState(step.status ?? 'done');
1169
+ const find = (/** @type {RunState} */ state) => list.find((step) => stateOf(step) === state) ?? null;
1170
+ const plain = (/** @type {TraceStep|null} */ step) => (step ? text(step.doing || step.label).replace(/(?:…|\.\.\.)\s*$/, '') || null : null);
1171
+ const time = summary.ms > 0 ? formatDuration(summary.ms) : '';
1172
+ const stepCount = summary.steps === 1 ? msg('runTrace.step') : msg('runTrace.steps', summary.steps);
1173
+ const counts = [
1174
+ summary.calls ? (summary.calls === 1 ? msg('runTrace.call') : msg('runTrace.calls', summary.calls)) : '',
1175
+ summary.sources ? (summary.sources === 1 ? msg('runTrace.source') : msg('runTrace.sources', summary.sources)) : '',
1176
+ summary.retries ? (summary.retries === 1 ? msg('runTrace.retry') : msg('runTrace.retries', summary.retries)) : ''
1177
+ ].filter(Boolean);
1178
+
1179
+ if (summary.running) return { state: 'running', label: msg('runTrace.working'), doing: plain(summary.running) };
1180
+ const waiting = find('waiting');
1181
+ if (waiting) return { state: 'waiting', label: msg(STATUS.waiting.key), doing: plain(waiting) };
1182
+ const blocked = find('blocked');
1183
+ if (blocked) {
1184
+ // A blocked step is doing nothing: it is named by its label, its "…ing" line only without one.
1185
+ const head = time ? msg('runTrace.blockedAfter', time) : msg(STATUS.blocked.key);
1186
+ return { state: 'blocked', label: [head, ...counts].join(' · '), doing: plain({ ...blocked, doing: blocked.label || blocked.doing }) };
1187
+ }
1188
+ const paused = find('paused');
1189
+ if (paused) return { state: 'paused', label: [msg(STATUS.paused.key), ...counts].join(' · '), doing: null };
1190
+ if (list.length && list.every((step) => stateOf(step) === 'queued')) {
1191
+ return { state: 'queued', label: [msg(STATUS.queued.key), stepCount].join(' · '), doing: null };
1192
+ }
1193
+
1194
+ /** @type {RunState} */
1195
+ let state = 'done';
1196
+ let head = '';
1197
+ if (summary.stopped) {
1198
+ state = 'stopped';
1199
+ head = time ? msg('runTrace.stoppedAfter', time) : msg(STATUS.stopped.key);
1200
+ } else if (summary.failed) {
1201
+ state = 'failed';
1202
+ head = time ? msg('runTrace.failedAfter', time) : msg(STATUS.failed.key);
1203
+ } else if (time) {
1204
+ head = msg('runTrace.worked', time);
1205
+ } else if (!counts.length) {
1206
+ head = stepCount;
1207
+ }
1208
+ return { state, label: [head, ...counts].filter(Boolean).join(' · '), doing: null };
1209
+ }