gentle-pi 3.7.0 → 4.1.0

package/lib/background-jobs-tools.ts

@@ -0,0 +1,202 @@
+// Model-facing surface of background jobs: the `bash_background`, `job_stop`,
+// and `job_list` tools, the exit notice text, and its transcript card.
+// Delivery of the notice belongs to the caller (Gentle Agents' parent
+// delivery router), so this module never sends messages itself.
+
+import { keyHint, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { BASH_BACKGROUND_TOOL, MAX_RUNNING_JOBS, MONITOR_TOOL, type JobRecord, type JobRegistry } from "./background-jobs.ts";
+import { MONITOR_BATCH_MS, MONITOR_FLOOD_LINES, MONITOR_FLOOD_WINDOW_MS, MONITOR_LINES_PER_NOTICE, MONITOR_MAX_TIMEOUT_SECONDS, type MonitorBatch, type MonitorController, type MonitorStopReason } from "./background-monitor.ts";
+import { CARD_TONE, renderCard, type CardTheme } from "./shell-card.ts";
+import { sanitizeTerminalText } from "./terminal-theme.ts";
+
+export const JOB_NOTICE_TYPE = "gentle-jobs.notice";
+export const JOB_GLYPH = "⧗";
+
+export function formatJobDuration(ms: number): string {
+	const seconds = Math.max(0, Math.round(ms / 1000));
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+	return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+
+const quoted = (job: JobRecord) => `${job.id} ("${job.label}")`;
+const noun = (job: JobRecord) => (job.kind === "monitor" ? "Monitor" : "Background job");
+const plural = (count: number, word: string) => `${count} ${word}${count === 1 ? "" : "s"}`;
+
+/** One-line outcome, shared by the notice, the list, and the jobs view. */
+export function jobOutcome(job: JobRecord): string {
+	if (job.status === "running") return "running";
+	if (job.status === "stopped") return "stopped";
+	if (job.status === "failed") return `could not run: ${job.error ?? "unknown error"}`;
+	return job.exitCode === null || job.exitCode === undefined ? "exited without an exit code" : `exited with code ${job.exitCode}`;
+}
+
+/** Model-facing exit notice: everything needed to act without polling. */
+export function jobNoticeText(job: JobRecord): string {
+	const duration = job.endedAt === undefined ? "" : ` after ${formatJobDuration(job.endedAt - job.startedAt)}`;
+	// Only a human stops a job without the agent knowing (job_stop sends no notice).
+	const outcome = job.status === "stopped" ? "was stopped by the user" : jobOutcome(job);
+	const events = job.kind === "monitor" ? `, ${plural(job.events ?? 0, "event")}` : "";
+	const lines = [`${noun(job)} ${quoted(job)} ${outcome}${duration}${events}.`, `Command: ${job.command}`];
+	if (job.tail.length > 0) lines.push("Last output:", ...job.tail);
+	else lines.push("No output.");
+	lines.push(`Full output: ${job.outputPath} (read it with the read tool if you need more).`);
+	return lines.join("\n");
+}
+
+/** Model-facing notice for one batch of monitor lines. */
+export function monitorEventsText(job: JobRecord, batch: MonitorBatch): string {
+	const lines = [`Monitor ${quoted(job)} reported ${plural(batch.lines.length, "new line")}:`, ...batch.lines];
+	if (batch.omitted > 0) lines.push(`(${plural(batch.omitted, "more line")} not shown; full output in ${job.outputPath})`);
+	return lines.join("\n");
+}
+
+/** Model-facing notice for a monitor the harness stopped. */
+export function monitorStoppedText(job: JobRecord, reason: MonitorStopReason): string {
+	const events = plural(job.events ?? 0, "event");
+	const output = `Full output: ${job.outputPath}`;
+	if (reason === "timeout") {
+		const limit = job.timeoutSeconds === undefined ? "its timeout" : `its ${job.timeoutSeconds}s timeout`;
+		return `Monitor ${quoted(job)} reached ${limit} after ${events} and was stopped. Start a new monitor if you still need to watch it.\n${output}`;
+	}
+	return `Monitor ${quoted(job)} was stopped: it printed more than ${MONITOR_FLOOD_LINES} lines within ${MONITOR_FLOOD_WINDOW_MS / 1000}s (${events}). Narrow the command's filter before watching it again.\n${output}`;
+}
+
+function listLine(job: JobRecord, now: number): string {
+	const ended = job.endedAt ?? now;
+	const status = `${job.kind === "monitor" ? "monitor " : ""}${job.status === "exited" ? `exited ${job.exitCode ?? "?"}` : job.status}`;
+	return `${job.id} · ${status} · ${job.label} · ${formatJobDuration(ended - job.startedAt)} · ${job.outputPath}`;
+}
+
+type ToolText = { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> };
+const text = (value: string, details: Record<string, unknown> = {}): ToolText => ({ content: [{ type: "text", text: value }], details });
+export const jobDetails = (job: JobRecord, event?: "events" | MonitorStopReason) => ({ gentleJobs: { jobId: job.id, kind: job.kind, label: job.label, status: job.status, exitCode: job.exitCode ?? null, outputPath: job.outputPath, ...(event ? { event } : {}) } });
+
+export interface BackgroundJobToolsOptions {
+	registry: JobRegistry;
+	/** The session the tool call runs in; jobs belong to it. */
+	sessionId(ctx: ExtensionContext): string;
+	now(): number;
+	/** Called after a job starts or stops, so views can refresh. */
+	onChange?(): void;
+	/** Starts and stops monitors; without it the monitor tool is not offered. */
+	monitors?: MonitorController;
+}
+
+export function registerBackgroundJobTools(pi: ExtensionAPI, options: BackgroundJobToolsOptions): void {
+	const { registry } = options;
+	const owned = (ctx: ExtensionContext, id: string) => {
+		const job = registry.get(id);
+		return job && job.ownerSessionId === options.sessionId(ctx) ? job : undefined;
+	};
+
+	pi.registerTool({
+		name: BASH_BACKGROUND_TOOL,
+		label: "Bash (background)",
+		description: [
+			"Run a shell command in the background and return a job id at once. You are notified once, automatically, when it exits (exit code, last output lines, output file); do not poll, sleep, or delegate a subagent to wait.",
+			"Use synchronous bash for local, finite, deterministic checks reasonably expected to finish within 30 seconds, with an explicit timeout <= 30 seconds (30 included). Use bash_background for longer or unknown duration, external waits, CI, builds, and servers, including deploys and long tests. Report a timeout as failure; never automatically retry, restart, or migrate it to background. Preserve RED/GREEN and public-check exit codes, stdout, and stderr; do not defer or batch Engram bugfix saves and session summaries or bypass RDD. This is guidance, not a performance guarantee.",
+			"Put the wait condition inside the command so its exit is the event, e.g. `gh run watch <run-id> --exit-status` or `until curl -sf localhost:3000/health; do sleep 1; done`.",
+			`Output goes to a file you can read with the read tool. Stop a job with job_stop; list jobs with job_list. At most ${MAX_RUNNING_JOBS} run at once.`,
+		].join(" "),
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			required: ["command"],
+			properties: {
+				command: { type: "string", description: "Shell command to run in the background, in the session working directory." },
+				label: { type: "string", maxLength: 80, description: "Short human-readable label, e.g. 'CI for PR 1834'." },
+			},
+		} as never,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const input = params as { command?: unknown; label?: unknown };
+			if (typeof input.command !== "string" || !input.command.trim()) throw new Error("bash_background requires a non-empty command");
+			const job = registry.start({ command: input.command, cwd: ctx.cwd, ownerSessionId: options.sessionId(ctx), label: typeof input.label === "string" ? input.label : undefined });
+			options.onChange?.();
+			return text(
+				`Started background job ${quoted(job)}.\nOutput: ${job.outputPath}\nYou will be notified once when it exits; keep working or end your turn. Stop it with job_stop.`,
+				jobDetails(job),
+			);
+		},
+	});
+
+	const monitors = options.monitors;
+	if (monitors) pi.registerTool({
+		name: MONITOR_TOOL,
+		label: "Monitor",
+		description: [
+			"Run a command in the background and receive each output line as an event while it runs, without waiting for it to exit. Do not poll or sleep between events.",
+			"Use it to react as things happen: `tail -f app.log | grep --line-buffered ERROR`, or a loop that prints each CI check as it finishes. For a single result when a command ends, use bash_background instead.",
+			`Lines within ${MONITOR_BATCH_MS} ms arrive as one notice of at most ${MONITOR_LINES_PER_NOTICE} lines. timeout_seconds is mandatory (1-${MONITOR_MAX_TIMEOUT_SECONDS}); the monitor is stopped when it expires, and also when it prints more than ${MONITOR_FLOOD_LINES} lines within ${MONITOR_FLOOD_WINDOW_MS / 1000}s, so filter the command's output.`,
+			"Stop it with job_stop; list it with job_list.",
+		].join(" "),
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			required: ["command", "timeout_seconds"],
+			properties: {
+				command: { type: "string", description: "Shell command whose output lines are events, run in the session working directory." },
+				timeout_seconds: { type: "integer", minimum: 1, maximum: MONITOR_MAX_TIMEOUT_SECONDS, description: "Mandatory: stop the monitor after this many seconds." },
+				label: { type: "string", maxLength: 80, description: "Short human-readable label, e.g. 'CI checks for PR 1842'." },
+			},
+		} as never,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const input = params as { command?: unknown; label?: unknown; timeout_seconds?: unknown };
+			if (typeof input.command !== "string" || !input.command.trim()) throw new Error("monitor requires a non-empty command");
+			const timeoutSeconds = typeof input.timeout_seconds === "number" ? input.timeout_seconds : Number.NaN;
+			const job = monitors.start({ command: input.command, cwd: ctx.cwd, ownerSessionId: options.sessionId(ctx), label: typeof input.label === "string" ? input.label : undefined, timeoutSeconds });
+			options.onChange?.();
+			return text(
+				`Started monitor ${quoted(job)} for up to ${timeoutSeconds}s.\nOutput: ${job.outputPath}\nEach new output line reaches you as an event; keep working or end your turn. Stop it with job_stop.`,
+				jobDetails(job),
+			);
+		},
+	});
+
+	pi.registerTool({
+		name: "job_stop",
+		label: "Stop background job",
+		description: "Stop a background job started with bash_background, killing its whole process tree. A stopped job sends no exit notice.",
+		parameters: { type: "object", additionalProperties: false, required: ["job_id"], properties: { job_id: { type: "string" } } } as never,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const id = (params as { job_id?: unknown }).job_id;
+			const job = typeof id === "string" ? owned(ctx, id) : undefined;
+			if (!job) throw new Error(`No background job ${String(id)} in this session. Use job_list to see this session's jobs.`);
+			const wasRunning = job.status === "running";
+			options.monitors?.cancel(job.id);
+			registry.stop(job.id);
+			options.onChange?.();
+			return text(wasRunning ? `Stopped ${quoted(job)}.` : `${quoted(job)} was already ${jobOutcome(job)}.`, jobDetails(job));
+		},
+	});
+
+	pi.registerTool({
+		name: "job_list",
+		label: "List background jobs",
+		description: "List this session's background jobs with status, label, elapsed time, and output file.",
+		parameters: { type: "object", additionalProperties: false, properties: {} } as never,
+		async execute(_id, _params, _signal, _onUpdate, ctx) {
+			const jobs = registry.list(options.sessionId(ctx));
+			if (jobs.length === 0) return text("No background jobs in this session.");
+			const now = options.now();
+			return text(jobs.map((job) => listLine(job, now)).join("\n"), { gentleJobs: { count: jobs.length } });
+		},
+	});
+
+	pi.registerMessageRenderer(JOB_NOTICE_TYPE, (message, renderOptions, theme) => {
+		const details = (message.details as { gentleJobs?: { label?: string; status?: string; exitCode?: number | null; kind?: string; event?: string } } | undefined)?.gentleJobs;
+		const content = typeof message.content === "string" ? message.content : message.content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
+		const lines = sanitizeTerminalText(content).split("\n");
+		const tone = details?.event === "events" ? CARD_TONE.INFO
+			: details?.status === "exited" && details.exitCode === 0 ? CARD_TONE.SUCCESS : CARD_TONE.ERROR;
+		let hint: string;
+		try { hint = keyHint("app.tools.expand", renderOptions.expanded ? "collapse" : "expand"); } catch { hint = renderOptions.expanded ? "collapse" : "expand"; }
+		return {
+			render(width: number) {
+				return renderCard({ title: details?.kind === "monitor" ? "Monitor" : "Background job", subtitle: details?.label, body: lines, tone, glyph: JOB_GLYPH }, theme as CardTheme, width, { expanded: renderOptions.expanded, previewRows: 3, hint });
+			},
+			invalidate() {},
+		};
+	});
+}

