@nredd/pi-session-kit 0.6.0 → 0.8.0

package/src/mon/model.ts

@@ -0,0 +1,153 @@
+/** Presentation-only resource values. The sampler adapter owns measurement and validity. */
+export interface MonProcess {
+	/** Stable sampler identity, not PID alone (PIDs can be reused). */
+	identity: string;
+	pid: number;
+	/** Untrusted executable basename; "" when the OS gave none. */
+	name: string;
+	/** `unknown`: no name was readable. `truncated`: the OS limit may have cut it (macOS 16 bytes). */
+	nameState?: "unknown" | "truncated";
+	cpuPercent: number | null;
+	rssBytes: number | null;
+}
+
+/** No process arguments, environment, working directories or host identifiers enter the view. */
+export interface MonSnapshot {
+	cpuPercent: number | null;
+	logicalCpus: number;
+	memoryUsedBytes: number | null;
+	memoryTotalBytes: number | null;
+	load: readonly number[];
+	processes: readonly MonProcess[];
+	/** Wall-clock capture time, for display only (it can jump). Never persisted. */
+	capturedAt: number;
+	/** Monotonic capture time; history spacing uses this, never wall time. */
+	sampledAtMs: number;
+	/** Collection time of this capture, when the adapter measured it. */
+	scanMs?: number | null;
+	/** Collector outcome: `live` is a successful collection even when host CPU has no value yet. */
+	status: "live" | "stale";
+	/** Host interval CPU state, independent of collector success. */
+	cpuState: "available" | "warming" | "unavailable";
+	/** Process interval CPU cannot exist for this platform; the view then defaults to RSS order. */
+	processCpu?: "unavailable";
+	/** Safe, bounded warning supplied by the adapter: something limits what the view can show. */
+	notice?: string;
+	/** Safe, bounded platform note (expected limits, e.g. macOS process CPU); rendered muted. */
+	hint?: string;
+}
+
+export type MonSort = "cpu" | "rss" | "pid";
+export const SORTS: readonly MonSort[] = ["cpu", "rss", "pid"];
+
+/** Unknown/non-finite measurements sort last; ties are deterministic across refreshes. */
+export function sortProcesses(processes: readonly MonProcess[], sort: MonSort): MonProcess[] {
+	return [...processes].sort((a, b) => {
+		const av = sort === "cpu" ? a.cpuPercent : sort === "rss" ? a.rssBytes : a.pid;
+		const bv = sort === "cpu" ? b.cpuPercent : sort === "rss" ? b.rssBytes : b.pid;
+		const au = av === null || !Number.isFinite(av);
+		const bu = bv === null || !Number.isFinite(bv);
+		if (au !== bu) return au ? 1 : -1;
+		if (!au && !bu && av !== bv) return sort === "pid" ? av - bv : bv - av;
+		return a.pid - b.pid || a.identity.localeCompare(b.identity);
+	});
+}
+
+export function percent(value: number | null): string {
+	return value === null || !Number.isFinite(value) ? "--" : `${value.toFixed(1)}%`;
+}
+
+/** Process share of total RAM, from the same sample's RSS and total. */
+export function share(part: number | null, total: number | null): string {
+	if (part === null || total === null || !Number.isFinite(part) || !Number.isFinite(total) || total <= 0) return "--";
+	return `${((part / total) * 100).toFixed(1)}`;
+}
+
+export function bytes(value: number | null): string {
+	if (value === null || !Number.isFinite(value)) return "--";
+	return value >= 1024 ** 3 ? `${(value / 1024 ** 3).toFixed(1)}G` : `${(value / 1024 ** 2).toFixed(0)}M`;
+}
+
+export interface MonHistoryPoint {
+	/** Monotonic milliseconds, so wall-clock steps cannot invent or hide gaps. */
+	sampledAtMs: number;
+	value: number | null;
+}
+
+/**
+ * Time-proportional buckets, newest on the right. A column is the typical sampling interval (lower
+ * median of consecutive captures), widened only when the history spans more than the width. Columns
+ * after the first capture without a CPU value are real gaps (`null`), never interpolated CPU; the
+ * leading `blank` columns precede the first capture because no history exists yet. The latest sample
+ * in a bucket wins.
+ */
+function historyBuckets(
+	history: readonly MonHistoryPoint[],
+	width: number,
+): { blank: number; buckets: (number | null)[] } {
+	const first = history[0];
+	const last = history.at(-1);
+	if (!first || !last || width < 1) return { blank: Math.max(0, width), buckets: [] };
+	const span = last.sampledAtMs - first.sampledAtMs;
+	if (span <= 0) return { blank: width - 1, buckets: [last.value] };
+	const deltas = history
+		.slice(1)
+		.map((point, i) => point.sampledAtMs - (history[i]?.sampledAtMs ?? point.sampledAtMs))
+		.filter((delta) => delta > 0)
+		.sort((a, b) => a - b);
+	const typical = deltas[Math.floor((deltas.length - 1) / 2)] ?? span;
+	const step = Math.max(typical, span / Math.max(1, width - 1));
+	const buckets: (number | null)[] = Array.from({ length: width }, () => null);
+	let oldest = width - 1;
+	for (const point of history) {
+		const index = width - 1 - Math.round((last.sampledAtMs - point.sampledAtMs) / step);
+		if (index < 0 || index >= width) continue;
+		buckets[index] = point.value;
+		oldest = Math.min(oldest, index);
+	}
+	return { blank: oldest, buckets: buckets.slice(oldest) };
+}
+
+/** One-row history: blank before data, `·` for gaps. */
+export function timeHistory(history: readonly MonHistoryPoint[], width: number): string {
+	if (!history.length || width < 1) return "";
+	const { blank, buckets } = historyBuckets(history, width);
+	return " ".repeat(blank) + sparkline(buckets, buckets.length);
+}
+
+/**
+ * Multi-row history (top row first), `rows * 8` levels on the same fixed 0..100 scale. A gap is `·`
+ * on the bottom row only; zero keeps a `▁` baseline so a quiet host never looks like missing data.
+ */
+export function timeHistoryRows(history: readonly MonHistoryPoint[], width: number, rows: number): string[] {
+	if (rows <= 1) return [timeHistory(history, width)];
+	const lines = Array.from({ length: rows }, () => "");
+	if (!history.length || width < 1) return lines;
+	const { blank, buckets } = historyBuckets(history, width);
+	const ticks = "▁▂▃▄▅▆▇█";
+	for (let row = 0; row < rows; row++) lines[row] = " ".repeat(blank);
+	for (const value of buckets) {
+		const level =
+			value === null || !Number.isFinite(value)
+				? -1
+				: Math.max(0, Math.min(rows * 8, Math.round((value * rows * 8) / 100)));
+		for (let row = 0; row < rows; row++) {
+			// Row 0 is the top; `fill` is how many eighths this row holds.
+			const floor = (rows - 1 - row) * 8;
+			const fill = level - floor;
+			const bottom = row === rows - 1;
+			lines[row] +=
+				level < 0 ? (bottom ? "·" : " ") : fill >= 8 ? "█" : fill > 0 ? (ticks[fill - 1] ?? " ") : bottom ? "▁" : " ";
+		}
+	}
+	return lines;
+}
+
+/** Fixed 0..100 host CPU scale: a quiet history must not look saturated. */
+export function sparkline(history: readonly (number | null)[], width: number): string {
+	const ticks = "▁▂▃▄▅▆▇█";
+	const values = history.slice(-Math.max(0, width));
+	return values
+		.map((n) => (n === null || !Number.isFinite(n) ? "·" : ticks[Math.min(7, Math.max(0, Math.round((n * 7) / 100)))]))
+		.join("");
+}

