@linxiraos/pi-tui 1.4.0 → 1.4.2

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 (105) hide show
  1. package/CHANGELOG.md +43 -43
  2. package/dist/types/autocomplete.d.ts +6 -0
  3. package/dist/types/components/sparkline.d.ts +34 -0
  4. package/dist/types/index.d.ts +1 -0
  5. package/dist/types/native/describe.d.ts +7 -1
  6. package/dist/types/native/overlay.d.ts +2 -0
  7. package/dist/types/native/tone.d.ts +2 -0
  8. package/dist/types/overlays/agent-hub.d.ts +3 -3
  9. package/dist/types/overlays/approval-dialog.d.ts +15 -1
  10. package/dist/types/overlays/jobs-panel.d.ts +3 -0
  11. package/dist/types/overlays/model-browser.d.ts +1 -1
  12. package/dist/types/render/output-block.d.ts +2 -0
  13. package/dist/types/render/tool-card.d.ts +2 -0
  14. package/dist/types/sixel.d.ts +28 -0
  15. package/dist/types/status-line/host.d.ts +3 -0
  16. package/dist/types/terminal-capabilities.d.ts +5 -0
  17. package/dist/types/tools/bash.d.ts +2 -0
  18. package/dist/types/tools/default-renderer.d.ts +3 -0
  19. package/dist/types/tools/eval.d.ts +9 -8
  20. package/dist/types/tools/irc.d.ts +6 -0
  21. package/dist/types/tools/job-widget.d.ts +226 -0
  22. package/dist/types/tools/json-tree.d.ts +2 -0
  23. package/dist/types/tools/line-ranges.d.ts +8 -1
  24. package/dist/types/tools/mcp.d.ts +23 -0
  25. package/dist/types/tools/output-meta.d.ts +1 -1
  26. package/dist/types/tools/read.d.ts +8 -2
  27. package/dist/types/tools/renderer.d.ts +8 -2
  28. package/dist/types/tools/result-card.d.ts +1 -1
  29. package/dist/types/tools/streaming-output.d.ts +1 -0
  30. package/dist/types/tools/task.d.ts +12 -0
  31. package/dist/types/tools/wait.d.ts +5 -0
  32. package/package.json +9 -9
  33. package/src/autocomplete.d.ts +6 -0
  34. package/src/autocomplete.ts +21 -6
  35. package/src/chat/skill-message.ts +16 -17
  36. package/src/chat/tool-execution.ts +35 -0
  37. package/src/chrome/transcript-container.ts +85 -13
  38. package/src/components/editor.ts +17 -7
  39. package/src/components/image.ts +5 -4
  40. package/src/components/markdown.ts +11 -3
  41. package/src/components/sparkline.d.ts +34 -0
  42. package/src/components/sparkline.ts +89 -0
  43. package/src/index.d.ts +1 -0
  44. package/src/index.ts +1 -0
  45. package/src/native/backend.ts +32 -6
  46. package/src/native/describe.d.ts +7 -1
  47. package/src/native/describe.ts +18 -1
  48. package/src/native/overlay.d.ts +2 -0
  49. package/src/native/overlay.ts +3 -0
  50. package/src/native/tone.d.ts +2 -0
  51. package/src/native/tone.ts +22 -0
  52. package/src/overlays/agent-hub.ts +14 -10
  53. package/src/overlays/agent-transcript-viewer.ts +2 -2
  54. package/src/overlays/agents-hub.ts +2 -1
  55. package/src/overlays/approval-dialog.ts +59 -13
  56. package/src/overlays/hub-frame.ts +2 -1
  57. package/src/overlays/jobs-panel.ts +24 -2
  58. package/src/overlays/model-browser.ts +3 -0
  59. package/src/overlays/model-hub.ts +2 -1
  60. package/src/prompt/attachment-chips.ts +1 -1
  61. package/src/render/output-block.d.ts +2 -0
  62. package/src/render/output-block.ts +25 -12
  63. package/src/render/tool-card.d.ts +2 -0
  64. package/src/render/tool-card.ts +6 -0
  65. package/src/sixel.d.ts +28 -0
  66. package/src/sixel.ts +185 -0
  67. package/src/status-line/component.ts +19 -2
  68. package/src/status-line/host.ts +3 -0
  69. package/src/terminal-capabilities.d.ts +5 -0
  70. package/src/terminal-capabilities.ts +43 -3
  71. package/src/theme/symbols.ts +5 -3
  72. package/src/tools/bash.d.ts +2 -0
  73. package/src/tools/bash.ts +25 -9
  74. package/src/tools/default-renderer.d.ts +3 -0
  75. package/src/tools/default-renderer.ts +54 -17
  76. package/src/tools/eval.d.ts +9 -8
  77. package/src/tools/eval.ts +32 -14
  78. package/src/tools/find.ts +4 -5
  79. package/src/tools/glob.ts +4 -6
  80. package/src/tools/grep.ts +2 -4
  81. package/src/tools/irc.d.ts +6 -0
  82. package/src/tools/irc.ts +6 -0
  83. package/src/tools/job-widget.d.ts +226 -0
  84. package/src/tools/job-widget.ts +1036 -0
  85. package/src/tools/json-tree.d.ts +2 -0
  86. package/src/tools/json-tree.ts +8 -0
  87. package/src/tools/line-ranges.d.ts +8 -1
  88. package/src/tools/line-ranges.ts +23 -13
  89. package/src/tools/mcp.d.ts +23 -0
  90. package/src/tools/mcp.ts +44 -1
  91. package/src/tools/output-meta.d.ts +1 -1
  92. package/src/tools/output-meta.ts +1 -1
  93. package/src/tools/read.d.ts +8 -2
  94. package/src/tools/read.ts +64 -21
  95. package/src/tools/renderer.d.ts +8 -2
  96. package/src/tools/renderer.ts +8 -2
  97. package/src/tools/result-card.d.ts +1 -1
  98. package/src/tools/result-card.ts +1 -2
  99. package/src/tools/streaming-output.d.ts +1 -0
  100. package/src/tools/streaming-output.ts +11 -9
  101. package/src/tools/task.d.ts +12 -0
  102. package/src/tools/task.ts +25 -1
  103. package/src/tools/wait.d.ts +5 -0
  104. package/src/tools/wait.ts +290 -147
  105. package/src/tui.ts +45 -5