package/lib/background-jobs.ts

@@ -0,0 +1,253 @@
+// Background jobs.
+//
+// A background job runs a shell command while the parent keeps working or
+// stays idle, so waiting on CI, a build, or a server never costs a sleep loop
+// or a subagent. A wait condition lives inside the command itself (for
+// example `until grep -q ready log; do sleep 1; done` or
+// `gh run watch <id> --exit-status`): the job's exit is the notification.
+//
+// The registry owns live jobs and reports each job's own exit exactly once
+// through `onSettled`. A stopped job reports nothing: whoever stopped it
+// already knows. Execution goes through Pi's own shell operations
+// (`createLocalBashOperations`), so the configured shell, the command
+// transport, process groups, and process-tree kill match native Bash.
+
+import { createWriteStream, type WriteStream } from "node:fs";
+import { join } from "node:path";
+
+/** The background sibling of Pi's native `bash` tool. */
+export const BASH_BACKGROUND_TOOL = "bash_background";
+/** A background job whose output lines are events. */
+export const MONITOR_TOOL = "monitor";
+/**
+ * Tools whose `command` input runs in a shell. Command guards (confirmation,
+ * YOLO, child safety) must cover every one of them, or the background tool
+ * would bypass them.
+ */
+export const SHELL_COMMAND_TOOLS: ReadonlySet<string> = new Set(["bash", BASH_BACKGROUND_TOOL, MONITOR_TOOL]);
+
+const STANDALONE_SLEEP_SEGMENT = /^sleep\s+\d+(?:\.\d+)?[smhd]?$/;
+
+/**
+ * True only for a command that does nothing but sleep: one or more literal
+ * `sleep <number>[smhd]` segments joined by `&&` or `;`. Wait conditions
+ * (`until ...; do sleep 1; done`), loops, pipes and sleeps mixed with real
+ * commands are never standalone (#1903).
+ */
+export function isStandaloneSleep(command: string): boolean {
+	const segments = command.split(/&&|;/).map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+	return segments.length > 0 && segments.every((segment) => STANDALONE_SLEEP_SEGMENT.test(segment));
+}
+
+/** Lines kept for the exit notice and job listings. */
+export const TAIL_LINES = 20;
+/**
+ * Characters kept per tail line. Progress bars and minified output can print
+ * one endless line; only its newest characters are kept, after an ellipsis.
+ */
+export const MAX_TAIL_LINE_CHARS = 2000;
+/** Running jobs allowed at once across the process. */
+export const MAX_RUNNING_JOBS = 25;
+
+/** Collects the last TAIL_LINES lines of a stream of output chunks. */
+export function createOutputTail() {
+	const complete: string[] = [];
+	let partial = "";
+	let partialTruncated = false;
+	const bound = (line: string, truncated: boolean) => {
+		const cut = line.length > MAX_TAIL_LINE_CHARS;
+		const kept = cut ? line.slice(-MAX_TAIL_LINE_CHARS) : line;
+		return cut || truncated ? `…${kept}` : kept;
+	};
+	const clean = (line: string) => (line.endsWith("\r") ? line.slice(0, -1) : line);
+	return {
+		push(text: string) {
+			const parts = (partial + text).split("\n");
+			partial = parts.pop() ?? "";
+			for (const [index, part] of parts.entries()) {
+				complete.push(bound(clean(part), index === 0 && partialTruncated));
+				if (complete.length > TAIL_LINES) complete.shift();
+				if (index === 0) partialTruncated = false;
+			}
+			if (partial.length > MAX_TAIL_LINE_CHARS) {
+				partial = partial.slice(-MAX_TAIL_LINE_CHARS);
+				partialTruncated = true;
+			}
+		},
+		lines(): string[] {
+			const all = partial.length > 0 ? [...complete, bound(clean(partial), partialTruncated)] : [...complete];
+			return all.slice(-TAIL_LINES);
+		},
+	};
+}
+
+/** The subset of Pi's `BashOperations` a job needs. */
+export interface JobExecOperations {
+	exec(command: string, cwd: string, options: { onData: (data: Buffer) => void; signal?: AbortSignal }): Promise<{ exitCode: number | null }>;
+}
+
+export type JobStatus = "running" | "exited" | "stopped" | "failed";
+/** A command reports its exit; a monitor also reports each output line. */
+export type JobKind = "command" | "monitor";
+
+export interface JobRecord {
+	readonly id: string;
+	readonly kind: JobKind;
+	readonly label: string;
+	readonly command: string;
+	readonly cwd: string;
+	readonly ownerSessionId: string;
+	readonly outputPath: string;
+	readonly startedAt: number;
+	status: JobStatus;
+	exitCode?: number | null;
+	error?: string;
+	endedAt?: number;
+	/** Last output lines; refreshed until the job ends. */
+	tail: string[];
+	/** Monitor only: output lines reported as events so far. */
+	events?: number;
+	/** Monitor only: the mandatory timeout it was started with. */
+	timeoutSeconds?: number;
+}
+
+export interface JobStartRequest {
+	command: string;
+	cwd: string;
+	ownerSessionId: string;
+	label?: string;
+	kind?: JobKind;
+	/** Called with each complete output line, and the last partial one at exit. */
+	onLine?: (line: string) => void;
+}
+
+export interface JobRegistryDeps {
+	/** Directory receiving one `<id>.log` file per job; read at each start. */
+	outputDir(): string;
+	now(): number;
+	/** Resolved at each start so a changed shell setting applies to the next job. */
+	shell(cwd: string): { operations: JobExecOperations; commandPrefix?: string };
+	/** Called once when a job ends on its own (exited or failed), never for a stop. */
+	onSettled(job: JobRecord): void;
+}
+
+export function createJobRegistry(deps: JobRegistryDeps) {
+	const jobs = new Map<string, JobRecord>();
+	const aborts = new Map<string, AbortController>();
+	// Every job's run, until its log file is closed and its exit reported.
+	const runs = new Set<Promise<void>>();
+	let counter = 0;
+
+	const running = () => [...jobs.values()].filter((job) => job.status === "running").length;
+
+	const finish = async (job: JobRecord, output: WriteStream, update: () => void) => {
+		update();
+		await new Promise<void>((resolve) => output.end(resolve));
+		aborts.delete(job.id);
+	};
+
+	const start = (request: JobStartRequest): JobRecord => {
+		if (running() >= MAX_RUNNING_JOBS) {
+			throw new Error(`${MAX_RUNNING_JOBS} background jobs are already running; stop one with job_stop first.`);
+		}
+		const { operations, commandPrefix } = deps.shell(request.cwd);
+		const id = `job-${++counter}`;
+		const job: JobRecord = {
+			id,
+			kind: request.kind ?? "command",
+			label: request.label?.trim() || request.command,
+			command: request.command,
+			cwd: request.cwd,
+			ownerSessionId: request.ownerSessionId,
+			outputPath: join(deps.outputDir(), `${id}.log`),
+			startedAt: deps.now(),
+			status: "running",
+			tail: [],
+		};
+		const output = createWriteStream(job.outputPath);
+		output.on("error", () => { /* A lost log must not crash the session; the tail survives. */ });
+		const tail = createOutputTail();
+		// Streaming decode keeps a multibyte character split across chunks intact.
+		const decoder = new TextDecoder("utf-8");
+		const abort = new AbortController();
+		jobs.set(id, job);
+		aborts.set(id, abort);
+		const execCommand = commandPrefix ? `${commandPrefix}\n${request.command}` : request.command;
+		let linePartial = "";
+		const emitLines = (text: string, end: boolean) => {
+			if (!request.onLine) return;
+			const parts = (linePartial + text).split("\n");
+			linePartial = end ? "" : parts.pop() ?? "";
+			// Keep one extra character so a cut partial still reads as cut.
+			if (linePartial.length > MAX_TAIL_LINE_CHARS) linePartial = linePartial.slice(-(MAX_TAIL_LINE_CHARS + 1));
+			for (const part of parts) {
+				const line = part.endsWith("\r") ? part.slice(0, -1) : part;
+				request.onLine(line.length > MAX_TAIL_LINE_CHARS ? `…${line.slice(-MAX_TAIL_LINE_CHARS)}` : line);
+			}
+		};
+		const flushDecoder = () => {
+			const rest = decoder.decode();
+			if (rest) {
+				tail.push(rest);
+				job.tail = tail.lines();
+			}
+			emitLines(rest, true);
+		};
+		const onData = (data: Buffer) => {
+			output.write(data);
+			const text = decoder.decode(data, { stream: true });
+			tail.push(text);
+			job.tail = tail.lines();
+			emitLines(text, false);
+		};
+		const run = operations.exec(execCommand, request.cwd, { onData, signal: abort.signal }).then(
+			({ exitCode }) => finish(job, output, () => {
+				flushDecoder();
+				if (job.status !== "running") return;
+				job.status = "exited";
+				job.exitCode = exitCode;
+				job.endedAt = deps.now();
+			}),
+			(error: unknown) => finish(job, output, () => {
+				flushDecoder();
+				if (job.status !== "running") return;
+				job.status = "failed";
+				job.error = error instanceof Error ? error.message : String(error);
+				job.endedAt = deps.now();
+			}),
+		).then(() => {
+			if (job.status === "exited" || job.status === "failed") deps.onSettled(job);
+		}).finally(() => runs.delete(run));
+		runs.add(run);
+		return job;
+	};
+
+	const stop = (id: string): JobRecord | undefined => {
+		const job = jobs.get(id);
+		if (!job) return undefined;
+		if (job.status === "running") {
+			job.status = "stopped";
+			job.endedAt = deps.now();
+			aborts.get(id)?.abort();
+		}
+		return job;
+	};
+
+	return {
+		start,
+		stop,
+		get: (id: string) => jobs.get(id),
+		/** Jobs in start order, optionally only those one session owns. */
+		list: (ownerSessionId?: string) => [...jobs.values()].filter((job) => ownerSessionId === undefined || job.ownerSessionId === ownerSessionId),
+		running,
+		/** Runs not yet finished: still executing or closing their log. */
+		pending: () => runs.size,
+		/** Stops every running job and resolves once every log file is closed. */
+		stopAll: async () => {
+			for (const id of jobs.keys()) stop(id);
+			await Promise.allSettled([...runs]);
+		},
+	};
+}
+
+export type JobRegistry = ReturnType<typeof createJobRegistry>;

