@gavin-hu/my-pi-agent 0.14.0 → 0.15.0

package/extensions/watch/README.md

@@ -197,6 +197,14 @@ other.
 
 ## Design notes
 
+The shared seams are `lib/`'s: `lib/spawn.ts` (spawn, tree-kill), `lib/lines.ts`
+(the byte-safe splitter), `lib/format.ts` (`sanitizeUntrustedLine`),
+`lib/report.ts` (pending matches → notice → one wake turn),
+`lib/tui/status-controller.ts` (chips and the alert), and
+`lib/tui/dock-screen.ts` (the `/watch` frame, navigation, and confirm layer).
+What stays here is the watcher policy: the tailer, the matcher, the source
+model, the command-child lifecycle in `child.ts`, and the watcher vocabulary.
+
 The file tailer polls and exposes `tick()` publicly; the interval is a thin
 wrapper over `tick()`, so tests drive matching deterministically with no real
 timer. A command tailer is event-driven and feeds both output streams through
@@ -214,15 +222,15 @@ outlive the session.
 
 | Module | Responsibility |
 |---|---|
-| `index.ts` | Extension factory: registers the tool and command, wires the lifecycle and the shared notices. |
+| `index.ts` | Extension factory: registers the tool and command, wires the lifecycle, the shared `lib/report.ts` match reporter, and the shared notices. |
 | `tools.ts` | The `watch` tool definition, execution, and transcript rendering. |
 | `schema.ts` | TypeBox parameters and pure `normalizeCall` validation. |
 | `types.ts` | `WatchAction`/`WatchStatus`, `WatchRecord`, `WatchDetails`, `PendingMatch`. |
-| `runtime.ts` | The session-scoped watcher table, matcher, poll tick, and shutdown. |
-| `process.ts` | Injectable spawn and process-tree kill. |
-| `format.ts` | Pure sanitization and text formatting. |
-| `ui.ts` | Status chips and the match alert, over the shared `lib/tui/status-controller.ts`. |
-| `tui.ts` | `WatchResult` transcript block and the `/watch` dock screen, drawn from the `lib/tui/` kit (`titleRule`, `listRow`, `emptyState`, `IdCursor`, `LinePane`). |
+| `runtime.ts` | The session-scoped watcher table, matcher, poll tick, and shutdown; spawning and tree-kill come from `child.ts`, line splitting from `lib/lines.ts`. |
+| `child.ts` | A command watcher's process lifecycle: spawn, the SIGTERM → SIGKILL grace, and the shutdown drain, over the injected `SpawnFn`/`KillTreeFn` seams. |
+| `format.ts` | Pure text formatting; sanitization is `lib/format.ts`'s `sanitizeUntrustedLine`. |
+| `ui.ts` | Status chips and the match alert, over the shared `lib/tui/status-controller.ts` (chips, attached context, `notify`). |
+| `tui.ts` | The `WatchResult` transcript block over the shared `TailResult`, and the `/watch` screen as a `DockListScreen` subclass: watcher rows, focus block, counts, verbs. |
 | `commands.ts` | The `/watch` command and its completions. |
 | `config.ts` | The `watch` config section load and normalization. |
 

package/extensions/watch/child.ts

