@nredd/pi-session-kit 0.0.0-stage → 0.3.0

package/src/monitor/manager.ts

@@ -0,0 +1,322 @@
+/**
+ * Per-session monitor registry. One instance per pi session: it owns every child it spawned, kills
+ * them all on `dispose()`, and never looks at another session's state (the pidfile sweep, which does
+ * look at other session directories, lives in `pidfiles.ts` and only touches dead owners).
+ */
+
+import { join } from "node:path";
+import { type CoalescedBatch, Coalescer } from "./coalescer.ts";
+import { BoundedMatcher } from "./matcher.ts";
+import { formatMessage, type TaggedLine } from "./messages.ts";
+import {
+	rootDir as defaultRootDir,
+	type PidRecord,
+	removePidfile,
+	removeSessionDirIfEmpty,
+	sessionDirName,
+	writePidfile,
+} from "./pidfiles.ts";
+import { type ExitInfo, KILL_GRACE_MS, type MonitorProcess, spawnMonitor } from "./process.ts";
+import { RingBuffer, type RingRead } from "./ring.ts";
+import { LineSplitter } from "./splitter.ts";
+import type { MonitorInfo, MonitorMessage, MonitorStatus } from "./types.ts";
+import { type StartParams, type ValidStart, validateStart } from "./validate.ts";
+
+export const COALESCE_MS = 2_000;
+const RETAINED_FINISHED = 10;
+
+export interface ManagerOptions {
+	sessionId: string;
+	/** Called once per coalesced batch / lifecycle event. Must not throw. */
+	send: (message: MonitorMessage) => void;
+	/** Called whenever the set or state of monitors changes (widget refresh). */
+	onChange?: () => void;
+	root?: string;
+	ownerPid?: number;
+	coalesceMs?: number;
+	killGraceMs?: number;
+}
+
+export class MonitorError extends Error {}
+
+interface Monitor {
+	id: string;
+	name: string;
+	argv: string[];
+	cwd: string;
+	wake: boolean;
+	matcher: BoundedMatcher | undefined;
+	matchSource: string | undefined;
+	timeoutMs: number;
+	startedAt: number;
+	endedAt?: number;
+	status: MonitorStatus;
+	exit: ExitInfo;
+	proc: MonitorProcess;
+	ring: RingBuffer;
+	coalescer: Coalescer<TaggedLine>;
+	timeoutTimer: NodeJS.Timeout;
+	stopReason: "stop" | "timeout" | undefined;
+	/** Resolves after the exit was fully processed (status set, pidfile removed). */
+	done: Promise<void>;
+}
+
+export class MonitorManager {
+	private readonly monitors = new Map<string, Monitor>();
+	private readonly sessionDir: string;
+	private readonly opts: Required<Pick<ManagerOptions, "coalesceMs" | "killGraceMs" | "ownerPid">> & ManagerOptions;
+	/** Names of monitors being spawned right now; reserved so parallel starts cannot exceed the caps. */
+	private readonly starting = new Set<string>();
+	private counter = 0;
+	private disposed = false;
+	private readonly exitBackstop = () => {
+		for (const m of this.monitors.values()) if (m.status === "running") m.proc.killNow();
+	};
+
+	constructor(opts: ManagerOptions) {
+		this.opts = { coalesceMs: COALESCE_MS, killGraceMs: KILL_GRACE_MS, ownerPid: process.pid, ...opts };
+		this.sessionDir = join(opts.root ?? defaultRootDir(), sessionDirName(opts.sessionId, this.opts.ownerPid));
+		// SIGKILL cannot be caught (the pidfile sweep covers that), but any other exit path must not leak children.
+		process.once("exit", this.exitBackstop);
+	}
+
+	list(): MonitorInfo[] {
+		return [...this.monitors.values()].map(toInfo);
+	}
+
+	running(): MonitorInfo[] {
+		return this.list().filter((m) => m.status === "running");
+	}
+
+	/** Look up by id, then by name (a running monitor wins over a finished one of the same name). */
+	find(idOrName: string): Monitor | undefined {
+		const byId = this.monitors.get(idOrName);
+		if (byId) return byId;
+		const named = [...this.monitors.values()].filter((m) => m.name === idOrName);
+		return named.find((m) => m.status === "running") ?? named.at(-1);
+	}
+
+	info(idOrName: string): MonitorInfo | undefined {
+		const m = this.find(idOrName);
+		return m ? toInfo(m) : undefined;
+	}
+
+	read(idOrName: string, since?: number): (RingRead & { info: MonitorInfo; lastLine: number }) | undefined {
+		const m = this.find(idOrName);
+		if (!m) return undefined;
+		return { ...m.ring.read(since), info: toInfo(m), lastLine: m.ring.lastLine };
+	}
+
+	async start(params: StartParams, cwd: string): Promise<MonitorInfo> {
+		if (this.disposed) throw new MonitorError("this session is shutting down");
+		const live = this.running();
+		const names = new Set([...live.map((m) => m.name), ...this.starting]);
+		const checked = validateStart(params, names, live.length + this.starting.size);
+		if (!checked.ok) throw new MonitorError(checked.error);
+		const { name } = checked.value;
+		this.starting.add(name);
+		try {
+			return await this.spawn(checked.value, params.match, cwd);
+		} finally {
+			this.starting.delete(name);
+		}
+	}
+
+	private async spawn(valid: ValidStart, matchSource: string | undefined, cwd: string): Promise<MonitorInfo> {
+		const { argv, name, regex, wake, timeoutMs } = valid;
+		const id = `m${++this.counter}`;
+		const ring = new RingBuffer();
+		let monitor: Monitor | undefined;
+		const early: string[] = [];
+		const onLine = (text: string) => {
+			if (monitor) this.ingest(monitor, text);
+			else early.push(text);
+		};
+		const out = new LineSplitter();
+		const err = new LineSplitter();
+		let proc: MonitorProcess;
+		try {
+			proc = await spawnMonitor(argv, {
+				cwd,
+				onStdout: (chunk) => out.push(chunk).forEach(onLine),
+				onStderr: (chunk) => err.push(chunk).forEach(onLine),
+			});
+		} catch (error) {
+			throw new MonitorError(`cannot start ${JSON.stringify(argv[0])}: ${(error as Error).message}`);
+		}
+		if (this.disposed) {
+			proc.killNow();
+			throw new MonitorError("this session is shutting down");
+		}
+
+		const record: PidRecord = {
+			ownerPid: this.opts.ownerPid,
+			childPid: proc.pid,
+			pgid: proc.pid,
+			startedAt: proc.startedAt,
+			name,
+			command: argv.join(" "),
+		};
+		try {
+			writePidfile(this.sessionDir, id, record);
+		} catch (error) {
+			proc.killNow();
+			throw new MonitorError(`cannot record monitor pidfile: ${(error as Error).message}`);
+		}
+
+		let matcher: BoundedMatcher | undefined;
+		try {
+			matcher = regex ? new BoundedMatcher(regex.source) : undefined;
+		} catch (error) {
+			proc.killNow();
+			removePidfile(this.sessionDir, id);
+			throw new MonitorError(`cannot start match worker: ${(error as Error).message}`);
+		}
+		const coalescer = new Coalescer<TaggedLine>(
+			this.opts.coalesceMs,
+			(batch) => this.emitBatch(monitor as Monitor, batch),
+			{ sizeOf: (line) => Buffer.byteLength(line.text), matched: (line) => line.matched },
+		);
+		const timeoutTimer = setTimeout(() => this.finishRequested(monitor as Monitor, "timeout"), timeoutMs);
+		timeoutTimer.unref();
+		monitor = {
+			id,
+			name,
+			argv,
+			cwd,
+			wake,
+			matcher,
+			matchSource: matchSource || undefined,
+			timeoutMs,
+			startedAt: proc.startedAt,
+			status: "running",
+			exit: { exitCode: null, signal: null },
+			proc,
+			ring,
+			coalescer,
+			timeoutTimer,
+			stopReason: undefined,
+			done: Promise.resolve(),
+		};
+		const m = monitor;
+		m.done = proc.exited.then(async (exit) => {
+			out.flush().forEach(onLine);
+			err.flush().forEach(onLine);
+			await m.matcher?.drain();
+			await m.matcher?.close();
+			this.onExited(m, exit);
+		});
+		this.monitors.set(id, m);
+		for (const text of early) this.ingest(m, text);
+		this.prune();
+		this.opts.onChange?.();
+		return toInfo(m);
+	}
+
+	/** Stop one monitor (id or name) and wait for it to be gone. Returns undefined when unknown. */
+	async stop(idOrName: string): Promise<MonitorInfo | undefined> {
+		const m = this.find(idOrName);
+		if (!m) return undefined;
+		if (m.status === "running") this.finishRequested(m, "stop");
+		await m.done;
+		return toInfo(m);
+	}
+
+	async stopAll(): Promise<MonitorInfo[]> {
+		const running = [...this.monitors.values()].filter((m) => m.status === "running");
+		for (const m of running) this.finishRequested(m, "stop");
+		await Promise.all(running.map((m) => m.done));
+		return running.map(toInfo);
+	}
+
+	/** Kill everything silently (no messages) and forget it. Idempotent. */
+	async dispose(): Promise<void> {
+		if (this.disposed) return;
+		this.disposed = true;
+		const running = [...this.monitors.values()].filter((m) => m.status === "running");
+		for (const m of running) {
+			clearTimeout(m.timeoutTimer);
+			m.coalescer.cancel();
+			m.proc.terminate(this.opts.killGraceMs);
+			// Interrupt a busy regex immediately, rather than making shutdown wait for its deadline.
+			void m.matcher?.close();
+		}
+		await Promise.all(running.map((m) => m.done));
+		for (const m of this.monitors.values()) removePidfile(this.sessionDir, m.id);
+		removeSessionDirIfEmpty(this.sessionDir);
+		this.monitors.clear();
+		process.off("exit", this.exitBackstop);
+	}
+
+	private ingest(m: Monitor, text: string): void {
+		const line = m.ring.push(text);
+		const add = (matched: boolean) => m.coalescer.add({ ...line, matched });
+		if (m.matcher) m.matcher.test(text, add);
+		else add(false);
+	}
+
+	private finishRequested(m: Monitor, reason: "stop" | "timeout"): void {
+		if (m.status !== "running" || m.stopReason !== undefined) return;
+		m.stopReason = reason;
+		m.proc.terminate(this.opts.killGraceMs);
+	}
+
+	private onExited(m: Monitor, exit: ExitInfo): void {
+		clearTimeout(m.timeoutTimer);
+		m.exit = exit;
+		m.endedAt = Date.now();
+		m.status = m.stopReason === "timeout" ? "timeout" : m.stopReason === "stop" ? "stopped" : "exited";
+		removePidfile(this.sessionDir, m.id);
+		const pending = m.coalescer.take();
+		if (this.disposed) return;
+		// A requested stop is already known to whoever asked, so it never wakes the agent, and says
+		// nothing at all when no output is pending. Natural exit and timeout always wake.
+		const quiet = m.stopReason === "stop";
+		if (!quiet || pending.items.length > 0 || pending.dropped > 0) {
+			this.deliver(formatMessage(toInfo(m), pending, { final: true, wake: !quiet }));
+		}
+		this.opts.onChange?.();
+	}
+
+	private emitBatch(m: Monitor, batch: CoalescedBatch<TaggedLine>): void {
+		if (this.disposed || (batch.items.length === 0 && batch.dropped === 0)) return;
+		this.deliver(
+			formatMessage(toInfo(m), batch, {
+				final: false,
+				wake: m.wake || batch.droppedMatched || batch.items.some((l) => l.matched),
+			}),
+		);
+	}
+
+	/** A failed delivery must never leave a monitor un-reaped, so it is swallowed here. */
+	private deliver(message: MonitorMessage): void {
+		try {
+			this.opts.send(message);
+		} catch {
+			// the output stays readable through monitor_read
+		}
+	}
+
+	private prune(): void {
+		const finished = [...this.monitors.values()].filter((m) => m.status !== "running");
+		for (const m of finished.slice(0, Math.max(0, finished.length - RETAINED_FINISHED))) this.monitors.delete(m.id);
+	}
+}
+
+function toInfo(m: Monitor): MonitorInfo {
+	return {
+		id: m.id,
+		name: m.name,
+		argv: m.argv,
+		pid: m.proc.pid,
+		status: m.status,
+		startedAt: m.startedAt,
+		endedAt: m.endedAt,
+		exitCode: m.exit.exitCode,
+		signal: m.exit.signal,
+		lines: m.ring.lastLine,
+		wake: m.wake,
+		match: m.matchSource,
+		timeoutMs: m.timeoutMs,
+	};
+}

