gentle-pi 3.7.0 → 4.1.0

package/lib/notification-scheduler.ts

@@ -0,0 +1,173 @@
+import {
+	NOTIFICATION_PRIORITY, notificationSoundFor,
+	type NotificationEvent, type NotificationSettings, type NotificationSound,
+} from "./notification-policy.ts";
+
+export const NOTIFICATION_TTL_MS = 2000;
+export const NOTIFICATION_DEDUPE_CAPACITY = 256;
+export interface NotificationOccurrence {
+	sessionId: string;
+	/** Run or task identity; sequence identifies the occurrence, not the state name. */
+	runId: string;
+	sequence: number;
+	event: NotificationEvent;
+	/** Same monotonic clock domain as SchedulerOptions.now. */
+	occurredAt: number;
+}
+export interface PlaybackPermit {
+	/** Backend MUST call once, synchronously immediately before spawn, after async detection/validation.
+	 * false means do not spawn. Backend owns bounded playback timeout and must honor abort,
+	 * settling only after its process stops. Resolving early violates serial playback. */
+	start(): boolean;
+}
+export interface SchedulerOptions {
+	now(): number;
+	setTimeout(callback: () => void, delayMs: number): number;
+	clearTimeout(handle: number): void;
+	player(sound: Exclude<NotificationSound, null>, signal: AbortSignal, permit: PlaybackPermit): Promise<void>;
+	/** Local diagnostics only. Exceptions here are contained; at most one report per 5 seconds. */
+	onError?(error: unknown): void;
+	dedupeCapacity?: number;
+}
+interface Pending {
+	sound: Exclude<NotificationSound, null>;
+	priority: number;
+	expiresAt: number;
+	readyAt: number;
+	/** Time spent waiting for started playback does not consume the remaining TTL. */
+	pausedAt?: number;
+}
+interface Active {
+	controller: AbortController;
+	generation: number;
+	started: boolean;
+	expiryTimer?: number;
+}
+/** Owner supplies validated settings and TUI/parent guards (including preview). No IO or backend detection here. */
+export class NotificationScheduler {
+	private settings?: NotificationSettings;
+	private muted = false;
+	private sessionId?: string;
+	private generation = 0;
+	private disposed = false;
+	private pending?: Pending;
+	private active?: Active;
+	private timer?: number;
+	private lastStart = -Infinity;
+	private lastError = -Infinity;
+	private readonly seen = new Set<string>();
+	private readonly capacity: number;
+	private readonly options: SchedulerOptions;
+
+	constructor(options: SchedulerOptions) {
+		this.options = options;
+		this.capacity = options.dedupeCapacity ?? NOTIFICATION_DEDUPE_CAPACITY;
+		if (!Number.isInteger(this.capacity) || this.capacity < 1) throw new RangeError("Invalid dedupe capacity");
+	}
+	configure(settings: NotificationSettings, muted: boolean): void {
+		if (this.disposed) return;
+		this.settings = structuredClone(settings); this.muted = muted;
+		if (!settings.enabled || muted) this.invalidate();
+		else this.schedule();
+	}
+	resetSession(sessionId: string): void {
+		if (this.disposed || this.sessionId === sessionId) return;
+		this.invalidate(); this.sessionId = sessionId; this.seen.clear();
+	}
+	/** Returns accepted-to-coalesce, NOT a promise of playback. Off/muted occurrences are consumed too.
+	 * Selected sound is snapshotted here; priority always comes from the event, not the sound. */
+	enqueue(occurrence: NotificationOccurrence): boolean {
+		if (this.disposed || occurrence.sessionId !== this.sessionId) return false;
+		const key = JSON.stringify([occurrence.sessionId, occurrence.runId, occurrence.sequence]);
+		if (this.seen.has(key)) return false;
+		this.seen.add(key);
+		if (this.seen.size > this.capacity) this.seen.delete(this.seen.values().next().value!);
+		const now = this.options.now();
+		const expiresAt = occurrence.occurredAt + NOTIFICATION_TTL_MS;
+		if (!this.automaticEnabled() || !Number.isFinite(occurrence.occurredAt) || occurrence.occurredAt > now || now >= expiresAt) return false;
+		const sound = notificationSoundFor(this.settings!, occurrence.event);
+		if (sound === null) return false;
+		if (this.pending && this.pending.pausedAt === undefined && now >= this.pending.expiresAt) this.pending = undefined;
+		const priority = NOTIFICATION_PRIORITY[occurrence.event];
+		if (this.pending && priority < this.pending.priority) return false;
+		this.pending = { sound, priority, expiresAt,
+			readyAt: this.pending?.readyAt ?? now + this.settings!.audio.coalesceWindowMs,
+			pausedAt: this.active?.started ? now : undefined };
+		this.schedule(); return true;
+	}
+	/** Explicit, bypasses enabled/mute only. Busy when active OR pending; never flushes autos.
+	 * Preview starts count toward automatic minimum interval, but previews themselves are not throttled. */
+	preview(sound: Exclude<NotificationSound, null>): boolean {
+		if (this.disposed || this.active || this.pending) return false;
+		this.play(sound); return true;
+	}
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true; this.invalidate(); this.seen.clear();
+	}
+	private automaticEnabled(): boolean { return !!this.settings?.enabled && !this.muted && !this.disposed; }
+	private clearTimer(): void {
+		if (this.timer !== undefined) this.options.clearTimeout(this.timer);
+		this.timer = undefined;
+	}
+	private invalidate(): void {
+		this.generation++; this.pending = undefined; this.clearTimer();
+		if (this.active) {
+			this.active.controller.abort();
+			if (this.active.expiryTimer !== undefined) this.options.clearTimeout(this.active.expiryTimer);
+		}
+		// Keep active reservation until backend settles, even after abort. Never overlap an uncooperative backend.
+	}
+	private schedule(): void {
+		this.clearTimer();
+		if (!this.pending || !this.automaticEnabled()) return;
+		const now = this.options.now();
+		if (this.pending.pausedAt !== undefined && !this.active?.started) {
+			this.pending.expiresAt += now - this.pending.pausedAt;
+			this.pending.pausedAt = undefined;
+		}
+		if (this.pending.pausedAt === undefined && now >= this.pending.expiresAt) { this.pending = undefined; return; }
+		if (this.active?.started) {
+			// Backend timeout bounds playback. Keep just one candidate, not an accumulating queue.
+			this.pending.pausedAt ??= now;
+			return;
+		}
+		const due = Math.max(this.pending.readyAt, this.lastStart + this.settings!.audio.minimumIntervalMs);
+		if (!this.active && now >= due) {
+			const pending = this.pending; this.pending = undefined;
+			this.play(pending.sound, pending.expiresAt); return;
+		}
+		const wake = this.active ? this.pending.expiresAt : Math.min(due, this.pending.expiresAt);
+		this.timer = this.options.setTimeout(() => { this.timer = undefined; this.schedule(); }, wake - now);
+	}
+	private play(sound: Exclude<NotificationSound, null>, expiresAt?: number): void {
+		const active: Active = { controller: new AbortController(), generation: this.generation, started: false };
+		this.active = active;
+		const permit: PlaybackPermit = { start: () => {
+			if (this.active !== active || active.started || active.controller.signal.aborted || this.disposed || active.generation !== this.generation
+				|| (expiresAt !== undefined && (!this.automaticEnabled() || this.options.now() >= expiresAt))) return false;
+			active.started = true; this.lastStart = this.options.now();
+			if (active.expiryTimer !== undefined) this.options.clearTimeout(active.expiryTimer);
+			this.schedule(); return true;
+		} };
+		if (expiresAt !== undefined) active.expiryTimer = this.options.setTimeout(() => {
+			if (!active.started) active.controller.abort();
+		}, expiresAt - this.options.now());
+		// Calling synchronously also supports a player that throws before returning its promise.
+		try { Promise.resolve(this.options.player(sound, active.controller.signal, permit))
+			.then(() => this.finish(active), error => { this.report(error, active); this.finish(active); }); }
+		catch (error) { this.report(error, active); this.finish(active); }
+	}
+	private report(error: unknown, active: Active): void {
+		if (active.controller.signal.aborted || active.generation !== this.generation || this.disposed) return;
+		const now = this.options.now();
+		if (now - this.lastError < 5000) return;
+		this.lastError = now;
+		try { this.options.onError?.(error); } catch { /* Diagnostics must not produce unhandled rejections. */ }
+	}
+	private finish(active: Active): void {
+		if (active.expiryTimer !== undefined) this.options.clearTimeout(active.expiryTimer);
+		if (this.active === active) this.active = undefined;
+		this.schedule();
+	}
+}