package/src/mon/poll.ts

@@ -0,0 +1,80 @@
+/** Single-flight, completion-paced sampling. No polling exists outside an open interaction. */
+import { type Clock, realClock, type TimerHandle } from "../clock.ts";
+import type { MonSnapshot } from "./model.ts";
+
+/** Presentation boundary; the production adapter must delegate to the shared sampler. */
+export interface MonSource {
+	sample(signal: AbortSignal): Promise<MonSnapshot>;
+	dispose(): void | Promise<void>;
+}
+
+/** Errors retain the last data as explicitly stale and stop probes until the view is reopened. */
+export class MonPoll {
+	private timer: TimerHandle | undefined;
+	private readonly abort = new AbortController();
+	private disposed = false;
+	private started = false;
+	private last: MonSnapshot | undefined;
+	private cleanup: Promise<void> | undefined;
+
+	constructor(
+		private readonly source: MonSource,
+		private readonly update: (snapshot: MonSnapshot) => void,
+		private readonly clock: Clock = realClock,
+		private readonly intervalMs = 2000,
+	) {}
+
+	start(): void {
+		if (this.started || this.disposed) return;
+		this.started = true;
+		void this.poll().catch(() => {});
+	}
+
+	private async poll(): Promise<void> {
+		try {
+			const snapshot = await this.source.sample(this.abort.signal);
+			if (this.disposed) return;
+			this.last = snapshot;
+			this.update(snapshot);
+			if (!this.disposed)
+				this.timer = this.clock.setTimeout(() => {
+					void this.poll().catch(() => {});
+				}, this.intervalMs);
+		} catch {
+			if (this.disposed) return;
+			try {
+				this.update({
+					cpuPercent: null,
+					logicalCpus: 0,
+					memoryUsedBytes: null,
+					memoryTotalBytes: null,
+					load: [],
+					processes: [],
+					capturedAt: this.clock.now(),
+					sampledAtMs: performance.now(),
+					cpuState: "unavailable",
+					...this.last,
+					status: "stale",
+					notice: "Sampling stopped. Close and reopen to retry.",
+				});
+			} catch {
+				// A failed renderer must not leave collection running or reject an unobserved task.
+			} finally {
+				await this.dispose();
+			}
+		}
+	}
+
+	/** Await this at the command boundary so asynchronous probes are reaped before returning. */
+	dispose(): Promise<void> {
+		if (this.cleanup) return this.cleanup;
+		this.disposed = true;
+		this.timer?.cancel();
+		this.timer = undefined;
+		this.abort.abort();
+		this.cleanup = Promise.resolve().then(() => this.source.dispose());
+		// Timer callbacks cannot surface cleanup failures; the command's finally awaits the same promise.
+		void this.cleanup.catch(() => {});
+		return this.cleanup;
+	}
+}

