@slack/radar-mcp 1.8.0 → 1.9.1

package/dist/shared/event-spool.js

@@ -0,0 +1,366 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+/**
+ * Appends every streamed SSE frame (network, rtm, clog, log, trace) to a
+ * per-session file so the full session record survives buffer eviction. The
+ * device rings and the host push ring both drop the oldest entry once full, so
+ * a long session loses its early events; the spool keeps the whole session. It
+ * does not replace the rings. The device ring stays the source of truth: it
+ * holds full payloads for detail and search, carries history from before the
+ * host connected, and serves the dashboard and every /api endpoint. This spool
+ * is a downstream summary log.
+ *
+ * It captures every frame delivered to the host, not every frame the device
+ * produced. Frames dropped during a transient device reconnect (callRadar tears
+ * the stream down and reconnects) never reach bufferEvent, so they are not
+ * spooled. Capture starts when the stream connects; there is no device backfill.
+ *
+ * A profile switch mid-session (activate_for_user) keeps appending to the same
+ * file, so two profiles' frames merge with no per-frame profile tag. Fine while
+ * nothing reads the spool; splitting by profile is for whoever adds the reader.
+ *
+ * Modeled on logcat-capture.ts: a session-scoped host file with a time-based GC,
+ * exit-handler cleanup, and safe rename-not-truncate rotation. One deliberate
+ * difference: no idle timeout. logcat idles out because a read can come long
+ * after the last write; this spool must hold the entire session, so it stops
+ * only on explicit disable or process exit.
+ *
+ * Lifecycle: startSpool when the session is enabled; stopSpool (which closes the
+ * fd but keeps the file) on explicit disable and on process exit, so a just-ended
+ * session stays readable until the GC reclaims it. Never on a transient device
+ * error. callRadar clears the enabled flag on a device blip; closing the spool
+ * there would cut the record short on a momentary drop.
+ */
+// Under os.tmpdir() (not ~/.slack-radar) so the OS reclaims it if the process
+// dies unclean (crash, kill -9, no disable). Our own stopSpool + exit handlers +
+// the GC still run first; the temp dir is the backstop for the unclean case.
+// Same choice db.ts makes for its pulled-DB scratch, and same reason.
+//
+// Pid-scoped like db.ts's DB_TMP: every MCP shares one RADAR_PORT, so a fixed
+// dir lets two concurrent MCP processes build the same events-<now>.jsonl path
+// and interleave sessions, and one process's gcOldSpools would walk the other's
+// live files. Scoping by pid gives each process its own dir. initializeSpoolDir
+// runs at startup; the default is the unscoped path so unit tests that never
+// call it still get a usable location.
+let SPOOL_DIR = path.join(os.tmpdir(), "slack-radar-events");
+let ROTATION_BYTES = 100 * 1024 * 1024;
+const GC_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+// Cheap-cadence rotation check: run needsRotation only every Nth write so the
+// hot path is a plain fd append almost always.
+const ROTATION_CHECK_EVERY = 1000;
+const state = {
+    fd: null,
+    filePath: null,
+    startedAt: null,
+    writeCount: 0,
+};
+// One-time breadcrumb latch: if writeFrame ever fails, log once so a spool that
+// dies mid-session (ENOSPC/EACCES/EBADF) is diagnosable, without spamming a line
+// per frame for the rest of the session. Reset on each startSpool.
+let writeErrorLogged = false;
+/**
+ * Point the spool dir at a per-process-unique path. Call once at startup with
+ * process.pid. Mirrors db.ts initializeDatabasePath: every MCP shares one port,
+ * so a pid key is the collision-free scope.
+ */
+export function initializeSpoolDir(scopeKey) {
+    SPOOL_DIR = path.join(os.tmpdir(), `slack-radar-events-${scopeKey}`);
+}
+function ensureSpoolDir() {
+    if (!fs.existsSync(SPOOL_DIR)) {
+        // 0700: the spool holds raw bodies, auth headers, and message content under
+        // a world-traversable tmpdir, so scope it to the owner. Same choice db.ts
+        // makes for its pulled-DB scratch in the same location.
+        fs.mkdirSync(SPOOL_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+/**
+ * Delete spool files older than GC_TTL_MS. Runs at session enable. Bounds disk
+ * usage without losing recent session records. dir + now injectable for tests.
+ * Mirrors gcOldCaptures (logcat-capture.ts). Returns the count removed.
+ */
+export function gcOldSpools(dir = SPOOL_DIR, now = Date.now()) {
+    if (!fs.existsSync(dir))
+        return 0;
+    let removed = 0;
+    for (const name of fs.readdirSync(dir)) {
+        // Match the live files and their rotated archives.
+        if (!name.startsWith("events-") || !name.includes(".jsonl"))
+            continue;
+        const full = path.join(dir, name);
+        try {
+            const stat = fs.statSync(full);
+            if (now - stat.mtimeMs > GC_TTL_MS) {
+                fs.unlinkSync(full);
+                removed += 1;
+            }
+        }
+        catch {
+            // ignore; file may have vanished between readdir and stat
+        }
+    }
+    return removed;
+}
+export function buildSpoolFilePath(now = Date.now()) {
+    return path.join(SPOOL_DIR, `events-${now}.jsonl`);
+}
+// The epoch that pins a query_session cursor to one spool file: the <ts> in events-<ts>.jsonl. It
+// changes on every rotation and re-enable, so a cursor minted against one file is detectably stale
+// against another. Pure inverse of buildSpoolFilePath's naming; a null path (no spool) yields "".
+// Owned here next to the name it strips so the mint and the check can never drift on the affixes.
+export function epochFromSpoolPath(filePath) {
+    if (filePath === null)
+        return "";
+    return path.basename(filePath).replace(/^events-/, "").replace(/\.jsonl$/, "");
+}
+export function isSpooling() {
+    return state.fd !== null;
+}
+export function getSpoolFilePath() {
+    return state.filePath;
+}
+/**
+ * Read the current session spool back into parsed frames, oldest first (append
+ * order). Separate from the write path; reads the live file by its own handle,
+ * never touching the writer's fd or state. Returns [] when no spool is open, the
+ * file is gone, or it cannot be read. Never throws into the caller: a query over
+ * a missing or damaged spool must degrade to empty, not fail the tool.
+ *
+ * Reads the whole file and lets the query shaper's byte cap bound the OUTPUT,
+ * rather than tailing here: a filter can match an old frame near the top, so a
+ * byte-tail read could drop a frame the caller asked for. Rotation already caps
+ * the live file at a normal-session size, so a whole read is safe.
+ *
+ * A torn final line (the process died mid-append, before the newline) is skipped
+ * so one bad tail line never sinks the whole read. Any line that will not parse
+ * is dropped the same way.
+ */
+export function readSpool() {
+    const filePath = state.filePath;
+    if (filePath === null)
+        return [];
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const frames = [];
+    for (const line of raw.split("\n")) {
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            // Only a well-formed frame: an object with a string `type` and an `event` object. A bare
+            // null/number/string (valid JSON, wrong shape) is dropped so a reader can dereference
+            // frame.event and frame.type without a guard on every field.
+            if (typeof parsed === "object" &&
+                parsed !== null &&
+                typeof parsed.type === "string" &&
+                typeof parsed.event === "object" &&
+                parsed.event !== null) {
+                frames.push(parsed);
+            }
+        }
+        catch {
+            // Torn or malformed line: skip it, keep the rest.
+        }
+    }
+    return frames;
+}
+/**
+ * Open a fresh spool file for append and set module state. Ensures the dir,
+ * runs gcOldSpools first, returns the path (or null on failure). Idempotent: a
+ * second call while a spool is open returns the current path without reopening.
+ */
+export function startSpool(now = Date.now()) {
+    if (isSpooling())
+        return state.filePath;
+    try {
+        ensureSpoolDir();
+        gcOldSpools();
+        const filePath = buildSpoolFilePath(now);
+        // 0600 for the same reason as the 0700 dir: the file is raw captured
+        // traffic, readable only by the owner. Matches db.ts's pulled-DB scratch.
+        const fd = fs.openSync(filePath, "a", 0o600);
+        state.fd = fd;
+        state.filePath = filePath;
+        state.startedAt = now;
+        state.writeCount = 0;
+        writeErrorLogged = false;
+        return filePath;
+    }
+    catch {
+        // Failed to open the spool. Leave state clean so writeFrame no-ops.
+        state.fd = null;
+        state.filePath = null;
+        state.startedAt = null;
+        state.writeCount = 0;
+        return null;
+    }
+}
+/**
+ * Append one frame as a single JSONL line. On the hot path (every streamed
+ * event) and inside the wait_for_events notify path. Synchronous on purpose:
+ * a sync append keeps frames in arrival order with no interleave, which an async
+ * write queue would not guarantee. It is also cheap and never lets an error
+ * reach the caller, so a spool write failure can never break bufferEvent or
+ * waiter delivery. No-op if no spool is open. Errors are swallowed after one
+ * breadcrumb.
+ */
+export function writeFrame(frame) {
+    if (state.fd === null)
+        return;
+    try {
+        // Loop until the whole buffer is written. fs.writeSync can short-write on a
+        // signal or a near-full disk; a partial line with no newline would fuse
+        // onto the next frame and break the JSONL boundary a reader would need.
+        const buf = Buffer.from(JSON.stringify(frame) + "\n");
+        let offset = 0;
+        while (offset < buf.length) {
+            offset += fs.writeSync(state.fd, buf, offset, buf.length - offset);
+        }
+        state.writeCount += 1;
+        if (state.writeCount % ROTATION_CHECK_EVERY === 0) {
+            rotateSpoolIfNeeded();
+        }
+    }
+    catch (err) {
+        // Disk full, EACCES, closed fd: swallow so the caller's waiter delivery is
+        // never affected. Log once so a spool that quietly died mid-session is
+        // diagnosable instead of silent.
+        if (!writeErrorLogged) {
+            writeErrorLogged = true;
+            console.error(`[radar] event spool write failed, spool may be truncated: ${err}`);
+        }
+    }
+}
+/**
+ * Close the fd and clear state, but KEEP the file on disk. Called on explicit
+ * disable and on process exit. The file survives so a just-ended session is
+ * still readable; the GC reclaims it after the TTL. This matches logcat, which
+ * also keeps its capture file on disable and lets the GC reclaim it. Never
+ * called on the transient device-error path.
+ */
+export function stopSpool() {
+    const fd = state.fd;
+    state.fd = null;
+    state.filePath = null;
+    state.startedAt = null;
+    state.writeCount = 0;
+    if (fd !== null) {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // already closed
+        }
+    }
+}
+/**
+ * If the open file exceeds ROTATION_BYTES, rename it `.rotated-<ts>` (readable
+ * until the GC reclaims it) and open a fresh file. Rotation is the one place
+ * capture-everything yields to bounded disk: a normal session never rotates,
+ * this is only the disk-safety backstop.
+ *
+ * Safe rename-not-truncate, mirroring rotateCaptureIfNeeded: truncating in
+ * place would leave the next append past EOF. No-op if no spool is open or the
+ * file is under cap. Returns the new path, or null when nothing rotated.
+ */
+export function rotateSpoolIfNeeded(now = Date.now(), capBytes = ROTATION_BYTES) {
+    const fd = state.fd;
+    const current = state.filePath;
+    if (fd === null || !current)
+        return null;
+    let size;
+    try {
+        size = fs.fstatSync(fd).size;
+    }
+    catch {
+        return null;
+    }
+    if (size <= capBytes)
+        return null;
+    try {
+        fs.closeSync(fd);
+    }
+    catch {
+        // already closed
+    }
+    state.fd = null;
+    try {
+        fs.renameSync(current, `${current}.rotated-${now}`);
+    }
+    catch {
+        // Rename failure is non-fatal: the file may have vanished. Fall through
+        // and open a fresh spool.
+    }
+    // Reopen a fresh file. startSpool is a no-op while a spool is open, so we
+    // cleared state.fd above first.
+    const reopened = startSpool(now);
+    if (reopened === null) {
+        // Reopen failed (disk full is exactly when rotation fires). state.fd stays
+        // null, so writeFrame no-ops for the rest of the session. Leave one
+        // breadcrumb so a dead-mid-session spool is diagnosable. A reopen-retry is
+        // out of scope here.
+        console.error("[radar] event spool rotation reopen failed; spool stopped");
+    }
+    return reopened;
+}
+/**
+ * Install once at process start so the spool file is deleted when the MCP
+ * server exits. Copies logcat-capture.ts registerCleanup, including the
+ * SIGINT/SIGTERM exit codes 130/143.
+ */
+let cleanupRegistered = false;
+export function registerCleanup() {
+    if (cleanupRegistered)
+        return;
+    cleanupRegistered = true;
+    const cleanup = () => stopSpool();
+    process.on("exit", cleanup);
+    process.on("SIGINT", () => {
+        cleanup();
+        process.exit(130);
+    });
+    process.on("SIGTERM", () => {
+        cleanup();
+        process.exit(143);
+    });
+}
+// Test-only: point the spool at an isolated dir so a test never writes to the
+// real one. Production uses initializeSpoolDir(pid) at startup instead.
+export function _setSpoolDirForTest(dir) {
+    SPOOL_DIR = dir;
+}
+// Test-only: lower the rotation cap so the periodic writeFrame check can drive a
+// real rename without writing 100MB. The internal rotate call reads this default.
+export function _setRotationBytesForTest(n) {
+    ROTATION_BYTES = n;
+}
+// Test-only: lower the write count so a test can trigger the periodic rotation
+// check without writing ROTATION_CHECK_EVERY frames. Not for production use.
+export function _setWriteCountForTest(n) {
+    state.writeCount = n;
+}
+// Test-only: the periodic rotation cadence, so a test can drive writeFrame to
+// the rotation branch without hard-coding the constant.
+export function _getRotationCheckEveryForTest() {
+    return ROTATION_CHECK_EVERY;
+}
+// Test-only: close the underlying fd WITHOUT clearing state, so a test can
+// prove writeFrame swallows a write-to-closed-fd error. Production code must
+// never leave a closed fd in state; only stopSpool/rotate close it, and both
+// null the fd.
+export function _closeFdLeavingStateForTest() {
+    if (state.fd !== null) {
+        try {
+            fs.closeSync(state.fd);
+        }
+        catch {
+            // already closed
+        }
+    }
+}

package/dist/shared/screen.d.ts

@@ -102,6 +102,28 @@ export declare function pickDisplay(displays: DisplayInfo[]): {
 };
 /** Strip any text prefix (e.g. a multi-display warning) before the PNG magic header. */
 export declare function stripPngPrefix(raw: Buffer): Buffer;
+/**
+ * Clamp a requested frame rate to a safe positive integer for use in an ffmpeg `fps=` filter.
+ * The rate ultimately comes from a client-controlled `?fps=` query param, and a raw number
+ * threaded into `fps=${n}` is a footgun: a negative or Infinity value makes ffmpeg write a
+ * 0-byte file (silent no-recording), a fractional value produces a stuttering near-empty clip,
+ * and a huge value hangs ffmpeg (a leaked, never-exiting encoder). Round to an integer and bound
+ * to [MIN_FPS, MAX_FPS]; anything non-finite or out of range falls back to DEFAULT_FPS.
+ */
+export declare function clampFps(fps: number): number;
+/**
+ * ffmpeg args for the record-to-mp4 pipeline: the live cast's concatenated JPEG stream on
+ * stdin -> a wall-clock-timed, constant-fps H.264 mp4 at `out`. Pure + exported so the arg
+ * SHAPE is unit-testable: the recording is a spawned subprocess with no device-free way to
+ * assert timing, and two arg bugs have hidden here — a fixed input `-r` (stamped every frame
+ * at 1/fps, slow motion) and `-use_wallclock_as_timestamps` paired with `-f image2pipe`
+ * (which ignores the flag and re-stamps a synthetic rate). The invariants the test pins:
+ * no `-r` before `-i`; the wallclock flag paired with the mjpeg demuxer that honors it (NOT
+ * image2pipe); and an output `fps` resample so playback is real-time and CFR. fps is clamped
+ * defensively here too, so the filter string is always a safe integer even if a caller skips
+ * the boundary clamp.
+ */
+export declare function recordingArgs(fps: number, out: string): string[];
 /** Detect (and cache) the active display id. resetScreenState() forces a re-detect. */
 export declare function detectDisplay(): Promise<string | null>;
 export declare function displayNote(): string;
@@ -120,7 +142,33 @@ interface LiveCast {
     recording: Recording | null;
     fps: number;
     keepalive: NodeJS.Timeout | null;
+    orphanTimer: NodeJS.Timeout | null;
 }
+/**
+ * Is this viewer's socket still open and writable? A closed/destroyed response is dead.
+ * Exported for unit testing: this predicate decides whether pushFrame prunes a viewer,
+ * so a regression here would either leak (never prune) or drop live viewers (prune too eagerly).
+ */
+export declare function viewerAlive(r: NodeJS.WritableStream): boolean;
+/**
+ * Pure decision for what to do once a viewer is gone, given how many viewers remain and
+ * whether a recording is running. Extracted from afterViewerRemoved so the loop-closing
+ * logic is unit-testable without spawning: this is the gate that decides between leaking
+ * (keep the cast) and reaping. "watched" = a viewer is still attached, keep the cast as-is;
+ * "arm-grace" = unwatched but recording, hold briefly for a clean stop; "reap" = nothing
+ * left, tear down now.
+ */
+export declare function nextViewerAction(viewers: number, recording: boolean): "watched" | "arm-grace" | "reap";
+/**
+ * The literal respawn root cause, as a pure predicate: on a screenrecord/ffmpeg exit, relaunch
+ * a fresh cast ONLY while a viewer is still watching. This is the exact gate onExit turns on
+ * ("if (viewers.size || recording) relaunch" was the bug — a recording alone respawned forever
+ * with no viewer). Extracted pure so the root-cause line is unit-testable, not only device-verified.
+ * Note the asymmetry with nextViewerAction: a recording does NOT keep the cast alive here (onExit
+ * lets cleanupLive finalize the clip + reap); it only defers reaping in the viewer-removal path
+ * via the orphan grace. So relaunch depends on viewers ALONE.
+ */
+export declare function shouldRelaunch(viewers: number): boolean;
 /**
  * Start (or return the existing) live cast. Returns null if ffmpeg is unavailable
  * — callers must degrade rather than assume a stream. The boundary string is