@slack/radar-mcp 1.7.0 → 1.8.0

package/dist/mcp/index.js

@@ -17,6 +17,7 @@ import { handleListDatabases, handleListTables, handleQueryDatabase, } from "./d
 import { cleanupPulledDatabases, initializeDatabasePath, resetDbState, } from "../shared/db.js";
 import { TOOL_DEFINITIONS, SERVER_INSTRUCTIONS, sessionGate } from "./tools.js";
 import { buildApiPath } from "./api-paths.js";
+import { interpretRadarResponse } from "./radar-response.js";
 // --- Subcommand + bin-name dispatch ---
 //
 // One entrypoint, two front doors, chosen so each invocation does the obvious thing:
@@ -200,6 +201,7 @@ async function runMcpServer() {
         process.once(sig, cleanupPulledDatabases);
     }
     let sessionEnabled = false;
+    // --- HTTP requests to the on-device radar server ---
     // Host-side ceiling on a proxied device response. radarRequest forwards the device body straight
     // into the model context, so an unbounded response (large trace/clog payloads) could flood it.
     // When the cap trips we stop reading, tear the socket down, and return a truncation marker
@@ -249,12 +251,7 @@ async function runMcpServer() {
                     data += chunk;
                 });
                 res.on("end", () => {
-                    try {
-                        done(JSON.parse(data));
-                    }
-                    catch {
-                        done({ raw: data });
-                    }
+                    done(interpretRadarResponse(res.statusCode ?? 0, data));
                 });
             });
             req.on("error", fail);
@@ -552,7 +549,7 @@ async function runMcpServer() {
         }
     }
     // --- MCP Server ---
-    const server = new Server({ name: "slack-radar", version: "1.7.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+    const server = new Server({ name: "slack-radar", version: "1.8.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: TOOL_DEFINITIONS,
     }));

package/dist/mcp/radar-response.d.ts

@@ -0,0 +1,21 @@
+export interface RadarResponse {
+    error?: string;
+    status?: number;
+    stream_connected?: boolean;
+    local_network_buffer?: number;
+    local_rtm_buffer?: number;
+    timeout_minutes?: number;
+    raw?: string;
+    [key: string]: unknown;
+}
+/**
+ * Turn a device HTTP (status, body) into the RadarResponse the tool layer returns. Parse JSON
+ * when the body is JSON: this preserves the device's own error bodies (e.g. an in-app 404 sends
+ * {"error":"Not Found"}) and every happy-path payload unchanged. The added guard is for a 4xx/5xx
+ * whose body is NOT JSON (empty, HTML, a bare string): a build that predates a tool's route, or
+ * an upstream proxy error, would otherwise surface as a confusing {raw:""} the caller cannot read.
+ * In that case synthesize a clear error naming the status so the model reports something useful
+ * (an older debug build can predate a newer tool) instead of an empty blob. A 2xx with a non-JSON
+ * body keeps the existing {raw} behavior, a real if unusual success payload.
+ */
+export declare function interpretRadarResponse(status: number, body: string): RadarResponse;

package/dist/mcp/radar-response.js