package/src/mon/source.ts

@@ -0,0 +1,121 @@
+/** Production /mon source: a thin mapping over the published shared sampler. No collector lives here. */
+import {
+	createResourceSampler,
+	type ResourceSampler,
+	type ResourceSnapshot,
+	type SamplerOptions,
+} from "@nredd/pi-resource-sampler";
+import type { MonSnapshot } from "./model.ts";
+import type { MonSource } from "./poll.ts";
+
+/** Bounded so a notice line stays readable even with many coverage reasons. */
+const MAX_REASONS = 3;
+/** macOS keeps at most this many bytes of the executable name (`p_comm`). */
+const DARWIN_NAME_BYTES = 16;
+/** Skips every Linux scan expects: kernel threads have no RSS, and processes exit mid-scan. */
+const ROUTINE_SKIP = "process-unreadable-or-changed";
+const REASONS: Readonly<Record<string, string>> = {
+	deadline: "time budget",
+	"pid-limit": "process cap",
+	"byte-limit": "read budget",
+	"file-byte-limit": "read budget",
+	[ROUTINE_SKIP]: "unreadable or exited",
+	"command-unavailable": "ps unavailable",
+	"command-failed": "ps failed",
+	"malformed-process-row": "unparsed rows",
+	"process-collection-unavailable": "process list unavailable",
+};
+const utf8 = new TextEncoder();
+
+function finite(value: number): number | null {
+	return Number.isFinite(value) ? value : null;
+}
+
+/** Every observed process lacks interval CPU by platform design, not because it is warming. */
+function processCpuUnavailable(snapshot: ResourceSnapshot): boolean {
+	return snapshot.processes.length > 0 && snapshot.processes.every((p) => p.cpu.state === "unavailable");
+}
+
+function nameState(snapshot: ResourceSnapshot, name: string): "unknown" | "truncated" | undefined {
+	if (name === "") return "unknown";
+	return snapshot.platform === "darwin" && utf8.encode(name).length >= DARWIN_NAME_BYTES ? "truncated" : undefined;
+}
+
+/** Limits that hide data the user would expect: budget caps, collector failures, unavailable host CPU. */
+function notice(snapshot: ResourceSnapshot, baseline: boolean): string | undefined {
+	const parts: string[] = [];
+	const { coverage } = snapshot;
+	const limits = coverage.reasons.filter((reason) => reason !== ROUTINE_SKIP);
+	if (!coverage.complete && (limits.length || !coverage.reasons.length)) {
+		const reasons = [...new Set(coverage.reasons.map((reason) => REASONS[reason] ?? reason))];
+		const text = reasons.slice(0, MAX_REASONS).join(", ") || "unknown";
+		parts.push(`Partial list: ${coverage.sampled} of ${coverage.enumerated} seen (${text})`);
+	}
+	if (snapshot.cpu.state === "unavailable") parts.push("Host CPU unavailable");
+	// The first observation is always a baseline; persistent warming (e.g. frozen counters) is explained.
+	else if (snapshot.cpu.state === "warming" && !baseline) parts.push(`Host CPU warming: ${snapshot.cpu.reason}`);
+	return parts.length ? parts.join(" · ") : undefined;
+}
+
+/** Expected platform limits, stated once so `--` and `(unknown)` are never mistaken for zero or a bug. */
+function hint(snapshot: ResourceSnapshot): string | undefined {
+	const parts: string[] = [];
+	const { coverage } = snapshot;
+	if (!coverage.complete && coverage.reasons.length && coverage.reasons.every((reason) => reason === ROUTINE_SKIP))
+		parts.push(`${coverage.enumerated - coverage.sampled} skipped: kernel threads, exited or unreadable`);
+	const unknown = snapshot.processes.filter((p) => p.name === "").length;
+	if (unknown) parts.push(`${unknown} ${unknown === 1 ? "name" : "names"} unknown (no access, e.g. other users)`);
+	if (processCpuUnavailable(snapshot))
+		parts.push(snapshot.platform === "darwin" ? "macOS: process CPU unavailable (see ?)" : "Process CPU unavailable");
+	return parts.length ? parts.join(" · ") : undefined;
+}
+
+/**
+ * Map one typed sampler snapshot without inventing zeros for warming/unavailable values.
+ * `baseline` marks a source's first observation, whose warming CPU needs no explanation.
+ */
+export function toMonSnapshot(snapshot: ResourceSnapshot, baseline = true): MonSnapshot {
+	const total = finite(snapshot.memory.totalBytes);
+	const free = finite(snapshot.memory.freeBytes);
+	const text = notice(snapshot, baseline);
+	const note = hint(snapshot);
+	return {
+		cpuPercent: snapshot.cpu.state === "available" ? finite(snapshot.cpu.value) : null,
+		logicalCpus: snapshot.logicalCpus,
+		memoryUsedBytes: total !== null && total > 0 && free !== null ? Math.max(0, total - free) : null,
+		memoryTotalBytes: total !== null && total > 0 ? total : null,
+		load: snapshot.loadAverage,
+		processes: snapshot.processes.map((p) => {
+			const state = nameState(snapshot, p.name);
+			return {
+				identity: p.identity,
+				pid: p.pid,
+				name: p.name,
+				...(state ? { nameState: state } : {}),
+				cpuPercent: p.cpu.state === "available" ? finite(p.cpu.value) : null,
+				rssBytes: finite(p.rssBytes),
+			};
+		}),
+		capturedAt: snapshot.wallTimeMs,
+		sampledAtMs: snapshot.monotonicTimeMs,
+		scanMs: finite(snapshot.durationMs),
+		// A resolved sample is a successful collection, whatever its CPU state.
+		status: "live",
+		cpuState: snapshot.cpu.state,
+		...(processCpuUnavailable(snapshot) ? { processCpu: "unavailable" as const } : {}),
+		...(text ? { notice: text } : {}),
+		...(note ? { hint: note } : {}),
+	};
+}
+
+/** One sampler per open interaction; its baseline and child cleanup end with the view. */
+export function createSamplerSource(
+	create: (options?: SamplerOptions) => ResourceSampler = createResourceSampler,
+): MonSource {
+	const sampler = create();
+	let observed = 0;
+	return {
+		sample: async (signal) => toMonSnapshot(await sampler.sample(signal), observed++ === 0),
+		dispose: () => sampler.dispose(),
+	};
+}

