@nredd/pi-session-kit 0.6.0 → 0.8.0

package/src/monitor/widget.ts

@@ -1,7 +1,13 @@
-/** Quiet above-editor summary of running monitors. */
+/**
+ * Above-editor monitors panel, laid out like the Todos and subagents widgets: a disclosure heading
+ * (clickable, plus a configurable shortcut), one bulleted row per monitor with flush-right stats,
+ * and a fixed-height scroll window. It is display only: passive monitor output still stays in the
+ * ring buffer and never enters the transcript or model context.
+ */
 
 import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { type TUI, type TuiMouseEvent, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { COLLAPSE_KEY_OFF } from "../config.ts";
 import { formatDuration } from "./messages.ts";
 import type { MonitorInfo } from "./types.ts";
 
@@ -9,54 +15,202 @@ export const WIDGET_KEY = "session-kit:monitors";
 const TICK_MS = 1_000;
 
 type WidgetTheme = Pick<Theme, "fg">;
+type Color = Parameters<Theme["fg"]>[0];
 
-function monitorSummary(info: MonitorInfo, now: number): string {
-	return `${info.name} ${formatDuration(now - info.startedAt)} ${info.lines} lines last: ${info.lastLine ?? "(no output)"}`;
+export type MonitorState = "running" | "matched" | "failed" | "exited";
+
+const STATE_COLOR: Record<MonitorState, Color> = {
+	running: "success",
+	matched: "warning",
+	failed: "error",
+	exited: "dim",
+};
+
+/** Bullet state: a running monitor that has matched, a non-clean end, or a clean/requested end. */
+export function monitorState(info: MonitorInfo): MonitorState {
+	if (info.status === "running") return info.matches > 0 ? "matched" : "running";
+	if (info.status === "timeout") return "failed";
+	if (info.status === "stopped") return "exited";
+	return info.exitCode === 0 && info.signal === null ? "exited" : "failed";
+}
+
+/** A slice `[start, end)` of the rows plus which edge hints take a row. */
+export interface MonitorWindow {
+	start: number;
+	end: number;
+	above: boolean;
+	below: boolean;
+	maxOffset: number;
+}
+
+/**
+ * Window of exactly `budget` rows over `total` monitors from `offset`: each visible edge hint costs
+ * a row, so the panel height never changes while scrolling (budget >= 3 keeps every position
+ * showing at least one monitor).
+ */
+export function windowFor(total: number, budget: number, offset: number): MonitorWindow {
+	if (total <= budget) return { start: 0, end: total, above: false, below: false, maxOffset: 0 };
+	const maxOffset = total - (budget - 1);
+	const start = Math.max(0, Math.min(maxOffset, offset));
+	if (start === 0) return { start, end: budget - 1, above: false, below: true, maxOffset };
+	if (start === maxOffset) return { start, end: total, above: true, below: false, maxOffset };
+	return { start, end: start + budget - 2, above: true, below: true, maxOffset };
+}
+
+/** `left` truncated first so `right` survives; never wider than `width` (a wrap desyncs pi's diff). */
+function rightAlign(left: string, right: string, width: number): string {
+	const rightWidth = visibleWidth(right);
+	const clamped = truncateToWidth(left, Math.max(0, width - rightWidth - 1), "…");
+	const gap = Math.max(1, width - visibleWidth(clamped) - rightWidth);
+	return truncateToWidth(clamped + " ".repeat(gap) + right, width, "…");
+}
+
+/** Keep the full heading ahead of an optional hint; a narrow panel omits the hint. */
+function headingLine(heading: string, hint: string | undefined, width: number): string {
+	if (hint && visibleWidth(heading) + visibleWidth(hint) + 1 <= width) return rightAlign(heading, hint, width);
+	return truncateToWidth(heading, width, "…");
+}
+
+export interface WidgetView {
+	collapsed: boolean;
+	offset: number;
+	/** Row budget including the heading. */
+	maxLines: number;
+	/** Shortcut shown in the collapsed hint, or `"off"`. */
+	collapseKey: string;
+	/** Show every row (pi's tool-output expansion) instead of the budget. */
+	showAll?: boolean;
+}
+
+export interface RenderedWidget {
+	lines: string[];
+	/** The offset actually used after clamping to the window. */
+	offset: number;
+	/** Largest scroll offset (0 when everything fits). */
+	maxOffset: number;
 }
 
-/** Render one compact summary, favouring the newest monitor when all do not fit. */
-export function formatSummary(infos: MonitorInfo[], now: number, width: number, theme: WidgetTheme): string[] {
-	if (infos.length === 0) return [];
-	const count = `${infos.length} monitor${infos.length === 1 ? "" : "s"}`;
-	const all = `● ${count}  ${infos.map((info) => monitorSummary(info, now)).join("  ")}`;
-	if (visibleWidth(all) <= width) return [theme.fg("success", "●") + theme.fg("muted", all.slice(1))];
-	const newest = infos.reduce((latest, info) => (info.startedAt > latest.startedAt ? info : latest));
-	const compact = `● ${count}  ${monitorSummary(newest, now)}`;
-	return [truncateToWidth(theme.fg("success", "●") + theme.fg("muted", compact.slice(1)), width, "…")];
+function headingText(infos: MonitorInfo[]): string {
+	const running = infos.filter((i) => i.status === "running").length;
+	const failed = infos.filter((i) => monitorState(i) === "failed").length;
+	const done = infos.length - running - failed;
+	const parts = [
+		running ? `${running} running` : "",
+		failed ? `${failed} failed` : "",
+		done ? `${done} done` : "",
+	].filter(Boolean);
+	return `Monitors (${parts.join(" · ")})`;
+}
+
+function rowLine(info: MonitorInfo, now: number, width: number, theme: WidgetTheme): string {
+	const bullet = theme.fg(STATE_COLOR[monitorState(info)], "●");
+	const last = info.lastLine === undefined || info.lastLine === "" ? "(no output)" : info.lastLine;
+	const left = `${bullet} ${info.name}  ${theme.fg("dim", last)}`;
+	const elapsed = formatDuration((info.endedAt ?? now) - info.startedAt);
+	const stats = theme.fg("dim", `${elapsed} · ${info.lines} ${info.lines === 1 ? "line" : "lines"}`);
+	return rightAlign(left, stats, width);
+}
+
+/** Pure render: collapsed is heading plus spacer, expanded is a constant-height window. */
+export function renderWidget(
+	infos: MonitorInfo[],
+	now: number,
+	width: number,
+	theme: WidgetTheme,
+	view: WidgetView,
+): RenderedWidget {
+	if (infos.length === 0) return { lines: [], offset: 0, maxOffset: 0 };
+	const anyRunning = infos.some((i) => i.status === "running");
+	const color: Color = anyRunning ? "accent" : "dim";
+	const disclosure = theme.fg("dim", view.collapsed ? "▸" : "▾");
+	const head = `${disclosure} ${theme.fg(color, anyRunning ? "●" : "○")} ${theme.fg(color, headingText(infos))}`;
+
+	if (view.collapsed) {
+		const hint = view.collapseKey === COLLAPSE_KEY_OFF ? "collapsed" : `${view.collapseKey} to expand`;
+		return { lines: [headingLine(head, theme.fg("dim", hint), width), ""], offset: 0, maxOffset: 0 };
+	}
+
+	const budget = view.showAll ? infos.length : view.maxLines - 1;
+	const win = windowFor(infos.length, budget, view.offset);
+	const rows: string[] = [];
+	if (win.above) rows.push(theme.fg("dim", `↑ ${win.start} more`));
+	for (const info of infos.slice(win.start, win.end)) rows.push(rowLine(info, now, Math.max(0, width - 3), theme));
+	if (win.below) rows.push(theme.fg("dim", `↓ ${infos.length - win.end} more`));
+
+	const lines = [headingLine(head, undefined, width)];
+	rows.forEach((row, i) => {
+		const connector = theme.fg("dim", i === rows.length - 1 ? "└─" : "├─");
+		lines.push(truncateToWidth(`${connector} ${row}`, width, "…"));
+	});
+	lines.push("");
+	return { lines, offset: win.start, maxOffset: win.maxOffset };
+}
+
+export interface WidgetOptions {
+	maxLines: number;
+	collapseKey: string;
+	now?: () => number;
 }
 
 export class MonitorWidget {
 	private ctx: ExtensionContext | undefined;
 	private visible = false;
-	private requestRender: (() => void) | undefined;
+	private tui: TUI | undefined;
 	private timer: NodeJS.Timeout | undefined;
+	private collapsed = false;
+	private offset = 0;
+	private maxOffset = 0;
 
-	constructor(private readonly running: () => MonitorInfo[]) {}
+	/** `list` is every retained monitor; the panel shows while at least one is running. */
+	constructor(
+		private readonly list: () => MonitorInfo[],
+		private readonly options: WidgetOptions,
+	) {}
 
 	/** Bind to the session's UI; a no-op outside the TUI. */
 	attach(ctx: ExtensionContext): void {
 		if (ctx.mode === "tui") this.ctx = ctx;
 	}
 
+	isVisible(): boolean {
+		return this.visible;
+	}
+
+	isCollapsed(): boolean {
+		return this.collapsed;
+	}
+
+	/** Collapse or expand, resetting the scroll position; a full redraw covers the height step. */
+	toggle(): void {
+		this.collapsed = !this.collapsed;
+		this.offset = 0;
+		this.tui?.requestRender(true);
+	}
+
 	/** Show or hide the widget to match the manager, and repaint. */
 	refresh(): void {
 		const ctx = this.ctx;
 		if (!ctx) return;
-		const any = this.running().length > 0;
+		const any = this.list().some((i) => i.status === "running");
 		if (any && !this.visible) {
-			ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
-				this.requestRender = () => tui.requestRender();
-				return {
-					render: (width: number) => formatSummary(this.running(), Date.now(), width, theme),
-					invalidate() {},
-				};
-			});
+			ctx.ui.setWidget(
+				WIDGET_KEY,
+				(tui, theme) => {
+					this.tui = tui;
+					return {
+						render: (width: number) => this.render(width, theme),
+						handleMouse: (event: TuiMouseEvent) => this.handleMouse(event),
+						invalidate() {},
+					};
+				},
+				{ placement: "aboveEditor" },
+			);
 			this.visible = true;
 			this.startTicking();
 		} else if (!any && this.visible) {
 			this.hide();
 		}
-		this.requestRender?.();
+		this.tui?.requestRender();
 	}
 
 	/** Remove the widget and stop the timer. */
@@ -65,16 +219,45 @@ export class MonitorWidget {
 		this.ctx = undefined;
 	}
 
+	private render(width: number, theme: WidgetTheme): string[] {
+		const out = renderWidget(this.list(), (this.options.now ?? Date.now)(), width, theme, {
+			collapsed: this.collapsed,
+			offset: this.offset,
+			maxLines: this.options.maxLines,
+			collapseKey: this.options.collapseKey,
+			showAll: this.ctx?.ui.getToolsExpanded?.() === true,
+		});
+		this.offset = out.offset;
+		this.maxOffset = out.maxOffset;
+		return out.lines;
+	}
+
+	private handleMouse(event: TuiMouseEvent): { handled: true } | undefined {
+		if (event.type === "click" && event.button === "left" && event.y === 0) {
+			this.toggle();
+			return { handled: true };
+		}
+		if (event.type !== "wheel" || this.collapsed) return undefined;
+		const next = Math.max(0, Math.min(this.maxOffset, this.offset + Math.trunc(event.wheelDelta ?? 0)));
+		if (next === this.offset) return undefined;
+		this.offset = next;
+		this.tui?.requestRender();
+		return { handled: true };
+	}
+
 	private hide(): void {
 		if (this.timer) clearInterval(this.timer);
 		this.timer = undefined;
 		if (this.visible) this.ctx?.ui.setWidget(WIDGET_KEY, undefined);
 		this.visible = false;
-		this.requestRender = undefined;
+		this.tui = undefined;
 	}
 
 	private startTicking(): void {
-		this.timer = setInterval(() => this.requestRender?.(), TICK_MS);
+		// Collapsed rows show no elapsed time; counts repaint through `refresh` on state changes.
+		this.timer = setInterval(() => {
+			if (!this.collapsed) this.tui?.requestRender();
+		}, TICK_MS);
 		this.timer.unref();
 	}
 }

package/src/stats/component.ts

@@ -5,7 +5,15 @@
  */
 
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
-import { type Color, type Component, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import {
+	type Color,
+	type Component,
+	Key,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
 import { sanitize } from "../diff/view.ts";
 import {
 	chartSeries,
@@ -39,8 +47,8 @@ import { seriesPalette } from "./palette.ts";
 import { timeAxis } from "./ticks.ts";
 
 type ThemeLike = Pick<Theme, "fg" | "bg" | "bold" | "style" | "colors">;
-export type Tab = "Overview" | "Models";
-const TABS: readonly Tab[] = ["Overview", "Models"];
+export type Tab = "Overview" | "Models" | "Machines";
+const TABS: readonly Tab[] = ["Overview", "Models", "Machines"];
 /** Chart lines, at most; their colours are shared by the chart, its legend and the model list. */
 const SERIES = 3;
 /** Narrowest plot `plot` can draw; only panes too narrow for a 6-week heatmap hit it. */
@@ -76,6 +84,8 @@ export interface StatsViewOptions {
 	today?: string;
 	now?: number;
 	coverage?: string;
+	/** Offline per-source provenance, rendered as a scrollable Machines tab. */
+	freshness?: readonly string[];
 	tab?: Tab;
 }
 
@@ -126,7 +136,8 @@ export class StatsView implements Component {
 			return;
 		}
 		if (matchesKey(data, Key.tab) || matchesKey(data, Key.shift("tab"))) {
-			this.tab = this.tab === "Overview" ? "Models" : "Overview";
+			const step = matchesKey(data, Key.shift("tab")) ? -1 : 1;
+			this.tab = TABS[(TABS.indexOf(this.tab) + step + TABS.length) % TABS.length] ?? "Overview";
 			this.scroll = 0;
 		} else if (data === "r") {
 			this.range = RANGES[(RANGES.indexOf(this.range) + 1) % RANGES.length] ?? "all";
@@ -155,6 +166,13 @@ export class StatsView implements Component {
 		let body: string[];
 		let hint = "";
 		if (this.tab === "Overview") body = this.scrolled(this.overviewBody(w, room), room);
+		else if (this.tab === "Machines")
+			body = this.scrolled(
+				(this.o.freshness ?? ["Per-machine freshness unknown (no source metadata)."]).flatMap((line) =>
+					wrapTextWithAnsi(this.paint("muted", line), contentWidth(w)),
+				),
+				room,
+			);
 		else {
 			const models = this.modelsBody(w, room);
 			body = this.scrolled(models.lines, room);
@@ -175,7 +193,7 @@ export class StatsView implements Component {
 		const joined = spread(tabs, coverage, inner);
 		const lines = [
 			joined ?? tabs,
-			...this.selectors(inner),
+			...(this.tab === "Machines" ? [] : this.selectors(inner)),
 			...(joined ? [] : [coverage]),
 			this.paint("dim", "─".repeat(inner)),
 		];

package/src/stats/freshness.ts

@@ -0,0 +1,46 @@
+/** Offline provenance display. Export time is not last activity or proof of fleet completeness. */
+import { sanitize } from "../diff/view.ts";
+import type { Coverage } from "./snapshot.ts";
+
+/** Invalid/absent clocks never become fresh; future clocks are explicitly untrustworthy. */
+export function timestampLabel(ms: number | undefined, now: number): string {
+	if (ms === undefined || !Number.isFinite(ms) || ms <= 0 || ms > 8640000000000000) return "unknown";
+	const timestamp = new Date(ms).toISOString();
+	if (ms > now) return `${timestamp} (future; clock skew)`;
+	const minutes = Math.floor((now - ms) / 60000);
+	const age =
+		minutes < 1
+			? "<1m"
+			: minutes < 60
+				? `${minutes}m`
+				: minutes < 1440
+					? `${Math.floor(minutes / 60)}h`
+					: `${Math.floor(minutes / 1440)}d`;
+	return `${timestamp} (${age} ago)`;
+}
+
+/** Shared print/TUI lines. UUIDs disambiguate default or duplicate labels without exposing hostnames. */
+export function freshnessLines(coverage: Coverage, now = Date.now()): string[] {
+	const lines = [
+		`Viewer last import: ${timestampLabel(coverage.importedAt, now)}`,
+		"Known sources only; other machines cannot be discovered here.",
+		"Export age is not last activity. Local history is scanned on opening.",
+	];
+	if (!coverage.sources?.length) return [...lines, "Per-machine freshness unknown (no source metadata)."];
+	for (const source of [...coverage.sources].sort(
+		(a, b) => Number(b.local) - Number(a.local) || a.machineId.localeCompare(b.machineId),
+	)) {
+		lines.push("", `${sanitize(source.label)} [${source.machineId}]${source.local ? " (local)" : ""}`);
+		if (source.local) lines.push(source.incomplete ? "Local scan incomplete" : "Local scan complete at opening");
+		else {
+			lines.push(`Producer exported: ${timestampLabel(source.exportedAt, now)}`);
+			if (source.incomplete)
+				lines.push(
+					source.exportedAt === undefined
+						? "Incomplete import; no last-good snapshot"
+						: "Incomplete import; retained last-good snapshot",
+				);
+		}
+	}
+	return lines;
+}

package/src/stats/index.ts

@@ -8,6 +8,7 @@ import { type Clock, realClock } from "../clock.ts";
 import type { KitConfig } from "../config.ts";
 import { say } from "../output.ts";
 import { StatsView, summary } from "./component.ts";
+import { freshnessLines } from "./freshness.ts";
 import type { Loaded } from "./load.ts";
 import { type Combined, coverageLabel, loadCombined } from "./snapshot.ts";
 
@@ -52,19 +53,20 @@ export function register(
 
 			const damage = [...problems(loaded), ...loaded.coverage.problems.map((p) => `/stats: ${p}`)];
 			const coverage = coverageLabel(loaded.coverage);
+			const freshness = freshnessLines(loaded.coverage, clock.now());
 			if (!tui) {
 				say(
 					pi,
 					ctx,
 					MESSAGE_TYPE,
-					[summary(loaded.calls.filter((c) => c.ms <= clock.now())), coverage, ...damage].join("\n"),
+					[summary(loaded.calls.filter((c) => c.ms <= clock.now())), coverage, ...freshness, ...damage].join("\n"),
 					"info",
 				);
 				return;
 			}
 			for (const line of damage) ctx.ui.notify(line, "warning");
 			if (loaded.calls.length === 0) {
-				ctx.ui.notify(`/stats: no usage recorded yet\n${coverage}`, "info");
+				ctx.ui.notify(`/stats: no usage recorded yet\n${coverage}\n${freshness.join("\n")}`, "info");
 				return;
 			}
 			const { calls, sessions, badLines } = loaded;
@@ -75,6 +77,7 @@ export function register(
 						sessions,
 						badLines,
 						coverage,
+						freshness,
 						now: clock.now(),
 						theme,
 						rows: () => tuiHost.terminal.rows,

package/src/stats/snapshot.ts

@@ -63,7 +63,14 @@ export interface GlobalCache {
 	machines: Record<string, MachineSnapshot>;
 	problems: string[];
 }
+/** Known sources only, including failed imports with no last-good snapshot. */
+export interface MachineCoverage extends Identity {
+	local: boolean;
+	exportedAt?: number;
+	incomplete: boolean;
+}
 export interface Coverage {
+	sources?: MachineCoverage[];
 	machines: number;
 	remoteMachines: number;
 	importedAt?: number;
@@ -484,6 +491,22 @@ export async function loadCombined(
 		sessionMetadata: [...sessions.values()],
 		sessions: [...sessions.values()].filter((s) => !s.child && owners.has(s.path)),
 		coverage: {
+			sources: [
+				{ ...identity, local: true, incomplete: local.errors > 0 || local.badLines > 0 },
+				...remotes.map(({ manifest }) => ({
+					machineId: manifest.machineId,
+					label: manifest.label,
+					local: false,
+					exportedAt: manifest.exportedAt,
+					incomplete: global.problems.some((p) => p.endsWith(` ${manifest.machineId}`)),
+				})),
+				...global.problems.flatMap((p) => {
+					const id = /^(?:Incomplete|Missing) snapshot (.+)$/.exec(p)?.[1];
+					return id && UUID.test(id) && id !== identity.machineId && !global.machines[id]
+						? [{ machineId: id, label: "Pi machine", local: false, incomplete: true }]
+						: [];
+				}),
+			],
 			machines: remotes.length + 1,
 			remoteMachines: remotes.length,
 			importedAt: global.importedAt || undefined,
@@ -493,5 +516,5 @@ export async function loadCombined(
 	};
 }
 export function coverageLabel(c: Coverage): string {
-	return `${c.incomplete ? "incomplete coverage · " : ""}${c.machines} machine${c.machines === 1 ? "" : "s"} · ${c.remoteMachines ? "cached" : "local-only"} · ${c.importedAt ? `last remote sync ${new Date(c.importedAt).toISOString()}` : "never synced"}`;
+	return `${c.incomplete ? "incomplete coverage · " : ""}${c.machines} machine${c.machines === 1 ? "" : "s"} · ${c.remoteMachines ? "cached" : "local-only"} · ${c.importedAt && positive(c.importedAt) ? `viewer last import ${new Date(c.importedAt).toISOString()}` : "viewer never imported"}`;
 }