@nredd/pi-session-kit 0.5.0 → 0.6.0

package/README.md

@@ -3,7 +3,7 @@
 Published to npm as `@nredd/pi-session-kit` (public). From `0.4.0`, each version is cut by the monorepo `Publish` workflow from a signed `@nredd/pi-session-kit@<version>` tag, with npm provenance and a GitHub release carrying the tarball, checksums and manifest (`docs/releases.md`); earlier versions were published manually without provenance. `0.4.0` adds `createSessionKit(options)` (explicit `config`, `agentDir`, `monitorRoot`, injectable `clock` and `spawnMonitor`; the default export is unchanged) and fixes leaderless orphan-group sweeps at `ps` start-time resolution. `0.5.0` redesigns `/stats` around the full pane (pinned header, aligned stat cells, a Models table on wide panes) and gives every chart a clock- or calendar-aligned time axis, including the 5h and 24h hourly views.
 Use the [monorepo development commands](https://github.com/nredd/pi-harness/blob/main/README.md). The Git install and standalone harness
 references below describe the legacy deployment, not installation or candidate verification of
-this package.
+this package. `0.6.0` keeps passive monitor output only in the monitor ring buffer rather than adding it to the transcript or model context; `monitor_read` is the explicit output surface, and match/exit/timeout wakes are compact summaries with a cursor.
 
 ## Standalone use
 
@@ -16,7 +16,7 @@ session branch. Closing pi stops its work.
 ## Install and config
 
 ```sh
-pi install npm:@nredd/pi-session-kit@0.4.0
+pi install npm:@nredd/pi-session-kit@0.6.0
 ```
 
 Optional `~/.pi/agent/pi-session-kit.json` (respects `PI_CODING_AGENT_DIR`):
@@ -67,8 +67,7 @@ persistent cron is installed. Deferred-tool configurations need `goal_update` in
   shell remains arbitrary command execution; this is not a sandbox.
 - `monitor_read({id, since?})`: numbered output since a cursor. Ring buffers retain 2000 lines.
 - `monitor_stop({id})`, `/monitor list`, `/monitor stop <id|all>`: stop and inspect owned monitors.
-- Output batches every two seconds with bounded pending storage and dropped-line reporting. Passive
-  batches do not start turns; regex matches, exit and `wake: true` can wake the agent.
+- Output batches every two seconds into the bounded ring buffer (with dropped-line reporting). Passive batches neither start turns nor create transcript/model-context entries; call `monitor_read` to fetch them. A regex match, natural exit, timeout or `wake: true` emits one compact visible wake with a cursor after the output the model last saw through a wake or read, not a replay of buffered output. A bounded batch preserves its first and latest dropped matching lines as wake evidence even if later output evicts them from the ring.
 - Children run in process groups: SIGTERM, then SIGKILL. Exit cleanup and pidfiles cover orderly quit
   and later recovery after SIGKILL. Files live at
   `$TMPDIR/pi-monitors-<uid>/<sessionId>.<ownerPid>/<monitorId>.json`. Startup checks dead-owner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nredd/pi-session-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "publishConfig": {
     "access": "public"
   },

package/src/monitor/coalescer.ts

@@ -5,6 +5,8 @@ export interface CoalescedBatch<T> {
 	items: T[];
 	dropped: number;
 	droppedMatched: boolean;
+	/** First and newest dropped matches, retained independently of passive batch storage. */
+	droppedMatches: T[];
 }
 
 export class Coalescer<T> {
@@ -12,6 +14,7 @@ export class Coalescer<T> {
 	private bytes = 0;
 	private dropped = 0;
 	private droppedMatched = false;
+	private droppedMatches: T[] = [];
 	private timer: TimerHandle | undefined;
 
 	constructor(
@@ -32,7 +35,11 @@ export class Coalescer<T> {
 		const maxBytes = this.options.maxBytes ?? 64 * 1024;
 		if (this.items.length >= maxItems || this.bytes + size > maxBytes) {
 			this.dropped++;
-			this.droppedMatched ||= this.options.matched?.(item) ?? false;
+			if (this.options.matched?.(item)) {
+				this.droppedMatched = true;
+				if (this.droppedMatches.length < 2) this.droppedMatches.push(item);
+				else this.droppedMatches[1] = item;
+			}
 		} else {
 			this.items.push(item);
 			this.bytes += size;
@@ -63,14 +70,21 @@ export class Coalescer<T> {
 		this.bytes = 0;
 		this.dropped = 0;
 		this.droppedMatched = false;
+		this.droppedMatches = [];
 	}
 
 	private takeBatch(): CoalescedBatch<T> {
-		const batch = { items: this.items, dropped: this.dropped, droppedMatched: this.droppedMatched };
+		const batch = {
+			items: this.items,
+			dropped: this.dropped,
+			droppedMatched: this.droppedMatched,
+			droppedMatches: this.droppedMatches,
+		};
 		this.items = [];
 		this.bytes = 0;
 		this.dropped = 0;
 		this.droppedMatched = false;
+		this.droppedMatches = [];
 		return batch;
 	}
 }

package/src/monitor/index.ts

@@ -2,8 +2,8 @@
  * `/monitor`: background process watchers the model can start, read and stop.
  *
  * - `monitor_start` / `monitor_read` / `monitor_stop` tools and a `/monitor` command (list, stop)
- * - output is coalesced for 2s into ONE custom message per monitor; the agent is only woken on a
- *   `match` hit, on exit/timeout, or when `wake: true`, otherwise the message is passive context
+ * - 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
  * - every child dies on `session_shutdown`, which pi fires for quit AND for /new, /resume, /fork
  *   and /reload (a reload replaces the extension runtime, so a monitor could not be reattached
  *   anyway). A SIGKILLed pi leaves pidfiles; the next session sweeps only dead owners' files
@@ -107,9 +107,9 @@ export function register(
 		description:
 			"Start a long-running background process (log tail, watcher, poller) and get its output as it appears. " +
 			'argv is spawned directly with no shell; use ["sh","-c","..."] explicitly for pipes. ' +
-			"Output lines are coalesced for 2s into one message. You are woken only when a line matches `match` " +
-			"(JS regex), when the process exits or times out, or on every batch when `wake` is true; otherwise output " +
-			"is passive context and monitor_read fetches it. Do not use this for commands that finish quickly.",
+			"Output lines are retained in the monitor buffer and read with monitor_read. You are woken only when a line " +
+			"matches `match` (JS regex), when the process exits or times out, or on every batch when `wake` is true; " +
+			"passive output is not added to the session. Do not use this for commands that finish quickly.",
 		promptSnippet: "Start a background process and be woken on matching output or exit",
 		parameters: Type.Object({
 			argv: Type.Array(Type.String(), { minItems: 1, description: "Command and arguments, no shell" }),

package/src/monitor/manager.ts

@@ -60,6 +60,8 @@ interface Monitor {
 	coalescer: Coalescer<TaggedLine>;
 	timeoutTimer: TimerHandle;
 	stopReason: "stop" | "timeout" | undefined;
+	/** Cursor after the output the model most recently received through a wake or read. */
+	notifiedSince: number;
 	/** Resolves after the exit was fully processed (status set, pidfile removed). */
 	done: Promise<void>;
 }
@@ -109,7 +111,9 @@ export class MonitorManager {
 	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 };
+		const lastLine = m.ring.lastLine;
+		m.notifiedSince = lastLine;
+		return { ...m.ring.read(since), info: toInfo(m), lastLine };
 	}
 
 	async start(params: StartParams, cwd: string): Promise<MonitorInfo> {
@@ -205,6 +209,7 @@ export class MonitorManager {
 			coalescer,
 			timeoutTimer,
 			stopReason: undefined,
+			notifiedSince: 0,
 			done: Promise.resolve(),
 		};
 		const m = monitor;
@@ -283,29 +288,23 @@ export class MonitorManager {
 		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 }));
-		}
+		// A requested stop is already known to whoever asked. Passive output stays only in the ring;
+		// natural exit and timeout each emit one compact wake.
+		if (m.stopReason !== "stop") this.deliver(m, pending, { final: true, wake: true });
 		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),
-			}),
-		);
+		const wake = m.wake || batch.droppedMatched || batch.items.some((l) => l.matched);
+		if (wake) this.deliver(m, batch, { final: false, wake });
 	}
 
 	/** A failed delivery must never leave a monitor un-reaped, so it is swallowed here. */