@@ -61,7 +61,7 @@ export interface EvalCellResult {
61
61
  durationMs?: number;
62
62
  exitCode?: number;
63
63
  statusEvents?: EvalStatusEvent[];
64
- /** Discrete events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
64
+ /** Evictable events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
65
65
  statusEventsElided?: number;
66
66
  }
67
67
  /** Tool result detail object surfaced to the UI/transcript. */
@@ -69,7 +69,7 @@ export interface EvalToolDetails {
69
69
  cells?: EvalCellResult[];
70
70
  images?: ImageContent[];
71
71
  statusEvents?: EvalStatusEvent[];
72
- /** Discrete events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
72
+ /** Evictable events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
73
73
  statusEventsElided?: number;
74
74
  isError?: boolean;
75
75
  meta?: OutputMeta;
@@ -104,7 +104,7 @@ interface EvalRenderContext {
104
104
  timeout?: number;
105
105
  }
106
106
  /**
107
- * Coalescing key of a progress-snapshot event: `agent` and `judge_batch`
107
+ * Coalescing key of a progress-snapshot event: `agent`, `judge_batch`, and `mcp_progress`
108
108
  * events keyed by `id`, where only the newest snapshot matters. Discrete
109
109
  * actions (everything else) have no key. Shared by {@link upsertStatusEvent}
110
110
  * and the executors' display collectors so both coalesce identically.
@@ -114,12 +114,12 @@ export declare function statusEventKey(event: {
114
114
  [key: string]: unknown;
115
115
  }): string | undefined;
116
116
  /**
117
- * Discrete status events a log keeps. A cell polling a helper in a loop emits
117
+ * Evictable status events a log keeps. A cell polling a helper in a loop emits
118
118
  * one event per call (hundreds of thousands), and every live update and the
119
119
  * persisted tool result would otherwise carry them all.
120
120
  */
121
121
  export declare const MAX_STATUS_EVENTS = 200;
122
- /** A status event list plus the count of discrete events dropped from its front. */
122
+ /** A status event list plus the count of evictable events dropped from its front. */
123
123
  export type StatusEventLog = Pick<EvalCellResult, "statusEvents" | "statusEventsElided">;
124
124
  /**
125
125
  * Append or replace a status event. Progress snapshots (see
@@ -129,9 +129,10 @@ export type StatusEventLog = Pick<EvalCellResult, "statusEvents" | "statusEvents
129
129
  export declare function upsertStatusEvent(events: EvalStatusEvent[], event: EvalStatusEvent): void;
130
130
  /**
131
131
  * {@link upsertStatusEvent} into a bounded log. Past {@link MAX_STATUS_EVENTS},
132
- * the oldest discrete event is dropped and counted. Snapshots stay, since agent
133
- * cards read them, and so does the newest committed `todo` result, which the
134
- * session todo panel refreshes from. Renderers already show only the newest
132
+ * the oldest discrete event or MCP progress snapshot is dropped and counted.
133
+ * Agent/judgment-batch snapshots stay, since agent cards read them, and so does
134
+ * the newest committed `todo` result, which the session todo panel refreshes
135
+ * from. Renderers already show only the newest
135
136
  * events behind an "… N earlier" row.
136
137
  */
137
138
  export declare function recordStatusEvent(log: StatusEventLog, event: EvalStatusEvent): void;
package/src/tools/eval.ts CHANGED
@@ -35,6 +35,7 @@ import {
35
35
  renderJsonTreeLines,
36
36
  } from "./json-tree";
37
37
  import { formatStyledTruncationWarning, stripOutputNotice } from "./output-meta";
38
+ import { formatMCPProgress, parseMCPProgress } from "./mcp";
38
39
  import { splitPathAndSel } from "./read";
39
40
  import {
40
41
  DEFAULT_TERMINAL_PREVIEW_LINES,
@@ -108,7 +109,7 @@ export interface EvalCellResult {
108
109
  durationMs?: number;
109
110
  exitCode?: number;
110
111
  statusEvents?: EvalStatusEvent[];
111
- /** Discrete events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
112
+ /** Evictable events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
112
113
  statusEventsElided?: number;
113
114
  }
114
115
 
@@ -117,7 +118,7 @@ export interface EvalToolDetails {
117
118
  cells?: EvalCellResult[];
118
119
  images?: ImageContent[];
119
120
  statusEvents?: EvalStatusEvent[];
120
- /** Discrete events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
121
+ /** Evictable events dropped from the front of `statusEvents` (see {@link recordStatusEvent}). */
121
122
  statusEventsElided?: number;
122
123
  isError?: boolean;
123
124
  meta?: OutputMeta;
@@ -222,26 +223,29 @@ function pushCodeCellLines(
222
223
  type AgentEventStatus = "pending" | "running" | "completed" | "failed" | "aborted";
223
224
 
224
225
  /**
225
- * Coalescing key of a progress-snapshot event: `agent` and `judge_batch`
226
+ * Coalescing key of a progress-snapshot event: `agent`, `judge_batch`, and `mcp_progress`
226
227
  * events keyed by `id`, where only the newest snapshot matters. Discrete
227
228
  * actions (everything else) have no key. Shared by {@link upsertStatusEvent}
228
229
  * and the executors' display collectors so both coalesce identically.
229
230
  */
230
231
  export function statusEventKey(event: { op: string; [key: string]: unknown }): string | undefined {
231
- if ((event.op === "agent" || event.op === "judge_batch") && typeof event.id === "string") {
232
+ if (
233
+ (event.op === "agent" || event.op === "judge_batch" || event.op === "mcp_progress") &&
234
+ typeof event.id === "string"
235
+ ) {
232
236
  return `${event.op}\0${event.id}`;
233
237
  }
234
238
  return undefined;
235
239
  }
236
240
 
237
241
  /**
238
- * Discrete status events a log keeps. A cell polling a helper in a loop emits
242
+ * Evictable status events a log keeps. A cell polling a helper in a loop emits
239
243
  * one event per call (hundreds of thousands), and every live update and the
240
244
  * persisted tool result would otherwise carry them all.
241
245
  */
242
246
  export const MAX_STATUS_EVENTS = 200;
243
247
 
244
- /** A status event list plus the count of discrete events dropped from its front. */
248
+ /** A status event list plus the count of evictable events dropped from its front. */
245
249
  export type StatusEventLog = Pick<EvalCellResult, "statusEvents" | "statusEventsElided">;
246
250
 
247
251
  /**
@@ -263,9 +267,10 @@ export function upsertStatusEvent(events: EvalStatusEvent[], event: EvalStatusEv
263
267
 
264
268
  /**
265
269
  * {@link upsertStatusEvent} into a bounded log. Past {@link MAX_STATUS_EVENTS},
266
- * the oldest discrete event is dropped and counted. Snapshots stay, since agent
267
- * cards read them, and so does the newest committed `todo` result, which the
268
- * session todo panel refreshes from. Renderers already show only the newest
270
+ * the oldest discrete event or MCP progress snapshot is dropped and counted.
271
+ * Agent/judgment-batch snapshots stay, since agent cards read them, and so does
272
+ * the newest committed `todo` result, which the session todo panel refreshes
273
+ * from. Renderers already show only the newest
269
274
  * events behind an "… N earlier" row.
270
275
  */
271
276
  export function recordStatusEvent(log: StatusEventLog, event: EvalStatusEvent): void {
@@ -273,7 +278,9 @@ export function recordStatusEvent(log: StatusEventLog, event: EvalStatusEvent):
273
278
  upsertStatusEvent(events, event);
274
279
  if (events.length <= MAX_STATUS_EVENTS) return;
275
280
  const keep = events.findLastIndex(e => e.op === "todo" && e.committed === true);
276
- const oldest = events.findIndex((e, i) => i !== keep && statusEventKey(e) === undefined);
281
+ const oldest = events.findIndex(
282
+ (e, i) => i !== keep && (e.op === "mcp_progress" || statusEventKey(e) === undefined),
283
+ );
277
284
  if (oldest < 0) return;
278
285
  events.splice(oldest, 1);
279
286
  log.statusEventsElided = (log.statusEventsElided ?? 0) + 1;
@@ -414,6 +421,12 @@ function formatStatusEvent(event: EvalStatusEvent, theme: Theme): string {
414
421
  }
415
422
 
416
423
  switch (op) {
424
+ case "mcp_progress": {
425
+ if (data.tool) parts.push(previewLine(sanitizeText(String(data.tool)), STATUS_VALUE_WIDTH));
426
+ const progress = parseMCPProgress(data);
427
+ if (progress) parts.push(formatMCPProgress(progress, STATUS_VALUE_WIDTH));
428
+ break;
429
+ }
417
430
  case "read":
418
431
  parts.push(`${data.chars ?? data.bytes ?? 0} chars`);
419
432
  if (data.path) parts.push(`from ${shortenPath(String(data.path))}`);
@@ -693,20 +706,25 @@ const STATUS_VALUE_WIDTH = 200;
693
706
 
694
707
  /**
695
708
  * Plain one-line summary of a status event: op plus its scalar fields, each
696
- * collapsed to one line. A `preview` (file or command text a helper returned)
697
- * never joins the line: an expanded cell shows it under the line as a code
698
- * block holding its first {@link PREVIEW_LIMITS.OUTPUT_EXPANDED} lines, folded
699
- * to {@link PREVIEW_LIMITS.COLLAPSED_LINES}.
709
+ * collapsed to one line. MCP progress shows its tool and then the shared
710
+ * {@link formatMCPProgress} text; its call id is internal. A `preview` (file or
711
+ * command text a helper returned) never joins the line: an expanded cell shows
712
+ * it under the line as a code block holding its first
713
+ * {@link PREVIEW_LIMITS.OUTPUT_EXPANDED} lines, folded to
714
+ * {@link PREVIEW_LIMITS.COLLAPSED_LINES}.
700
715
  */
701
716
  function describeStatusEvent(event: EvalStatusEvent, expanded: boolean): NativeNode {
702
717
  const spans: TspSpan[] = [span(event.op, "accent")];
718
+ const mcpProgress = event.op === "mcp_progress" ? parseMCPProgress(event) : undefined;
703
719
  for (const key in event) {
704
720
  if (key === "op" || key === "preview" || key === "resolvedThinkingLevel") continue;
721
+ if (event.op === "mcp_progress" && key !== "tool") continue;
705
722
  const value = event[key];
706
723
  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
707
724
  spans.push(span(` ${key}=`, "muted"), span(previewLine(sanitizeText(String(value)), STATUS_VALUE_WIDTH)));
708
725
  }
709
726
  }
727
+ if (mcpProgress) spans.push(span(` ${formatMCPProgress(mcpProgress, STATUS_VALUE_WIDTH)}`));
710
728
  const line = text(spans, { truncate: "end", role: "zeta.tool.eval.status" });
711
729
  const preview = expanded ? eventString(event.preview)?.trimEnd() : undefined;
712
730
  if (!preview) return line;
package/src/tools/find.ts CHANGED
@@ -256,7 +256,7 @@ export const findToolRenderer = {
256
256
  },
257
257
  uiTheme,
258
258
  );
259
- return new Text(text, 1, 0);
259
+ return new Text(text, 0, 0);
260
260
  },
261
261
 
262
262
  renderResult(
@@ -269,7 +269,7 @@ export const findToolRenderer = {
269
269
  const text = result.content?.find(c => c.type === "text")?.text ?? "";
270
270
 
271
271
  if (result.isError) {
272
- return new Text(formatErrorMessage(text || "Unknown error", uiTheme), 1, 0);
272
+ return new Text(formatErrorMessage(text || "Unknown error", uiTheme), 0, 0);
273
273
  }
274
274
 
275
275
  // Streaming progress: the tool reports the phase it is in.
@@ -285,7 +285,7 @@ export const findToolRenderer = {
285
285
  },
286
286
  uiTheme,
287
287
  );
288
- return new Text(header, 1, 0);
288
+ return new Text(header, 0, 0);
289
289
  }
290
290
 
291
291
  const { hits, stats, threshold } = details;
@@ -317,7 +317,7 @@ export const findToolRenderer = {
317
317
  : "No relevant passages found";
318
318
  const lines = [header, formatEmptyMessage(empty, uiTheme)];
319
319
  for (const failure of stats.failures) lines.push(uiTheme.fg("warning", failure));
320
- return new Text(lines.join("\n"), 1, 0);
320
+ return new Text(lines.join("\n"), 0, 0);
321
321
  }
322
322
 
323
323
  const header = renderStatusLine(
@@ -359,7 +359,6 @@ export const findToolRenderer = {
359
359
  }
360
360
  return [header, ...hitLines, ...extra].map(line => truncateToWidth(line, width, Ellipsis.Omit));
361
361
  },
362
- { paddingX: 1 },
363
362
  );
364
363
  },
365
364
  describeCall(args: FindRenderArgs): NativeToolView {
package/src/tools/glob.ts CHANGED
@@ -151,7 +151,7 @@ export const globToolRenderer = {
151
151
  },
152
152
  uiTheme,
153
153
  );
154
- return new Text(text, 1, 0);
154
+ return new Text(text, 0, 0);
155
155
  },
156
156
 
157
157
  renderResult(
@@ -165,7 +165,7 @@ export const globToolRenderer = {
165
165
 
166
166
  if (result.isError || details?.error) {
167
167
  const errorText = details?.error || result.content?.find(c => c.type === "text")?.text || "Unknown error";
168
- return new Text(formatErrorMessage(errorText, uiTheme), 1, 0);
168
+ return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
169
169
  }
170
170
 
171
171
  const hasDetailedData = details?.fileCount !== undefined;
@@ -178,7 +178,7 @@ export const globToolRenderer = {
178
178
  textContent.includes("No files found") ||
179
179
  textContent.trim() === ""
180
180
  ) {
181
- return new Text(formatEmptyMessage("No files found", uiTheme), 1, 0);
181
+ return new Text(formatEmptyMessage("No files found", uiTheme), 0, 0);
182
182
  }
183
183
 
184
184
  const lines = textContent.split("\n").filter(l => l.trim());
@@ -207,7 +207,6 @@ export const globToolRenderer = {
207
207
  );
208
208
  return [header, ...listLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
209
209
  },
210
- { paddingX: 1 },
211
210
  );
212
211
  }
213
212
 
@@ -244,7 +243,7 @@ export const globToolRenderer = {
244
243
  );
245
244
  const lines = [header, formatEmptyMessage(emptyLabel, uiTheme)];
246
245
  if (missingNote) lines.push(missingNote);
247
- return new Text(lines.join("\n"), 1, 0);
246
+ return new Text(lines.join("\n"), 0, 0);
248
247
  }
249
248
  const meta: string[] = [formatCount("file", fileCount)];
250
249
  if (details?.scopePath) meta.push(`in ${details.scopePath}`);
@@ -298,7 +297,6 @@ export const globToolRenderer = {
298
297
  );
299
298
  return [header, ...fileLines, ...extraLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
300
299
  },
301
- { paddingX: 1 },
302
300
  );
303
301
  },
