@linxiraos/pi-tui 1.3.2 → 1.4.1

package/src/tools/job-widget.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Live widgets for background jobs: the rendered state of what a job is
+ * doing (a benchmark's requests/s over time, tests passed per model, CI jobs
+ * green so far), shown in the `wait` card, the HUD's jobs pill and the jobs
+ * sheet.
+ *
+ * A widget is data, not code. In coding-agent, a cheap model writes a
+ * `JobWidgetSpec` once per job (rules that pull numbers out of the job's
+ * output streams, and the blocks to draw them with); the job-widgets runtime
+ * then applies those rules to every new line and recomputes a
+ * {@link JobWidgetView}. Renderers here draw that view as TSP nodes (Tern) or
+ * ANSI lines, and never see a rule or a regex.
+ */
+import type { TspPropNode, TspSpan, TspTone } from "@linxiraos/pi-wire";
+import type { NativeNode } from "../native/node";
+import type { Theme } from "../theme/theme";
+/** Where a widget's view stands. */
+export type JobWidgetState = 
+/** The cheap model is writing the spec; the view holds the model-free fallback meanwhile. */
+"authoring"
+/** The spec's rules drive the view. */
+ | "live"
+/** No spec (no model, authoring failed, nothing to read yet): last line and rates only. */
+ | "fallback";
+/** A formatted number with the direction it moved, for headlines and stats. */
+export interface JobWidgetTrend {
+    /** `▲ 15%`, `▼ 3.2 ms`. */
+    text: string;
+    /** `success` when the move is toward `better`, `error` away from it, `muted` without a direction. */
+    tone: "success" | "error" | "muted";
+}
+/** The headline value: the one number a glance should take away (`186 tok/s`). */
+export interface JobWidgetHeadline {
+    /** Formatted value with its unit. */
+    text: string;
+    /** What the value is, when the title does not already say it (`decode`, `p50`). */
+    label?: string;
+    trend?: JobWidgetTrend;
+}
+/** A time series drawn as columns, newest right, with optional reference lines. */
+export interface JobWidgetSparkBlock {
+    kind: "spark";
+    /** What the series measures (`tok/s · nvfp4 b1`). */
+    label: string;
+    /** At most 48 values, oldest first, already downsampled. */
+    values: number[];
+    /** Domain of the chart; covers the values and every mark. */
+    min: number;
+    max: number;
+    /** Horizontal reference lines in value units (a target, a baseline). */
+    marks?: {
+        value: number;
+        label: string;
+        tone?: TspTone;
+    }[];
+    /** Latest value, formatted (`186 tok/s`). */
+    last: string;
+    /** Per-point tooltip text, same length as `values` (`12:04:31 · 186 tok/s`). */
+    tips?: string[];
+    tone?: TspTone;
+}
+/** One bar per key (a model, a shard): a value against a common maximum. */
+export interface JobWidgetBarsBlock {
+    kind: "bars";
+    label: string;
+    items: {
+        label: string;
+        value: number;
+        text: string;
+        tone?: TspTone;
+    }[];
+    /** The value a full bar stands for. */
+    max: number;
+}
+/** Progress of a countable whole (`7/9 trials`). */
+export interface JobWidgetMeterBlock {
+    kind: "meter";
+    label: string;
+    /** 0–1. */
+    value: number;
+    /** `7/9 trials`. */
+    text: string;
+    tone?: TspTone;
+}
+/** A few labelled numbers on one line (`p50 41 ms · p99 212 ms · errors 0`). */
+export interface JobWidgetStatBlock {
+    kind: "stat";
+    items: {
+        label: string;
+        text: string;
+        tone?: TspTone;
+        trend?: JobWidgetTrend;
+    }[];
+}
+/** One cell per key with its latest state (CI jobs, shards, workers). */
+export interface JobWidgetGridBlock {
+    kind: "grid";
+    label: string;
+    items: {
+        label: string;
+        text: string;
+        tone: TspTone;
+    }[];
+}
+/** The latest line a rule captured (the test now running, the current phase). */
+export interface JobWidgetTextBlock {
+    kind: "text";
+    text: string;
+}
+export type JobWidgetBlock = JobWidgetSparkBlock | JobWidgetBarsBlock | JobWidgetMeterBlock | JobWidgetStatBlock | JobWidgetGridBlock | JobWidgetTextBlock;
+/**
+ * Everything a renderer needs to draw one job's widget. Plain JSON: it rides
+ * on `JobSnapshot.widget` through `wait` progress updates and is persisted
+ * with the final `wait` result, so a sealed card redraws the last state after
+ * a session reload.
+ */
+export interface JobWidgetView {
+    /** Short name of what is being watched (`verb-bench · 3 models`). */
+    title: string;
+    headline?: JobWidgetHeadline;
+    /** What the job is doing now: a subagent's stage, or the last line of output. */
+    stage?: string;
+    /** Top to bottom; the first block is the primary one, and compact views show only it. */
+    blocks: JobWidgetBlock[];
+    state: JobWidgetState;
+    /** Epoch ms of the newest data the view reflects. */
+    updatedAt: number;
+}
+/** A running job's widget, as the HUD and the status line list them. */
+export interface JobWidgetEntry {
+    id: string;
+    type: JobTileType;
+    view: JobWidgetView;
+}
+/** What a glance at a widget reads: its headline, else the primary figure of its blocks. */
+export interface JobWidgetGlance {
+    text: string;
+    label?: string;
+    trend?: JobWidgetTrend;
+}
+/** What one glance at the widget reads: the headline, else the latest figure of its first spark or meter. */
+export declare function jobWidgetGlance(view: JobWidgetView): JobWidgetGlance | undefined;
+/** The widget's first spark cut to its newest `points` values (the HUD's mini chart); undefined without data. */
+export declare function jobWidgetSpark(view: JobWidgetView, points?: number): JobWidgetSparkBlock | undefined;
+/** The entry whose live widget (one a spec drives) saw data last. */
+export declare function latestJobWidget<T extends JobWidgetEntry>(entries: readonly T[]): T | undefined;
+/** The widget as one plain line for tooltips: `verb-bench · 3 models — decode 186 tok/s ▲ 15%`. */
+export declare function jobWidgetSummary(view: JobWidgetView): string;
+/** Spans of a glance: muted label, strong number, toned trend. */
+export declare function jobWidgetGlanceSpans(glance: JobWidgetGlance): TspSpan[];
+/**
+ * A glance for the ANSI status line: the figure with its trend, then a
+ * `cells`-wide sparkline of the primary spark when there is one.
+ */
+export declare function formatJobWidgetGlance(view: JobWidgetView, theme: Theme, cells?: number): string;
+/**
+ * A job's whole widget as a TSP subtree (role `zeta.job.widget`), as the jobs
+ * sheet details it: a head row (title, stage, headline) over every block.
+ */
+export declare function describeJobWidget(view: JobWidgetView): NativeNode;
+/**
+ * The HUD jobs pill's hover card: up to four running jobs as tiles, then a
+ * count of the rest; undefined without widgets. Its tiles carry no clock:
+ * Tern draws the card only once hovered, and a clock drawn then would start
+ * from the last time the program wrote.
+ */
+export declare function describeJobWidgetsHovercard(entries: readonly JobWidgetEntry[]): TspPropNode | undefined;
+/** The HUD's mini chart: the newest values of the widget's first spark; undefined without one. */
+export declare function describeJobWidgetMiniSpark(view: JobWidgetView): NativeNode | undefined;
+/** Where a tiled job stands. */
+export type JobTileStatus = "running" | "completed" | "failed" | "cancelled";
+/** What kind of job a tile shows: a subagent (`task`) goes by its name, any other job by what it runs. */
+export type JobTileType = "bash" | "task" | "eval";
+/** One job as a tile draws it: who it is, how long it has run, and its widget when it has one. */
+export interface JobTile {
+    id: string;
+    type: JobTileType;
+    status: JobTileStatus;
+    /** The job's label (a command): the title of a job that is no subagent, before a widget names it. */
+    label: string;
+    /** How long the job has run; a tile without it shows no clock. */
+    durationMs?: number;
+    /** Whether the job is live (its dot pulses, its clock runs); settled and sealed tiles freeze. */
+    live: boolean;
+    /** The job's widget; only a live one (a spec drives it) draws figures and charts, any lends its stage. */
+    widget?: JobWidgetView;
+    /** A task's own completion estimate (0–100), drawn as a ring. */
+    completionPercent?: number;
+    /** What the job is doing now, when its widget names nothing: a task's stage in its own words. */
+    stage?: string;
+    exitCode?: number;
+}
+/**
+ * Jobs as one frame of equal tiles (role `zeta.job.tiles`) that wraps onto
+ * more rows when the frame runs out of width.
+ */
+export declare function describeJobTiles(tiles: readonly JobTile[]): NativeNode;
+/**
+ * One job as a tile (role `zeta.job.tile`): a head line (status, name, id,
+ * a task's own completion estimate as a ring, clock), then what a live
+ * widget shows (the figure a glance takes away, its primary block, quiet
+ * lines of stats) and the stage. With nothing to chart, the stage is the
+ * tile's body.
+ */
+export declare function describeJobTile(tile: JobTile): NativeNode;
+/**
+ * A job's whole widget as terminal lines, each within `width` (capped at 80
+ * so bars stay next to their labels): the head line (title, stage, headline
+ * at the right), then every block under a shared label column.
+ */
+export declare function renderJobWidgetLines(view: JobWidgetView, width: number, theme: Theme): string[];
+/** How the ANSI wait card draws a tile. */
+export interface JobTileLineOptions {
+    /** Opens the title line: the caller's status icon and type badge. */
+    lead: string;
+    /** Closes the title line at the right, after the figure: the duration. */
+    meta: string;
+    /** Every block rather than the primary one alone (an expanded card). */
+    full?: boolean;
+}
+/**
+ * A tile as terminal lines within `width`: the lead, name and id with the
+ * figure and meta at the right, then a live widget's primary block (every
+ * block when `full`) and dim lines of stats and stage, capped at 80 cells.
+ */
+export declare function renderJobTileLines(tile: JobTile, width: number, theme: Theme, options: JobTileLineOptions): string[];