-	private deliver(message: MonitorMessage): void {
+	private deliver(m: Monitor, batch: CoalescedBatch<TaggedLine>, opts: { final: boolean; wake: boolean }): void {
 		try {
-			this.opts.send(message);
+			this.opts.send(formatMessage(toInfo(m), batch, { ...opts, since: m.notifiedSince }));
+			m.notifiedSince = m.ring.lastLine;
 		} catch {
 			// the output stays readable through monitor_read
 		}
@@ -329,6 +328,7 @@ function toInfo(m: Monitor): MonitorInfo {
 		exitCode: m.exit.exitCode,
 		signal: m.exit.signal,
 		lines: m.ring.lastLine,
+		lastLine: m.ring.lastText,
 		wake: m.wake,
 		match: m.matchSource,
 		timeoutMs: m.timeoutMs,

package/src/monitor/messages.ts

@@ -1,12 +1,9 @@
-/** Formats coalesced monitor output and lifecycle events as one custom-message body. */
+/** Formats compact monitor wake and lifecycle custom messages. */
 
 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 {
@@ -21,72 +18,52 @@ 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`;
+			return `timed out after ${took} and was killed`;
 		case "stopped":
-			return `stopped after ${took}; ${info.lines} lines total`;
+			return `stopped after ${took}`;
 		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--;
+				? `died from ${info.signal} after ${took}`
+				: `exited with code ${info.exitCode ?? "?"} after ${took}`;
 	}
-	kept = kept.slice(from);
-	return { kept, omitted: lines.length - kept.length };
 }
 
+/** A wake names its event and cursor without replaying passive buffered output. */
 export function formatMessage(
 	info: MonitorInfo,
 	input: CoalescedBatch<TaggedLine> | TaggedLine[],
-	opts: { final: boolean; wake: boolean },
+	opts: { final: boolean; wake: boolean; since?: number },
 ): MonitorMessage {
-	const batch = Array.isArray(input) ? { items: input, dropped: 0, droppedMatched: false } : input;
+	const batch = Array.isArray(input) ? { items: input, dropped: 0, droppedMatched: false, droppedMatches: [] } : input;
+	const matched = [...batch.items.filter((line) => line.matched), ...batch.droppedMatches].sort((a, b) => a.n - b.n);
+	const firstLine = (batch.items[0]?.n ?? info.lines + 1) - batch.dropped;
+	const lastLine = batch.items.at(-1)?.n ?? info.lines;
+	const readSince = Math.max(0, opts.since ?? 0);
 	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}`);
+	const parts = [head];
+	if (matched.length > 0) {
+		const first = matched[0];
+		const last = matched.at(-1);
+		parts.push(
+			first === last
+				? `matched line ${first?.n}: ${first?.text}`
+				: `matched lines ${first?.n}: ${first?.text}; ${last?.n}: ${last?.text}`,
+		);
+	} else if (!opts.final && batch.items.length > 0) {
+		const line = batch.items.at(-1);
+		parts.push(`output line ${line?.n}: ${line?.text}`);
 	}
-	if (opts.final) parts.push(`${head} ${exitNote(info)}`);
+	if (opts.final) parts.push(exitNote(info));
+	parts.push(`monitor_read {"id":"${info.id}","since":${readSince}}`);
 	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,
+			firstLine,
+			lastLine,
+			matched: matched.map((line) => line.n),
 			status: info.status,
 		},
 	};

package/src/monitor/output.ts

@@ -18,6 +18,8 @@ export interface Bounded {
 /** Room reserved for the truncation notice inside the limits. */
 const NOTICE_BYTES = 256;
 const NOTICE_LINES = 2;
+/** Prefix preceding the spilled-file path when model-visible output is truncated. */
+export const OUTPUT_TRUNCATED_PREFIX = "[output truncated at the start; full text in ";
 
 let spillDir: Promise<string> | undefined;
 let spillSeq = 0;
@@ -34,7 +36,7 @@ export async function boundTail(text: string, label: string): Promise<Bounded> {
 	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}]`,
+		text: `${result.content}\n${OUTPUT_TRUNCATED_PREFIX}${fullOutputPath}]`,
 		truncated: true,
 		fullOutputPath,
 	};

package/src/monitor/ring.ts

@@ -35,6 +35,11 @@ export class RingBuffer {
 		return this.total;
 	}
 
+	/** Text of the newest line, undefined when nothing was ever pushed. */
+	get lastText(): string | undefined {
+		return this.total === 0 ? undefined : this.slots[(this.total - 1) % this.capacity];
+	}
+
 	/** Number of the oldest retained line, `lastLine + 1` when empty. */
 	get firstLine(): number {
 		return Math.max(1, this.total - this.capacity + 1);

package/src/monitor/types.ts

@@ -14,7 +14,7 @@ export interface MonitorMessageDetails {
 export interface MonitorMessage {
 	text: string;
 	details: MonitorMessageDetails;
-	/** Trigger an agent turn (match, exit, timeout, or `wake: true`); otherwise passive context. */
+	/** Trigger an agent turn (match, exit, timeout, or `wake: true`). */
 	wake: boolean;
 }
 
@@ -29,6 +29,8 @@ export interface MonitorInfo {
 	exitCode: number | null;
 	signal: NodeJS.Signals | null;
 	lines: number;
+	/** Newest buffered output, for the compact TUI summary only. */
+	lastLine?: string;
 	wake: boolean;
 	match?: string;
 	timeoutMs: number;

package/src/monitor/widget.ts

@@ -1,22 +1,28 @@
-/** One widget row per running monitor (TUI only). Renders live from the manager, never from copies. */
+/** Quiet above-editor summary of running monitors. */
 
 import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { formatDuration } from "./messages.ts";
 import type { MonitorInfo } from "./types.ts";
 
 export const WIDGET_KEY = "session-kit:monitors";
 const TICK_MS = 1_000;
 
-export function formatRow(info: MonitorInfo, now: number, theme: Pick<Theme, "fg">): string {
-	const parts = [
-		theme.fg("success", "●"),
-		` ${theme.fg("accent", info.name)}`,
-		theme.fg("muted", `  ${info.id}  ${formatDuration(now - info.startedAt)}  ${info.lines} lines`),
-	];
-	if (info.match) parts.push(theme.fg("muted", `  match /${info.match}/`));
-	else if (info.wake) parts.push(theme.fg("muted", "  wake"));
-	return parts.join("");
+type WidgetTheme = Pick<Theme, "fg">;
+
+function monitorSummary(info: MonitorInfo, now: number): string {
+	return `${info.name} ${formatDuration(now - info.startedAt)} ${info.lines} lines last: ${info.lastLine ?? "(no output)"}`;
+}
+
+/** 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, "…")];
 }
 
 export class MonitorWidget {
@@ -41,8 +47,7 @@ export class MonitorWidget {
 			ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
 				this.requestRender = () => tui.requestRender();
 				return {
-					render: (width: number) =>
-						this.running().map((info) => truncateToWidth(formatRow(info, Date.now(), theme), width, "…")),
+					render: (width: number) => formatSummary(this.running(), Date.now(), width, theme),
 					invalidate() {},
 				};
 			});