@@ -0,0 +1,150 @@
+/**
+ * A command watcher's process lifecycle: spawn, tree-kill, escalate, and drain.
+ *
+ * A command source is a spawned process whose merged stdout and stderr feed the
+ * matcher. This module owns the process side only — the spawn, the SIGTERM →
+ * SIGKILL grace, and the shutdown drain — over the injected `SpawnFn` and
+ * `KillTreeFn` seams, so the runtime keeps the watcher's status, its repaint,
+ * and its clock.
+ *
+ * Value-only: the child handle and its escalation timer live on the caller's
+ * slot, never here, because Pi loads each extension with its own module cache.
+ */
+
+import { defaultKillTree, defaultSpawn, type KillTreeFn, type SpawnFn, type SpawnedProcess } from "../../lib/spawn.ts";
+
+/** Grace period before a stopped command is escalated to SIGKILL. */
+export const KILL_GRACE_MS = 2000;
+
+/**
+ * The process fields a watcher record carries. The supervisor mutates them in
+ * place, so the runtime's record and the module's handle cannot disagree about
+ * whether a child is still live.
+ */
+export interface ChildSlot {
+	pid?: number;
+	child?: SpawnedProcess;
+	killTimer?: ReturnType<typeof setTimeout>;
+}
+
+/** How a child settled, for the sink that owns the watcher's status transition. */
+export type ChildOutcome =
+	| { kind: "closed"; code: number | null; signal: string | null }
+	| { kind: "failed"; message: string };
+
+export interface ChildSink {
+	/** One chunk of merged stdout/stderr. */
+	onData(chunk: Buffer): void;
+	/**
+	 * The child closed or failed to spawn. The sink owns the status, because only
+	 * it knows whether the watcher was still running when that happened.
+	 */
+	onSettled(outcome: ChildOutcome): void;
+}
+
+export interface ChildSupervisorOptions {
+	spawn?: SpawnFn;
+	killTree?: KillTreeFn;
+	/** Grace before SIGTERM escalates to SIGKILL; default {@link KILL_GRACE_MS}. */
+	graceMs?: number;
+}
+
+export interface ChildSupervisor {
+	/** Spawn `command`, or return the spawn error and leave the slot's child unset. */
+	start(slot: ChildSlot, command: string, cwd: string, sink: ChildSink): string | undefined;
+	/** SIGTERM a command, escalating to SIGKILL when it has not closed in time. */
+	terminate(slot: ChildSlot): void;
+	/** Kill immediately, without arming an escalation. */
+	kill(slot: ChildSlot, signal: "SIGTERM" | "SIGKILL"): void;
+	/** Cancel a pending escalation. */
+	clearTimer(slot: ChildSlot): void;
+	/** Resolve when every slot's child has closed, or after `ms`, whichever comes first. */
+	wait(slots: readonly ChildSlot[], ms: number): Promise<void>;
+}
+
+export function createChildSupervisor(options: ChildSupervisorOptions = {}): ChildSupervisor {
+	const spawnFn = options.spawn ?? defaultSpawn;
+	const killTree = options.killTree ?? defaultKillTree;
+	const graceMs = options.graceMs ?? KILL_GRACE_MS;
+
+	const clearTimer = (slot: ChildSlot): void => {
+		if (slot.killTimer) {
+			clearTimeout(slot.killTimer);
+			slot.killTimer = undefined;
+		}
+	};
+
+	const kill = (slot: ChildSlot, signal: "SIGTERM" | "SIGKILL"): void => {
+		const pid = slot.pid;
+		try {
+			if (pid !== undefined) killTree(pid, signal, signal === "SIGKILL");
+			else slot.child?.kill(signal);
+		} catch {
+			// Best-effort: the child may already be gone.
+		}
+	};
+
+	const terminate = (slot: ChildSlot): void => {
+		clearTimer(slot);
+		kill(slot, "SIGTERM");
+		if (slot.pid === undefined && !slot.child) return;
+		slot.killTimer = setTimeout(() => {
+			slot.killTimer = undefined;
+			if (slot.child) kill(slot, "SIGKILL");
+		}, graceMs);
+		slot.killTimer.unref?.();
+	};
+
+	const start = (slot: ChildSlot, command: string, cwd: string, sink: ChildSink): string | undefined => {
+		let child: SpawnedProcess;
+		try {
+			child = spawnFn(command, { cwd });
+		} catch (error) {
+			return error instanceof Error ? error.message : String(error);
+		}
+		slot.child = child;
+		slot.pid = child.pid;
+		const onData = (chunk: Buffer): void => sink.onData(chunk);
+		child.stdout?.on("data", onData);
+		child.stderr?.on("data", onData);
+		child.on("close", (code, signal) => {
+			clearTimer(slot);
+			slot.child = undefined;
+			sink.onSettled({ kind: "closed", code, signal });
+		});
+		child.on("error", (error) => {
+			clearTimer(slot);
+			slot.child = undefined;
+			sink.onSettled({ kind: "failed", message: error.message });
+		});
+		return undefined;
+	};
+
+	const wait = (slots: readonly ChildSlot[], ms: number): Promise<void> => {
+		const alive = slots.filter((slot) => slot.child !== undefined);
+		if (alive.length === 0) return Promise.resolve();
+		return new Promise((resolve) => {
+			let remaining = alive.length;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const settle = (): void => {
+				if (--remaining > 0) return;
+				if (timer !== undefined) clearTimeout(timer);
+				resolve();
+			};
+			for (const slot of alive) {
+				let done = false;
+				const once = (): void => {
+					if (done) return;
+					done = true;
+					settle();
+				};
+				slot.child?.on("close", once);
+				slot.child?.on("error", once);
+			}
+			timer = setTimeout(resolve, ms);
+			timer.unref?.();
+		});
+	};
+
+	return { start, terminate, kill, clearTimer, wait };
+}