304
302
  describeCall(args: GlobRenderArgs): NativeToolView {
package/src/tools/grep.ts CHANGED
@@ -365,7 +365,7 @@ export const grepToolRenderer = {
365
365
  { icon: "pending", title: "Grep", titleColor: "toolTitle", description: args.pattern || "?", meta },
366
366
  uiTheme,
367
367
  );
368
- return new Text(text, 1, 0);
368
+ return new Text(text, 0, 0);
369
369
  },
370
370
 
371
371
  renderResult(
@@ -422,7 +422,6 @@ export const grepToolRenderer = {
422
422
  );
423
423
  return [header, ...listLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
424
424
  },
425
- { paddingX: 1 },
426
425
  );
427
426
  }
428
427
  const linkTargets = grepLinkTargets(details, options.renderContext?.rawDetails);
@@ -456,7 +455,7 @@ export const grepToolRenderer = {
456
455
  );
457
456
  const lines = [header, formatEmptyMessage(tuiText("gpNoMatches", "No matches found"), uiTheme)];
458
457
  if (missingNote) lines.push(missingNote);
459
- return new Text(lines.join("\n"), 1, 0);
458
+ return new Text(lines.join("\n"), 0, 0);
460
459
  }
461
460
 
462
461
  const summaryParts = [formatCount("match", matchCount), formatCount("file", fileCount)];