package/lib/background-monitor.ts

@@ -0,0 +1,154 @@
+// Background monitor: pure event batching.
+//
+// A monitor is a background job whose every stdout line is an event for the
+// agent, delivered while the command keeps running (for example
+// `tail -f app.log | grep --line-buffered ERROR`, or a loop that prints each
+// CI check as it finishes). Lines arriving close together share one notice,
+// each notice is bounded, and a stream that floods is stopped instead of
+// burning the agent's turns. This module owns no timers or processes: the
+// caller flushes MONITOR_BATCH_MS after a line opens a batch. The controller
+// below wires it to a job registry with an injected scheduler.
+
+import type { JobRecord, JobRegistry, JobStartRequest } from "./background-jobs.ts";
+
+/** Lines arriving within this window share one notice. */
+export const MONITOR_BATCH_MS = 200;
+/** Lines kept per notice; the rest are only counted. */
+export const MONITOR_LINES_PER_NOTICE = 20;
+/** More lines than this within MONITOR_FLOOD_WINDOW_MS is a flood. */
+export const MONITOR_FLOOD_LINES = 120;
+export const MONITOR_FLOOD_WINDOW_MS = 60_000;
+/** The mandatory monitor timeout is capped at 30 minutes. */
+export const MONITOR_MAX_TIMEOUT_SECONDS = 1800;
+
+export interface MonitorBatch {
+	lines: string[];
+	/** Lines beyond MONITOR_LINES_PER_NOTICE, counted but not delivered. */
+	omitted: number;
+}
+
+export function createEventBatcher() {
+	let batch: MonitorBatch | undefined;
+	let total = 0;
+	// Arrival times inside the current flood window, oldest first.
+	const recent: number[] = [];
+	return {
+		/**
+		 * Records one stdout line. `opensBatch` asks the caller to schedule a
+		 * flush; `flood` asks it to stop the monitor.
+		 */
+		pushLine(line: string, now: number): { opensBatch: boolean; flood: boolean } {
+			if (line.trim().length === 0) return { opensBatch: false, flood: false };
+			total += 1;
+			recent.push(now);
+			while (recent.length > 0 && now - recent[0]! >= MONITOR_FLOOD_WINDOW_MS) recent.shift();
+			const opensBatch = batch === undefined;
+			batch ??= { lines: [], omitted: 0 };
+			if (batch.lines.length < MONITOR_LINES_PER_NOTICE) batch.lines.push(line);
+			else batch.omitted += 1;
+			return { opensBatch, flood: recent.length > MONITOR_FLOOD_LINES };
+		},
+		/** Takes the current batch, or undefined when no line arrived. */
+		flush(): MonitorBatch | undefined {
+			const taken = batch;
+			batch = undefined;
+			return taken;
+		},
+		/** Every event line seen so far. */
+		total: () => total,
+	};
+}
+
+/** Coalesces two pending notices for one monitor within the same line bound. */
+export function mergeMonitorBatches(first: MonitorBatch, second: MonitorBatch): MonitorBatch {
+	const room = Math.max(0, MONITOR_LINES_PER_NOTICE - first.lines.length);
+	return {
+		lines: [...first.lines, ...second.lines.slice(0, room)],
+		omitted: first.omitted + second.omitted + Math.max(0, second.lines.length - room),
+	};
+}
+
+export type MonitorStopReason = "timeout" | "flood";
+
+export type MonitorNotice =
+	| { job: JobRecord; kind: "events"; batch: MonitorBatch }
+	| { job: JobRecord; kind: "stopped"; reason: MonitorStopReason };
+
+export interface MonitorControllerDeps {
+	registry: JobRegistry;
+	schedule(fn: () => void, ms: number): () => void;
+	now(): number;
+	/** Hands one notice to the parent delivery router. */
+	deliver(notice: MonitorNotice): void;
+}
+
+export interface MonitorStartRequest extends Omit<JobStartRequest, "kind" | "onLine"> {
+	/** Mandatory: the monitor is stopped after this many seconds (1-1800). */
+	timeoutSeconds: number;
+}
+
+export function createMonitorController(deps: MonitorControllerDeps) {
+	const active = new Map<string, { batcher: ReturnType<typeof createEventBatcher>; cancelFlush?: () => void; cancelTimeout: () => void }>();
+
+	const flush = (job: JobRecord) => {
+		const state = active.get(job.id);
+		if (!state) return;
+		state.cancelFlush?.();
+		state.cancelFlush = undefined;
+		const batch = state.batcher.flush();
+		if (batch) deps.deliver({ job, kind: "events", batch });
+	};
+	const cancel = (id: string) => {
+		const state = active.get(id);
+		if (!state) return;
+		state.cancelFlush?.();
+		state.cancelTimeout();
+		active.delete(id);
+	};
+	const stopFor = (job: JobRecord, reason: MonitorStopReason) => {
+		// A command that already ended reports its own exit (finish flushes it).
+		if (job.status !== "running") return;
+		flush(job);
+		cancel(job.id);
+		deps.registry.stop(job.id);
+		deps.deliver({ job, kind: "stopped", reason });
+	};
+
+	return {
+		start(request: MonitorStartRequest): JobRecord {
+			const { timeoutSeconds, ...rest } = request;
+			if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > MONITOR_MAX_TIMEOUT_SECONDS) {
+				throw new Error(`timeout_seconds must be a whole number from 1 to ${MONITOR_MAX_TIMEOUT_SECONDS}.`);
+			}
+			const batcher = createEventBatcher();
+			let job: JobRecord | undefined;
+			const onLine = (line: string) => {
+				const state = job && active.get(job.id);
+				// A stopped or finished monitor reports nothing more.
+				if (!job || !state || job.status !== "running") return;
+				const { opensBatch, flood } = batcher.pushLine(line, deps.now());
+				job.events = batcher.total();
+				if (flood) return stopFor(job, "flood");
+				if (opensBatch) state.cancelFlush = deps.schedule(() => job && flush(job), MONITOR_BATCH_MS);
+			};
+			job = deps.registry.start({ ...rest, kind: "monitor", onLine });
+			job.events = 0;
+			job.timeoutSeconds = timeoutSeconds;
+			const started = job;
+			active.set(started.id, { batcher, cancelTimeout: deps.schedule(() => stopFor(started, "timeout"), timeoutSeconds * 1000) });
+			return started;
+		},
+		/** The job ended on its own: deliver its pending lines before the exit notice. */
+		finish(job: JobRecord) {
+			flush(job);
+			cancel(job.id);
+		},
+		/** Stopped by job_stop or a human: drop its timers and pending lines. */
+		cancel,
+		cancelAll() {
+			for (const id of [...active.keys()]) cancel(id);
+		},
+	};
+}
+
+export type MonitorController = ReturnType<typeof createMonitorController>;