package/extensions/watch/format.ts

@@ -6,50 +6,23 @@
  * status chip, the `/watch` screen, the transcript, and the model.
  *
  * File and command output is untrusted, so every line that reaches a widget or
- * the model goes through `sanitizeLine` at the boundary.
+ * the model goes through `sanitizeUntrustedLine` from `lib/format.ts` at the
+ * boundary; `sanitizeLine` covers the extension's own trusted text.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { sanitizeLine } from "../../lib/format.ts";
-import { clip, labelLine } from "../../lib/tui/columns.ts";
+import { boundedTail, sanitizeLine } from "../../lib/format.ts";
+import { clip, clipLabel, labelLine } from "../../lib/tui/columns.ts";
 import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { byRunningFirst } from "../../lib/tui/rows.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { PendingMatch, WatchRecord, WatchStatus } from "./types.ts";
 
-/** Longest sanitized watched line kept for display; longer lines are clipped. */
-const MAX_WATCH_LINE = 200;
-
-/** ESC-introduced sequences: OSC, CSI, and single-character escapes. */
-const OSC = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
-const CSI = /\u001b\[[0-?]*[ -/]*[@-~]/g;
-const OTHER_ESC = /\u001b[@-Z\\-_]/g;
-const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
-
-/**
- * Make one line of untrusted file/command output safe to render.
- *
- * Resolves carriage returns the way a terminal would (keep the text after the
- * last `\r`, so progress rewrites collapse to their final state), strips ANSI
- * escapes and control characters, collapses whitespace, and clips the result.
- * `sanitizeLine` alone would leave the printable tail of an ANSI sequence.
- */
-export function sanitizeWatchLine(raw: string): string {
-	const withoutAnsi = raw.replace(OSC, "").replace(CSI, "").replace(OTHER_ESC, "");
-	const afterCr = withoutAnsi.slice(withoutAnsi.lastIndexOf("\r") + 1);
-	const cleaned = afterCr.replace(CONTROL, " ").replace(/\s+/g, " ").trim();
-	return cleaned.length > MAX_WATCH_LINE ? `${cleaned.slice(0, MAX_WATCH_LINE - 1)}…` : cleaned;
-}
-
 /** Compile a pattern; case-insensitive unless `caseSensitive`. */
 export function compileRegex(pattern: string, caseSensitive: boolean): RegExp {
 	return new RegExp(pattern, caseSensitive ? "" : "i");
 }
 
-/** A label clipped to one safe display line. */
-export function clipLabel(text: string): string {
-	return labelLine(text, sanitizeWatchLine);
-}
-
 /** What a watcher reads: a path or a command, clipped for display. */
 export function sourceLabel(watch: WatchRecord): string {
 	if (watch.source.kind === "file") return clipLabel(watch.source.path ?? "");
@@ -89,11 +62,6 @@ export function statusGlyphChar(status: WatchStatus): string {
 	}
 }
 
-/** Width-1 themed glyph for a watcher status. */
-export function statusGlyph(status: WatchStatus, theme: Theme): string {
-	return paint(theme, statusRole(status), statusGlyphChar(status));
-}
-
 /** Short status word, including an exit code or error when present. */
 export function statusWord(watch: WatchRecord): string {
 	if (watch.status === "error" && watch.error) return `error (${watch.error})`;
@@ -104,10 +72,7 @@ export function statusWord(watch: WatchRecord): string {
 }
 
 /** Order watchers for display: running first, then by most recent start. */
-export function compareWatches(a: WatchRecord, b: WatchRecord): number {
-	const rank = (watch: WatchRecord): number => (watch.status === "running" ? 0 : 1);
-	return rank(a) - rank(b) || b.startedAt - a.startedAt;
-}
+export const compareWatches = byRunningFirst<WatchRecord>((watch) => watch.status === "running");
 
 /** One-line watcher summary shared by model output and the `/watch` screen. */
 function watchSummary(watch: WatchRecord, now: number): string {
@@ -155,12 +120,7 @@ export function formatTail(
 			truncated: false,
 		};
 	}
-	let body = lines.join("\n");
-	let truncated = false;
-	if (body.length > maxChars) {
-		body = body.slice(body.length - maxChars);
-		truncated = true;
-	}
+	const { text: body, truncated } = boundedTail(lines, maxChars);
 	const suffix = truncated ? `\n… truncated (${lines.length} lines total)` : "";
 	return { text: `${watch.id} (${statusWord(watch)}) ${label}:\n${body}${suffix}`, truncated };
 }
@@ -199,7 +159,7 @@ export function formatWatchOutcomeLine(watch: WatchRecord, theme: Theme, now = D
 			? paint(theme, "bad", statusWord(watch))
 			: paint(theme, "faint", `${watch.matchCount} match${watch.matchCount === 1 ? "" : "es"}`);
 	return (
-		statusGlyph(watch.status, theme) +
+		paint(theme, statusRole(watch.status), statusGlyphChar(watch.status)) +
 		" " +
 		paint(theme, "accent", watch.id) +
 		" " +

package/extensions/watch/index.ts

@@ -14,10 +14,11 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
 import { WATCH_MATCH_CHANNEL, type WatchMatchEvent } from "../../lib/events.ts";
 import { sanitizeLine } from "../../lib/format.ts";
-import { noticeMessage, type NoticeMessage, pruneStaleNotices } from "../../lib/notice.ts";
-import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
+import { noticeMessage, type NoticeMessage } from "../../lib/notice.ts";
+import { createPendingReporter } from "../../lib/report.ts";
 import { registerCommands } from "./commands.ts";
-import { clipLabel, formatPendingMatch } from "./format.ts";
+import { clipLabel } from "../../lib/tui/columns.ts";
+import { formatPendingMatch } from "./format.ts";
 import { createWatchRuntime, type WatchRuntime } from "./runtime.ts";
 import { registerTools } from "./tools.ts";
 import type { PendingMatch } from "./types.ts";
@@ -62,53 +63,46 @@ export interface WatchDeps {
 export default function watch(pi: ExtensionAPI, deps: WatchDeps = {}): void {
 	if (!isExtensionEnabled("watch")) return;
 	const runtime = deps.runtime ?? createWatchRuntime();
-	let busy = false;
-	let waking = false;
 
-	registerTools(pi, runtime);
-	registerCommands(pi, runtime);
-
-	// Opt-in wake: a `wake` watcher matched while the agent is idle. Report *all*
-	// pending matches, not just the waking one, so a non-wake match is not
-	// silently dropped. `waking` guards the window before `agent_start` fires.
-	const handleMatch = (): void => {
-		if (busy || waking) return;
-		const pending = runtime.pendingMatches();
-		if (pending.length === 0) return;
-		try {
-			pi.sendMessage(watchNotice(pending), { triggerTurn: true });
-			runtime.markReported(pending);
-			waking = true;
-		} catch {
-			// Waking is best-effort; the next turn still reports the matches.
-			return;
-		}
+	// Opt-in wake: a `wake` watcher matched while the agent is idle. The reporter
+	// reports *all* pending matches, not just the waking one, so a non-wake match
+	// is not silently dropped.
+	const reporter = createPendingReporter<PendingMatch>({
+		wake: (notice) => pi.sendMessage(notice, { triggerTurn: true }),
+		pending: () => runtime.pendingMatches(),
+		markReported: (matches) => runtime.markReported(matches),
+		buildNotice: watchNotice,
+		source: "watch",
 		// A wake means the user is away from the terminal, so the alert also leaves
 		// the process. bytefly's notify capability owns delivery; this publishes the
 		// fact and never learns how it is sent. The newest match is the one an alert
 		// is about, while the count covers the whole cycle.
-		const newest = pending[pending.length - 1];
-		if (!newest) return;
-		try {
-			const event: WatchMatchEvent = {
-				count: pending.length,
-				watcherId: newest.watcherId,
-				label: newest.label,
-				line: newest.line,
-			};
-			pi.events.emit(WATCH_MATCH_CHANNEL, event);
-		} catch {
-			// A throwing listener must not cost the wake that already happened.
-		}
-	};
+		onWoke: (matches) => {
+			const newest = matches[matches.length - 1];
+			if (!newest) return;
+			try {
+				const event: WatchMatchEvent = {
+					count: matches.length,
+					watcherId: newest.watcherId,
+					label: newest.label,
+					line: newest.line,
+				};
+				pi.events.emit(WATCH_MATCH_CHANNEL, event);
+			} catch {
+				// A throwing listener must not cost the wake that already happened.
+			}
+		},
+	});
+
+	registerTools(pi, runtime);
+	registerCommands(pi, runtime);
 
 	pi.on("session_start", (_event, ctx) => {
-		busy = false;
-		waking = false;
+		reporter.sessionStart();
 		runtime.load(ctx);
 		// `shutdown` clears this; a reload or session replacement reuses the
 		// runtime, so re-arm it on every session start.
-		runtime.onMatch = handleMatch;
+		runtime.onMatch = () => reporter.report();
 	});
 
 	// Tree navigation does not change the watcher table; only repaint.
@@ -117,37 +111,27 @@ export default function watch(pi: ExtensionAPI, deps: WatchDeps = {}): void {
 	});
 
 	pi.on("agent_start", () => {
-		busy = true;
+		reporter.agentStart();
 	});
 	pi.on("agent_settled", () => {
-		busy = false;
-		waking = false;
+		reporter.agentSettled();
 	});
 
 	// Report matches to the model at the start of the next turn.
 	pi.on("before_agent_start", (_event, ctx) => {
-		const pending = runtime.pendingMatches();
-		if (pending.length === 0) return undefined;
-		runtime.markReported(pending);
+		const reported = reporter.beforeAgentStart();
+		if (!reported) return undefined;
 		runtime.setStatus(ctx);
-		return { message: watchNotice(pending) };
+		return reported;
 	});
 
 	// Keep stale match notices out of later turns. Only this extension's notices
 	// are pruned; another source's are left for its own handler.
-	pi.on("context", (event) => {
-		const pruned = pruneStaleNotices(event.messages, "watch");
-		return pruned ? { messages: pruned } : undefined;
-	});
+	pi.on("context", (event) => reporter.filterContext(event.messages));
 
-	pi.on("session_shutdown", async (_event, ctx) => {
+	// `shutdown` detaches the UI controller, which clears both chips.
+	pi.on("session_shutdown", async () => {
 		runtime.onMatch = undefined;
 		await runtime.shutdown();
-		try {
-			ctx.ui.setStatus(STATUS_KEYS.watch, undefined);
-			ctx.ui.setStatus(STATUS_KEYS.watchMatches, undefined);
-		} catch {
-			// UI may already be gone.
-		}
 	});
 }