package/lib/notification-service.ts

@@ -0,0 +1,202 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { NotificationPlayer, validateNotificationAudio } from "./notification-audio.ts";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import {
+	DEFAULT_NOTIFICATION_SETTINGS, NOTIFICATION_EVENTS, isNotificationSettings, isNotificationSound,
+	resolveNotificationSettings, restoreNotificationPreset, writeNotificationSettings,
+	type NotificationOptions, type NotificationResolution, type NotificationSettings, type NotificationSound,
+} from "./notification-policy.ts";
+import { NotificationScheduler, type NotificationOccurrence, type SchedulerOptions } from "./notification-scheduler.ts";
+
+export interface NotificationServiceDependencies {
+	now?: () => number;
+	env?: NodeJS.ProcessEnv;
+	policy?: NotificationOptions;
+	read?: () => NotificationResolution;
+	write?: (settings: NotificationSettings) => string;
+	backend?: Pick<NotificationPlayer, "play" | "availability" | "capabilities">;
+	setTimeout?: SchedulerOptions["setTimeout"];
+	clearTimeout?: SchedulerOptions["clearTimeout"];
+}
+export interface NotificationState extends NotificationResolution {
+	muted: boolean;
+	supportedEvents: readonly NotificationOccurrence["event"][];
+}
+/** UI consumers only retrieve this facade. They never claim a lease or subscribe to events. */
+export interface NotificationService {
+	getState(): NotificationState;
+	setConfig(ctx: ExtensionContext, settings: NotificationSettings, options?: { confirmRecovery?: boolean }): boolean;
+	restorePreset(ctx: ExtensionContext, options?: { confirmRecovery?: boolean }): boolean;
+	setMuted(ctx: ExtensionContext, muted: boolean): boolean;
+	preview(ctx: ExtensionContext, sound: Exclude<NotificationSound, null>): boolean;
+	availability(ctx: ExtensionContext): Promise<"available" | "unavailable">;
+	/** Selection-time validation only; never discovers or starts a player. */
+	validateFile(ctx: ExtensionContext, sound: `file:${string}`): Promise<boolean>;
+}
+interface Holder {
+	muted: boolean;
+	epoch: number;
+	ownerLease?: symbol;
+	retire?: () => void;
+	service?: NotificationService;
+	startupNotified: boolean;
+	sourceSession?: string;
+	highwater: Map<string, number>;
+	/** A retired scheduler's backend must settle before any replacement can play. */
+	playback?: object;
+}
+const HOLDER = Symbol.for("gentle-pi.notification-service.v1");
+function holder(): Holder {
+	const root = globalThis as typeof globalThis & { [HOLDER]?: Holder };
+	return root[HOLDER] ??= { muted: false, epoch: 0, startupNotified: false, highwater: new Map() };
+}
+export function getNotificationService(): NotificationService | undefined { return holder().service; }
+export function notificationContextAllowed(ctx: ExtensionContext, env: NodeJS.ProcessEnv = process.env): boolean {
+	// Dialog-capable interactive RPC is intentionally NOT an audio host.
+	return ctx.mode === "tui" && env.GENTLE_PI_AGENTS_CHILD !== "1";
+}
+
+/** Owner-only claim; factory collision invalidates old hooks before the new owner attaches. */
+export function claimNotificationOwner(retireRuntime: () => void, deps: NotificationServiceDependencies = {}) {
+	const shared = holder(); shared.retire?.();
+	const lease = Symbol("notification-owner"); const epoch = ++shared.epoch;
+	shared.ownerLease = lease;
+	const now = deps.now ?? (() => performance.now());
+	const env = deps.env ?? process.env;
+	const backend = deps.backend ?? new NotificationPlayer();
+	let ctx: ExtensionContext | undefined; let sessionId: string | undefined;
+	let scheduler: NotificationScheduler | undefined; let disposed = false; let attachment = 0;
+	let resolution: NotificationResolution | undefined;
+	const diagnostics = new Set<string>();
+	const current = () => !disposed && shared.ownerLease === lease && shared.epoch === epoch;
+	const allowed = (candidate?: ExtensionContext) => current() && !!ctx && !!candidate
+		&& notificationContextAllowed(candidate, env) && notificationContextAllowed(ctx, env)
+		&& candidate.sessionManager.getSessionId() === sessionId && ctx.sessionManager.getSessionId() === sessionId;
+	const report = (category: string, message: string) => {
+		if (!allowed(ctx) || diagnostics.has(category)) return;
+		diagnostics.add(category);
+		try { ctx!.ui.notify(message, "warning"); } catch { /* Local diagnostics cannot fail a run. */ }
+	};
+	const read = () => {
+		resolution = structuredClone((deps.read ?? (() => resolveNotificationSettings(deps.policy)))());
+		if (resolution.malformed || resolution.readError) {
+			resolution.settings = structuredClone(DEFAULT_NOTIFICATION_SETTINGS);
+			report("config", "Notification configuration unavailable or invalid; audio disabled.");
+		}
+	};
+	const makeScheduler = () => {
+		scheduler = new NotificationScheduler({ now,
+			// SAFETY: scheduler treats this handle as opaque; Node's Timeout is returned unchanged to clearTimeout.
+			setTimeout: deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms) as unknown as number),
+			clearTimeout: deps.clearTimeout ?? (id => clearTimeout(id)),
+			player: async (sound, signal, permit) => {
+				if (!allowed(ctx) || shared.playback || signal.aborted) return;
+				const reservation = {}; shared.playback = reservation;
+				try {
+					const available = await backend.availability();
+					if (signal.aborted || !allowed(ctx)) return;
+					if (available === "unavailable") { report("backend", "Notification audio backend unavailable."); return; }
+					await backend.play(sound, signal, { start: () => allowed(ctx) && permit.start() });
+				} finally { if (shared.playback === reservation) shared.playback = undefined; }
+			},
+			onError: () => report("playback", "Notification audio could not be played."),
+		});
+		scheduler.resetSession(sessionId!); scheduler.configure(resolution!.settings, shared.muted);
+	};
+	const shutdown = () => {
+		scheduler?.dispose(); scheduler = undefined; ctx = undefined; sessionId = undefined;
+		attachment++;
+		if (shared.ownerLease === lease) shared.service = undefined;
+	};
+	const service: NotificationService = {
+		getState: () => ({ ...structuredClone(resolution!), muted: shared.muted,
+			// Quit cannot await lazy detection/playback without delaying cleanup/exit.
+			supportedEvents: NOTIFICATION_EVENTS.filter(event => event !== "session.shutdown") }),
+		setConfig: (candidate, settings, options = {}) => {
+			if (!allowed(candidate) || !resolution || !isNotificationSettings(settings, deps.policy?.pathFlavor)
+				|| ((resolution.malformed || resolution.readError) && options.confirmRecovery !== true)) return false;
+			try {
+				const snapshot = structuredClone(settings);
+				const globalFile = (deps.write ?? (value => writeNotificationSettings(value, deps.policy)))(snapshot);
+				// Invalidate even enabled->enabled changes: pending mappings must not become stale.
+				scheduler?.dispose();
+				resolution = { settings: snapshot, globalFile, source: "global_file", malformed: false, readError: false };
+				makeScheduler(); return true;
+			} catch { report("write", "Notification configuration could not be saved."); return false; }
+		},
+		restorePreset: (candidate, options) => service.setConfig(candidate, restoreNotificationPreset(resolution!.settings), options),
+		setMuted: (candidate, muted) => {
+			if (!allowed(candidate) || typeof muted !== "boolean") return false;
+			shared.muted = muted; scheduler?.configure(resolution!.settings, muted); return true;
+		},
+		preview: (candidate, sound) => allowed(candidate) && !shared.playback && isNotificationSound(sound, deps.policy?.pathFlavor)
+			&& sound !== null && !!scheduler?.preview(sound),
+		validateFile: async (candidate, sound) => {
+			if (!allowed(candidate) || !isNotificationSound(sound) || !sound.startsWith("file:")) return false;
+			const activeScheduler = scheduler;
+			try {
+				const handle = await open(sound.slice(5), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+				try {
+					const stat = await handle.stat();
+					if (!stat.isFile() || stat.size < 44 || stat.size > 2 * 1024 * 1024) return false;
+					const bytes = Buffer.alloc(stat.size + 1);
+					const { bytesRead } = await handle.read(bytes);
+					if (bytesRead !== stat.size) return false;
+					const { format } = validateNotificationAudio(bytes.subarray(0, bytesRead));
+					// Assignment-time rejection: a player that cannot play this container must never receive it.
+					if (format !== "wav" && !(await backend.capabilities()).has(format)) return false;
+					return allowed(candidate) && scheduler === activeScheduler;
+				} finally { await handle.close(); }
+			} catch { return false; }
+		},
+		availability: async candidate => {
+			if (!allowed(candidate)) return "unavailable";
+			const activeScheduler = scheduler;
+			try {
+				const result = await backend.availability();
+				return allowed(candidate) && scheduler === activeScheduler ? result : "unavailable";
+			} catch { return "unavailable"; }
+		},
+	};
+	const bindService = (): NotificationService => {
+		const generation = attachment;
+		const live = () => generation === attachment && current();
+		return {
+			getState: service.getState,
+			setConfig: (candidate, settings, options) => live() && service.setConfig(candidate, settings, options),
+			restorePreset: (candidate, options) => live() && service.restorePreset(candidate, options),
+			setMuted: (candidate, muted) => live() && service.setMuted(candidate, muted),
+			preview: (candidate, sound) => live() && service.preview(candidate, sound),
+			availability: candidate => live() ? service.availability(candidate) : Promise.resolve("unavailable"),
+			validateFile: (candidate, sound) => live() ? service.validateFile(candidate, sound) : Promise.resolve(false),
+		};
+	};
+	const retire = () => {
+		if (disposed) return;
+		shutdown(); disposed = true; retireRuntime();
+		if (shared.ownerLease === lease) { shared.ownerLease = undefined; shared.retire = undefined; }
+	};
+	shared.retire = retire;
+	return { now, current, allowed, shutdown, retire,
+		acceptSource: (producerId: string, runId: string, sequence: number) => {
+			if (!allowed(ctx)) return false;
+			const key = JSON.stringify([producerId, runId]);
+			if (sequence <= (shared.highwater.get(key) ?? 0)) return false;
+			shared.highwater.set(key, sequence); return true;
+		},
+		attach: (candidate: ExtensionContext) => {
+			if (!current()) return false;
+			shutdown();
+			if (!notificationContextAllowed(candidate, env)) return false;
+			ctx = candidate; sessionId = candidate.sessionManager.getSessionId();
+			if (shared.sourceSession !== sessionId) { shared.highwater.clear(); shared.sourceSession = sessionId; }
+			read(); makeScheduler(); shared.service = bindService(); return true;
+		},
+		enqueue: (event: NotificationOccurrence) => allowed(ctx) && scheduler?.enqueue(event),
+		startup: () => {
+			if (!allowed(ctx) || shared.startupNotified) return false;
+			shared.startupNotified = true; return true;
+		},
+	};
+}

