Waggle Room is not part of the community edition (decision Q2, ADR-0002). Its headless runs of Claude Code, Codex, Hermes and OpenClaw needed the packaged collaboration CLI from the removed @waggle/hive-mind-cli, so POST /api/tools/run answered 503 collaboration_runtime_missing. - Remove POST /api/tools/run (routes/external-tool-runs.ts) with its Room fan-out, WaggleDance publishing, OpenClaw provisioning and the memory write-back of run results. - Remove runExternalTool (agent/external-tool-runner.ts) and resolveWaggleRuntime; the taskkill path helper moves into the process tracker, its only remaining user. - Launcher: drop the hidden "Run task" composer, the Room hand-off and adapter.runExternalToolTask. Detect, launch, watch and stop stay. - Drop the `room` flag from the memory feature map: it only gated the Launcher task button. - The viewer policy no longer reads participants[].workspaceIds, a body shape only /api/tools/run accepted.
375 lines
13 KiB
TypeScript
375 lines
13 KiB
TypeScript
/**
|
|
* AI-OS Phase 4 polish — in-memory tracker for processes spawned via
|
|
* `launchTool()`.
|
|
*
|
|
* The Launcher Phase 2A/2B path spawns external AI tools detached
|
|
* and returns a PID. Without tracking we have no way to tell whether
|
|
* the process is still running, so the UI cannot render a 'Running'
|
|
* badge or offer a "stop" affordance.
|
|
*
|
|
* Scope:
|
|
* - Optionally persisted. When a `persistPath` (or injected
|
|
* load/save deps) is supplied, the tracker writes a JSON pidfile
|
|
* on every mutation and **reconciles on construction**: it reloads
|
|
* the file, probes each pid's liveness, keeps the survivors, and
|
|
* prunes the dead. This is how a detached tool that outlives a
|
|
* sidecar restart keeps its 'Running' badge / kill affordance.
|
|
* With no persistence configured the tracker is pure in-memory
|
|
* (the original behavior — used by tests).
|
|
* - Liveness check via `process.kill(pid, 0)`. POSIX + Windows
|
|
* both raise on dead PIDs; we catch and return false.
|
|
* - Hermetic via injected `isAlive` / `now` / `loadPersisted` /
|
|
* `savePersisted` deps for testing.
|
|
*
|
|
* Known caveat (PID reuse):
|
|
* Reconciliation can only ask "is *a* process with this pid alive?"
|
|
* — not "is it still *our* tool?". If the OS recycled a dead agent's
|
|
* pid for an unrelated process before restart, that row would render
|
|
* as running. Acceptable for a desktop sidecar (short restart window,
|
|
* loopback-only, kill is gated to tracked pids); revisit with a
|
|
* start-time fingerprint if it ever bites.
|
|
*
|
|
* Out of scope (deferred):
|
|
* - Per-process start-time fingerprinting to defeat pid reuse.
|
|
*/
|
|
|
|
import { execFile } from 'node:child_process';
|
|
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
|
|
const WINDOWS_TREE_KILL_TIMEOUT_MS = 5_000;
|
|
|
|
/** Absolute path to taskkill.exe, so a PATH entry cannot shadow it. */
|
|
export function resolveWindowsTaskkillPath(env: NodeJS.ProcessEnv = process.env): string {
|
|
const candidate = env.SystemRoot ?? env.WINDIR;
|
|
const windowsRoot = candidate && path.win32.isAbsolute(candidate)
|
|
? path.win32.normalize(candidate)
|
|
: 'C:\\Windows';
|
|
return path.win32.join(windowsRoot, 'System32', 'taskkill.exe');
|
|
}
|
|
|
|
export interface TrackedProcess {
|
|
pid: number;
|
|
toolId: string;
|
|
startedAt: string;
|
|
workspaceId?: string;
|
|
/**
|
|
* True for OBSERVED (piped-stdio) launches. These are tethered to the
|
|
* sidecar and cannot survive a restart, so they are tracked in memory only
|
|
* and excluded from the persisted pidfile (see `persist()`).
|
|
*/
|
|
observed?: boolean;
|
|
}
|
|
|
|
export interface ToolProcessTrackerDeps {
|
|
/** Liveness probe; returns true if pid is alive. Production = process.kill(pid, 0). */
|
|
isAlive?: (pid: number) => boolean;
|
|
/** Clock override for deterministic startedAt in tests. */
|
|
now?: () => Date;
|
|
/**
|
|
* Signal sender. Production sends real OS signals via process.kill.
|
|
* Returns true if the signal was delivered, false on ESRCH/EPERM.
|
|
* Tests inject a mock to assert signal payloads without killing the
|
|
* test runner.
|
|
*/
|
|
sendSignal?: (pid: number, signal: NodeJS.Signals | number) => boolean;
|
|
/**
|
|
* Bounded wait helper for the kill flow's SIGTERM-then-SIGKILL
|
|
* escalation. Production = setTimeout-backed Promise.
|
|
*/
|
|
delay?: (ms: number) => Promise<void>;
|
|
/** Platform override for deterministic Windows/POSIX termination tests. */
|
|
platform?: NodeJS.Platform;
|
|
/**
|
|
* Windows process-tree terminator. Production uses bounded, shell-free
|
|
* taskkill.exe /T /F and reports false on spawn, timeout, or exit failure.
|
|
*/
|
|
killTree?: (pid: number) => Promise<boolean>;
|
|
/**
|
|
* Path to the JSON pidfile used for cross-restart persistence. When
|
|
* set (and no explicit load/save override is given), the tracker
|
|
* reads/writes this file. Omit for pure in-memory.
|
|
*/
|
|
persistPath?: string;
|
|
/**
|
|
* Override the persistence reader. Defaults to reading `persistPath`.
|
|
* Tests inject an in-memory store. A corrupt/missing file yields [].
|
|
*/
|
|
loadPersisted?: () => TrackedProcess[];
|
|
/**
|
|
* Override the persistence writer. Defaults to writing `persistPath`
|
|
* (best-effort — never throws into the launch path).
|
|
*/
|
|
savePersisted?: (records: readonly TrackedProcess[]) => void;
|
|
}
|
|
|
|
/** True if `x` is a structurally-valid persisted record (guards a corrupt pidfile). */
|
|
function isTrackedProcess(x: unknown): x is TrackedProcess {
|
|
if (!x || typeof x !== 'object') return false;
|
|
const r = x as Record<string, unknown>;
|
|
return (
|
|
typeof r.pid === 'number' &&
|
|
Number.isInteger(r.pid) &&
|
|
r.pid > 0 &&
|
|
typeof r.toolId === 'string' &&
|
|
typeof r.startedAt === 'string' &&
|
|
(r.workspaceId === undefined || typeof r.workspaceId === 'string') &&
|
|
(r.observed === undefined || typeof r.observed === 'boolean')
|
|
);
|
|
}
|
|
|
|
function defaultLoadPersisted(persistPath: string): TrackedProcess[] {
|
|
try {
|
|
const raw = fs.readFileSync(persistPath, 'utf8');
|
|
const parsed: unknown = JSON.parse(raw);
|
|
if (!Array.isArray(parsed)) return [];
|
|
return parsed.filter(isTrackedProcess);
|
|
} catch {
|
|
// Missing file / parse error → start clean. Persistence is a
|
|
// convenience, never a hard dependency.
|
|
return [];
|
|
}
|
|
}
|
|
|
|
function defaultSavePersisted(persistPath: string, records: readonly TrackedProcess[]): void {
|
|
try {
|
|
fs.mkdirSync(path.dirname(persistPath), { recursive: true });
|
|
fs.writeFileSync(persistPath, JSON.stringify(records, null, 2), 'utf8');
|
|
} catch {
|
|
// Best-effort: a failed write must not break launch/list/kill.
|
|
}
|
|
}
|
|
|
|
function defaultIsAlive(pid: number): boolean {
|
|
// signal 0 = "check existence without sending a signal". POSIX +
|
|
// Windows both throw ESRCH/EPERM/EINVAL on dead/inaccessible pids;
|
|
// we treat ANY throw as "not alive" rather than parse error codes
|
|
// (a foreign-owned pid is also not "ours" to render as running).
|
|
try {
|
|
process.kill(pid, 0);
|
|
return true;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
function defaultSendSignal(pid: number, signal: NodeJS.Signals | number): boolean {
|
|
try {
|
|
process.kill(pid, signal);
|
|
return true;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
function defaultDelay(ms: number): Promise<void> {
|
|
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
}
|
|
|
|
function defaultKillTree(pid: number): Promise<boolean> {
|
|
return new Promise((resolve) => {
|
|
execFile(
|
|
resolveWindowsTaskkillPath(),
|
|
['/PID', String(pid), '/T', '/F'],
|
|
{ timeout: WINDOWS_TREE_KILL_TIMEOUT_MS, windowsHide: true },
|
|
(error) => resolve(error === null),
|
|
);
|
|
});
|
|
}
|
|
|
|
export class ToolProcessTracker {
|
|
private processes: Map<number, TrackedProcess> = new Map();
|
|
private readonly isAlive: (pid: number) => boolean;
|
|
private readonly now: () => Date;
|
|
private readonly sendSignal: (pid: number, signal: NodeJS.Signals | number) => boolean;
|
|
private readonly delay: (ms: number) => Promise<void>;
|
|
private readonly platform: NodeJS.Platform;
|
|
private readonly killTree: (pid: number) => Promise<boolean>;
|
|
/** Whether persistence is configured (persistPath or injected load/save). */
|
|
private readonly persists: boolean;
|
|
private readonly loadPersisted: () => TrackedProcess[];
|
|
private readonly savePersisted: (records: readonly TrackedProcess[]) => void;
|
|
|
|
constructor(deps: ToolProcessTrackerDeps = {}) {
|
|
this.isAlive = deps.isAlive ?? defaultIsAlive;
|
|
this.now = deps.now ?? (() => new Date());
|
|
this.sendSignal = deps.sendSignal ?? defaultSendSignal;
|
|
this.delay = deps.delay ?? defaultDelay;
|
|
this.platform = deps.platform ?? process.platform;
|
|
this.killTree = deps.killTree ?? defaultKillTree;
|
|
|
|
this.persists = Boolean(deps.persistPath || deps.loadPersisted || deps.savePersisted);
|
|
const persistPath = deps.persistPath;
|
|
this.loadPersisted =
|
|
deps.loadPersisted ?? (persistPath ? () => defaultLoadPersisted(persistPath) : () => []);
|
|
this.savePersisted =
|
|
deps.savePersisted ?? (persistPath ? (r) => defaultSavePersisted(persistPath, r) : () => {});
|
|
|
|
if (this.persists) this.reconcile();
|
|
}
|
|
|
|
/**
|
|
* Boot reconciliation: reload persisted pids, keep the ones still
|
|
* alive, drop the dead, and rewrite the file iff we actually pruned
|
|
* (so a fresh/empty store never triggers an eager write).
|
|
*/
|
|
private reconcile(): void {
|
|
const persisted = this.loadPersisted();
|
|
for (const rec of persisted) {
|
|
if (this.isAlive(rec.pid)) this.processes.set(rec.pid, rec);
|
|
}
|
|
if (persisted.length !== this.processes.size) this.persist();
|
|
}
|
|
|
|
/**
|
|
* Write the current snapshot to the store when persistence is on. Observed
|
|
* (tethered) processes are excluded — they cannot survive a restart, so
|
|
* persisting them would risk a stale 'Running' badge / pid-reuse false
|
|
* positive on the next boot reconcile.
|
|
*/
|
|
private persist(): void {
|
|
if (this.persists) {
|
|
this.savePersisted(
|
|
Array.from(this.processes.values()).filter((p) => !p.observed),
|
|
);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Register a freshly-spawned process. Returns the tracked record
|
|
* (useful for chaining or echoing back in the route response).
|
|
* Idempotent on pid — re-registering replaces the prior entry.
|
|
*/
|
|
register(
|
|
pid: number,
|
|
toolId: string,
|
|
workspaceId?: string,
|
|
opts?: { observed?: boolean },
|
|
): TrackedProcess {
|
|
const record: TrackedProcess = {
|
|
pid,
|
|
toolId,
|
|
startedAt: this.now().toISOString(),
|
|
...(workspaceId !== undefined ? { workspaceId } : {}),
|
|
...(opts?.observed ? { observed: true } : {}),
|
|
};
|
|
this.processes.set(pid, record);
|
|
this.persist();
|
|
return record;
|
|
}
|
|
|
|
/**
|
|
* Return the list of currently-tracked-and-alive processes.
|
|
* Garbage-collects dead pids as a side effect so subsequent
|
|
* calls don't re-probe them.
|
|
*/
|
|
list(): TrackedProcess[] {
|
|
let pruned = false;
|
|
for (const pid of Array.from(this.processes.keys())) {
|
|
if (!this.isAlive(pid)) {
|
|
this.processes.delete(pid);
|
|
pruned = true;
|
|
}
|
|
}
|
|
if (pruned) this.persist();
|
|
return Array.from(this.processes.values());
|
|
}
|
|
|
|
/** Drop a pid (e.g. after a successful explicit stop). */
|
|
forget(pid: number): boolean {
|
|
const deleted = this.processes.delete(pid);
|
|
if (deleted) this.persist();
|
|
return deleted;
|
|
}
|
|
|
|
/**
|
|
* Attempt to stop a tracked process. Windows uses bounded taskkill /T /F
|
|
* so success covers the full descendant tree; POSIX uses SIGTERM and then
|
|
* escalates to SIGKILL after `gracefulTimeoutMs`. Returns a structured
|
|
* result so the route layer can surface honest UX.
|
|
*
|
|
* Refuses to kill a pid we don't track — this guards against the
|
|
* UI accidentally sending an arbitrary OS pid (e.g. from URL
|
|
* tampering) and nuking the user's editor.
|
|
*/
|
|
async kill(
|
|
pid: number,
|
|
gracefulTimeoutMs: number = 3000,
|
|
): Promise<{
|
|
ok: boolean;
|
|
pid: number;
|
|
reason:
|
|
| 'not-tracked'
|
|
| 'already-dead'
|
|
| 'tree-cleanup-unverified'
|
|
| 'tree-kill-ok'
|
|
| 'tree-kill-failed'
|
|
| 'sigterm-ok'
|
|
| 'sigkill-ok'
|
|
| 'sigterm-failed-sigkill-failed';
|
|
}> {
|
|
if (!this.processes.has(pid)) {
|
|
return { ok: false, pid, reason: 'not-tracked' };
|
|
}
|
|
if (!this.isAlive(pid)) {
|
|
if (this.platform === 'win32') {
|
|
return { ok: false, pid, reason: 'tree-cleanup-unverified' };
|
|
}
|
|
// Already gone — GC the entry and report success.
|
|
this.processes.delete(pid);
|
|
this.persist();
|
|
return { ok: true, pid, reason: 'already-dead' };
|
|
}
|
|
if (this.platform === 'win32') {
|
|
let treeKilled = false;
|
|
try {
|
|
treeKilled = await this.killTree(pid);
|
|
} catch {
|
|
treeKilled = false;
|
|
}
|
|
if (treeKilled) {
|
|
await this.delay(50);
|
|
if (!this.isAlive(pid)) {
|
|
this.processes.delete(pid);
|
|
this.persist();
|
|
return { ok: true, pid, reason: 'tree-kill-ok' };
|
|
}
|
|
}
|
|
return { ok: false, pid, reason: 'tree-kill-failed' };
|
|
}
|
|
// Best effort: SIGTERM first so the child can clean up.
|
|
const termSent = this.sendSignal(pid, 'SIGTERM');
|
|
if (termSent) {
|
|
await this.delay(gracefulTimeoutMs);
|
|
if (!this.isAlive(pid)) {
|
|
this.processes.delete(pid);
|
|
this.persist();
|
|
return { ok: true, pid, reason: 'sigterm-ok' };
|
|
}
|
|
}
|
|
// Escalate to SIGKILL.
|
|
const killSent = this.sendSignal(pid, 'SIGKILL');
|
|
if (killSent && !this.isAlive(pid)) {
|
|
this.processes.delete(pid);
|
|
this.persist();
|
|
return { ok: true, pid, reason: 'sigkill-ok' };
|
|
}
|
|
return {
|
|
ok: false,
|
|
pid,
|
|
reason: 'sigterm-failed-sigkill-failed',
|
|
};
|
|
}
|
|
|
|
/** Total processes currently tracked (alive or not — call list() to GC). */
|
|
get size(): number {
|
|
return this.processes.size;
|
|
}
|
|
|
|
/** Clear all tracked processes. Used in tests. */
|
|
clear(): void {
|
|
this.processes.clear();
|
|
this.persist();
|
|
}
|
|
}
|