package/src/monitor/matcher.ts

@@ -0,0 +1,113 @@
+/**
+ * Isolate model-provided backtracking regexes from pi's event loop. One worker per matching monitor,
+ * one line in flight, 100ms per test (excluding worker startup, which has a 1s deadline). Queued
+ * text plus per-item overhead is capped at 256KiB; final draining is bounded to 1s. On timeout, overflow or worker failure, disable matching for this monitor
+ * and conservatively mark pending/future lines matched: output still wakes rather than losing alerts.
+ * Normal tests retain JS RegExp semantics and line ordering. close() interrupts work and awaits worker
+ * termination; drain() waits for queued callbacks before the monitor's final output is delivered.
+ */
+import { Worker } from "node:worker_threads";
+
+export const MATCH_TIMEOUT_MS = 100;
+export const MATCH_QUEUE_BYTES = 256 * 1024;
+const STARTUP_TIMEOUT_MS = 1000;
+const SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads');
+const regex = new RegExp(workerData);
+parentPort.on('message', text => parentPort.postMessage(regex.test(text)));
+`;
+
+interface Pending {
+	text: string;
+	bytes: number;
+	done: (matched: boolean) => void;
+}
+
+export class BoundedMatcher {
+	private worker: Worker | undefined;
+	private ready = false;
+	private active: Pending | undefined;
+	private readonly queue: Pending[] = [];
+	private bytes = 0;
+	private timer: NodeJS.Timeout | undefined;
+	private readonly drained: (() => void)[] = [];
+	private termination: Promise<unknown> = Promise.resolve();
+
+	constructor(source: string) {
+		this.worker = new Worker(SOURCE, { eval: true, workerData: source });
+		this.timer = setTimeout(() => this.disable(), STARTUP_TIMEOUT_MS);
+		this.worker.once("online", () => {
+			if (!this.worker) return;
+			clearTimeout(this.timer);
+			this.ready = true;
+			this.pump();
+		});
+		this.worker.on("message", (matched: boolean) => {
+			if (!this.worker || !this.active) return;
+			clearTimeout(this.timer);
+			const item = this.active;
+			this.active = undefined;
+			this.bytes -= item.bytes;
+			item.done(matched);
+			this.pump();
+		});
+		this.worker.on("error", () => this.disable());
+		this.worker.on("exit", () => this.disable());
+	}
+
+	test(text: string, done: (matched: boolean) => void): void {
+		if (!this.worker) {
+			done(true);
+			return;
+		}
+		const bytes = Buffer.byteLength(text) + 64;
+		if (this.bytes + bytes > MATCH_QUEUE_BYTES) {
+			this.disable();
+			done(true);
+			return;
+		}
+		this.bytes += bytes;
+		this.queue.push({ text, bytes, done });
+		this.pump();
+	}
+
+	async drain(): Promise<void> {
+		if (this.active || this.queue.length) {
+			const deadline = setTimeout(() => this.disable(), STARTUP_TIMEOUT_MS);
+			try {
+				await new Promise<void>((resolve) => this.drained.push(resolve));
+			} finally {
+				clearTimeout(deadline);
+			}
+		}
+	}
+
+	async close(): Promise<void> {
+		this.disable();
+		await this.termination;
+	}
+
+	private pump(): void {
+		if (!this.worker || !this.ready || this.active) return;
+		this.active = this.queue.shift();
+		if (!this.active) {
+			for (const resolve of this.drained.splice(0)) resolve();
+			return;
+		}
+		this.timer = setTimeout(() => this.disable(), MATCH_TIMEOUT_MS);
+		this.worker.postMessage(this.active.text);
+	}
+
+	private disable(): void {
+		clearTimeout(this.timer);
+		const worker = this.worker;
+		this.worker = undefined;
+		if (worker) this.termination = worker.terminate();
+		const pending = this.active ? [this.active, ...this.queue] : [...this.queue];
+		this.active = undefined;
+		this.queue.length = 0;
+		this.bytes = 0;
+		for (const item of pending) item.done(true);
+		for (const resolve of this.drained.splice(0)) resolve();
+	}
+}

package/src/monitor/messages.ts

@@ -0,0 +1,93 @@
+/** Formats coalesced monitor output and lifecycle events as one custom-message body. */
+
+import type { CoalescedBatch } from "./coalescer.ts";
+import type { NumberedLine } from "./ring.ts";
+import type { MonitorInfo, MonitorMessage } from "./types.ts";
+
+export const MAX_MESSAGE_LINES = 40;
+export const MAX_MESSAGE_BYTES = 8 * 1024;
+
+export type TaggedLine = NumberedLine & { matched: boolean };
+
+export function formatDuration(ms: number): string {
+	const s = Math.max(0, Math.round(ms / 1000));
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	if (m < 60) return `${m}m${String(s % 60).padStart(2, "0")}s`;
+	return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
+}
+
+function exitNote(info: MonitorInfo): string {
+	const took = formatDuration((info.endedAt ?? Date.now()) - info.startedAt);
+	switch (info.status) {
+		case "timeout":
+			return `timed out after ${took} and was killed; ${info.lines} lines total`;
+		case "stopped":
+			return `stopped after ${took}; ${info.lines} lines total`;
+		default:
+			return info.signal
+				? `died from ${info.signal} after ${took}; ${info.lines} lines total`
+				: `exited with code ${info.exitCode ?? "?"} after ${took}; ${info.lines} lines total`;
+	}
+}
+
+/** Keep the newest lines that fit both caps; returns them and how many older ones were dropped. */
+function bound(lines: TaggedLine[]): { kept: TaggedLine[]; omitted: number } {
+	let kept = lines.slice(-MAX_MESSAGE_LINES);
+	let bytes = 0;
+	let from = kept.length;
+	while (from > 0) {
+		const next = bytes + Buffer.byteLength(kept[from - 1]?.text ?? "") + 8;
+		if (next > MAX_MESSAGE_BYTES && from < kept.length) break;
+		bytes = next;
+		from--;
+	}
+	kept = kept.slice(from);
+	return { kept, omitted: lines.length - kept.length };
+}
+
+export function formatMessage(
+	info: MonitorInfo,
+	input: CoalescedBatch<TaggedLine> | TaggedLine[],
+	opts: { final: boolean; wake: boolean },
+): MonitorMessage {
+	const batch = Array.isArray(input) ? { items: input, dropped: 0, droppedMatched: false } : input;
+	const head = `[monitor ${info.id} "${info.name}"]`;
+	const parts: string[] = [];
+	const matched = batch.items.filter((l) => l.matched).map((l) => l.n);
+	if (batch.items.length > 0 || batch.dropped > 0) {
+		const { kept, omitted } = bound(batch.items);
+		const first = (batch.items[0]?.n ?? info.lines + 1) - batch.dropped;
+		const last = batch.items.at(-1)?.n ?? info.lines;
+		const total = batch.items.length + batch.dropped;
+		const tag =
+			matched.length > 0
+				? `; match on ${matched.slice(0, 5).join(", ")}${matched.length > 5 ? ", ..." : ""}`
+				: batch.droppedMatched
+					? "; match"
+					: "";
+		parts.push(`${head} lines ${first}-${last} (${total} new${tag})`);
+		if (batch.dropped > 0)
+			parts.push(
+				`... ${batch.dropped} lines dropped from the pending 2s batch; monitor_read {"id":"${info.id}","since":${first - 1}} has them`,
+			);
+		if (omitted > 0)
+			parts.push(
+				`... ${omitted} earlier lines omitted; monitor_read {"id":"${info.id}","since":${first - 1}} has them`,
+			);
+		for (const l of kept) parts.push(`${l.n}: ${l.text}`);
+	}
+	if (opts.final) parts.push(`${head} ${exitNote(info)}`);
+	return {
+		text: parts.join("\n"),
+		wake: opts.wake,
+		details: {
+			id: info.id,
+			name: info.name,
+			firstLine: (batch.items[0]?.n ?? info.lines + 1) - batch.dropped,
+			lastLine: batch.items.at(-1)?.n ?? info.lines,
+			matched,
+			status: info.status,
+		},
+	};
+}

package/src/monitor/output.ts

@@ -0,0 +1,41 @@
+/**
+ * Bound what the model sees from `monitor_read` / `monitor_stop` at pi's own limits
+ * (`DEFAULT_MAX_BYTES` / `DEFAULT_MAX_LINES`), keeping the newest lines and spilling the full text
+ * to a temp file. Same idea as `pi-dev-tools`' `core/output.ts`.
+ */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncateTail } from "@earendil-works/pi-coding-agent";
+
+export interface Bounded {
+	text: string;
+	truncated: boolean;
+	fullOutputPath?: string;
+}
+
+/** Room reserved for the truncation notice inside the limits. */
+const NOTICE_BYTES = 256;
+const NOTICE_LINES = 2;
+
+let spillDir: Promise<string> | undefined;
+let spillSeq = 0;
+
+export async function boundTail(text: string, label: string): Promise<Bounded> {
+	const result = truncateTail(text, {
+		maxBytes: DEFAULT_MAX_BYTES - NOTICE_BYTES,
+		maxLines: DEFAULT_MAX_LINES - NOTICE_LINES,
+	});
+	if (!result.truncated) return { text, truncated: false };
+	spillDir ??= mkdtemp(join(tmpdir(), "pi-session-kit-monitor-"));
+	const dir = await spillDir;
+	spillSeq += 1;
+	const fullOutputPath = join(dir, `${label}-${spillSeq}.txt`);
+	await writeFile(fullOutputPath, text, { encoding: "utf8", mode: 0o600 });
+	return {
+		text: `${result.content}\n[output truncated at the start; full text in ${fullOutputPath}]`,
+		truncated: true,
+		fullOutputPath,
+	};
+}