package/lib/notification-ui.ts

@@ -0,0 +1,87 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_NOTIFICATION_IDS, isNotificationSound, type NotificationEvent, type NotificationSettings, type NotificationSound } from "./notification-policy.ts";
+import { getNotificationService, notificationContextAllowed, type NotificationService } from "./notification-service.ts";
+
+/**
+ * Native dialogs, outside the transcript. No owner creation, commands or visual-store writes.
+ * @deprecated Superseded by the direct rows in `lib/notification-customize.ts`; kept as an
+ * unused test-covered fallback, not wired into `/gentle:customize` anymore.
+ */
+export async function openNotificationPanel(ctx: ExtensionContext): Promise<void> {
+	if (!ctx.hasUI || !notificationContextAllowed(ctx)) return;
+	const fresh = (expected: NotificationService) => {
+		const service = getNotificationService();
+		return service === expected ? service : undefined;
+	};
+	const notify = (message: string, error = false) => ctx.ui.notify(message, error ? "warning" : "info");
+	const chooseSound = async (expected: NotificationService): Promise<NotificationSound | undefined> => {
+		const choice = await ctx.ui.select("Notification sound", ["Silence", ...BUILTIN_NOTIFICATION_IDS.map(id => `builtin:${id}`), "Local WAV file"]);
+		if (!fresh(expected) || choice === undefined) return undefined;
+		if (choice === "Silence") return null;
+		if (choice !== "Local WAV file") return isNotificationSound(choice) ? choice : undefined;
+		const path = await ctx.ui.input("Local WAV file", "Absolute path (no URLs or shell expansion)");
+		const service = fresh(expected);
+		if (!service || path === undefined) return undefined;
+		const sound = `file:${path}` as const;
+		if (!isNotificationSound(sound) || !await service.validateFile(ctx, sound)) {
+			if (fresh(expected)) notify("Select a readable regular PCM WAV (≤2 MiB, ≤10 seconds); absolute local path only.", true);
+			return undefined;
+		}
+		return fresh(expected) ? sound : undefined;
+	};
+	const save = async (expected: NotificationService, change?: (settings: NotificationSettings) => void) => {
+		let service = fresh(expected);
+		if (!service) return;
+		const state = service.getState();
+		let confirmRecovery = false;
+		if (state.malformed || state.readError) {
+			confirmRecovery = await ctx.ui.confirm("Replace invalid notification configuration?",
+				"The existing configuration is invalid or unreadable. Replace it with these settings? Cancellation leaves it untouched.") === true;
+			if (!confirmRecovery) return;
+		}
+		service = fresh(expected);
+		if (!service) return;
+		// Read again after all prompts: never overwrite another action with an old snapshot.
+		const settings = service.getState().settings;
+		change?.(settings);
+		const saved = change ? service.setConfig(ctx, settings, { confirmRecovery }) : service.restorePreset(ctx, { confirmRecovery });
+		notify(saved ? "Notification preferences saved." : "Notification preferences not saved; choose again to retry.", !saved);
+	};
+	while (true) {
+		const service = getNotificationService();
+		if (!service) return;
+		const state = service.getState();
+		const enable = state.settings.enabled ? "Disable audio" : "Enable audio";
+		const mute = state.muted ? "Resume" : "Mute";
+		const action = await ctx.ui.select(`Notifications · audio ${state.settings.enabled ? "on" : "off"} · ${state.muted ? "muted" : "unmuted"}`,
+			[enable, "Assign sound", "Preview sound", mute, "Check availability", "Restore preset"]);
+		if (!fresh(service) || action === undefined) return;
+		try {
+			if (action === enable) await save(service, settings => { settings.enabled = action === "Enable audio"; });
+			else if (action === mute) fresh(service)?.setMuted(ctx, action === "Mute");
+			else if (action === "Restore preset") await save(service);
+			else if (action === "Check availability") {
+				const result = await fresh(service)!.availability(ctx);
+				if (fresh(service)) notify(`Notification audio backend: ${result}.`);
+			} else if (action === "Preview sound") {
+				const sound = await chooseSound(service);
+				const current = fresh(service);
+				if (current && sound !== undefined && sound !== null && !current.preview(ctx, sound)) notify("Preview unavailable or audio busy; try again.", true);
+			} else if (action === "Assign sound") {
+				const origins = [...new Set(service.getState().supportedEvents.map(event => event.split(".")[0]!))];
+				const origin = await ctx.ui.select("Notification origin", origins);
+				let current = fresh(service);
+				if (!current || origin === undefined || !origins.includes(origin)) continue;
+				const events = current.getState().supportedEvents.filter(event => event.startsWith(`${origin}.`));
+				const event = await ctx.ui.select("Notification event", [...events]);
+				current = fresh(service);
+				if (!current || !events.includes(event as NotificationEvent)) continue;
+				const sound = await chooseSound(service);
+				if (sound !== undefined) await save(service, settings => { settings.audio.events[event as NotificationEvent] = sound; });
+			}
+		} catch {
+			if (fresh(service)) notify("Notification action failed; no automatic retry.", true);
+		}
+		if (!fresh(service)) return;
+	}
+}