@@ -0,0 +1,38 @@
+// The shape a proxied device call resolves to, and how a raw (status, body) becomes one. Split
+// out of index.ts so it is unit-testable: index.ts connects stdio at module load, so importing it
+// from a test would hang.
+/**
+ * Turn a device HTTP (status, body) into the RadarResponse the tool layer returns. Parse JSON
+ * when the body is JSON: this preserves the device's own error bodies (e.g. an in-app 404 sends
+ * {"error":"Not Found"}) and every happy-path payload unchanged. The added guard is for a 4xx/5xx
+ * whose body is NOT JSON (empty, HTML, a bare string): a build that predates a tool's route, or
+ * an upstream proxy error, would otherwise surface as a confusing {raw:""} the caller cannot read.
+ * In that case synthesize a clear error naming the status so the model reports something useful
+ * (an older debug build can predate a newer tool) instead of an empty blob. A 2xx with a non-JSON
+ * body keeps the existing {raw} behavior, a real if unusual success payload.
+ */
+export function interpretRadarResponse(status, body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        if (status >= 400) {
+            const bodyPrefix = body.substring(0, 200).trim();
+            const bodyDetail = bodyPrefix ? ` Body: ${bodyPrefix}` : "";
+            return {
+                error: `Device returned HTTP ${status} with a non-JSON body. The route may not exist on this build (an older debug build can predate a newer tool), or an upstream error occurred.${bodyDetail}`,
+                status,
+            };
+        }
+        return { raw: body };
+    }
+    // Device routes return JSON OBJECTS. A bare null/number/array/string is valid JSON but not a
+    // RadarResponse, and a downstream `result.error` read on a non-object (esp. null) would throw.
+    // Keep it as a raw payload instead of casting a lie. (The old code cast straight to
+    // RadarResponse and carried this hole; guarding here closes it.)
+    if (typeof parsed !== "object" || parsed === null) {
+        return { raw: body };
+    }
+    return parsed;
+}

package/dist/mcp/snapshot.d.ts

