@slack/radar-mcp 1.2.0 → 1.3.0

package/dist/mcp/index.js

@@ -6,7 +6,9 @@ import fs from "fs";
 import http from "http";
 import { AndroidTransport } from "../shared/android.js";
 import { RADAR_HOST, RADAR_PORT } from "../shared/constants.js";
+import { stopCapture } from "../shared/logcat-capture.js";
 import { connectStream, destroyStream, waitForEvents, clearLocalBuffers, isStreamConnected, localNetworkBuffer, localRtmBuffer, setTransport, } from "../shared/stream.js";
+import { buildBufferPath, createSnapshot } from "./snapshot.js";
 import { TOOL_DEFINITIONS, SERVER_INSTRUCTIONS } from "./tools.js";
 // --- Platform selection ---
 function createTransport() {
@@ -135,6 +137,11 @@ function handleSessionDisable() {
     sessionEnabled = false;
     destroyStream();
     clearLocalBuffers();
+    // Explicit disable stops the logcat capture immediately. Without this, the
+    // capture would linger up to the capture-idle timeout (15 min) after a
+    // deliberate user action saying "I am done", which is surprising and
+    // wastes disk + an adb logcat child.
+    stopCapture();
     return textResult({
         enabled: false,
         note: "Radar disabled. Use /radar-enable to reconnect.",
@@ -173,17 +180,16 @@ function handleGetAppState() {
 }
 function handleListProfiles() {
     try {
-        // Narrow to implementations that expose listProfiles; the base
-        // DeviceTransport interface leaves it platform-specific.
+        // Narrow to implementations that expose `listProfiles`; it is optional on `DeviceTransport`.
         const maybe = device;
         if (typeof maybe.listProfiles !== "function") {
             return textResult({ error: `Profile listing not supported on platform ${device.platform}` }, true);
         }
         const profiles = maybe.listProfiles();
-        const activeUserId = typeof device.getActiveUserId === "function"
-            ? device.getActiveUserId()
-            : null;
-        return textResult({ profiles, active_user_id: activeUserId });
+        return textResult({
+            profiles,
+            active_user_id: device.getActiveUserId(),
+        });
     }
     catch (e) {
         return textResult({ error: `Profile list failed: ${e.message}` }, true);
@@ -206,13 +212,10 @@ async function handleActivateForUser(args) {
         // handleSessionEnable so an immediate get_recent_logs call does not
         // read an empty file.
         await new Promise((r) => setTimeout(r, 500));
-        const sourceFile = typeof device.getCaptureFilePath === "function"
-            ? device.getCaptureFilePath()
-            : null;
         return textResult({
             user_id: args.user_id,
             timeout_minutes: timeout,
-            capture_file: sourceFile,
+            capture_file: device.getCaptureFilePath?.() ?? null,
             note: "Profile activated. Log capture restarted on a new file; old capture preserved for 7 days.",
         });
     }
@@ -220,6 +223,30 @@ async function handleActivateForUser(args) {
         return textResult({ error: `Profile activation failed: ${e.message}` }, true);
     }
 }
+async function handleCaptureSnapshot(args) {
+    try {
+        // Adapt `callRadar` (device HTTP + retry + session gate) into the
+        // simple `fetchBuffer(kind)` contract `createSnapshot` expects. Any
+        // `res.error` from callRadar is rethrown so the composer's per-buffer
+        // try/catch can record it in `errors[]` without bringing down the
+        // whole snapshot.
+        const fetchBuffer = async (kind) => {
+            const res = await callRadar(buildBufferPath(kind));
+            if (res.error)
+                throw new Error(res.error);
+            return res;
+        };
+        const result = await createSnapshot(device, fetchBuffer, {
+            includeLogs: args?.include_logs !== false,
+            includeScreenshot: args?.include_screenshot !== false,
+            logTailLines: args?.log_tail_lines,
+        });
+        return textResult(result, result.errors.length > 0 && result.files.length === 0);
+    }
+    catch (e) {
+        return textResult({ error: `Snapshot failed: ${e.message}` }, true);
+    }
+}
 function handleGetRecentLogs(args) {
     try {
         const lines = device.getRecentLogs(args.tag, args.limit || 50, args.grep);
@@ -352,7 +379,7 @@ function buildApiPath(name, args) {
     }
 }
 // --- MCP Server ---
-const server = new Server({ name: "slack-radar", version: "1.2.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+const server = new Server({ name: "slack-radar", version: "1.3.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOL_DEFINITIONS,
 }));
@@ -385,6 +412,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request, _extra) => {
     if (name === "get_recent_logs") {
         return handleGetRecentLogs(toolArgs);
     }
+    if (name === "capture_snapshot") {
+        return handleCaptureSnapshot(toolArgs);
+    }
     if (name === "screenshot") {
         return handleScreenshot(toolArgs);
     }

package/dist/mcp/snapshot.d.ts

@@ -0,0 +1,63 @@
+import type { DeviceTransport } from "../shared/transport.js";
+export interface SnapshotOptions {
+    includeLogs?: boolean;
+    includeScreenshot?: boolean;
+    logTailLines?: number;
+}
+export interface SnapshotResult {
+    path: string;
+    files: string[];
+    zip_path: string | null;
+    timestamp: number;
+    counts: {
+        network: number;
+        rtm: number;
+        clogs: number;
+        log_lines: number;
+        log_lines_truncated: boolean;
+        screenshot: boolean;
+    };
+    fetched: {
+        network: boolean;
+        rtm: boolean;
+        clogs: boolean;
+    };
+    errors: string[];
+    privacy_notice: string;
+}
+/**
+ * Resolve the output directory for a snapshot. Exported for tests.
+ */
+export declare function buildSnapshotDir(now?: number, root?: string): string;
+/**
+ * Build the device-side URL for a given buffer kind. Extracted so the
+ * mapping is testable without standing up a device. `limit=1000` is
+ * intentionally larger than point-query defaults — snapshots are bulk
+ * exports and the device-side ring buffers cap their own responses.
+ */
+export declare function buildBufferPath(kind: "network" | "rtm" | "clogs"): string;
+export interface LogTailResult {
+    text: string;
+    truncated: boolean;
+}
+/**
+ * Take the last N lines from the active capture file. Returns an empty
+ * result if no capture is active or the file is unreadable. Bounded read
+ * so we do not load a 100 MB capture into memory.
+ *
+ * `truncated` is true when the 1 MB file-read cap was the limiting factor
+ * (i.e. the user asked for more lines than fit), so the caller can tell
+ * the user they got fewer lines than requested.
+ */
+export declare function readRecentLogTail(requestedLimit?: number): LogTailResult;
+/**
+ * Write a snapshot bundle to disk. The caller supplies `fetchBuffer` (a
+ * callback that hits the device's HTTP endpoint for a given buffer name)
+ * so this module does not need to know how `radarRequest` works — easier
+ * to test and keeps the device-HTTP plumbing in `index.ts`.
+ *
+ * On partial failure (e.g. screenshot fails because ADB is flaky), the
+ * snapshot still lands on disk with whatever succeeded; failures are
+ * collected in `result.errors` so the model can tell the user.
+ */
+export declare function createSnapshot(device: DeviceTransport, fetchBuffer: (kind: "network" | "rtm" | "clogs") => Promise<unknown>, opts?: SnapshotOptions, now?: number, snapshotRoot?: string): Promise<SnapshotResult>;

package/dist/mcp/snapshot.js

@@ -0,0 +1,301 @@
+import { spawnSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { getCaptureFilePath, readTailBytes } from "../shared/logcat-capture.js";
+/**
+ * `capture_snapshot` composer: bundles everything Radar has seen into a
+ * single on-disk artifact so a user can attach it to a Jira, drop it in a
+ * Slack thread, or share it with a teammate without copying individual
+ * tool outputs.
+ *
+ * Snapshot contents:
+ *   - `bundle.json` — device-side buffers (net + RTM + clogs) plus metadata
+ *   - `screenshot.png` — current screen (optional)
+ *   - `logcat.tail.log` — last N lines of the active capture file (optional)
+ *
+ * Written to `~/.slack-radar/snapshots/snapshot-<ts>/`. No cleanup: snapshots
+ * are user-triggered, small, and should persist for post-hoc inspection.
+ * If that becomes a disk-growth concern, add a TTL GC like `logcat-capture.ts`.
+ */
+const SNAPSHOT_DIR = path.join(os.homedir(), ".slack-radar", "snapshots");
+const DEFAULT_LOG_TAIL_LINES = 500;
+const MAX_LOG_TAIL_LINES = 10_000;
+const DEFAULT_LOG_TAIL_BYTES = 1 * 1024 * 1024; // 1 MB bound on file read
+// Restrictive permissions on the snapshot dir and its files. The bundle
+// contains network request/response bodies (including auth headers),
+// message content, and user IDs — readable only by the owning user.
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+const BUNDLE_README = `Slack Radar snapshot
+====================
+
+This directory is a point-in-time bundle of Radar state.
+
+Files:
+- bundle.json: device-side network/RTM/clog buffers, counts, and metadata.
+- logcat.tail.log (optional): last N lines of the on-device logcat capture.
+- screenshot.png (optional): current screen.
+
+Privacy: bundle.json contains raw API request/response bodies (auth headers,
+tokens), RTM message content, user IDs, channel IDs, and clog payloads.
+Review before sharing externally. This bundle lives on your local disk only;
+nothing is uploaded anywhere by Radar.
+
+To inspect: cat bundle.json | jq .
+To share: zip -r snapshot.zip . then attach the zip.
+`;
+const PRIVACY_NOTICE = "bundle.json contains raw API request/response bodies (including auth headers), RTM message content, user IDs, and clog payloads. Review before sharing externally.";
+/**
+ * Resolve the output directory for a snapshot. Exported for tests.
+ */
+export function buildSnapshotDir(now = Date.now(), root = SNAPSHOT_DIR) {
+    return path.join(root, `snapshot-${now}`);
+}
+/**
+ * Build the device-side URL for a given buffer kind. Extracted so the
+ * mapping is testable without standing up a device. `limit=1000` is
+ * intentionally larger than point-query defaults — snapshots are bulk
+ * exports and the device-side ring buffers cap their own responses.
+ */
+export function buildBufferPath(kind) {
+    return `/api/${kind}?limit=1000`;
+}
+/**
+ * Take the last N lines from the active capture file. Returns an empty
+ * result if no capture is active or the file is unreadable. Bounded read
+ * so we do not load a 100 MB capture into memory.
+ *
+ * `truncated` is true when the 1 MB file-read cap was the limiting factor
+ * (i.e. the user asked for more lines than fit), so the caller can tell
+ * the user they got fewer lines than requested.
+ */
+export function readRecentLogTail(requestedLimit = DEFAULT_LOG_TAIL_LINES) {
+    // Defensive clamp — caller validates at the handler boundary too, but
+    // a direct caller cannot accidentally get "entire file" by passing NaN.
+    const limit = Number.isFinite(requestedLimit) &&
+        requestedLimit > 0 &&
+        requestedLimit <= MAX_LOG_TAIL_LINES
+        ? Math.floor(requestedLimit)
+        : DEFAULT_LOG_TAIL_LINES;
+    const filePath = getCaptureFilePath();
+    if (!filePath)
+        return { text: "", truncated: false };
+    const raw = readTailBytes(filePath, DEFAULT_LOG_TAIL_BYTES);
+    if (!raw)
+        return { text: "", truncated: false };
+    const lines = raw.split("\n");
+    // If the raw read hit the 1 MB byte cap, the FIRST line is likely
+    // partial — readTailBytes drops it — and the user got whatever fits.
+    // "Truncated" means "user asked for more lines than the byte cap can
+    // contain AND we delivered fewer lines than requested."
+    const truncated = lines.length < limit && raw.length >= DEFAULT_LOG_TAIL_BYTES;
+    const tail = lines.slice(Math.max(0, lines.length - limit));
+    return { text: tail.join("\n"), truncated };
+}
+/**
+ * Write a snapshot bundle to disk. The caller supplies `fetchBuffer` (a
+ * callback that hits the device's HTTP endpoint for a given buffer name)
+ * so this module does not need to know how `radarRequest` works — easier
+ * to test and keeps the device-HTTP plumbing in `index.ts`.
+ *
+ * On partial failure (e.g. screenshot fails because ADB is flaky), the
+ * snapshot still lands on disk with whatever succeeded; failures are
+ * collected in `result.errors` so the model can tell the user.
+ */
+export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.now(), snapshotRoot = SNAPSHOT_DIR) {
+    const includeLogs = opts.includeLogs !== false;
+    const includeScreenshot = opts.includeScreenshot !== false;
+    // Clamp log_tail_lines at the composer boundary. The handler and schema
+    // validate too; this is defense-in-depth so no downstream consumer sees
+    // a pathological value.
+    const logTailLines = typeof opts.logTailLines === "number" &&
+        Number.isFinite(opts.logTailLines) &&
+        opts.logTailLines > 0 &&
+        opts.logTailLines <= MAX_LOG_TAIL_LINES
+        ? Math.floor(opts.logTailLines)
+        : DEFAULT_LOG_TAIL_LINES;
+    const dir = buildSnapshotDir(now, snapshotRoot);
+    fs.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+    // `mkdirSync({ recursive: true, mode })` only applies the mode to
+    // directories it CREATES. If `~/.slack-radar/` or `.../snapshots/`
+    // already existed (e.g. created by a pre-R1 build or by the logcat
+    // capture module with default umask → 0o755), they keep old perms.
+    // Tighten them to 0o700 on every snapshot so the parent tree cannot
+    // leak directory-listing on a shared host.
+    for (const p of [snapshotRoot, path.dirname(snapshotRoot)]) {
+        try {
+            if (fs.existsSync(p))
+                fs.chmodSync(p, DIR_MODE);
+        }
+        catch {
+            // Best effort; not fatal.
+        }
+    }
+    const files = [];
+    const errors = [];
+    let network = null;
+    let rtm = null;
+    let clogs = null;
+    const fetched = { network: false, rtm: false, clogs: false };
+    // Device-side buffers. Failures are individually caught so one failing
+    // buffer does not nuke the whole snapshot. `fetched` distinguishes
+    // "empty because the buffer was empty" from "null because the fetch
+    // failed" — counts alone cannot tell these apart.
+    try {
+        network = await fetchBuffer("network");
+        fetched.network = true;
+    }
+    catch (e) {
+        errors.push(`network buffer: ${e.message}`);
+    }
+    try {
+        rtm = await fetchBuffer("rtm");
+        fetched.rtm = true;
+    }
+    catch (e) {
+        errors.push(`rtm buffer: ${e.message}`);
+    }
+    try {
+        clogs = await fetchBuffer("clogs");
+        fetched.clogs = true;
+    }
+    catch (e) {
+        errors.push(`clog buffer: ${e.message}`);
+    }
+    // Logcat tail.
+    let logTail = { text: "", truncated: false };
+    if (includeLogs) {
+        try {
+            logTail = readRecentLogTail(logTailLines);
+            if (logTail.text) {
+                const logFile = path.join(dir, "logcat.tail.log");
+                fs.writeFileSync(logFile, logTail.text, { mode: FILE_MODE });
+                files.push(logFile);
+            }
+        }
+        catch (e) {
+            errors.push(`logcat tail: ${e.message}`);
+        }
+    }
+    // Screenshot. 720px default is plenty for bug reports; full-res is
+    // 5-8x larger on disk and rarely adds forensic value.
+    let screenshotCaptured = false;
+    if (includeScreenshot) {
+        try {
+            const tmp = device.screenshot(false);
+            const dest = path.join(dir, "screenshot.png");
+            fs.copyFileSync(tmp, dest);
+            // copyFileSync preserves source mode by default on POSIX; chmod to
+            // 0600 so the copy is owner-only regardless of source permissions.
+            try {
+                fs.chmodSync(dest, FILE_MODE);
+            }
+            catch (e) {
+                // Non-fatal (worst case: screenshot has source mode, typically
+                // 0644 on macOS /tmp pulls) but user should know — a bundle they
+                // share externally has a world-readable PNG file if this path
+                // hits.
+                errors.push(`screenshot chmod failed: ${e.message} (file keeps source mode)`);
+            }
+            files.push(dest);
+            screenshotCaptured = true;
+        }
+        catch (e) {
+            errors.push(`screenshot: ${e.message}`);
+        }
+    }
+    // README. One-paragraph explainer so a receiver who opens the dir for
+    // the first time knows what each file is and what privacy exposure it
+    // carries.
+    try {
+        const readmeFile = path.join(dir, "README.txt");
+        fs.writeFileSync(readmeFile, BUNDLE_README, { mode: FILE_MODE });
+        files.push(readmeFile);
+    }
+    catch (e) {
+        errors.push(`README: ${e.message}`);
+    }
+    // Bundle JSON. Written last so counts reflect everything captured.
+    const counts = {
+        network: countItems(network),
+        rtm: countItems(rtm),
+        clogs: countItems(clogs),
+        log_lines: logTail.text
+            ? logTail.text.split("\n").filter(Boolean).length
+            : 0,
+        log_lines_truncated: logTail.truncated,
+        screenshot: screenshotCaptured,
+    };
+    const bundle = {
+        version: 1,
+        timestamp: now,
+        platform: device.platform,
+        active_user_id: device.getActiveUserId(),
+        capture_file: getCaptureFilePath(),
+        buffers: { network, rtm, clogs },
+        counts,
+        fetched,
+        errors,
+        privacy_notice: PRIVACY_NOTICE,
+    };
+    const bundleFile = path.join(dir, "bundle.json");
+    fs.writeFileSync(bundleFile, JSON.stringify(bundle, null, 2), {
+        mode: FILE_MODE,
+    });
+    files.unshift(bundleFile);
+    // Auto-zip: collapse the 4-file directory into a single shareable
+    // artifact. Users universally want to attach ONE file to Jira or drop
+    // ONE file in Slack, not drag a directory. Best-effort: if `zip` is
+    // missing on the user's PATH (rare — ships with macOS and most Linux
+    // distros) we just record the failure and the user can zip manually.
+    let zipPath = null;
+    const zipCandidate = `${dir}.zip`;
+    try {
+        const zipResult = spawnSync("zip", ["-rq", zipCandidate, "."], {
+            cwd: dir,
+            timeout: 10000,
+        });
+        if (zipResult.status === 0) {
+            try {
+                fs.chmodSync(zipCandidate, FILE_MODE);
+            }
+            catch {
+                // Leave mode as-is; already a zip copy of owner-readable files.
+            }
+            zipPath = zipCandidate;
+        }
+        else {
+            errors.push(`zip failed with status ${zipResult.status ?? "null"}${zipResult.stderr ? ": " + zipResult.stderr.toString().trim() : ""}`);
+        }
+    }
+    catch (e) {
+        errors.push(`zip not available: ${e.message}`);
+    }
+    return {
+        path: dir,
+        files,
+        zip_path: zipPath,
+        timestamp: now,
+        counts,
+        fetched,
+        errors,
+        privacy_notice: PRIVACY_NOTICE,
+    };
+}
+/**
+ * Count items inside a buffer response. Handles the `{ calls: [...] }`,
+ * `{ events: [...] }`, `{ clogs: [...] }` shapes the radar HTTP server
+ * uses. Falls back to 0 on malformed responses.
+ */
+function countItems(body) {
+    if (!body || typeof body !== "object")
+        return 0;
+    const b = body;
+    for (const key of ["calls", "events", "clogs", "items"]) {
+        const v = b[key];
+        if (Array.isArray(v))
+            return v.length;
+    }
+    return 0;
+}

package/dist/mcp/tools.js

@@ -22,6 +22,7 @@ export const SERVER_INSTRUCTIONS = [
     '- "what API call was that" -> get_recent_network_calls then get_network_call_detail',
     '- "did I get X" / "did X happen" -> search(query="X") across ALL buffers, not just one',
     '- "check the debug logs" -> get_recent_logs(tag="...")',
+    '- "save this" / "file this as a bug" / "share this" / "bundle this" / "attach to ticket" / "give me a repro" / "snapshot this" / "preserve this" / "hold this state" / "save what you just saw" -> capture_snapshot',
     "",
     "Key behaviors:",
     "- Network/RTM buffers clear on shutdown. Clogs persist from app start.",
@@ -48,6 +49,22 @@ export const SERVER_INSTRUCTIONS = [
     "DO NOT invoke /radar-ui yourself. Opening a browser window is a user-visible action.",
     "DO NOT suggest /radar-ui for single-query debugging or when the user is happy reading",
     "results in the transcript. Suggest it when visual inspection adds real value.",
+    "",
+    "CAPTURE_SNAPSHOT OUTPUT:",
+    "When capture_snapshot returns, tell the user:",
+    "  1. The result.zip_path if non-null (the single shareable file). Fall back to",
+    "     result.path (a directory) if zip_path is null.",
+    "  2. A one-line summary of counts (network/rtm/clogs/log_lines/screenshot).",
+    "  3. Print this EXACT sentence as the privacy line, verbatim — no paraphrase, no",
+    "     compression, no skipping even under time pressure:",
+    '     "Privacy: bundle.json contains raw API request/response bodies (including auth headers), RTM message content, user IDs, and clog payloads. Review before sharing externally."',
+    "  4. If result.log_lines_truncated is true, say: 'you got fewer log lines than",
+    "     requested because the 1 MB read cap was the limiting factor.'",
+    "  5. If the user's original ask was 'file this as a bug' / 'attach to ticket' /",
+    "     similar, offer to attach result.zip_path via the Jira MCP or Slack MCP as",
+    "     the next step. Do NOT invoke the attach without asking. Just offer.",
+    "  6. If result.errors is non-empty, enumerate which parts failed so the user",
+    "     knows what is missing before they ship the bundle.",
 ].join("\n");
 export const TOOL_DEFINITIONS = [
     {
@@ -212,6 +229,30 @@ export const TOOL_DEFINITIONS = [
         },
         annotations: {},
     },
+    {
+        name: "capture_snapshot",
+        description: "Bundle the current Radar state into a single on-disk artifact for sharing. Writes four files to ~/.slack-radar/snapshots/snapshot-<ts>/: bundle.json (network + RTM + clog buffers, up to 1000 items each — a bulk export, much larger than point queries like get_network_call_detail), logcat.tail.log (last N lines of the active capture), screenshot.png (current screen), and README.txt (receiver-facing explainer). Use when the user says 'save this', 'file this as a bug', 'share this', 'bundle this up', 'attach to a ticket', 'make me a repro', or otherwise wants a shareable reproducible handoff. PRIVACY: bundle.json contains raw API request/response bodies including auth headers, RTM message content, user/team/channel IDs, and clog payloads — review before sharing externally.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                include_logs: {
+                    type: "boolean",
+                    description: "Include last N lines of the active logcat capture (default: true). No-op when no capture is active.",
+                },
+                include_screenshot: {
+                    type: "boolean",
+                    description: "Include a current screenshot (default: true). Requires a connected device.",
+                },
+                log_tail_lines: {
+                    type: "number",
+                    description: "How many trailing lines of the capture file to include (default: 500, min: 1, max: 10000). Truncation flagged in counts.log_lines_truncated.",
+                    minimum: 1,
+                    maximum: 10000,
+                },
+            },
+        },
+        annotations: { readOnlyHint: false },
+    },
     {
         name: "screenshot",
         description: "Capture a screenshot from the connected Android device.",

package/dist/shared/android.js

@@ -137,7 +137,7 @@ export class AndroidTransport {
         this.detectedUserId = null;
         this.radarEnabled = false;
         this.lastForwardError = null;
-        stopCapture();
+        // Capture has its own idle timer; not stopped on activation reset (see logcat-capture.ts).
     }
     isForwarded() {
         return this.portForwarded;

package/dist/shared/logcat-capture.d.ts

@@ -3,6 +3,9 @@ export interface CaptureState {
     child: ChildProcess | null;
     filePath: string | null;
     startedAt: number | null;
+    lastReadAt: number | null;
+    idleTimer: ReturnType<typeof setTimeout> | null;
+    captureIdleMs: number;
 }
 /**
  * Delete capture files older than GC_TTL_MS. Runs at session enable. Bounded
@@ -12,6 +15,18 @@ export declare function gcOldCaptures(dir?: string, now?: number): number;
 export declare function buildCaptureFilePath(now?: number): string;
 export declare function isCapturing(): boolean;
 export declare function getCaptureFilePath(): string | null;
+/**
+ * Override the default capture-idle timeout. Internal — not currently exposed
+ * to MCP callers; reserved for future tuning. Values <= 0, NaN, or past
+ * `MAX_SETTIMEOUT_MS` fall back to the default so the timer can never
+ * pathologically collapse to an immediate-fire.
+ */
+export declare function setCaptureIdleMs(ms: number): void;
+export declare function _getCaptureIdleMsForTest(): number;
+export declare function _hasIdleTimerForTest(): boolean;
+export declare function _rescheduleIdleTimerForTest(): void;
+export declare function _touchLastReadForTest(now?: number): void;
+export declare function _setStateForTest(patch: Partial<CaptureState>): void;
 /**
  * Start streaming logcat to a session-scoped file. Idempotent: a second call
  * while the first capture is live is a no-op. If a prior capture's child is

package/dist/shared/logcat-capture.js

@@ -17,10 +17,14 @@ const LOG_DIR = path.join(os.homedir(), ".slack-radar", "logs");
 const ROTATION_BYTES = 100 * 1024 * 1024;
 const ROTATION_KEEP_BYTES = 50 * 1024 * 1024;
 const GC_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_CAPTURE_IDLE_MS = 15 * 60 * 1000;
 const state = {
     child: null,
     filePath: null,
     startedAt: null,
+    lastReadAt: null,
+    idleTimer: null,
+    captureIdleMs: DEFAULT_CAPTURE_IDLE_MS,
 };
 function ensureLogDir() {
     if (!fs.existsSync(LOG_DIR)) {
@@ -61,6 +65,88 @@ export function isCapturing() {
 export function getCaptureFilePath() {
     return state.filePath;
 }
+// Node's setTimeout treats values past 2^31-1 ms as 1 ms (fires immediately),
+// which would instantly kill capture. Clamp to the max safe value here.
+const MAX_SETTIMEOUT_MS = 2_147_483_647;
+/**
+ * Schedule (or reschedule) the capture-idle timer to fire when
+ * `state.captureIdleMs` elapses without a new read. Called on every
+ * successful `readRecentLogs` and at `startCapture` boot so the timer is
+ * always pointing at the most recent activity.
+ *
+ * The scheduled callback closes over the timer handle it created and only
+ * fires `stopCapture()` if the module's current `state.idleTimer` is
+ * still THAT same handle. This defends against the case where a previously
+ * scheduled (but not yet fired) callback gets queued to run AFTER a
+ * subsequent reschedule or `stopCapture` — without identity comparison it
+ * would incorrectly kill a freshly-rescheduled capture.
+ */
+function rescheduleIdleTimer() {
+    if (state.idleTimer)
+        clearTimeout(state.idleTimer);
+    const delay = Math.min(state.captureIdleMs, MAX_SETTIMEOUT_MS);
+    const thisTimer = setTimeout(() => {
+        // Identity check: if state was cleared or a newer timer replaced us,
+        // do nothing. This prevents a stale queued callback from tearing down
+        // a fresh capture.
+        if (state.idleTimer !== thisTimer)
+            return;
+        stopCapture();
+    }, delay);
+    state.idleTimer = thisTimer;
+    // Node timers keep the event loop alive. For a long-running MCP this is
+    // fine, but for short-lived callers we do not want the timer to be the
+    // last thing keeping the process alive.
+    if (typeof thisTimer.unref === "function")
+        thisTimer.unref();
+}
+// Record that a read of the capture file just happened. Keeps the capture
+// idle timer sliding forward so an actively-used capture does not time out.
+function touchLastRead(now = Date.now()) {
+    state.lastReadAt = now;
+    if (isCapturing())
+        rescheduleIdleTimer();
+}
+/**
+ * Override the default capture-idle timeout. Internal — not currently exposed
+ * to MCP callers; reserved for future tuning. Values <= 0, NaN, or past
+ * `MAX_SETTIMEOUT_MS` fall back to the default so the timer can never
+ * pathologically collapse to an immediate-fire.
+ */
+export function setCaptureIdleMs(ms) {
+    const valid = typeof ms === "number" && ms > 0 && ms <= MAX_SETTIMEOUT_MS;
+    state.captureIdleMs = valid ? ms : DEFAULT_CAPTURE_IDLE_MS;
+    if (isCapturing())
+        rescheduleIdleTimer();
+}
+// Test-only accessors so unit tests can assert on state that is otherwise
+// module-private. Must never be called from production code paths.
+export function _getCaptureIdleMsForTest() {
+    return state.captureIdleMs;
+}
+export function _hasIdleTimerForTest() {
+    return state.idleTimer !== null;
+}
+export function _rescheduleIdleTimerForTest() {
+    rescheduleIdleTimer();
+}
+export function _touchLastReadForTest(now) {
+    touchLastRead(now);
+}
+// Enforces the state-machine invariants the tests rely on so `Object.assign`
+// cannot silently produce an impossible configuration (e.g. an idle timer
+// pointing at a dead capture). Throws on misuse; callers that legitimately
+// want to clear state should pass matched pairs.
+export function _setStateForTest(patch) {
+    const next = { ...state, ...patch };
+    if (next.idleTimer !== null && next.child === null) {
+        throw new Error("_setStateForTest invariant: idleTimer must be null when child is null");
+    }
+    if (next.filePath !== null && next.child === null) {
+        throw new Error("_setStateForTest invariant: filePath must be null when child is null");
+    }
+    Object.assign(state, patch);
+}
 /**
  * Start streaming logcat to a session-scoped file. Idempotent: a second call
  * while the first capture is live is a no-op. If a prior capture's child is
@@ -90,6 +176,11 @@ export function startCapture(adbPath) {
             }
             if (state.child === child) {
                 state.child = null;
+                // Clear the idle timer: no capture to kill anymore.
+                if (state.idleTimer) {
+                    clearTimeout(state.idleTimer);
+                    state.idleTimer = null;
+                }
             }
         });
         child.on("error", () => {
@@ -103,11 +194,23 @@ export function startCapture(adbPath) {
                 state.child = null;
                 state.filePath = null;
                 state.startedAt = null;
+                state.lastReadAt = null;
+                // Clear the idle timer we created for this (now-dead) capture so it
+                // cannot fire against stale state.
+                if (state.idleTimer) {
+                    clearTimeout(state.idleTimer);
+                    state.idleTimer = null;
+                }
             }
         });
         state.child = child;
         state.filePath = filePath;
         state.startedAt = Date.now();
+        state.lastReadAt = state.startedAt;
+        // Capture-idle timer starts fresh with the new child. Activation may
+        // time out (5 min) long before this fires, but capture keeps running
+        // so reads into recent history remain possible.
+        rescheduleIdleTimer();
         // Child bring-up warmup is handled at the MCP handler boundary
         // (handleSessionEnable / handleActivateForUser add a small async delay
         // before returning). Doing it here would require either blocking the
@@ -127,9 +230,14 @@ export function startCapture(adbPath) {
 }
 export function stopCapture() {
     const child = state.child;
+    const timer = state.idleTimer;
     state.child = null;
     state.filePath = null;
     state.startedAt = null;
+    state.lastReadAt = null;
+    state.idleTimer = null;
+    if (timer)
+        clearTimeout(timer);
     if (child && child.exitCode === null) {
         try {
             child.kill("SIGTERM");
@@ -270,6 +378,16 @@ export function readRecentLogs(tag, limit, grep) {
     catch {
         return null;
     }
+    // Slide the capture-idle timer forward whenever a read hits a HEALTHY
+    // capture child. A freshly spawned child may have written zero bytes to
+    // the file if there is no device traffic yet — that is not a sign of
+    // death. `isCapturing()` checks the child process itself (spawned, not
+    // exited), which is the authoritative health signal. The `exit` /
+    // `error` handlers will null out the child if it dies, and those same
+    // handlers clear the idle timer so no stale callback can fire.
+    if (isCapturing()) {
+        touchLastRead();
+    }
     const lines = tail.split("\n").filter(Boolean);
     return filterLogLines(lines, tag, limit, grep);
 }

package/dist/shared/transport.d.ts

@@ -55,6 +55,15 @@ export interface DeviceTransport {
      * @returns Array of matching log lines
      */
     getRecentLogs(tag: string, limit: number, grep?: string): string[];
+    /**
+     * Returns the currently active user ID, or null if none is set. On Android
+     * this is the profile (e.g. "0" for personal, "10" for work); on iOS it
+     * is typically null (single-user device) or a synthetic identifier.
+     *
+     * Required so snapshot tooling and other callers do not fall back to
+     * unchecked casts when asking "which profile did this capture?".
+     */
+    getActiveUserId(): string | null;
     /**
      * Returns the last error message from an `ensureForward()` failure, or null
      * if the last attempt succeeded or has not happened. Lets callers surface
@@ -88,10 +97,4 @@ export interface DeviceTransport {
      * @param timeoutMinutes Auto-shutdown timeout in minutes
      */
     activateForUser?(userId: string, timeoutMinutes: number): void;
-    /**
-     * Returns the currently active user ID, or null if not set. Surfaced in
-     * list_profiles output so callers can tell which profile the current
-     * session is targeting without making a second call. Optional.
-     */
-    getActiveUserId?(): string | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slack/radar-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "MCP server and web dashboard for on-device debugging of the Slack Android app via ADB",
   "type": "module",
   "main": "dist/mcp/index.js",