package/src/monitor/index.ts

@@ -1,6 +1,7 @@
 /**
  * `/monitor`: background process watchers the model can start, read and stop.
  *
+ * - a collapsible above-editor widget (`monitor.collapseKey`, default `ctrl+shift+m`) lists them
  * - `monitor_start` / `monitor_read` / `monitor_stop` tools and a `/monitor` command (list, stop)
  * - output is coalesced for 2s in each monitor's ring buffer; only `match`, exit/timeout or
  *   `wake: true` emits a compact custom wake, while passive output stays out of the session
@@ -12,9 +13,10 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { isChildSession, registerChildIdentity, registerParentTool } from "../child.ts";
-import type { KitConfig } from "../config.ts";
+import { COLLAPSE_KEY_OFF, defaultConfig, type KitConfig } from "../config.ts";
 import { type ManagerOptions, MonitorError, MonitorManager } from "./manager.ts";
 import { formatDuration } from "./messages.ts";
 import { boundTail } from "./output.ts";
@@ -46,7 +48,7 @@ function text(out: string, details?: unknown, isError = false) {
 
 export function register(
 	pi: ExtensionAPI,
-	_config: KitConfig,
+	config: KitConfig,
 	monitorRoot?: string,
 	runtime: Pick<ManagerOptions, "clock" | "spawnMonitor"> = {},
 ): void {
@@ -55,6 +57,17 @@ export function register(
 	let manager: MonitorManager | undefined;
 	let widget: MonitorWidget | undefined;
 
+	// Registered once per runtime, like Todos: a key change needs /reload. `off` skips the binding.
+	const { collapseKey, maxWidgetLines } = config.monitor ?? defaultConfig().monitor; // hosts passing a pre-0.7 config shape get defaults
+	if (collapseKey !== COLLAPSE_KEY_OFF) {
+		pi.registerShortcut(collapseKey as KeyId, {
+			description: "Collapse or expand the monitors widget",
+			handler: (ctx) => {
+				if (ctx.hasUI && widget?.isVisible()) widget.toggle();
+			},
+		});
+	}
+
 	const teardown = async (): Promise<void> => {
 		const old = manager;
 		const oldWidget = widget;
@@ -75,7 +88,7 @@ export function register(
 			ctx.ui.notify(`/monitor: cannot create ${root}: ${(error as Error).message}`, "warning");
 			return;
 		}
-		const w = new MonitorWidget(() => manager?.running() ?? []);
+		const w = new MonitorWidget(() => manager?.list() ?? [], { maxLines: maxWidgetLines, collapseKey });
 		w.attach(ctx);
 		widget = w;
 		manager = new MonitorManager({

package/src/monitor/manager.ts

@@ -62,6 +62,8 @@ interface Monitor {
 	stopReason: "stop" | "timeout" | undefined;
 	/** Cursor after the output the model most recently received through a wake or read. */
 	notifiedSince: number;