@@ -514,7 +513,6 @@ export const grepToolRenderer = {
514
513
  );
515
514
  return [header, ...matchLines, ...extraLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
516
515
  },
517
- { paddingX: 1 },
518
516
  );
519
517
  },
520
518
  describeCall(args: GrepRenderArgs): NativeToolView {
@@ -19,6 +19,12 @@ export interface IrcMessage {
19
19
  * ping-pong forever.
20
20
  */
21
21
  wakeRelay?: boolean;
22
+ /**
23
+ * One leg of an `all` broadcast. Like relays, broadcasts never draw an
24
+ * automatic wake-turn reply: every woken idle peer would otherwise answer
25
+ * the broadcaster, mostly to say the message was not for it.
26
+ */
27
+ broadcast?: boolean;
22
28
  }
23
29
  /** Delivery outcome for one peer recipient. */
24
30
  export interface IrcDeliveryReceipt {
package/src/tools/irc.ts CHANGED
@@ -21,6 +21,12 @@ export interface IrcMessage {
21
21
  * ping-pong forever.
22
22
  */
23
23
  wakeRelay?: boolean;
24
+ /**
25
+ * One leg of an `all` broadcast. Like relays, broadcasts never draw an
26
+ * automatic wake-turn reply: every woken idle peer would otherwise answer
27
+ * the broadcaster, mostly to say the message was not for it.
28
+ */
29
+ broadcast?: boolean;
24
30
  }
25
31
 
26
32
  /** Delivery outcome for one peer recipient. */
@@ -0,0 +1,226 @@
1
+ /**
2
+ * Live widgets for background jobs: the rendered state of what a job is
3
+ * doing (a benchmark's requests/s over time, tests passed per model, CI jobs
4
+ * green so far), shown in the `wait` card, the HUD's jobs pill and the jobs
5
+ * sheet.
6
+ *
7
+ * A widget is data, not code. In coding-agent, a cheap model writes a
8
+ * `JobWidgetSpec` once per job (rules that pull numbers out of the job's
9
+ * output streams, and the blocks to draw them with); the job-widgets runtime
10
+ * then applies those rules to every new line and recomputes a
11
+ * {@link JobWidgetView}. Renderers here draw that view as TSP nodes (Tern) or
12
+ * ANSI lines, and never see a rule or a regex.
13
+ */
14
+ import type { TspPropNode, TspSpan, TspTone } from "@linxiraos/pi-wire";
15
+ import type { NativeNode } from "../native/node";
16
+ import type { Theme } from "../theme/theme";
17
+ /** Where a widget's view stands. */
18
+ export type JobWidgetState =
19
+ /** The cheap model is writing the spec; the view holds the model-free fallback meanwhile. */
20
+ "authoring"
21
+ /** The spec's rules drive the view. */
22
+ | "live"
23
+ /** No spec (no model, authoring failed, nothing to read yet): last line and rates only. */
24
+ | "fallback";
25
+ /** A formatted number with the direction it moved, for headlines and stats. */
26
+ export interface JobWidgetTrend {
27
+ /** `▲ 15%`, `▼ 3.2 ms`. */
28
+ text: string;
29
+ /** `success` when the move is toward `better`, `error` away from it, `muted` without a direction. */
30
+ tone: "success" | "error" | "muted";
31
+ }
32
+ /** The headline value: the one number a glance should take away (`186 tok/s`). */
33
+ export interface JobWidgetHeadline {
34
+ /** Formatted value with its unit. */
35
+ text: string;
36
+ /** What the value is, when the title does not already say it (`decode`, `p50`). */
37
+ label?: string;
38
+ trend?: JobWidgetTrend;
39
+ }
40
+ /** A time series drawn as columns, newest right, with optional reference lines. */
41
+ export interface JobWidgetSparkBlock {
42
+ kind: "spark";
43
+ /** What the series measures (`tok/s · nvfp4 b1`). */
44
+ label: string;
45
+ /** At most 48 values, oldest first, already downsampled. */
46
+ values: number[];
47
+ /** Domain of the chart; covers the values and every mark. */
48
+ min: number;
49
+ max: number;
50
+ /** Horizontal reference lines in value units (a target, a baseline). */
51
+ marks?: {
52
+ value: number;
53
+ label: string;
54
+ tone?: TspTone;
55
+ }[];
56
+ /** Latest value, formatted (`186 tok/s`). */
57
+ last: string;
58
+ /** Per-point tooltip text, same length as `values` (`12:04:31 · 186 tok/s`). */
59
+ tips?: string[];
60
+ tone?: TspTone;
61
+ }
62
+ /** One bar per key (a model, a shard): a value against a common maximum. */
63
+ export interface JobWidgetBarsBlock {
64
+ kind: "bars";
65
+ label: string;
66
+ items: {
67
+ label: string;
68
+ value: number;
69
+ text: string;
70
+ tone?: TspTone;
71
+ }[];
72
+ /** The value a full bar stands for. */
73
+ max: number;
74
+ }
75
+ /** Progress of a countable whole (`7/9 trials`). */
76
+ export interface JobWidgetMeterBlock {
77
+ kind: "meter";
78
+ label: string;
79
+ /** 0–1. */
80
+ value: number;
81
+ /** `7/9 trials`. */
82
+ text: string;
83
+ tone?: TspTone;
84
+ }
85
+ /** A few labelled numbers on one line (`p50 41 ms · p99 212 ms · errors 0`). */
86
+ export interface JobWidgetStatBlock {
87
+ kind: "stat";
88
+ items: {
89
+ label: string;
90
+ text: string;
91
+ tone?: TspTone;
92
+ trend?: JobWidgetTrend;
93
+ }[];
94
+ }
95
+ /** One cell per key with its latest state (CI jobs, shards, workers). */
96
+ export interface JobWidgetGridBlock {
97
+ kind: "grid";
98
+ label: string;
99
+ items: {
100
+ label: string;
101
+ text: string;
102
+ tone: TspTone;
103
+ }[];
104
+ }
105
+ /** The latest line a rule captured (the test now running, the current phase). */
106
+ export interface JobWidgetTextBlock {
107
+ kind: "text";
108
+ text: string;
109
+ }
110
+ export type JobWidgetBlock = JobWidgetSparkBlock | JobWidgetBarsBlock | JobWidgetMeterBlock | JobWidgetStatBlock | JobWidgetGridBlock | JobWidgetTextBlock;
111
+ /**
112
+ * Everything a renderer needs to draw one job's widget. Plain JSON: it rides
113
+ * on `JobSnapshot.widget` through `wait` progress updates and is persisted
114
+ * with the final `wait` result, so a sealed card redraws the last state after
115
+ * a session reload.
116
+ */
117
+ export interface JobWidgetView {
118
+ /** Short name of what is being watched (`verb-bench · 3 models`). */
119
+ title: string;
120
+ headline?: JobWidgetHeadline;
121
+ /** What the job is doing now: a subagent's stage, or the last line of output. */
122
+ stage?: string;
123
+ /** Top to bottom; the first block is the primary one, and compact views show only it. */
124
+ blocks: JobWidgetBlock[];
125
+ state: JobWidgetState;
126
+ /** Epoch ms of the newest data the view reflects. */
127
+ updatedAt: number;
128
+ }
129
+ /** A running job's widget, as the HUD and the status line list them. */
130
+ export interface JobWidgetEntry {
131
+ id: string;
132
+ type: JobTileType;
133
+ view: JobWidgetView;
134
+ }
135
+ /** What a glance at a widget reads: its headline, else the primary figure of its blocks. */
136
+ export interface JobWidgetGlance {
137
+ text: string;
138
+ label?: string;
139
+ trend?: JobWidgetTrend;
140
+ }
141
+ /** What one glance at the widget reads: the headline, else the latest figure of its first spark or meter. */
142
+ export declare function jobWidgetGlance(view: JobWidgetView): JobWidgetGlance | undefined;
143
+ /** The widget's first spark cut to its newest `points` values (the HUD's mini chart); undefined without data. */
144
+ export declare function jobWidgetSpark(view: JobWidgetView, points?: number): JobWidgetSparkBlock | undefined;
145
+ /** The entry whose live widget (one a spec drives) saw data last. */
146
+ export declare function latestJobWidget<T extends JobWidgetEntry>(entries: readonly T[]): T | undefined;
147
+ /** The widget as one plain line for tooltips: `verb-bench · 3 models — decode 186 tok/s ▲ 15%`. */
148
+ export declare function jobWidgetSummary(view: JobWidgetView): string;
149
+ /** Spans of a glance: muted label, strong number, toned trend. */
150
+ export declare function jobWidgetGlanceSpans(glance: JobWidgetGlance): TspSpan[];
151
+ /**
152
+ * A glance for the ANSI status line: the figure with its trend, then a
153
+ * `cells`-wide sparkline of the primary spark when there is one.
154
+ */
155
+ export declare function formatJobWidgetGlance(view: JobWidgetView, theme: Theme, cells?: number): string;
156
+ /**
157
+ * A job's whole widget as a TSP subtree (role `zeta.job.widget`), as the jobs
158
+ * sheet details it: a head row (title, stage, headline) over every block.
159
+ */
160
+ export declare function describeJobWidget(view: JobWidgetView): NativeNode;
161
+ /**
162
+ * The HUD jobs pill's hover card: up to four running jobs as tiles, then a
163
+ * count of the rest; undefined without widgets. Its tiles carry no clock:
164
+ * Tern draws the card only once hovered, and a clock drawn then would start
165
+ * from the last time the program wrote.
166
+ */
167
+ export declare function describeJobWidgetsHovercard(entries: readonly JobWidgetEntry[]): TspPropNode | undefined;
168
+ /** The HUD's mini chart: the newest values of the widget's first spark; undefined without one. */
169
+ export declare function describeJobWidgetMiniSpark(view: JobWidgetView): NativeNode | undefined;
170
+ /** Where a tiled job stands. */
171
+ export type JobTileStatus = "running" | "completed" | "failed" | "cancelled";
172
+ /** What kind of job a tile shows: a subagent (`task`) goes by its name, any other job by what it runs. */
173
+ export type JobTileType = "bash" | "task" | "eval";
174
+ /** One job as a tile draws it: who it is, how long it has run, and its widget when it has one. */
175
+ export interface JobTile {
176
+ id: string;
177
+ type: JobTileType;
178
+ status: JobTileStatus;
179
+ /** The job's label (a command): the title of a job that is no subagent, before a widget names it. */
180
+ label: string;
181
+ /** How long the job has run; a tile without it shows no clock. */
182
+ durationMs?: number;
183
+ /** Whether the job is live (its dot pulses, its clock runs); settled and sealed tiles freeze. */
184
+ live: boolean;
185
+ /** The job's widget; only a live one (a spec drives it) draws figures and charts, any lends its stage. */
186
+ widget?: JobWidgetView;
187
+ /** A task's own completion estimate (0–100), drawn as a ring. */
188
+ completionPercent?: number;
189
+ /** What the job is doing now, when its widget names nothing: a task's stage in its own words. */
190
+ stage?: string;
191
+ exitCode?: number;
192
+ }
193
+ /**
194
+ * Jobs as one frame of equal tiles (role `zeta.job.tiles`) that wraps onto
195
+ * more rows when the frame runs out of width.
196
+ */
197
+ export declare function describeJobTiles(tiles: readonly JobTile[]): NativeNode;
198
+ /**
199
+ * One job as a tile (role `zeta.job.tile`): a head line (status, name, id,
200
+ * a task's own completion estimate as a ring, clock), then what a live
201
+ * widget shows (the figure a glance takes away, its primary block, quiet
202
+ * lines of stats) and the stage. With nothing to chart, the stage is the
203
+ * tile's body.
204
+ */
205
+ export declare function describeJobTile(tile: JobTile): NativeNode;
206
+ /**
207
+ * A job's whole widget as terminal lines, each within `width` (capped at 80
208
+ * so bars stay next to their labels): the head line (title, stage, headline
209
+ * at the right), then every block under a shared label column.
210
+ */
211
+ export declare function renderJobWidgetLines(view: JobWidgetView, width: number, theme: Theme): string[];
212
+ /** How the ANSI wait card draws a tile. */
213
+ export interface JobTileLineOptions {
214
+ /** Opens the title line: the caller's status icon and type badge. */
215
+ lead: string;
216
+ /** Closes the title line at the right, after the figure: the duration. */
217
+ meta: string;
218
+ /** Every block rather than the primary one alone (an expanded card). */
219
+ full?: boolean;
220
+ }
221
+ /**
222
+ * A tile as terminal lines within `width`: the lead, name and id with the
223
+ * figure and meta at the right, then a live widget's primary block (every
224
+ * block when `full`) and dim lines of stats and stage, capped at 80 cells.
225
+ */
226
+ export declare function renderJobTileLines(tile: JobTile, width: number, theme: Theme, options: JobTileLineOptions): string[];