@@ -13,6 +13,7 @@ export interface SnapshotResult {
         network: number;
         rtm: number;
         clogs: number;
+        traces: number;
         log_lines: number;
         log_lines_truncated: boolean;
         screenshot: boolean;
@@ -21,6 +22,7 @@ export interface SnapshotResult {
         network: boolean;
         rtm: boolean;
         clogs: boolean;
+        traces: boolean;
     };
     errors: string[];
     privacy_notice: string;
@@ -35,7 +37,7 @@ export declare function buildSnapshotDir(now?: number, root?: string): string;
  * 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 declare function buildBufferPath(kind: "network" | "rtm" | "clogs" | "traces"): string;
 export interface LogTailResult {
     text: string;
     truncated: boolean;
@@ -60,4 +62,4 @@ export declare function readRecentLogTail(requestedLimit?: number): LogTailResul
  * 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>;
+export declare function createSnapshot(device: DeviceTransport, fetchBuffer: (kind: "network" | "rtm" | "clogs" | "traces") => Promise<unknown>, opts?: SnapshotOptions, now?: number, snapshotRoot?: string): Promise<SnapshotResult>;

package/dist/mcp/snapshot.js

@@ -10,7 +10,7 @@ import { getCaptureFilePath, readTailBytes } from "../shared/logcat-capture.js";
  * tool outputs.
  *
  * Snapshot contents:
- *   - `bundle.json` — device-side buffers (net + RTM + clogs) plus metadata
+ *   - `bundle.json` — device-side buffers (net + RTM + clogs + traces) plus metadata
  *   - `screenshot.png` — current screen (optional)
  *   - `logcat.tail.log` — last N lines of the active capture file (optional)
  *
@@ -33,19 +33,19 @@ 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.
+- bundle.json: device-side network/RTM/clog/trace 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.
+tokens), RTM message content, user IDs, channel IDs, clog payloads, and
+performance trace spans. 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.";
+const PRIVACY_NOTICE = "bundle.json contains raw API request/response bodies (including auth headers), RTM message content, user IDs, clog payloads, and performance trace spans. Review before sharing externally.";
 /**
  * Resolve the output directory for a snapshot. Exported for tests.
  */
@@ -137,7 +137,8 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
     let network = null;
     let rtm = null;
     let clogs = null;
-    const fetched = { network: false, rtm: false, clogs: false };
+    let traces = null;
+    const fetched = { network: false, rtm: false, clogs: false, traces: 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
@@ -163,6 +164,17 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
     catch (e) {
         errors.push(`clog buffer: ${e.message}`);
     }
+    // Traces capture from app start (like clogs), so they are worth
+    // bundling. An older debug build without the /api/traces route fails
+    // this one fetch and it is recorded in errors[] like any other buffer;
+    // the rest of the snapshot still lands.
+    try {
+        traces = await fetchBuffer("traces");
+        fetched.traces = true;
+    }
+    catch (e) {
+        errors.push(`trace buffer: ${e.message}`);
+    }
     // Logcat tail.
     let logTail = { text: "", truncated: false };
     if (includeLogs) {
@@ -221,6 +233,7 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
         network: countItems(network),
         rtm: countItems(rtm),
         clogs: countItems(clogs),
+        traces: countItems(traces),
         log_lines: logTail.text
             ? logTail.text.split("\n").filter(Boolean).length
             : 0,
@@ -228,12 +241,12 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
         screenshot: screenshotCaptured,
     };
     const bundle = {
-        version: 1,
+        version: 2,
         timestamp: now,
         platform: device.platform,
         active_user_id: device.getActiveUserId(),
         capture_file: getCaptureFilePath(),
-        buffers: { network, rtm, clogs },
+        buffers: { network, rtm, clogs, traces },
         counts,
         fetched,
         errors,
@@ -285,14 +298,14 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
 }
 /**
  * Count items inside a buffer response. Handles the `{ calls: [...] }`,
- * `{ events: [...] }`, `{ clogs: [...] }` shapes the radar HTTP server
- * uses. Falls back to 0 on malformed responses.
+ * `{ events: [...] }`, `{ clogs: [...] }`, `{ traces: [...] }` 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"]) {
+    for (const key of ["calls", "events", "clogs", "traces", "items"]) {
         const v = b[key];
         if (Array.isArray(v))
             return v.length;

package/dist/mcp/tools.js

@@ -102,10 +102,10 @@ export const SERVER_INSTRUCTIONS = [
     "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).",
+    "  2. A one-line summary of counts (network/rtm/clogs/traces/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."',
+    '     "Privacy: bundle.json contains raw API request/response bodies (including auth headers), RTM message content, user IDs, clog payloads, and performance trace spans. 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' /",
@@ -302,7 +302,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         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.",
+        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 + trace 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, clog payloads, and performance trace spans — review before sharing externally.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/shared/db.d.ts

@@ -77,6 +77,19 @@ export declare function pullDatabase(name: string, user?: string | null, force?:
  * (1) and (2), not from the open mode.
  */
 export declare function assertReadOnlyQuery(sql: string): void;
+/**
+ * True for EXPLAIN / EXPLAIN QUERY PLAN, which sqlite3 prints as a text table (ignoring -json).
+ * Leading-token match; assertReadOnlyQuery gates the same leading keyword, so both reject on
+ * comment-prefixed queries before this routing matters.
+ */
+export declare function isExplainQuery(sql: string): boolean;
+/**
+ * sqlite3 ignores -json for EXPLAIN (prints text table instead of JSON).
+ * Shape it into row objects so the web grid renders the plan readably.
+ */
+export declare function parseExplainOutput(out: string): {
+    plan: string;
+}[];
 /**
  * Run a read-only query against a (lazily pulled) local copy. The query is gated by
  * assertReadOnlyQuery (see there for the full read-only/exfil rationale). Surfaces sqlite's

package/dist/shared/db.js

@@ -353,6 +353,24 @@ export function assertReadOnlyQuery(sql) {
         throw new Error("that function/statement is not allowed (read-only, no file access)");
     }
 }
+/**
+ * True for EXPLAIN / EXPLAIN QUERY PLAN, which sqlite3 prints as a text table (ignoring -json).
+ * Leading-token match; assertReadOnlyQuery gates the same leading keyword, so both reject on
+ * comment-prefixed queries before this routing matters.
+ */
+export function isExplainQuery(sql) {
+    return /^\s*explain\b/i.test(sql);
+}
+/**
+ * sqlite3 ignores -json for EXPLAIN (prints text table instead of JSON).
+ * Shape it into row objects so the web grid renders the plan readably.
+ */
+export function parseExplainOutput(out) {
+    return out
+        .split("\n")
+        .filter((line) => line.trim().length > 0)
+        .map((line) => ({ plan: line }));
+}
 /**
  * Run a read-only query against a (lazily pulled) local copy. The query is gated by
  * assertReadOnlyQuery (see there for the full read-only/exfil rationale). Surfaces sqlite's
@@ -365,6 +383,12 @@ export async function queryDatabase(name, sql, user) {
     const local = localPath(name, u);
     if (!fs.existsSync(local))
         await pullDatabase(name, u);
+    // EXPLAIN / EXPLAIN QUERY PLAN are read-query-shaped (they pass the gate) but sqlite3 IGNORES
+    // -json for them: it prints a fixed-width opcode/plan TEXT table, not JSON, so JSON.parse below
+    // would throw "Unexpected token" and the user sees a confusing parse error for a query that
+    // actually ran. Handle them as text: one result row per output line under a single column, so
+    // the existing grid renders the plan readably instead of choking.
+    const explain = isExplainQuery(sql);
     let out;
     try {
         // Open the pulled copy NORMALLY (not `immutable`, not `-readonly`): pullDatabase brought
@@ -375,14 +399,15 @@ export async function queryDatabase(name, sql, user) {
         // is touched. `-safe` is the load-bearing read-only/exfil control (blocks ATTACH/readfile/
         // writefile/load_extension at the engine level) and holds in normal mode too. The path is
         // URI-encoded so spaces/specials are safe. Async exec so a large query does not block the
-        // event loop.
+        // event loop. -json for normal queries; plain text for EXPLAIN (sqlite ignores -json there).
         const uri = `file:${encodeURI(local)}`;
-        const r = await execFileP(sqliteBin(), ["-safe", "-json", uri, sql], {
+        const args = explain ? ["-safe", uri, sql] : ["-safe", "-json", uri, sql];
+        const r = await execFileP(sqliteBin(), args, {
             timeout: 15000,
             maxBuffer: SQLITE_MAX_BUFFER,
             encoding: "utf8",
         });
-        out = String(r.stdout) || "[]";
+        out = String(r.stdout) || (explain ? "" : "[]");
     }
     catch (e) {
         const err = e;
@@ -390,6 +415,8 @@ export async function queryDatabase(name, sql, user) {
         const m = stderr.match(/(no such table:.*|no such column:.*|near ".*|syntax error.*|.*error.*)/i);
         throw new Error(m ? m[0].trim() : stderr.split("\n")[0] || "query failed");
     }
+    if (explain)
+        return parseExplainOutput(out);
     return JSON.parse(out);
 }
 /** Size in bytes of a pulled local copy for the given user, or 0 if not pulled. */

package/dist/web/public/next/store.js

@@ -100,6 +100,12 @@ class Store {
     _localPushKey = null;
     _lastBoundLabel = null;
     _backfillToken = 0;
+    // True while the connection is in a dropped/waiting state. Lets pollHealth detect the
+    // drop->recover EDGE (device came back) so it can re-open the stream + backfill ONCE on
+    // recovery, instead of every poll. Without this, an auto-recovered tab flips the dot to
+    // connected but the dead EventSource is never re-opened and the device ring is never pulled,
+    // so the tab shows nothing until a manual refresh.
+    _dropped = false;
     _rafPending = false;
     _intervals = [];
     // ---- shared detail cache (bounded FIFO) ----
@@ -204,6 +210,7 @@ class Store {
         this._localPushKey = null;
         this._lastBoundLabel = null;
         this._backfillToken = 0;
+        this._dropped = false;
         this._rafPending = false;
     }
     // ---- start everything ----
@@ -317,7 +324,12 @@ class Store {
         this.closeStream();
         const es = new EventSource("/stream");
         es.onmessage = (m) => this.onFrame(m);
-        es.onerror = () => this.setConn("waiting", "reconnecting…");
+        // An SSE error is the most direct signal the stream died; mark dropped so the next healthy
+        // poll re-opens + backfills (recovered()), not just flips the dot green.
+        es.onerror = () => {
+            this._dropped = true;
+            this.setConn("waiting", "reconnecting…");
+        };
         this._es = es;
     }
     closeStream() {
@@ -349,6 +361,10 @@ class Store {
         if (!STREAM_KINDS.includes(f.type))
             return;
         this._lastEventTs = Date.now();
+        // A live frame proves the stream healed itself (the browser EventSource auto-reconnects on a
+        // transient blip). Clear _dropped here so recovered() does NOT later tear down this healthy
+        // stream and re-open it: recovered() should only fire when the stream did NOT self-heal.
+        this._dropped = false;
         this.setConn("connected", "");
         const ev = f.event || {};
         ev._type = f.type;
@@ -593,6 +609,7 @@ class Store {
     async pollHealth() {
         if (Date.now() - this._lastEventTs < 6000) {
             this._healthMisses = 0;
+            this.recovered();
             this.setConn("connected", "");
             return;
         }
@@ -600,17 +617,31 @@ class Store {
             const h = await (await fetch("/health")).json();
             if (h.device) {
                 this._healthMisses = 0;
+                this.recovered();
                 this.setConn("connected", "");
             }
             else if (++this._healthMisses >= 2) {
+                this._dropped = true;
                 this.setConn("waiting", "device offline, retrying…");
             }
         }
         catch {
-            if (++this._healthMisses >= 2)
+            if (++this._healthMisses >= 2) {
+                this._dropped = true;
                 this.setConn("waiting", "reconnecting…");
+            }
         }
     }
+    // Called when health flips back to connected. If we were in a dropped state, the EventSource
+    // did not survive the drop and the tab has been silent, so re-open the stream + backfill the
+    // device ring ONCE on the recovery edge. The _dropped guard makes this fire on the transition,
+    // not on every healthy poll (resyncStream clears the flag). The <6s-since-last-event fast path
+    // means a tab that never lost its stream skips this (live frames keep _lastEventTs fresh).
+    recovered() {
+        if (!this._dropped)
+            return;
+        this.resyncStream();
+    }
     async pollProfile() {
         try {
             const [profilesR, healthR] = await Promise.all([
@@ -635,6 +666,26 @@ class Store {
             /* leave the last label */
         }
     }
+    // Re-open the SSE stream and backfill the device ring for the ACTIVE streaming source, so the
+    // current tab repopulates from what the device already holds (not just new live events).
+    // Needed because the EventSource does not survive a device drop and pollSpec only re-applies
+    // (and so re-opens+backfills) on a spec-KEY change, which a reconnect is not. Guarded for
+    // streaming sources only, matching applySpec: db + blank own no SSE feed; log opens the stream
+    // but backfill() self-skips it (host-side capture, no device ring to replay).
+    //
+    // Clears _dropped itself so the two recovery entry points -- the manual reconnect() button and
+    // the auto recovered() edge -- collapse into one idempotent op: whichever fires first wins, the
+    // other sees _dropped false and no-ops. Without this, a manual reconnect on a waiting tab fires
+    // resyncStream() here AND again from recovered() once the health poll resolves, so the stream is
+    // opened, torn down, reopened, and the ring is backfilled twice.
+    resyncStream() {
+        this._dropped = false;
+        const src = this.spec.source;
+        if (this.spec.blank || !src || src === "db")
+            return;
+        this.openStream();
+        this.backfill();
+    }
     async reconnect() {
         try {
             await fetch("/enable", { method: "POST" });
@@ -645,6 +696,7 @@ class Store {
         this.pollHealth();
         this.pollProfile();
         this.pollSpec();
+        this.resyncStream();
     }
 }
 // ---- aggregate math (moved here from widgets per the plan: it belongs WITH the aggregate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slack/radar-mcp",
-  "version": "1.7.0",
+  "version": "1.8.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",