repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/activity/runtime.ts
Rawimport { 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<typeof setTimeout>;
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<Waiter>;
child?: ChildProcess;
killer?: ChildProcess;
treeKillSucceeded?: boolean;
terminal?: TerminalHandle;
watcher?: FSWatcher;
lifetime?: ReturnType<typeof setTimeout>;
escalation?: ReturnType<typeof setTimeout>;
tick?: ReturnType<typeof setTimeout>;
coalesce?: ReturnType<typeof setTimeout>;
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<string, Record>();
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<Promise<void>>();
constructor(onEvent?: (id: string, event: ActivityEvent) => void) {
this.#onEvent = onEvent;
}
async start(spec: ActivityStart, cwd: string): Promise<ActivitySnapshot> {
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<ActivitySnapshot> {
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<ActivitySnapshot> {
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<ActivitySnapshot>((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<void> {
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<void>((resolve) =>
child.once("close", () => resolve()),
);
this.#terminateProcess(record);
const boundedCleanup = new Promise<void>((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<void> {
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<ActivityStart, { kind: "watch" }>,
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<ActivityStart, { kind: "timer" }>,
): 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);
}
}