@slack/radar-mcp 1.4.0 → 1.6.0

package/README.md

@@ -49,6 +49,13 @@ Opens `http://localhost:8100` automatically. Set `SLACK_RADAR_WEB_PORT` to use a
 
 Each tab has a counter, rate, sparkline, graph, a filter / sort / pause feed, and a payload inspector. Switching tabs replays what you have already seen this session (the browser caches it, bounded by count and age) so the view does not reset to empty. ADB forwarding and device activation are handled for you; a reconnect control re-arms after a device sleep.
 
+### Screen overlay
+
+A **▣ Screen** button opens a side panel that mirrors the live device screen, with a full-resolution screenshot and a screen recording. It is off by default and opens to a consent notice first, because it shows whatever is on the phone (open DMs, message content, notifications).
+
+* **Screenshot** works on any machine (pure `screencap`, no extra tools).
+* **Live mirror and recording** need `ffmpeg` on your machine. If it is missing, the panel shows the install command for your platform and the screenshot still works. ffmpeg is not bundled and is never installed for you.
+
 ## Prerequisites
 
 * Node.js 18+
@@ -124,8 +131,9 @@ What gets captured depends on the in-app server implementation. The MCP server i
 * **Network calls**: OkHttp interceptor. Ring buffer: 200 calls.
 * **RTM events**: WebSocket listener. Ring buffer: 500 events.
 * **Clogs**: Analytics interceptor. Ring buffer: 500 events. Persists across radar activation cycles.
+* **SQLite database** (Database tab, web dashboard only): when you open a database, a read-only **plaintext** copy of that on-device store (message text, request/response bodies, user/channel/team IDs) is pulled to a temp directory **on your own machine** (`os.tmpdir()/slack-radar-db-<port>`, files mode 0600). Auto-deleted when the dashboard process stops.
 
-All data is in-memory only. No disk writes.
+The network, RTM, and clog captures are in-memory ring buffers. The Database tab is the exception: it writes a plaintext copy of the selected on-device database to a temp file on your host for the duration of the session. Review before sharing anything from it.
 
 ### What gets captured, in detail
 
@@ -177,4 +185,4 @@ The MCP server auto-detects the Android user ID via `ps` and targets the broadca
 Restart your Claude Code session. MCP servers are registered at session start.
 
 **Port already in use (web dashboard)**
-Another instance may be running. Kill it with `lsof -ti :8100 | xargs kill` or set a different port with `SLACK_RADAR_WEB_PORT=8101 npx @slack/radar-mcp web`.
+If a Radar dashboard is already running on the port, launching again just opens it. If the port is held by another program, run Radar on a different port with `SLACK_RADAR_WEB_PORT=8101 npx @slack/radar-mcp web`.

package/dist/mcp/db-tools.d.ts

@@ -0,0 +1,46 @@
+/**
+ * MCP tool handlers for the on-device SQLite browser.
+ *
+ * These expose the same read-only DB access the web dashboard already has (src/web/server.ts),
+ * but over MCP so terminal Claude can inspect the device store during a debugging session
+ * without opening the dashboard. All the work lives in shared/db.ts; these handlers are thin
+ * wrappers that resolve the bound profile and shape the result for MCP.
+ *
+ * Read-only is enforced in shared/db.ts: the copy-based design (the device file is `cat`'d to
+ * a throwaway local copy and never written back) plus `sqlite3 -safe` (blocks ATTACH/readfile/
+ * writefile/load_extension at the engine level) plus the single-statement read-only gate
+ * (assertReadOnlyQuery). NOTE: the copy is opened WITHOUT `-readonly` on purpose, so SQLite
+ * replays the WAL sidecar; the read-only guarantee does not depend on the open mode. This
+ * handler calls assertReadOnlyQuery() up front so a bad query is rejected BEFORE the device
+ * pull, and results are capped by both row count and serialized bytes (see capQueryRows) so
+ * neither a `SELECT *` nor a one-row `group_concat` dump can stream the whole plaintext store
+ * into the model context.
+ */
+import type { DeviceTransport } from "../shared/transport.js";
+/**
+ * Bound a result set for the model context by BOTH row count and serialized bytes. Pure (no
+ * I/O) so it is unit-testable without a device. Returns the rows to actually return plus the
+ * honest counters. truncated is true if EITHER ceiling trips. A single row larger than the
+ * byte budget cannot be split, so it is dropped (returnedRows 0) rather than blowing the
+ * budget — the note says so, and total_rows still reports the true count so the model knows
+ * data exists and can re-query a narrower projection.
+ */
+export declare function capQueryRows(rows: unknown[]): {
+    rows: unknown[];
+    rowCount: number;
+    totalRows: number;
+    truncated: boolean;
+    note?: string;
+};
+export declare function handleListDatabases(transport: DeviceTransport): {
+    data: unknown;
+    isError: boolean;
+};
+export declare function handleListTables(transport: DeviceTransport, db: string, refresh?: boolean): Promise<{
+    data: unknown;
+    isError: boolean;
+}>;
+export declare function handleQueryDatabase(transport: DeviceTransport, db: string, sql: string, refresh?: boolean): Promise<{
+    data: unknown;
+    isError: boolean;
+}>;

