@slack/radar-mcp 1.2.0 → 1.4.0

package/dist/mcp/index.js

@@ -2,72 +2,220 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { spawn } from "child_process";
 import fs from "fs";
 import http from "http";
+import path from "path";
+import { fileURLToPath } from "url";
 import { AndroidTransport } from "../shared/android.js";
-import { RADAR_HOST, RADAR_PORT } from "../shared/constants.js";
+import { RADAR_HOST, RADAR_PORT, WEB_PORT_DEFAULT } 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 { TOOL_DEFINITIONS, SERVER_INSTRUCTIONS } from "./tools.js";
-// --- Platform selection ---
-function createTransport() {
-    const platformArg = process.argv.find((a) => a.startsWith("--platform="));
-    const platform = platformArg?.split("=")[1] ?? "android";
-    switch (platform) {
-        case "android":
-            return new AndroidTransport();
-        default:
-            throw new Error(`Unsupported platform: ${platform}. Supported: android`);
-    }
+import { buildBufferPath, createSnapshot } from "./snapshot.js";
+import { TOOL_DEFINITIONS, SERVER_INSTRUCTIONS, sessionGate } from "./tools.js";
+// --- Subcommand + bin-name dispatch ---
+//
+// One entrypoint, two front doors, chosen so each invocation does the obvious thing:
+//
+//   slack-radar            -> web dashboard   (the human launcher: bare = open the UI)
+//   slack-radar web        -> web dashboard
+//   slack-radar mcp        -> stdio MCP server (explicit, if a human ever needs it)
+//   radar-mcp              -> stdio MCP server  (the name MCP hosts configure; no arg)
+//   slack-radar-mcp        -> stdio MCP server
+//   npx @slack/radar-mcp web -> web dashboard   (npx picks the radar-mcp bin; "web" arg)
+//   slack-radar-web        -> web dashboard      (dedicated bin, still works)
+//
+// Rationale: a person typing `slack-radar` wants the UI, not a process that blocks
+// on stdin looking hung. But `radar-mcp`/`slack-radar-mcp` are what editor/agent MCP
+// configs launch with no args, so those MUST stay stdio. We disambiguate on the
+// invoked bin name (argv[1]) and allow an explicit subcommand to override either way.
+const sub = process.argv[2];
+const binName = (process.argv[1] ?? "").split("/").pop() ?? "";
+const wantsWeb = sub === "web" || (binName === "slack-radar" && sub !== "mcp");
+// --- Web dashboard bridge (open_radar_dashboard) ---
+//
+// The MCP server and the web dashboard are separate processes. open_radar_dashboard
+// ensures the web server is up (spawning it detached if not) and POSTs the authored
+// spec to its /setspec route — the same route the pre-built tabs use — so it appears
+// as a "Custom" tab. Both sides resolve the port from SLACK_RADAR_WEB_PORT (default
+// WEB_PORT_DEFAULT) so they never drift.
+const WEB_BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "web", "bin.js");
+const WEB_PORT = Number(process.env.SLACK_RADAR_WEB_PORT ?? WEB_PORT_DEFAULT);
+const WEB_BASE = `http://localhost:${WEB_PORT}`;
+function webAlive() {
+    return new Promise((resolve) => {
+        const req = http.request({ host: "localhost", port: WEB_PORT, path: "/health", method: "GET", timeout: 1500 }, (res) => {
+            res.resume();
+            resolve(true);
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.end();
+    });
+}
+function startWeb(initialSpec) {
+    // Detached + unref so the dashboard outlives this MCP process; inherit env so the
+    // child honors the same SLACK_RADAR_WEB_PORT. Reuse the current node binary rather
+    // than assuming `node` is on PATH (MCP hosts often launch with a bare PATH).
+    //
+    // Seed the spec via SLACK_RADAR_INITIAL_SPEC so the freshly-spawned server writes the
+    // custom spec at startup, BEFORE the browser opens and runs bootDefault(). Otherwise
+    // bootDefault (fires only on a blank spec) and our /setspec POST race, and a lost race
+    // leaves the Live preset showing after we already reported the Custom tab is live.
+    // SLACK_RADAR_NO_OPEN: this is a bridge-spawned dashboard, so the server must NOT
+    // auto-open a browser (the Claude Code session returns the URL; popping a window unbidden would
+    // violate the no-auto-open-browser rule the SERVER_INSTRUCTIONS state for /radar-ui).
+    const child = spawn(process.execPath, [WEB_BIN], {
+        detached: true,
+        stdio: "ignore",
+        env: {
+            ...process.env,
+            SLACK_RADAR_NO_OPEN: "1",
+            ...(initialSpec ? { SLACK_RADAR_INITIAL_SPEC: JSON.stringify(initialSpec) } : {}),
+        },
+    });
+    child.unref();
 }
-const device = createTransport();
-setTransport(device);
-let sessionEnabled = false;
-function radarRequest(requestPath) {
+function postSpec(spec) {
     return new Promise((resolve, reject) => {
-        const req = http.get({
-            host: RADAR_HOST,
-            port: RADAR_PORT,
-            path: requestPath,
-            timeout: 10000,
+        const body = JSON.stringify(spec);
+        const req = http.request({
+            host: "localhost",
+            port: WEB_PORT,
+            path: "/setspec",
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) },
+            timeout: 4000,
         }, (res) => {
-            let data = "";
-            res.on("data", (chunk) => {
-                data += chunk;
-            });
+            let b = "";
+            res.on("data", (c) => (b += c));
             res.on("end", () => {
                 try {
-                    resolve(JSON.parse(data));
+                    resolve({ status: res.statusCode ?? 0, json: JSON.parse(b) });
                 }
                 catch {
-                    resolve({ raw: data });
+                    resolve({ status: res.statusCode ?? 0, json: {} });
                 }
             });
         });
         req.on("error", reject);
         req.on("timeout", () => {
             req.destroy();
-            reject(new Error("Request timed out"));
+            reject(new Error("timed out posting spec to the dashboard"));
         });
+        req.write(body);
+        req.end();
     });
 }
-async function callRadar(requestPath) {
-    if (!device.ensureForward()) {
-        return {
-            error: "Port forwarding failed. Ensure a device is connected and the debug build is running.",
-        };
+function getSpecTitle() {
+    return new Promise((resolve) => {
+        const req = http.request({ host: "localhost", port: WEB_PORT, path: "/spec", method: "GET", timeout: 2000 }, (res) => {
+            let b = "";
+            res.on("data", (c) => (b += c));
+            res.on("end", () => {
+                try {
+                    const s = JSON.parse(b);
+                    resolve(s.blank ? null : (s.title ?? ""));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on("error", () => resolve(null));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(null);
+        });
+        req.end();
+    });
+}
+async function openDashboardSpec(spec) {
+    const cold = !(await webAlive());
+    if (cold) {
+        // Seed the spec into the spawned server so it is the startup writer and the browser's
+        // bootDefault() never overwrites it with the Live preset (see startWeb / server.ts).
+        startWeb(spec);
+        // Poll for the freshly-spawned server to start listening (~5s budget).
+        for (let i = 0; i < 20; i++) {
+            await new Promise((r) => setTimeout(r, 250));
+            if (await webAlive())
+                break;
+        }
     }
-    device.activate(device.getTimeoutMinutes());
-    connectStream();
-    try {
-        return await radarRequest(requestPath);
+    const r = await postSpec(spec);
+    if (r.status !== 200) {
+        throw new Error(r.json.error ?? `dashboard rejected the spec (HTTP ${r.status})`);
+    }
+    // Confirm OUR spec is the one stored, not a racing writer's (a browser bootDefault on a
+    // cold load, or another open_radar_dashboard call). The seed makes the cold path safe by
+    // construction; this verify is the backstop and also covers the warm path. Retry the POST
+    // once if a racer won, then trust the result rather than blocking forever.
+    const want = spec.title ?? "";
+    for (let i = 0; i < 2; i++) {
+        const stored = await getSpecTitle();
+        if (stored === want)
+            break;
+        await postSpec(spec);
+    }
+    return r.json;
+}
+if (wantsWeb) {
+    await import("../web/bin.js");
+}
+else {
+    await runMcpServer();
+}
+async function runMcpServer() {
+    // --- Platform selection ---
+    function createTransport() {
+        const platformArg = process.argv.find((a) => a.startsWith("--platform="));
+        const platform = platformArg?.split("=")[1] ?? "android";
+        switch (platform) {
+            case "android":
+                return new AndroidTransport();
+            default:
+                throw new Error(`Unsupported platform: ${platform}. Supported: android`);
+        }
     }
-    catch {
-        device.resetState();
-        destroyStream();
+    const device = createTransport();
+    setTransport(device);
+    let sessionEnabled = false;
+    function radarRequest(requestPath) {
+        return new Promise((resolve, reject) => {
+            const req = http.get({
+                host: RADAR_HOST,
+                port: RADAR_PORT,
+                path: requestPath,
+                timeout: 10000,
+            }, (res) => {
+                let data = "";
+                res.on("data", (chunk) => {
+                    data += chunk;
+                });
+                res.on("end", () => {
+                    try {
+                        resolve(JSON.parse(data));
+                    }
+                    catch {
+                        resolve({ raw: data });
+                    }
+                });
+            });
+            req.on("error", reject);
+            req.on("timeout", () => {
+                req.destroy();
+                reject(new Error("Request timed out"));
+            });
+        });
+    }
+    async function callRadar(requestPath) {
         if (!device.ensureForward()) {
-            sessionEnabled = false;
             return {
-                error: "Device not connected or radar not running. Session disabled. Use /radar-enable to reconnect.",
+                error: "Port forwarding failed. Ensure a device is connected and the debug build is running.",
             };
         }
         device.activate(device.getTimeoutMinutes());
@@ -75,334 +223,407 @@ async function callRadar(requestPath) {
         try {
             return await radarRequest(requestPath);
         }
-        catch (e2) {
+        catch {
+            device.resetState();
+            destroyStream();
+            if (!device.ensureForward()) {
+                sessionEnabled = false;
+                return {
+                    error: "Device not connected or radar not running. Session disabled. Use /radar-enable to reconnect.",
+                };
+            }
+            device.activate(device.getTimeoutMinutes());
+            connectStream();
+            try {
+                return await radarRequest(requestPath);
+            }
+            catch (e2) {
+                sessionEnabled = false;
+                return {
+                    error: `Radar not responding: ${e2.message}. Session disabled. Use /radar-enable to reconnect.`,
+                };
+            }
+        }
+    }
+    function textResult(data, isError = false) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+                },
+            ],
+            ...(isError ? { isError: true } : {}),
+        };
+    }
+    // --- Tool handlers ---
+    async function handleSessionEnable(args) {
+        const timeout = args?.timeout_minutes || 5;
+        sessionEnabled = true;
+        const forwarded = device.ensureForward();
+        if (!forwarded) {
             sessionEnabled = false;
-            return {
-                error: `Radar not responding: ${e2.message}. Session disabled. Use /radar-enable to reconnect.`,
-            };
+            const reason = device.getLastForwardError?.() ?? null;
+            return textResult({
+                error: reason ??
+                    "Port forwarding failed. Ensure a device is connected.",
+                enabled: false,
+                platform: device.platform,
+            }, true);
+        }
+        device.activate(timeout);
+        connectStream();
+        await new Promise((r) => setTimeout(r, 500));
+        try {
+            const status = await radarRequest("/api/ping");
+            return textResult({
+                enabled: true,
+                platform: device.platform,
+                stream_connected: isStreamConnected(),
+                ...status,
+            });
+        }
+        catch {
+            return textResult({
+                enabled: true,
+                platform: device.platform,
+                stream_connected: isStreamConnected(),
+                ping: "failed",
+                note: "Radar activated but ping failed. Device may need a moment.",
+            });
         }
     }
-}
-function textResult(data, isError = false) {
-    return {
-        content: [
-            {
-                type: "text",
-                text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
-            },
-        ],
-        ...(isError ? { isError: true } : {}),
-    };
-}
-// --- Tool handlers ---
-async function handleSessionEnable(args) {
-    const timeout = args?.timeout_minutes || 5;
-    sessionEnabled = true;
-    const forwarded = device.ensureForward();
-    if (!forwarded) {
+    function handleSessionDisable() {
         sessionEnabled = false;
-        const reason = device.getLastForwardError?.() ?? null;
+        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({
-            error: reason ??
-                "Port forwarding failed. Ensure a device is connected.",
             enabled: false,
-            platform: device.platform,
-        }, true);
-    }
-    device.activate(timeout);
-    connectStream();
-    await new Promise((r) => setTimeout(r, 500));
-    try {
-        const status = await radarRequest("/api/ping");
-        return textResult({
-            enabled: true,
-            platform: device.platform,
-            stream_connected: isStreamConnected(),
-            ...status,
+            note: "Radar disabled. Use /radar-enable to reconnect.",
         });
     }
-    catch {
+    async function handleWaitForEvents(args) {
+        if (!isStreamConnected()) {
+            if (!device.ensureForward()) {
+                return textResult({ error: "Not connected. Ensure device is connected and radar is enabled." }, true);
+            }
+            device.activate(device.getTimeoutMinutes());
+            connectStream();
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+        const events = await waitForEvents({
+            event_type: args?.event_type,
+            channel: args?.channel,
+            source: args?.source,
+            timeout_ms: args?.timeout_ms,
+            idle_timeout_ms: args?.idle_timeout_ms,
+        });
         return textResult({
-            enabled: true,
-            platform: device.platform,
+            event_count: events.length,
+            events,
             stream_connected: isStreamConnected(),
-            ping: "failed",
-            note: "Radar activated but ping failed. Device may need a moment.",
         });
     }
-}
-function handleSessionDisable() {
-    sessionEnabled = false;
-    destroyStream();
-    clearLocalBuffers();
-    return textResult({
-        enabled: false,
-        note: "Radar disabled. Use /radar-enable to reconnect.",
-    });
-}
-async function handleWaitForEvents(args) {
-    if (!isStreamConnected()) {
-        if (!device.ensureForward()) {
-            return textResult({ error: "Not connected. Ensure device is connected and radar is enabled." }, true);
+    function handleGetAppState() {
+        try {
+            const output = device.getAppState();
+            return textResult(output);
+        }
+        catch (e) {
+            return textResult({ error: `App state query failed: ${e.message}` }, true);
         }
-        device.activate(device.getTimeoutMinutes());
-        connectStream();
-        await new Promise((r) => setTimeout(r, 1000));
-    }
-    const events = await waitForEvents({
-        event_type: args?.event_type,
-        channel: args?.channel,
-        source: args?.source,
-        timeout_ms: args?.timeout_ms,
-        idle_timeout_ms: args?.idle_timeout_ms,
-    });
-    return textResult({
-        event_count: events.length,
-        events,
-        stream_connected: isStreamConnected(),
-    });
-}
-function handleGetAppState() {
-    try {
-        const output = device.getAppState();
-        return textResult(output);
     }
-    catch (e) {
-        return textResult({ error: `App state query failed: ${e.message}` }, true);
+    function handleListProfiles() {
+        try {
+            // 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();
+            return textResult({
+                profiles,
+                active_user_id: device.getActiveUserId(),
+            });
+        }
+        catch (e) {
+            return textResult({ error: `Profile list failed: ${e.message}` }, true);
+        }
     }
-}
-function handleListProfiles() {
-    try {
-        // Narrow to implementations that expose listProfiles; the base
-        // DeviceTransport interface leaves it platform-specific.
+    async function handleActivateForUser(args) {
         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 });
-    }
-    catch (e) {
-        return textResult({ error: `Profile list failed: ${e.message}` }, true);
-    }
-}
-async function handleActivateForUser(args) {
-    const maybe = device;
-    if (typeof maybe.activateForUser !== "function") {
-        return textResult({ error: `Profile switching not supported on platform ${device.platform}` }, true);
-    }
-    try {
-        const timeout = args?.timeout_minutes || device.getTimeoutMinutes() || 5;
-        maybe.activateForUser(args.user_id, timeout);
-        // Restart the SSE stream so network/RTM/clog events from the newly
-        // activated profile start flowing again.
-        destroyStream();
-        connectStream();
-        // Give the newly spawned adb logcat child a moment to emit its first
-        // lines to the capture file. Matches the warmup delay used by
-        // 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,
-            note: "Profile activated. Log capture restarted on a new file; old capture preserved for 7 days.",
-        });
-    }
-    catch (e) {
-        return textResult({ error: `Profile activation failed: ${e.message}` }, true);
-    }
-}
-function handleGetRecentLogs(args) {
-    try {
-        const lines = device.getRecentLogs(args.tag, args.limit || 50, args.grep);
-        // Surface the capture file path so the model knows which on-disk file
-        // produced these lines. Helps avoid cross-session staleness (e.g. the
-        // model remembering an earlier profile's logs after a profile switch).
-        const sourceFile = device.getCaptureFilePath?.() ?? null;
-        return textResult({
-            tag: args.tag,
-            lines,
-            count: lines.length,
-            source_file: sourceFile,
-            source: sourceFile ? "capture" : "adb_logcat_d",
-        });
+        if (typeof maybe.activateForUser !== "function") {
+            return textResult({ error: `Profile switching not supported on platform ${device.platform}` }, true);
+        }
+        try {
+            const timeout = args?.timeout_minutes || device.getTimeoutMinutes() || 5;
+            maybe.activateForUser(args.user_id, timeout);
+            // Restart the SSE stream so network/RTM/clog events from the newly
+            // activated profile start flowing again.
+            destroyStream();
+            connectStream();
+            // Give the newly spawned adb logcat child a moment to emit its first
+            // lines to the capture file. Matches the warmup delay used by
+            // handleSessionEnable so an immediate get_recent_logs call does not
+            // read an empty file.
+            await new Promise((r) => setTimeout(r, 500));
+            return textResult({
+                user_id: args.user_id,
+                timeout_minutes: timeout,
+                capture_file: device.getCaptureFilePath?.() ?? null,
+                note: "Profile activated. Log capture restarted on a new file; old capture preserved for 7 days.",
+            });
+        }
+        catch (e) {
+            return textResult({ error: `Profile activation failed: ${e.message}` }, true);
+        }
     }
-    catch (e) {
-        return textResult({ error: `Log query failed: ${e.message}`, lines: [] }, 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 handleScreenshot(args) {
-    try {
-        const fullRes = args?.full_res === true;
-        const tmpFile = device.screenshot(fullRes);
-        const stats = fs.statSync(tmpFile);
-        return textResult({
-            file: tmpFile,
-            size_bytes: stats.size,
-            full_res: fullRes,
-            hint: "Use the Read tool to view this image.",
-        });
+    function handleGetRecentLogs(args) {
+        try {
+            const lines = device.getRecentLogs(args.tag, args.limit || 50, args.grep);
+            // Surface the capture file path so the model knows which on-disk file
+            // produced these lines. Helps avoid cross-session staleness (e.g. the
+            // model remembering an earlier profile's logs after a profile switch).
+            const sourceFile = device.getCaptureFilePath?.() ?? null;
+            return textResult({
+                tag: args.tag,
+                lines,
+                count: lines.length,
+                source_file: sourceFile,
+                source: sourceFile ? "capture" : "adb_logcat_d",
+            });
+        }
+        catch (e) {
+            return textResult({ error: `Log query failed: ${e.message}`, lines: [] }, true);
+        }
     }
-    catch (e) {
-        return textResult({ error: `Screenshot failed: ${e.message}` }, true);
+    function handleScreenshot(args) {
+        try {
+            const fullRes = args?.full_res === true;
+            const tmpFile = device.screenshot(fullRes);
+            const stats = fs.statSync(tmpFile);
+            return textResult({
+                file: tmpFile,
+                size_bytes: stats.size,
+                full_res: fullRes,
+                hint: "Use the Read tool to view this image.",
+            });
+        }
+        catch (e) {
+            return textResult({ error: `Screenshot failed: ${e.message}` }, true);
+        }
     }
-}
-function handleRecordScreen(args) {
-    try {
-        const duration = Math.min(Math.max(args?.duration_s || 5, 1), 30);
-        const tmpFile = device.recordScreen(duration);
-        const stats = fs.statSync(tmpFile);
-        return textResult({
-            file: tmpFile,
-            size_bytes: stats.size,
-            duration_s: duration,
-        });
+    function handleRecordScreen(args) {
+        try {
+            const duration = Math.min(Math.max(args?.duration_s || 5, 1), 30);
+            const tmpFile = device.recordScreen(duration);
+            const stats = fs.statSync(tmpFile);
+            return textResult({
+                file: tmpFile,
+                size_bytes: stats.size,
+                duration_s: duration,
+            });
+        }
+        catch (e) {
+            return textResult({ error: `Recording failed: ${e.message}` }, true);
+        }
     }
-    catch (e) {
-        return textResult({ error: `Recording failed: ${e.message}` }, true);
+    async function handleClearBuffers() {
+        clearLocalBuffers();
+        const result = await callRadar("/api/clear");
+        return textResult(result, !!result.error);
     }
-}
-async function handleClearBuffers() {
-    clearLocalBuffers();
-    const result = await callRadar("/api/clear");
-    return textResult(result, !!result.error);
-}
-async function handlePing(args) {
-    if (args?.timeout_minutes) {
-        device.activate(args.timeout_minutes);
+    async function handlePing(args) {
+        if (args?.timeout_minutes) {
+            device.activate(args.timeout_minutes);
+        }
+        const result = await callRadar("/api/ping");
+        if (!result.error) {
+            result.stream_connected = isStreamConnected();
+            result.local_network_buffer = localNetworkBuffer.length;
+            result.local_rtm_buffer = localRtmBuffer.length;
+            result.timeout_minutes = device.getTimeoutMinutes();
+            result.platform = device.platform;
+        }
+        return textResult(result, !!result.error);
     }
-    const result = await callRadar("/api/ping");
-    if (!result.error) {
-        result.stream_connected = isStreamConnected();
-        result.local_network_buffer = localNetworkBuffer.length;
-        result.local_rtm_buffer = localRtmBuffer.length;
-        result.timeout_minutes = device.getTimeoutMinutes();
-        result.platform = device.platform;
+    async function handleOpenDashboard(args) {
+        try {
+            // The web server runs its own coerce+validate on /setspec, so a thin pass of
+            // the authored args is enough; a bad spec comes back as an HTTP 400 with its
+            // reason, which we surface verbatim rather than rendering silent zeros.
+            const out = await openDashboardSpec(args);
+            const url = out.url ?? WEB_BASE;
+            return textResult({
+                ok: true,
+                url,
+                title: out.title ?? args.title ?? "",
+                note: `Custom dashboard "${out.title ?? args.title ?? ""}" is live at ${url} (the 'Custom' tab). ` +
+                    "It reads the connected device, so Slack Radar must be enabled on it — the dashboard has " +
+                    "its own Reconnect button if the device is not yet armed. Call open_radar_dashboard again to refine it.",
+            });
+        }
+        catch (e) {
+            return textResult({
+                error: `Could not open the dashboard: ${e.message}`,
+                hint: "The web dashboard runs locally on this machine. Check that the spec is valid and try again.",
+            }, true);
+        }
     }
-    return textResult(result, !!result.error);
-}
-function buildApiPath(name, args) {
-    switch (name) {
-        case "get_recent_network_calls": {
-            const a = args;
-            const params = new URLSearchParams();
-            if (a?.limit)
-                params.set("limit", String(a.limit));
-            if (a?.url_filter)
-                params.set("url_filter", a.url_filter);
-            if (a?.status_code)
-                params.set("status_code", String(a.status_code));
-            const qs = params.toString();
-            return `/api/network${qs ? "?" + qs : ""}`;
-        }
-        case "get_network_call_detail": {
-            const a = args;
-            return `/api/network/${a.id}`;
-        }
-        case "get_recent_rtm_events": {
-            const a = args;
-            const params = new URLSearchParams();
-            if (a?.limit)
-                params.set("limit", String(a.limit));
-            if (a?.event_type)
-                params.set("event_type", a.event_type);
-            if (a?.direction)
-                params.set("direction", a.direction);
-            if (a?.channel)
-                params.set("channel", a.channel);
-            const qs = params.toString();
-            return `/api/rtm${qs ? "?" + qs : ""}`;
-        }
-        case "get_rtm_event_detail": {
-            const a = args;
-            return `/api/rtm/${a.id}`;
-        }
-        case "get_recent_clogs": {
-            const a = args;
-            const params = new URLSearchParams();
-            if (a?.limit)
-                params.set("limit", String(a.limit));
-            if (a?.name)
-                params.set("name", a.name);
-            const qs = params.toString();
-            return `/api/clogs${qs ? "?" + qs : ""}`;
-        }
-        case "get_clog_detail": {
-            const a = args;
-            return `/api/clogs/${a.id}`;
-        }
-        case "search": {
-            const a = args;
-            const params = new URLSearchParams();
-            params.set("q", a.query);
-            if (a?.limit)
-                params.set("limit", String(a.limit));
-            return `/api/search?${params.toString()}`;
-        }
-        default:
-            return null;
+    function buildApiPath(name, args) {
+        switch (name) {
+            case "get_recent_network_calls": {
+                const a = args;
+                const params = new URLSearchParams();
+                if (a?.limit)
+                    params.set("limit", String(a.limit));
+                if (a?.url_filter)
+                    params.set("url_filter", a.url_filter);
+                if (a?.status_code)
+                    params.set("status_code", String(a.status_code));
+                const qs = params.toString();
+                return `/api/network${qs ? "?" + qs : ""}`;
+            }
+            case "get_network_call_detail": {
+                const a = args;
+                return `/api/network/${a.id}`;
+            }
+            case "get_recent_rtm_events": {
+                const a = args;
+                const params = new URLSearchParams();
+                if (a?.limit)
+                    params.set("limit", String(a.limit));
+                if (a?.event_type)
+                    params.set("event_type", a.event_type);
+                if (a?.direction)
+                    params.set("direction", a.direction);
+                if (a?.channel)
+                    params.set("channel", a.channel);
+                const qs = params.toString();
+                return `/api/rtm${qs ? "?" + qs : ""}`;
+            }
+            case "get_rtm_event_detail": {
+                const a = args;
+                return `/api/rtm/${a.id}`;
+            }
+            case "get_recent_clogs": {
+                const a = args;
+                const params = new URLSearchParams();
+                if (a?.limit)
+                    params.set("limit", String(a.limit));
+                if (a?.name)
+                    params.set("name", a.name);
+                const qs = params.toString();
+                return `/api/clogs${qs ? "?" + qs : ""}`;
+            }
+            case "get_clog_detail": {
+                const a = args;
+                return `/api/clogs/${a.id}`;
+            }
+            case "search": {
+                const a = args;
+                const params = new URLSearchParams();
+                params.set("q", a.query);
+                if (a?.limit)
+                    params.set("limit", String(a.limit));
+                return `/api/search?${params.toString()}`;
+            }
+            default:
+                return null;
+        }
     }
+    // --- MCP Server ---
+    const server = new Server({ name: "slack-radar", version: "1.4.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOL_DEFINITIONS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, _extra) => {
+        const { name, arguments: args } = request.params;
+        const toolArgs = (args ?? {});
+        if (name === "_radar_session_enable") {
+            return handleSessionEnable(toolArgs);
+        }
+        if (name === "_radar_session_disable") {
+            return handleSessionDisable();
+        }
+        // Single source of truth for the session gate (also unit-tested in tools.test.mjs).
+        // Returns an error result when a tool requires an enabled session and there is none;
+        // null when the tool is allowed (ping, the session enable/disable verbs, and
+        // open_radar_dashboard — the dashboard is an independent local process with its own
+        // device-enable Reconnect button, so opening it does not need an enabled MCP session).
+        const gate = sessionGate(name, sessionEnabled);
+        if (gate) {
+            return textResult(JSON.parse(gate.content[0].text), gate.isError);
+        }
+        if (name === "open_radar_dashboard") {
+            return handleOpenDashboard(toolArgs);
+        }
+        if (name === "wait_for_events") {
+            return handleWaitForEvents(toolArgs);
+        }
+        if (name === "get_app_state") {
+            return handleGetAppState();
+        }
+        if (name === "list_profiles") {
+            return handleListProfiles();
+        }
+        if (name === "activate_for_user") {
+            return handleActivateForUser(toolArgs);
+        }
+        if (name === "get_recent_logs") {
+            return handleGetRecentLogs(toolArgs);
+        }
+        if (name === "capture_snapshot") {
+            return handleCaptureSnapshot(toolArgs);
+        }
+        if (name === "screenshot") {
+            return handleScreenshot(toolArgs);
+        }
+        if (name === "record_screen") {
+            return handleRecordScreen(toolArgs);
+        }
+        if (name === "clear_buffers") {
+            return handleClearBuffers();
+        }
+        if (name === "ping") {
+            return handlePing(toolArgs);
+        }
+        const apiPath = buildApiPath(name, toolArgs);
+        if (apiPath === null) {
+            return textResult(`Unknown tool: ${name}`, true);
+        }
+        const result = await callRadar(apiPath);
+        return textResult(result, !!result.error);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
 }
-// --- MCP Server ---
-const server = new Server({ name: "slack-radar", version: "1.2.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: TOOL_DEFINITIONS,
-}));
-server.setRequestHandler(CallToolRequestSchema, async (request, _extra) => {
-    const { name, arguments: args } = request.params;
-    const toolArgs = (args ?? {});
-    if (name === "_radar_session_enable") {
-        return handleSessionEnable(toolArgs);
-    }
-    if (name === "_radar_session_disable") {
-        return handleSessionDisable();
-    }
-    if (!sessionEnabled && name !== "ping") {
-        return textResult({
-            error: "Radar is not active. Use /radar-enable to connect, or ask about the device to auto-enable.",
-        }, true);
-    }
-    if (name === "wait_for_events") {
-        return handleWaitForEvents(toolArgs);
-    }
-    if (name === "get_app_state") {
-        return handleGetAppState();
-    }
-    if (name === "list_profiles") {
-        return handleListProfiles();
-    }
-    if (name === "activate_for_user") {
-        return handleActivateForUser(toolArgs);
-    }
-    if (name === "get_recent_logs") {
-        return handleGetRecentLogs(toolArgs);
-    }
-    if (name === "screenshot") {
-        return handleScreenshot(toolArgs);
-    }
-    if (name === "record_screen") {
-        return handleRecordScreen(toolArgs);
-    }
-    if (name === "clear_buffers") {
-        return handleClearBuffers();
-    }
-    if (name === "ping") {
-        return handlePing(toolArgs);
-    }
-    const apiPath = buildApiPath(name, toolArgs);
-    if (apiPath === null) {
-        return textResult(`Unknown tool: ${name}`, true);
-    }
-    const result = await callRadar(apiPath);
-    return textResult(result, !!result.error);
-});
-const transport = new StdioServerTransport();
-await server.connect(transport);