+	/** Lines that matched, counted as they are ingested. */
+	matches: number;
 	/** Resolves after the exit was fully processed (status set, pidfile removed). */
 	done: Promise<void>;
 }
@@ -210,6 +212,7 @@ export class MonitorManager {
 			timeoutTimer,
 			stopReason: undefined,
 			notifiedSince: 0,
+			matches: 0,
 			done: Promise.resolve(),
 		};
 		const m = monitor;
@@ -266,6 +269,7 @@ export class MonitorManager {
 		const line = m.ring.push(text);
 		return new Promise((resolve) => {
 			const add = (matched: boolean) => {
+				if (matched) m.matches++;
 				m.coalescer.add({ ...line, matched });
 				resolve();
 			};
@@ -328,6 +332,7 @@ function toInfo(m: Monitor): MonitorInfo {
 		exitCode: m.exit.exitCode,
 		signal: m.exit.signal,
 		lines: m.ring.lastLine,
+		matches: m.matches,
 		lastLine: m.ring.lastText,
 		wake: m.wake,
 		match: m.matchSource,

package/src/monitor/types.ts

@@ -29,6 +29,8 @@ export interface MonitorInfo {
 	exitCode: number | null;
 	signal: NodeJS.Signals | null;
 	lines: number;
+	/** Lines that matched `match`, for the widget's matched state. */
+	matches: number;
 	/** Newest buffered output, for the compact TUI summary only. */
 	lastLine?: string;
 	wake: boolean;