package/dist/mcp/db-tools.js

@@ -0,0 +1,160 @@
+/**
+ * MCP tool handlers for the on-device SQLite browser.
+ *
+ * These expose the same read-only DB access the web dashboard already has (src/web/server.ts),
+ * but over MCP so terminal Claude can inspect the device store during a debugging session
+ * without opening the dashboard. All the work lives in shared/db.ts; these handlers are thin
+ * wrappers that resolve the bound profile and shape the result for MCP.
+ *
+ * Read-only is enforced in shared/db.ts: the copy-based design (the device file is `cat`'d to
+ * a throwaway local copy and never written back) plus `sqlite3 -safe` (blocks ATTACH/readfile/
+ * writefile/load_extension at the engine level) plus the single-statement read-only gate
+ * (assertReadOnlyQuery). NOTE: the copy is opened WITHOUT `-readonly` on purpose, so SQLite
+ * replays the WAL sidecar; the read-only guarantee does not depend on the open mode. This
+ * handler calls assertReadOnlyQuery() up front so a bad query is rejected BEFORE the device
+ * pull, and results are capped by both row count and serialized bytes (see capQueryRows) so
+ * neither a `SELECT *` nor a one-row `group_concat` dump can stream the whole plaintext store
+ * into the model context.
+ */
+import { assertReadOnlyQuery, listDatabases, pullDatabase, queryDatabase, pulledSize, } from "../shared/db.js";
+/**
+ * Caps on what query_database streams into the MODEL CONTEXT. The on-device store holds tens
+ * of thousands of plaintext message/PII rows; an unbounded result would dump the whole store
+ * into the transcript (db.ts only bounds the raw sqlite output at 64MB).
+ *
+ * Two independent ceilings, because bounding rows alone is not enough: a single
+ * `SELECT group_concat(text) FROM messages` collapses the entire table into ONE row whose
+ * lone column is every message body — that sails past a row-count cap untouched. So we cap
+ * BOTH the row count AND the serialized byte size of the returned payload.
+ *
+ * The web dashboard is intentionally exempt (handleDbQuery in web/server.ts returns the
+ * uncapped set): it renders to a consenting local human behind a privacy banner, not into an
+ * LLM transcript, so a large render is a UI annoyance, not the context/PII harm this guards.
+ * (It does not paginate; the exemption is about WHO consumes the rows, not how they are shown.)
+ */
+const MAX_QUERY_ROWS = 500;
+const MAX_QUERY_BYTES = 256 * 1024; // serialized cap on rows returned to the model (~256KB)
+/**
+ * Bound a result set for the model context by BOTH row count and serialized bytes. Pure (no
+ * I/O) so it is unit-testable without a device. Returns the rows to actually return plus the
+ * honest counters. truncated is true if EITHER ceiling trips. A single row larger than the
+ * byte budget cannot be split, so it is dropped (returnedRows 0) rather than blowing the
+ * budget — the note says so, and total_rows still reports the true count so the model knows
+ * data exists and can re-query a narrower projection.
+ */
+export function capQueryRows(rows) {
+    const total = rows.length;
+    const byCount = rows.length > MAX_QUERY_ROWS ? rows.slice(0, MAX_QUERY_ROWS) : rows.slice();
+    // Then trim by serialized size: keep prefix rows until the JSON budget is hit. Measure UTF-8
+    // BYTES (Buffer.byteLength), not String.length: the MCP layer emits this payload as UTF-8 over
+    // stdio, and .length counts UTF-16 code units, so an emoji/CJK row (surrogate pairs: 2 code
+    // units, 4 UTF-8 bytes) would otherwise pass at up to ~2x the real wire size.
+    const kept = [];
+    let bytes = 0;
+    for (const r of byCount) {
+        const sz = Buffer.byteLength(JSON.stringify(r) ?? "", "utf8");
+        if (kept.length > 0 && bytes + sz > MAX_QUERY_BYTES)
+            break;
+        kept.push(r);
+        bytes += sz;
+        if (bytes > MAX_QUERY_BYTES)
+            break; // a single oversized first row trips here; dropped below
+    }
+    // If even the first kept row blew the budget, drop it: do not stream a >256KB blob.
+    const overBudget = kept.length === 1 && bytes > MAX_QUERY_BYTES;
+    const finalRows = overBudget ? [] : kept;
+    const truncated = finalRows.length < total;
+    let note;
+    if (overBudget) {
+        note = `first row alone exceeds the ${Math.round(MAX_QUERY_BYTES / 1024)}KB response budget; returned no rows. Select fewer/narrower columns (avoid group_concat/blob dumps).`;
+    }
+    else if (truncated) {
+        note = `result truncated to ${finalRows.length} of ${total} rows (row or byte budget); narrow with WHERE/LIMIT or fewer columns.`;
+    }
+    return { rows: finalRows, rowCount: finalRows.length, totalRows: total, truncated, note };
+}
+/** Resolve the Android profile Radar is bound to. Returns undefined so db.ts falls back to its first available user. */
+function resolveUser(transport) {
+    try {
+        return transport.resolveActiveUser();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function handleListDatabases(transport) {
+    try {
+        const { user, availableUsers, names } = listDatabases(resolveUser(transport));
+        return { data: { user, available_users: availableUsers, databases: names }, isError: false };
+    }
+    catch (e) {
+        return { data: { error: e.message, databases: [] }, isError: true };
+    }
+}
+export async function handleListTables(transport, db, refresh = false) {
+    if (!db)
+        return { data: { error: "db is required" }, isError: true };
+    const user = resolveUser(transport);
+    try {
+        // force=refresh re-pulls the live device copy; default reuses the cached pull so a
+        // multi-MB store is not re-streamed on every call.
+        await pullDatabase(db, user, refresh);
+        const tableRows = (await queryDatabase(db, "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name", user));
+        const tables = [];
+        for (const t of tableRows) {
+            let rows = "?";
+            try {
+                rows = (await queryDatabase(db, `SELECT COUNT(*) c FROM "${t.name}"`, user))[0].c;
+            }
+            catch {
+                // a view or virtual table may not COUNT cleanly; leave "?"
+            }
+            tables.push({ name: t.name, rows });
+        }
+        return { data: { db, size_bytes: pulledSize(db, user), tables }, isError: false };
+    }
+    catch (e) {
+        return { data: { error: e.message, tables: [] }, isError: true };
+    }
+}
+export async function handleQueryDatabase(transport, db, sql, refresh = false) {
+    if (!db)
+        return { data: { error: "db is required" }, isError: true };
+    if (!sql)
+        return { data: { error: "sql is required" }, isError: true };
+    // Gate the SQL BEFORE the device pull: a rejected write/exfil query must not trigger a
+    // multi-MB `exec-out cat` first. queryDatabase re-checks, so this is an early-out, not the
+    // sole boundary. Running device-free, it also makes the read-only gate unit-testable here.
+    try {
+        assertReadOnlyQuery(sql);
+    }
+    catch (e) {
+        return { data: { error: e.message, rows: [] }, isError: true };
+    }
+    const user = resolveUser(transport);
+    try {
+        // force=refresh re-pulls the live device copy; default reuses the cached pull. Pass
+        // refresh:true when the device state may have changed since the first query this session.
+        await pullDatabase(db, user, refresh);
+        const rows = await queryDatabase(db, sql, user);
+        // Cap what goes into the model context by BOTH row count and serialized bytes: the store
+        // is plaintext PII and a broad SELECT (or a group_concat that collapses the table into one
+        // huge row) would otherwise dump it into the transcript. See capQueryRows.
+        const capped = capQueryRows(rows);
+        return {
+            data: {
+                db,
+                sql,
+                row_count: capped.rowCount,
+                total_rows: capped.totalRows,
+                truncated: capped.truncated,
+                ...(capped.note ? { note: capped.note } : {}),
+                rows: capped.rows,
+            },
+            isError: false,
+        };
+    }
+    catch (e) {
+        return { data: { error: e.message, rows: [] }, isError: true };
+    }
+}

package/dist/mcp/index.js

@@ -12,6 +12,8 @@ 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 { buildBufferPath, createSnapshot } from "./snapshot.js";
+import { handleListDatabases, handleListTables, handleQueryDatabase, } from "./db-tools.js";
+import { cleanupPulledDatabases, initializeDatabasePath, resetDbState, } from "../shared/db.js";
 import { TOOL_DEFINITIONS, SERVER_INSTRUCTIONS, sessionGate } from "./tools.js";
 // --- Subcommand + bin-name dispatch ---
 //
@@ -164,7 +166,8 @@ async function openDashboardSpec(spec) {
     return r.json;
 }
 if (wantsWeb) {
-    await import("../web/bin.js");
+    const { startWebServer } = await import("../web/bin.js");
+    startWebServer();
 }
 else {
     await runMcpServer();
@@ -183,6 +186,17 @@ async function runMcpServer() {
     }
     const device = createTransport();
     setTransport(device);
+    // Scope pulled-DB copies to THIS process by pid, then clean them on exit (mirrors the web
+    // server's lifecycle). The DB tools write plaintext message-store copies to a 0600 tmp dir;
+    // pid-scoping keeps two concurrent Radar MCP servers from sharing a dir and clobbering each
+    // other's live pulls (a fixed port would collide, since every MCP uses the same RADAR_PORT).
+    // A hard crash leaks this process's dir until the OS sweeps tmp; the files stay 0600 in a
+    // 0700 dir, so that is a bounded exposure, not a cross-user leak.
+    initializeDatabasePath(process.pid);
+    cleanupPulledDatabases();
+    for (const sig of ["SIGINT", "SIGTERM", "exit"]) {
+        process.once(sig, cleanupPulledDatabases);
+    }
     let sessionEnabled = false;
     function radarRequest(requestPath) {
         return new Promise((resolve, reject) => {
@@ -260,6 +274,10 @@ async function runMcpServer() {
     async function handleSessionEnable(args) {
         const timeout = args?.timeout_minutes || 5;
         sessionEnabled = true;
+        // A re-enable may be a different device or a re-armed profile, so drop the cached DB
+        // user set + sqlite path; the next DB tool call re-detects the profiles fresh. Mirrors
+        // the web server's handleEnable (server.ts), which resets for the same reason.
+        resetDbState();
         const forwarded = device.ensureForward();
         if (!forwarded) {
             sessionEnabled = false;
@@ -562,7 +580,7 @@ async function runMcpServer() {
         }
     }
     // --- MCP Server ---
-    const server = new Server({ name: "slack-radar", version: "1.4.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+    const server = new Server({ name: "slack-radar", version: "1.6.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: TOOL_DEFINITIONS,
     }));
@@ -617,6 +635,20 @@ async function runMcpServer() {
         if (name === "ping") {
             return handlePing(toolArgs);
         }
+        if (name === "list_databases") {
+            const { data, isError } = handleListDatabases(device);
+            return textResult(data, isError);
+        }
+        if (name === "list_tables") {
+            const { db, refresh } = toolArgs;
+            const { data, isError } = await handleListTables(device, db ?? "", refresh === true);
+            return textResult(data, isError);
+        }
+        if (name === "query_database") {
+            const { db, sql, refresh } = toolArgs;
+            const { data, isError } = await handleQueryDatabase(device, db ?? "", sql ?? "", refresh === true);
+            return textResult(data, isError);
+        }
         const apiPath = buildApiPath(name, toolArgs);
         if (apiPath === null) {
             return textResult(`Unknown tool: ${name}`, true);

package/dist/mcp/tools.js

@@ -61,6 +61,17 @@ export const SERVER_INSTRUCTIONS = [
     "DO NOT offer for single-query debugging or when the user is happy reading results in the",
     "transcript. Offer when visual inspection adds real value.",
     "",
+    "SCREEN OVERLAY (in the dashboard):",
+    "The dashboard has a '▣ Screen' button that mirrors the LIVE device screen in a side panel,",
+    "plus a full-resolution screenshot and screen recording. It is OFF by default and opens to a",
+    "consent notice first, because it shows real on-screen content (open DMs, messages). The live",
+    "mirror needs ffmpeg on the user's machine; the screenshot does not. If the user wants the live",
+    "screen and ffmpeg is missing, tell them plainly that live mirroring needs ffmpeg and give the",
+    "platform install command (mac: `brew install ffmpeg`; debian/ubuntu: `sudo apt install ffmpeg`;",
+    "windows: `winget install ffmpeg`), and note the screenshot works without it. NEVER run the",
+    "install for them. The dashboard's /health response reports screen.ffmpeg / screen.liveCast /",
+    "screen.installHint, so you can check before suggesting.",
+    "",
     "CUSTOM DASHBOARD (open_radar_dashboard):",
     "The pre-built tabs (Live/Network/RTM/Clogs/Logs) cover the common cases. When the user",
     "describes a live view the tabs do not show, SUGGEST building it; invoke open_radar_dashboard",
@@ -228,11 +239,11 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "get_recent_logs",
-        description: "Get recent logcat entries from the connected device, filtered by tag.",
+        description: "Get recent device logs for the Slack debug build, filtered by tag. Reads the app's own log buffer first (the DEBUG-and-above Timber lines the in-app Log Viewer shows, this app only), and falls back to an adb logcat snapshot when that buffer cannot be read. For native crashes, VERBOSE lines, or non-Slack processes, use adb logcat directly.",
         inputSchema: {
             type: "object",
             properties: {
-                tag: { type: "string", description: "Logcat tag to filter by" },
+                tag: { type: "string", description: "Substring to filter log lines by (matched anywhere in the line, not an exact tag-column match)" },
                 limit: { type: "number", description: "Max number of lines to return (default: 50)" },
                 grep: { type: "string", description: "Optional text to grep within the filtered output" },
             },
@@ -407,6 +418,45 @@ export const TOOL_DEFINITIONS = [
         // Not read-only: it starts a local web server and pushes a spec to it.
         annotations: { readOnlyHint: false, idempotentHint: true },
     },
+    {
+        name: "list_databases",
+        description: "List the app's on-device SQLite databases (the message store, telemetry, etc.) for the bound profile.",
+        inputSchema: { type: "object", properties: {} },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "list_tables",
+        description: "List the tables (with row counts) in one on-device database. Pass a name from list_databases.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                db: { type: "string", description: "Database name from list_databases" },
+                refresh: {
+                    type: "boolean",
+                    description: "Re-pull a fresh copy from the device instead of reusing the cached pull (default false)",
+                },
+            },
+            required: ["db"],
+        },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "query_database",
+        description: "Run a read-only SQL query against an on-device database and get the rows back. SELECT/PRAGMA/WITH only (writes and file access are blocked). Use it to answer 'is this row actually in the DB?' during a debug session. Results are capped by row count and total size (the store is plaintext PII); when trimmed the response sets truncated:true with total_rows, so narrow with WHERE/LIMIT and avoid group_concat/blob dumps.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                db: { type: "string", description: "Database name from list_databases" },
+                sql: { type: "string", description: "A single read-only statement (SELECT, WITH, PRAGMA, EXPLAIN)" },
+                refresh: {
+                    type: "boolean",
+                    description: "Re-pull a fresh copy from the device before querying (default false reuses this session's cached pull)",
+                },
+            },
+            required: ["db", "sql"],
+        },
+        annotations: { readOnlyHint: true },
+    },
 ];
 /**
  * Check whether a tool call should be blocked by the session gate.

package/dist/shared/android.d.ts

@@ -32,6 +32,14 @@ export declare class AndroidTransport implements DeviceTransport {
     isForwarded(): boolean;
     getTimeoutMinutes(): number;
     getActiveUserId(): string | null;
+    /**
+     * Resolve the Android user the debug build is actually running as: the already-detected
+     * user if known, else a `ps`-based detection (which prefers the non-zero/secondary profile
+     * the work build runs under). Unlike getActiveUserId() this never returns null, so callers
+     * that need a concrete target (the DB browser) default to the profile Radar is bound to
+     * rather than blindly to user 0.
+     */
+    resolveActiveUser(): string;
     getCaptureFilePath(): string | null;
     screenshot(fullRes: boolean): string;
     recordScreen(durationS: number): string;

package/dist/shared/android.js

@@ -2,7 +2,8 @@ import { execSync } from "child_process";
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { getCaptureFilePath, isCapturing, readRecentLogs, registerCleanup, rotateCaptureIfNeeded, startCapture, stopCapture, } from "./logcat-capture.js";
+import { readDebugLogBuffer } from "./debug-log.js";
+import { filterLogLines, getCaptureFilePath, isCapturing, readRecentLogs, registerCleanup, rotateCaptureIfNeeded, startCapture, stopCapture, } from "./logcat-capture.js";
 const RADAR_PORT = 8099;
 const SOCKET_NAME = "slack-radar";
 const ENABLE_ACTION = "slack.debug.ENABLE_RADAR";
@@ -149,6 +150,16 @@ export class AndroidTransport {
     getActiveUserId() {
         return this.detectedUserId;
     }
+    /**
+     * Resolve the Android user the debug build is actually running as: the already-detected
+     * user if known, else a `ps`-based detection (which prefers the non-zero/secondary profile
+     * the work build runs under). Unlike getActiveUserId() this never returns null, so callers
+     * that need a concrete target (the DB browser) default to the profile Radar is bound to
+     * rather than blindly to user 0.
+     */
+    resolveActiveUser() {
+        return this.detectDebugBuildUser();
+    }
     getCaptureFilePath() {
         return getCaptureFilePath();
     }
@@ -189,8 +200,19 @@ export class AndroidTransport {
     getRecentLogs(tag, limit, grep) {
         if (!ADB)
             throw new Error("adb not found on PATH or common SDK locations");
-        // Preferred path: read from the session capture file so lines cannot
-        // have been evicted from the device ring buffer between enable and now.
+        // Primary source: the app's own DebugLogger buffer, read off the sandbox via
+        // run-as. This is the app's structured log (exact tags, no logcat column
+        // padding) and survives the radar enable/disable cycle, so it does not lose
+        // lines to device-logcat ring eviction between enable and read. Target the
+        // profile Radar is bound to (resolveActiveUser prefers the non-zero/work
+        // profile), not a blind user 0, so a dual-profile device reads the right
+        // sandbox -- matching how the DB browser threads its user.
+        const appLog = readDebugLogBuffer(ADB, this.resolveActiveUser());
+        if (appLog !== null) {
+            return filterLogLines(appLog, tag, limit, grep);
+        }
+        // Fallback: read from the session capture file so lines cannot have been
+        // evicted from the device ring buffer between enable and now.
         if (isCapturing()) {
             // Opportunistic rotation. Stop+rename+restart when the file grows
             // past the threshold so the child never writes past a truncated EOF.

package/dist/shared/constants.d.ts

@@ -1,12 +1,41 @@
+/**
+ * Package version, read once from package.json at load — NOT a hardcoded copy, so it cannot
+ * drift from the published version. Surfaced as the `X-Radar-Version` header on /spec so a
+ * second launcher can tell whether the dashboard already holding the port is a different
+ * Radar version than itself (the adopt path notices a mismatch; it still adopts, never kills).
+ * Falls back to "unknown" if package.json cannot be read (should not happen in a real install).
+ */
+export declare const RADAR_VERSION: string;
 /** Port used to reach the on-device radar HTTP server via forwarding. */
 export declare const RADAR_PORT = 8099;
 /** Host address for the forwarded connection. */
 export declare const RADAR_HOST = "127.0.0.1";
 /** Max events to retain in each local SSE buffer. */
 export declare const MAX_LOCAL_BUFFER = 500;
+/**
+ * Max parsed logcat frames the web dashboard retains for the whole server
+ * session. The device does not buffer logcat host-side, so the dashboard keeps
+ * its own session ring and replays it to every newly connected stream — this is
+ * what lets a tab switch (which reopens the SSE stream) show the full history
+ * instead of only the lines that arrive after the reconnect. Bounded so a long,
+ * chatty session cannot grow without limit. logcat is captured for ALL apps (the
+ * dashboard filters by package client-side), so the depth is sized for an all-app
+ * stream: at typical line sizes this keeps the buffer well under ~10 MB (a
+ * stack-trace-heavy session runs larger per line, so treat this as a typical, not
+ * a hard, ceiling). Like Android Studio's logcat, retention is a bounded ring —
+ * the oldest lines age out once the cap is reached, not kept forever.
+ */
+export declare const MAX_LOG_SESSION_BUFFER = 20000;
 /**
  * Default port for the web dashboard. Shared so the MCP `open_radar_dashboard`
  * tool POSTs its spec to the same port the web server listens on; both honor the
  * `SLACK_RADAR_WEB_PORT` env override.
  */
 export declare const WEB_PORT_DEFAULT = 8100;
+/**
+ * The Slack debug build whose sandbox the host can `run-as` into. Both the
+ * on-device SQLite browser (db.ts) and the app log-buffer reader (debug-log.ts)
+ * read sandbox files through `adb exec-out "run-as <pkg> ..."`, which only works
+ * on a debuggable build. Defined once here so the two readers cannot drift.
+ */
+export declare const SLACK_DEBUG_PKG = "com.Slack.internal.debug";

package/dist/shared/constants.js

@@ -1,12 +1,50 @@
+import { createRequire } from "module";
+/**
+ * Package version, read once from package.json at load — NOT a hardcoded copy, so it cannot
+ * drift from the published version. Surfaced as the `X-Radar-Version` header on /spec so a
+ * second launcher can tell whether the dashboard already holding the port is a different
+ * Radar version than itself (the adopt path notices a mismatch; it still adopts, never kills).
+ * Falls back to "unknown" if package.json cannot be read (should not happen in a real install).
+ */
+export const RADAR_VERSION = (() => {
+    try {
+        const require = createRequire(import.meta.url);
+        return require("../../package.json").version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+})();
 /** Port used to reach the on-device radar HTTP server via forwarding. */
 export const RADAR_PORT = 8099;
 /** Host address for the forwarded connection. */
 export const RADAR_HOST = "127.0.0.1";
 /** Max events to retain in each local SSE buffer. */
 export const MAX_LOCAL_BUFFER = 500;
+/**
+ * Max parsed logcat frames the web dashboard retains for the whole server
+ * session. The device does not buffer logcat host-side, so the dashboard keeps
+ * its own session ring and replays it to every newly connected stream — this is
+ * what lets a tab switch (which reopens the SSE stream) show the full history
+ * instead of only the lines that arrive after the reconnect. Bounded so a long,
+ * chatty session cannot grow without limit. logcat is captured for ALL apps (the
+ * dashboard filters by package client-side), so the depth is sized for an all-app
+ * stream: at typical line sizes this keeps the buffer well under ~10 MB (a
+ * stack-trace-heavy session runs larger per line, so treat this as a typical, not
+ * a hard, ceiling). Like Android Studio's logcat, retention is a bounded ring —
+ * the oldest lines age out once the cap is reached, not kept forever.
+ */
+export const MAX_LOG_SESSION_BUFFER = 20000;
 /**
  * Default port for the web dashboard. Shared so the MCP `open_radar_dashboard`
  * tool POSTs its spec to the same port the web server listens on; both honor the
  * `SLACK_RADAR_WEB_PORT` env override.
  */
 export const WEB_PORT_DEFAULT = 8100;
+/**
+ * The Slack debug build whose sandbox the host can `run-as` into. Both the
+ * on-device SQLite browser (db.ts) and the app log-buffer reader (debug-log.ts)
+ * read sandbox files through `adb exec-out "run-as <pkg> ..."`, which only works
+ * on a debuggable build. Defined once here so the two readers cannot drift.
+ */
+export const SLACK_DEBUG_PKG = "com.Slack.internal.debug";

package/dist/shared/db.d.ts

@@ -0,0 +1,92 @@
+/**
+ * On-device SQLite browser (host-side, read-only).
+ *
+ * Slack's on-device databases are plaintext SQLite (not SQLCipher) on a debug build,
+ * which is what makes host-side reading possible at all: `adb exec-out "run-as <pkg>
+ * cat databases/<db>"` streams the file to the host, where the platform-tools `sqlite3`
+ * binary runs read-only SELECT/PRAGMA against a local copy. Nothing is written on the
+ * device; no app rebuild is needed. If a future build encrypts these DBs, the magic-header
+ * check in `pullDatabase` fails fast with a clear message rather than producing garbage.
+ *
+ * SECURITY: a pulled DB is the full message store in plaintext (request bodies, message
+ * text, user/channel IDs). Pulled copies are written 0600 under a dedicated tmp dir and
+ * cleaned on server start/stop (see `cleanupPulledDatabases`). The DB names are learned
+ * live from the device (`listDatabases`); none are baked into this file.
+ */
+/**
+ * Initialize DB_TMP with a per-process-unique path. Call on startup. The web server scopes
+ * by its port; the MCP server scopes by process.pid (every MCP shares one fixed port, so a
+ * port key would collide between two concurrent MCP servers).
+ */
+export declare function initializeDatabasePath(scopeKey: number): void;
+export declare function availableUsers(): string[];
+/**
+ * Reset cached device state. Clears the sqlite-binary path so a device swap
+ * re-detects it. The targeted Android user is passed explicitly to every call
+ * (sourced from the dashboard's bound profile) rather than guessed, so list / pull /
+ * query can never silently disagree on which profile's store they touch.
+ */
+export declare function resetDbState(): void;
+/**
+ * List the on-device databases for the given Android user (the dashboard's bound
+ * profile). Filters out WAL/SHM/journal sidecar files. Returns the resolved user and
+ * the full set of profiles that have the build, so the UI can show which profile this
+ * store belongs to and offer a switch when more than one exists.
+ */
+export declare function listDatabases(user?: string | null): {
+    user: string;
+    availableUsers: string[];
+    names: string[];
+};
+/**
+ * Stream a database off the device to a local 0600 copy (scoped to the target user) and
+ * return its path. `run-as ... cp` into shared storage fails silently (sandbox), so the
+ * working path is `exec-out cat` piped to a host file. Validates the SQLite magic header
+ * so a missing DB (whose `cat` emits an error string, not file bytes) fails with a clear
+ * message instead of being written as a junk file that later trips an opaque parse error.
+ *
+ * WAL: Slack's on-device DBs are WAL-mode and the live app holds write connections open,
+ * so recently-committed rows live in the `-wal` sidecar, NOT yet in the main file. Pulling
+ * the main file alone (and reading it `immutable`) silently drops those recent rows — the
+ * exact data a debugger wants. So we also pull the `-wal` and `-shm` sidecars next to the
+ * main copy (best-effort; absent if the DB was checkpointed), and queryDatabase opens the
+ * copy NORMALLY (not immutable) so SQLite replays the WAL into the view.
+ */
+export declare function pullDatabase(name: string, user?: string | null, force?: boolean): Promise<string>;
+/**
+ * Read-only SQL gate. Throws on anything that is not a single read-only statement.
+ *
+ * Exported so a caller (the MCP query handler) can reject a bad query BEFORE pulling a
+ * multi-MB DB copy off the device. queryDatabase calls it too, so the boundary holds even
+ * if a caller forgets the pre-check.
+ *
+ * What actually keeps this safe (the boundary does NOT rest on this gate alone):
+ *   1. copy-based design — we only ever READ the device file (`exec-out cat`) and query a
+ *      throwaway local copy; nothing is ever written back, so no query can mutate device
+ *      state no matter what it does to the copy.
+ *   2. `sqlite3 -safe` — engine-level: forbids ATTACH, readfile/writefile/edit, and
+ *      load_extension while still allowing ordinary SELECT/PRAGMA. The load-bearing exfil
+ *      control; a keyword denylist alone is whack-a-mole.
+ *   3. this gate — a single SELECT/PRAGMA/WITH/EXPLAIN/VALUES statement (no `;`-chaining),
+ *      a write-PRAGMA reject, and an explicit reject of file-access primitive names as
+ *      defense in depth.
+ * NOTE: the copy is opened NORMALLY (not `-readonly`, not `immutable`) on purpose, so SQLite
+ * replays the `-wal` sidecar and recently-committed rows stay visible. `-readonly`/immutable
+ * would read the main file alone and silently drop them; writes to the throwaway copy are
+ * harmless. So `-readonly` is intentionally NOT passed — the read-only guarantee comes from
+ * (1) and (2), not from the open mode.
+ */
+export declare function assertReadOnlyQuery(sql: string): void;
+/**
+ * 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
+ * own error message on failure.
+ */
+export declare function queryDatabase(name: string, sql: string, user?: string | null): Promise<unknown[]>;
+/** Size in bytes of a pulled local copy for the given user, or 0 if not pulled. */
+export declare function pulledSize(name: string, user?: string | null): number;
+/**
+ * Remove all pulled database copies. Pulled DBs are plaintext message stores, so they
+ * must not linger; call on server start and stop. Best-effort.
+ */
+export declare function cleanupPulledDatabases(): void;