import { type ChildProcess, spawn } from "node:child_process"; import { randomUUID } from "node:crypto"; import { type FSWatcher, watch } from "node:fs"; import { join, resolve } from "node:path"; import { StringDecoder } from "node:string_decoder"; import type { ActivityEvent, ActivitySnapshot, ActivityStart, ActivityStatus, ProcessStart, TerminalHandle, TerminalScreen, } from "./types.ts"; const MAX_ACTIVE = 8; const MAX_RETAINED = 32; const MAX_INPUT_BYTES = 64 * 1024; const MAX_OUTPUT_BYTES = 64 * 1024; const MAX_READ_BYTES = 16 * 1024; const MAX_EVENTS = 32; const MAX_EVENT_TEXT = 256; const DEFAULT_LIFETIME_MS = 60 * 60 * 1000; const MAX_LIFETIME_MS = 24 * 60 * 60 * 1000; const MAX_DELAY_MS = 24 * 60 * 60 * 1000; const MIN_REPEAT_MS = 1000; const COALESCE_MS = 100; type Waiter = { after: number; resolve: (snapshot: ActivitySnapshot) => void; reject: (error: Error) => void; timer?: ReturnType; signal?: AbortSignal; abort?: () => void; }; type Record = { id: string; spec: ActivityStart; title: string; createdAt: number; status: ActivityStatus; sequence: number; notify: boolean; pid?: number; exitCode?: number | null; error?: string; terminationWarning?: string; output: Buffer[]; outputBytes: number; outputTruncated: boolean; events: ActivityEvent[]; eventsTruncated: boolean; waiters: Set; child?: ChildProcess; killer?: ChildProcess; treeKillSucceeded?: boolean; terminal?: TerminalHandle; watcher?: FSWatcher; lifetime?: ReturnType; escalation?: ReturnType; tick?: ReturnType; coalesce?: ReturnType; pendingOutput: string; pendingChange: string; matchTail: string; matchSeen: boolean; acknowledged?: true; screen?: TerminalScreen; }; function boundedText(value: string, bytes: number): string { const data = Buffer.from(value); if (data.byteLength <= bytes) return value; let end = bytes; while (end > 0 && (data[end] & 0xc0) === 0x80) end--; return data.subarray(0, end).toString("utf8"); } function boundedTail( chunks: Buffer[], bytes: number, ): { text: string; truncated: boolean } { let used = 0; const kept: Buffer[] = []; for (let index = chunks.length - 1; index >= 0 && used < bytes; index -= 1) { const chunk = chunks[index]; const room = bytes - used; if (chunk.byteLength <= room) { kept.unshift(chunk); used += chunk.byteLength; } else { let start = chunk.byteLength - room; while (start < chunk.byteLength && (chunk[start] & 0xc0) === 0x80) start += 1; const tail = chunk.subarray(start); kept.unshift(tail); used += tail.byteLength; break; } } return { text: Buffer.concat(kept, used).toString("utf8"), truncated: chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0) > used, }; } function isTerminal(status: ActivityStatus): boolean { return status === "completed" || status === "failed" || status === "stopped"; } function activityError(message: string): Error { return new Error(`Activity: ${message}`); } export class ActivityManager { readonly #records = new Map(); readonly #listeners = new Set<() => void>(); readonly #onEvent?: (id: string, event: ActivityEvent) => void; readonly #prefix = randomUUID().slice(0, 8); #nextId = 1; #disposed = false; readonly #openings = new Set>(); constructor(onEvent?: (id: string, event: ActivityEvent) => void) { this.#onEvent = onEvent; } async start(spec: ActivityStart, cwd: string): Promise { if (this.#disposed) throw activityError("manager is disposed"); this.#validate(spec); if (this.#activeCount() >= MAX_ACTIVE) throw activityError(`maximum ${MAX_ACTIVE} active activities`); const now = Date.now(); const record: Record = { id: `activity-${this.#prefix}-${this.#nextId++}`, spec, title: boundedText(spec.title?.trim() || this.#defaultTitle(spec), 256), createdAt: now, status: "running", sequence: 0, notify: spec.notify === true, output: [], outputBytes: 0, outputTruncated: false, events: [], eventsTruncated: false, waiters: new Set(), pendingOutput: "", pendingChange: "", matchTail: "", matchSeen: false, }; this.#records.set(record.id, record); this.#armLifetime(record); this.#publish(record); try { if (spec.kind === "process") this.#startProcess(record, spec, cwd); else if (spec.kind === "watch") this.#startWatch(record, spec, cwd); else if (spec.kind === "timer") this.#startTimer(record, spec); else { const opening = this.#startTerminal(record, spec, cwd); this.#openings.add(opening); try { await opening; } finally { this.#openings.delete(opening); } } } catch (error) { this.#finish(record, "failed", undefined, this.#message(error)); } return this.#snapshot(record, false); } list(): ActivitySnapshot[] { return [...this.#records.values()].map((record) => this.#snapshot(record, false), ); } read(id: string): ActivitySnapshot { return this.#snapshot(this.#record(id), true); } /** Active work plus failures the human has not acknowledged. */ attention(): ActivitySnapshot[] { return [...this.#records.values()] .filter( (record) => !isTerminal(record.status) || (record.status === "failed" && !record.acknowledged), ) .map((record) => this.#snapshot(record, false)); } /** Hide finished work from attention; active work and unknown IDs are ignored. */ acknowledge(id: string): void { const record = this.#records.get(id); if (!record || !isTerminal(record.status) || record.acknowledged) return; record.acknowledged = true; this.#publish(record); } terminalView(id: string): import("./view.js").TerminalView | undefined { return this.#record(id).terminal?.view(); } timerView(id: string): import("./types.js").TimerView | undefined { const record = this.#record(id); if (record.spec.kind !== "timer") return undefined; const lastTick = record.events.findLast((event) => event.type === "tick"); return { delayMs: record.spec.delayMs, repeat: record.spec.repeat === true, nextAt: (lastTick?.time ?? record.createdAt) + record.spec.delayMs, }; } write(id: string, text: string, paste = false, keyboard = false): void { const record = this.#record(id); if (record.status !== "running") throw activityError("activity is not running"); if (Buffer.byteLength(text) > MAX_INPUT_BYTES) throw activityError("input exceeds 64 KiB"); if (!record.terminal) throw activityError("activity does not accept input"); if (paste) record.terminal.paste(text); else record.terminal.write(text, keyboard); } resize(id: string, cols: number, rows: number): void { const record = this.#record(id); if ( !Number.isInteger(cols) || !Number.isInteger(rows) || cols < 20 || rows < 5 || cols > 200 || rows > 60 ) throw activityError("invalid terminal dimensions"); if (!record.terminal) throw activityError("activity is not a terminal"); record.terminal.resize(cols, rows); record.screen = record.terminal.screen(); this.#publish(record); } async stop(id: string): Promise { const record = this.#record(id); if (isTerminal(record.status)) return this.#snapshot(record, true); if (record.status === "running") { record.status = "stopping"; this.#event(record, "stop"); } if (record.watcher) this.#finish(record, "stopped"); else if (record.tick) this.#finish(record, "stopped"); else if (record.spec.kind === "terminal" && !record.terminal) this.#finish(record, "stopped"); else if (record.terminal) { try { if (!(await record.terminal.stop())) { record.error = "Termination requested but not confirmed."; this.#publish(record); } } catch (error) { record.error = boundedText(this.#message(error), 1024); this.#publish(record); } } else this.#terminateProcess(record); return this.#snapshot(record, true); } async wait( id: string, after: number, timeoutMs: number, signal?: AbortSignal, ): Promise { const record = this.#record(id); if (!Number.isSafeInteger(after) || after < 0) throw activityError("invalid sequence"); if ( !Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > MAX_LIFETIME_MS ) throw activityError("invalid wait timeout"); if (signal?.aborted) throw new DOMException("Aborted", "AbortError"); if (record.sequence > after || isTerminal(record.status)) return this.#snapshot(record, true); return new Promise((resolve, reject) => { const waiter: Waiter = { after, resolve, reject, signal }; waiter.timer = setTimeout(() => { this.#removeWaiter(record, waiter); resolve(this.#snapshot(record, true)); }, timeoutMs); waiter.timer.unref?.(); if (signal) { waiter.abort = () => { this.#removeWaiter(record, waiter); reject(new DOMException("Aborted", "AbortError")); }; signal.addEventListener("abort", waiter.abort, { once: true }); } record.waiters.add(waiter); }); } subscribe(listener: () => void): () => void { if (this.#disposed) return () => {}; this.#listeners.add(listener); return () => this.#listeners.delete(listener); } async dispose(): Promise { if (this.#disposed) return; this.#disposed = true; this.#listeners.clear(); const cleanup = [...this.#records.values()].map(async (record) => { if (!isTerminal(record.status)) record.status = "stopping"; for (const waiter of record.waiters) this.#rejectWaiter(record, waiter, activityError("manager disposed")); this.#clearTimers(record); try { record.watcher?.close(); if (record.terminal) await record.terminal.dispose(); else if (record.child && !isTerminal(record.status)) { const child = record.child; const closed = new Promise((resolve) => child.once("close", () => resolve()), ); this.#terminateProcess(record); const boundedCleanup = new Promise((resolve) => { const timer = setTimeout(resolve, 1_500); timer.unref?.(); }); await Promise.race([closed, boundedCleanup]); } } catch { // Disposal is best-effort and must not create unhandled failures. } }); await Promise.allSettled([...cleanup, ...this.#openings]); } #startProcess(record: Record, spec: ProcessStart, cwd: string): void { const child = spawn(spec.command, spec.args ?? [], { cwd: spec.cwd ? resolve(cwd, spec.cwd) : cwd, detached: process.platform !== "win32", shell: false, stdio: ["ignore", "pipe", "pipe"], }); record.child = child; record.pid = child.pid; const stdout = new StringDecoder("utf8"); const stderr = new StringDecoder("utf8"); child.stdout.on("data", (chunk: Buffer) => this.#output(record, stdout.write(chunk), "stdout"), ); child.stderr.on("data", (chunk: Buffer) => this.#output(record, stderr.write(chunk), "stderr"), ); child.once("error", (error) => this.#finish(record, "failed", undefined, this.#message(error)), ); child.once("close", (code, signal) => { this.#output(record, stdout.end(), "stdout"); this.#output(record, stderr.end(), "stderr"); this.#flushOutput(record); if (!isTerminal(record.status)) this.#finish( record, record.status === "stopping" ? "stopped" : code === 0 ? "completed" : "failed", code, signal && record.status !== "stopping" ? `Process exited from signal ${signal}.` : undefined, ); }); this.#publish(record); } async #startTerminal( record: Record, spec: ProcessStart, cwd: string, ): Promise { const { openTerminal } = await import("./terminal.ts"); if (this.#disposed || record.status !== "running") return; const handle = await openTerminal( spec, spec.cwd ? resolve(cwd, spec.cwd) : cwd, { data: (text) => this.#output(record, text), changed: () => this.#publish(record), exit: (code, error) => { if (record.terminal) record.screen = record.terminal.screen(); this.#refreshTerminalPid(record); this.#flushOutput(record); this.#finish( record, record.status === "stopping" ? "stopped" : error ? "failed" : code === 0 ? "completed" : "failed", code, error, ); }, }, ); if (this.#disposed || record.status !== "running") { record.screen = handle.screen(); await handle.dispose(); const pid = handle.pid; if (typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0) record.pid = pid; return; } record.terminal = handle; this.#refreshTerminalPid(record); record.screen = handle.screen(); this.#publish(record); } #startWatch( record: Record, spec: Extract, cwd: string, ): void { const path = resolve(cwd, spec.path); const watcher = watch(path, { recursive: false }, (eventType, filename) => { if (record.status !== "running") return; record.pendingChange = boundedText( `${eventType}${filename ? ` ${filename.toString()}` : ""}`, MAX_EVENT_TEXT, ); this.#scheduleCoalesce(record); }); record.watcher = watcher; watcher.once("error", (error) => this.#finish(record, "failed", undefined, this.#message(error)), ); } #startTimer( record: Record, spec: Extract, ): void { const fire = (): void => { this.#event(record, "tick"); if (!spec.repeat) this.#finish(record, "completed"); }; if (spec.repeat) { record.tick = setInterval(fire, spec.delayMs); record.tick.unref?.(); } else { record.tick = setTimeout(fire, spec.delayMs); record.tick.unref?.(); } } #output(record: Record, text: string, channel?: "stdout" | "stderr"): void { if (!text || isTerminal(record.status)) return; const spec = record.spec; if ( (spec.kind === "process" || spec.kind === "terminal") && spec.match && !record.matchSeen ) { const observed = record.matchTail + text; if (observed.includes(spec.match)) { record.matchSeen = true; record.matchTail = ""; this.#event(record, "match", "Literal output condition matched."); if (spec.stopOnMatch) void this.stop(record.id); } else record.matchTail = spec.match.length > 1 ? observed.slice(1 - spec.match.length) : ""; } const labelled = channel ? `[${channel}] ${text}` : text; let data = Buffer.from(labelled); if (data.byteLength > MAX_OUTPUT_BYTES) { let start = data.byteLength - MAX_OUTPUT_BYTES; while (start < data.byteLength && (data[start] & 0xc0) === 0x80) start += 1; data = data.subarray(start); record.output = []; record.outputBytes = 0; record.outputTruncated = true; } record.output.push(data); record.outputBytes += data.byteLength; if (record.output.length > 128) { const merged = Buffer.concat(record.output.splice(0, 64)); record.output.unshift(merged); } while (record.outputBytes > MAX_OUTPUT_BYTES && record.output.length > 0) { const first = record.output[0]; const excess = record.outputBytes - MAX_OUTPUT_BYTES; if (first.byteLength <= excess) { record.output.shift(); record.outputBytes -= first.byteLength; } else { let cut = excess; while (cut < first.byteLength && (first[cut] & 0xc0) === 0x80) cut++; record.output[0] = first.subarray(cut); record.outputBytes -= cut; } record.outputTruncated = true; } record.pendingOutput = boundedText( record.pendingOutput + boundedText(labelled, MAX_EVENT_TEXT), MAX_EVENT_TEXT, ); this.#scheduleCoalesce(record); } #scheduleCoalesce(record: Record): void { if (record.coalesce) return; record.coalesce = setTimeout(() => { record.coalesce = undefined; this.#flushOutput(record); if (record.pendingChange) { const text = record.pendingChange; record.pendingChange = ""; this.#event(record, "change", text); } }, COALESCE_MS); record.coalesce.unref?.(); } #flushOutput(record: Record): void { if (!record.pendingOutput) return; const text = record.pendingOutput; record.pendingOutput = ""; this.#event(record, "output", text); } #terminateProcess(record: Record): void { const child = record.child; if ( !child || isTerminal(record.status) || !child.pid || record.escalation || record.killer || record.treeKillSucceeded ) return; if ( process.platform === "win32" && (child.exitCode !== null || child.signalCode !== null) ) { record.terminationWarning = "Process leader exited; descendant termination cannot be confirmed. Skipped taskkill to avoid targeting a reused PID."; record.error = record.terminationWarning; this.#publish(record); return; } let fallbackSent = false; const fallback = (): void => { if (fallbackSent) return; fallbackSent = true; if (process.platform === "win32") { record.terminationWarning = "taskkill could not confirm descendant termination; requested termination of process leader only."; record.error = record.terminationWarning; this.#publish(record); } try { child.kill(); } catch {} }; try { if (process.platform === "win32") { const killer = spawn( join( process.env["SystemRoot"] ?? "C:\\Windows", "System32", "taskkill.exe", ), ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true, timeout: 1000 }, ); record.killer = killer; killer.once("error", fallback); killer.once("close", (code) => { record.killer = undefined; if (code !== 0) fallback(); else { record.treeKillSucceeded = true; if (record.escalation) clearTimeout(record.escalation); record.escalation = undefined; if (record.error === record.terminationWarning) record.error = undefined; record.terminationWarning = undefined; this.#publish(record); } }); killer.unref(); } else { process.kill(-child.pid, "SIGTERM"); record.terminationWarning = undefined; } } catch { fallback(); } record.escalation = setTimeout(() => { record.escalation = undefined; if (isTerminal(record.status)) return; if (process.platform === "win32") { fallback(); return; } try { if (process.platform !== "win32" && child.pid) process.kill(-child.pid, "SIGKILL"); else child.kill("SIGKILL"); } catch {} }, 1000); record.escalation.unref?.(); } #finish( record: Record, status: ActivityStatus, code?: number | null, error?: string, ): void { if (isTerminal(record.status)) return; record.status = status; record.exitCode = code; record.error = error ? boundedText(error, 1024) : record.terminationWarning; this.#clearTimers(record); try { record.watcher?.close(); } catch {} this.#refreshTerminalPid(record); const handle = record.terminal; if (handle) { record.screen = handle.screen(); record.terminal = undefined; void handle.dispose().catch(() => {}); } const type = error ? "error" : "exit"; this.#event(record, type, error); this.#trimRetained(); } #event(record: Record, type: ActivityEvent["type"], text?: string): void { const event: ActivityEvent = { sequence: ++record.sequence, type, time: Date.now(), ...(text ? { text: boundedText(text, MAX_EVENT_TEXT) } : {}), }; if (record.events.length === MAX_EVENTS) { record.events.shift(); record.eventsTruncated = true; } record.events.push(event); try { if (!this.#disposed) this.#onEvent?.(record.id, event); } catch {} this.#publish(record); } #publish(record: Record): void { for (const waiter of record.waiters) if (record.sequence > waiter.after || isTerminal(record.status)) this.#resolveWaiter(record, waiter); for (const listener of this.#listeners) try { listener(); } catch {} } #removeWaiter(record: Record, waiter: Waiter): void { record.waiters.delete(waiter); if (waiter.timer) clearTimeout(waiter.timer); if (waiter.signal && waiter.abort) waiter.signal.removeEventListener("abort", waiter.abort); } #resolveWaiter(record: Record, waiter: Waiter): void { this.#removeWaiter(record, waiter); waiter.resolve(this.#snapshot(record, true)); } #rejectWaiter(record: Record, waiter: Waiter, error: Error): void { this.#removeWaiter(record, waiter); waiter.reject(error); } #snapshot(record: Record, includeDetails: boolean): ActivitySnapshot { this.#refreshTerminalPid(record); const snapshot: ActivitySnapshot = { id: record.id, kind: record.spec.kind, title: record.title, status: record.status, notify: record.notify, createdAt: record.createdAt, sequence: record.sequence, ...(record.pid === undefined ? {} : { pid: record.pid }), ...(record.exitCode === undefined ? {} : { exitCode: record.exitCode }), ...(record.error ? { error: record.error } : {}), }; if (!includeDetails) return snapshot; const output = boundedTail(record.output, MAX_READ_BYTES); const screen = record.terminal?.screen() ?? record.screen; return { ...snapshot, output: output.text, outputTruncated: record.outputTruncated || output.truncated, ...(screen ? { screen: { ...screen } } : {}), events: record.events.map((event) => ({ ...event })), eventsTruncated: record.eventsTruncated, }; } #refreshTerminalPid(record: Record): void { const pid = record.terminal?.pid; if (typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0) record.pid = pid; } #record(id: string): Record { const record = this.#records.get(id); if (!record) throw activityError("unknown activity"); return record; } #armLifetime(record: Record): void { const spec = record.spec; const timeout = spec.timeoutMs ?? (spec.kind === "timer" && !spec.repeat ? undefined : DEFAULT_LIFETIME_MS); if (timeout === undefined) return; record.lifetime = setTimeout(() => { this.#event(record, "stop", "Activity lifetime expired."); void this.stop(record.id); }, timeout); record.lifetime.unref?.(); } #clearTimers(record: Record): void { if (record.lifetime) clearTimeout(record.lifetime); if (record.escalation) clearTimeout(record.escalation); if (record.tick) { clearTimeout(record.tick); clearInterval(record.tick); } if (record.coalesce) clearTimeout(record.coalesce); record.lifetime = undefined; record.escalation = undefined; record.tick = undefined; record.coalesce = undefined; } #trimRetained(): void { const completed = [...this.#records.values()].filter((record) => isTerminal(record.status), ); while (completed.length > MAX_RETAINED) { const record = completed.shift(); if (!record) break; this.#records.delete(record.id); } } #activeCount(): number { let count = 0; for (const record of this.#records.values()) if (!isTerminal(record.status)) count += 1; return count; } #validate(spec: ActivityStart): void { if ( spec.timeoutMs !== undefined && (!Number.isFinite(spec.timeoutMs) || spec.timeoutMs < 1 || spec.timeoutMs > MAX_LIFETIME_MS) ) throw activityError("timeout must be 1 ms through 24 h"); if (spec.kind === "timer") { if ( !Number.isFinite(spec.delayMs) || spec.delayMs < 10 || spec.delayMs > MAX_DELAY_MS ) throw activityError("timer delay must be 10 ms through 24 h"); if (spec.repeat && spec.delayMs < MIN_REPEAT_MS) throw activityError("repeating timer delay must be at least 1000 ms"); return; } if (spec.kind === "watch") { if ( !spec.path || spec.recursive === true || Buffer.byteLength(spec.path) > 4096 ) throw activityError("invalid watch path"); return; } if (spec.match !== undefined && (!spec.match || spec.match.length > 256)) throw activityError("output match must be 1–256 characters"); if (spec.stopOnMatch && !spec.match) throw activityError("stopOnMatch requires an output match"); if ( !spec.command || Buffer.byteLength(spec.command) > 4096 || (spec.args?.length ?? 0) > 128 || (spec.args ?? []).some((arg) => Buffer.byteLength(arg) > 4096) || Buffer.byteLength((spec.args ?? []).join("\0")) > 16 * 1024 ) throw activityError("invalid command or arguments"); } #defaultTitle(spec: ActivityStart): string { if (spec.kind === "timer") return spec.repeat ? "repeating timer" : "timer"; if (spec.kind === "watch") return `watch ${spec.path}`; return [spec.command, ...(spec.args ?? [])].join(" "); } #message(error: unknown): string { return error instanceof Error ? error.message : String(error); } }