@slack/radar-mcp 1.3.0 → 1.5.0

package/dist/mcp/tools.js

@@ -1,3 +1,4 @@
+import { SOURCES, VIZ, SERIES_METRICS } from "../web/spec.js";
 export const SERVER_INSTRUCTIONS = [
     "Slack Radar provides on-device debugging tools for the Slack Android app via ADB.",
     "",
@@ -31,24 +32,70 @@ export const SERVER_INSTRUCTIONS = [
     "- RTM event types use subtypes when available (e.g. message_changed, not message).",
     "- Use wait_for_events with idle_timeout_ms instead of polling loops.",
     "- Use ping(timeout_minutes=N) to extend sessions. Monitor remaining_minutes proactively.",
+    "- ping reports which app/profile is bound (android_user_id, profile, package). The debug",
+    "  build can run on more than one user (personal=0, plus a work profile or secondary user),",
+    "  and only the first to bind the socket wins. If events seem to come from the wrong app, tell",
+    "  the user which profile is bound and use list_profiles + activate_for_user to switch.",
     "- Screenshots default to 720px. Use full_res=true only when detail matters.",
     "- Setup: /slack-radar-setup",
     "- Manual enable (no skill): adb shell am broadcast -a slack.debug.ENABLE_RADAR --ei timeout_minutes 5 -p com.Slack.internal.debug",
     "  Then: adb forward tcp:8099 localabstract:slack-radar",
     "",
     "WEB DASHBOARD (/radar-ui):",
-    "A browser-based dashboard (http://localhost:8100) shows the same live device data in a",
-    "visual UI. Launched via the /radar-ui skill, which wraps `npx -p @slack/radar-mcp slack-radar-web`.",
+    "A browser-based dashboard (http://localhost:8100) shows the same live device data as",
+    "tabs: Live (everything), Network, RTM, Clogs, and Logs, each with counters, a graph, a",
+    "filterable feed, and a payload inspector. Launched via the /radar-ui skill, which runs",
+    "`npx @slack/radar-mcp web` (a global install also exposes it as `slack-radar`).",
     "",
-    "When to suggest /radar-ui (mention it ONCE per thread, do not auto-invoke):",
+    "PROACTIVELY offer the dashboard when it would help — do not wait to be asked. The moment a",
+    "device session turns visual or multi-step, say so and offer to open it, e.g.: \"This is",
+    "easier to watch live — want me to open the Radar dashboard?\" Offer (once per thread) when:",
     '- User says "watch", "monitor", "let me see", "show me live" about device traffic',
     "- User wants to share traffic with a colleague, pair, or teammate",
     "- User is doing a multi-minute investigation and the transcript is getting noisy",
     '- User explicitly asks about a GUI, UI, browser view, or dashboard',
     "",
-    "DO NOT invoke /radar-ui yourself. Opening a browser window is a user-visible action.",
-    "DO NOT suggest /radar-ui for single-query debugging or when the user is happy reading",
-    "results in the transcript. Suggest it when visual inspection adds real value.",
+    "OFFER, then open ONLY AFTER THE USER AGREES — opening a browser window is a user-visible",
+    "action; never pop one unbidden. On a yes, run the /radar-ui skill (or tell them to run",
+    "`npx @slack/radar-mcp web`) and hand over the URL. Nudge, do not auto-open.",
+    "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",
+    "only after they agree or explicitly ask for a custom view/dashboard (same discipline as",
+    "/radar-ui). To build, translate their words into a spec and call the tool; it renders your",
+    "spec as a 'Custom' tab on the dashboard (default http://localhost:8100) and returns the URL",
+    "for you to share. Cases worth suggesting it for:",
+    '- "graph calls per second vs average response time and flag the slow ones"',
+    '- "count every DM I receive and beep when one arrives"',
+    '- "show only RTM events on channel C... and let me click each for its payload"',
+    '- "watch network calls whose body contains <substring>"',
+    "Authoring rules:",
+    "- source is one of network/rtm/clog/log/all ('all' = one unified timeline).",
+    "- match filters on SUMMARY fields only, by source: network=url/method/status_code,",
+    "  rtm=event_type/direction/channel, clog=event_name, log=tag/level/message/pid/package.",
+    "  NEVER invent a field; a match on a field the stream does not carry silently matches",
+    "  nothing. To filter on body text use bodyContains (network/all only), which fetches detail.",
+    "- viz composes counter/rate/sparkline/feed/inspector/graph. graph needs a series array",
+    "  (1-2 entries; metric ratePerSec/count/avg/errorRate; avg needs a field like duration_ms).",
+    "- highlight {field, op, value} flags rows breaching a numeric threshold; alert {sound,flash,",
+    "  say, at} fires on each live match (or once at the Nth). Author an honest one-line `summary`.",
+    "Calling it again replaces/refines the live custom dashboard. The dashboard reads a connected",
+    "device, so Radar must be armed to show data (it has its own Reconnect button). Debug builds",
+    "only; local only. Does not open a browser window for you; surface the returned URL to the user.",
     "",
     "CAPTURE_SNAPSHOT OUTPUT:",
     "When capture_snapshot returns, tell the user:",
@@ -69,7 +116,7 @@ export const SERVER_INSTRUCTIONS = [
 export const TOOL_DEFINITIONS = [
     {
         name: "ping",
-        description: "Check if Slack Radar is running. Returns uptime, buffer sizes, remaining session time, and stream status.",
+        description: "Check if Slack Radar is running. Returns uptime, buffer sizes, remaining session time, stream status, and which app/profile is bound: android_user_id (0 = personal, non-zero = a secondary user such as a work profile), profile ('personal'/'secondary'), and package.",
         inputSchema: {
             type: "object",
             properties: {
@@ -206,19 +253,19 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "list_profiles",
-        description: "List Android user profiles that have the Slack debug build running. Use this before activate_for_user when the user asks to switch profiles (personal vs work) or when logs/app state seem to point at the wrong profile. Returns each profile's userId (e.g. '0' for personal, '10' for work) and a human label.",
+        description: "List Android user profiles that have the Slack debug build running. Use this before activate_for_user when the user asks to switch profiles (personal vs a secondary user such as a work profile) or when logs/app state seem to point at the wrong profile. Returns each profile's userId (e.g. '0' for personal, '10' for a secondary user) and a human label.",
         inputSchema: { type: "object", properties: {} },
         annotations: { readOnlyHint: true },
     },
     {
         name: "activate_for_user",
-        description: "Activate Slack Radar on a specific Android user profile. Use after list_profiles to switch between personal and work profile targets. Switching profiles restarts log capture with a new session-scoped file and reconnects the SSE event stream so events come from the newly activated profile; old captures remain on disk for up to 7 days. Call this when already connected and only the target profile needs to change.",
+        description: "Activate Slack Radar on a specific Android user profile. Use after list_profiles to switch between the personal user and a secondary user (such as a work profile). Switching profiles restarts log capture with a new session-scoped file and reconnects the SSE event stream so events come from the newly activated profile; old captures remain on disk for up to 7 days. Call this when already connected and only the target profile needs to change.",
         inputSchema: {
             type: "object",
             properties: {
                 user_id: {
                     type: "string",
-                    description: "Android user ID from list_profiles (e.g. '0' for personal, '10' for work).",
+                    description: "Android user ID from list_profiles (e.g. '0' for personal, '10' for a secondary user).",
                 },
                 timeout_minutes: {
                     type: "number",
@@ -298,6 +345,79 @@ export const TOOL_DEFINITIONS = [
         inputSchema: { type: "object", properties: {} },
         annotations: { readOnlyHint: false, idempotentHint: true },
     },
+    {
+        name: "open_radar_dashboard",
+        description: "Build or refine a custom live dashboard tab in the Slack Radar web UI from a spec YOU author. " +
+            "Suggest this when the user describes a live view the pre-built tabs (Live/Network/RTM/Clogs/Logs) do not cover " +
+            "(e.g. 'graph calls per second vs response time and flag slow ones', 'beep when I get a DM'); invoke it once they agree. " +
+            "Translate the request into the spec fields below and call this tool; it ensures the web dashboard is " +
+            "running (default http://localhost:8100) and renders your spec as a 'Custom' tab, then returns the URL to share. " +
+            "Calling again replaces/refines it. Does not open a browser window for the user. The dashboard reads a connected " +
+            "device, so Radar must be armed to show data (the dashboard has its own Reconnect button). Debug builds only, local only.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Short 1-3 word dashboard title; also the Custom tab label." },
+                summary: {
+                    type: "string",
+                    description: "ONE honest plain-English line describing what this shows, including any active filter.",
+                },
+                source: {
+                    type: "string",
+                    enum: [...SOURCES],
+                    description: "Which device stream to read. 'all' is a unified timeline mixing network, RTM, and clog.",
+                },
+                match: {
+                    type: "object",
+                    description: "Case-insensitive substring filter on SUMMARY fields, keyed by source. network: url/method/status_code; " +
+                        "rtm: event_type/direction/channel; clog: event_name; log: tag/level/package. NEVER invent a field " +
+                        "(a match on an absent field silently matches nothing). For body text use bodyContains instead.",
+                },
+                bodyContains: {
+                    type: "string",
+                    description: "network/all only: keep calls whose request/response BODY contains this substring (fetches each call's detail).",
+                },
+                viz: {
+                    type: "array",
+                    items: { type: "string", enum: [...VIZ] },
+                    description: "Widgets to compose. 'graph' requires a series array.",
+                },
+                rateWindowSec: {
+                    type: "number",
+                    description: "Sliding window in seconds for the rate widget (default 10).",
+                },
+                series: {
+                    type: "array",
+                    description: "Required when viz includes 'graph'. 1-2 entries.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            label: { type: "string" },
+                            metric: { type: "string", enum: [...SERIES_METRICS] },
+                            field: { type: "string", description: "Required for the 'avg' metric, e.g. duration_ms." },
+                            unit: { type: "string" },
+                        },
+                        required: ["metric"],
+                    },
+                },
+                extract: {
+                    type: "object",
+                    description: "Pull CONTENT from a record body into the feed: {parse:'response_body'|'request_body'|'data', field:'dot.path', label}.",
+                },
+                highlight: {
+                    type: "object",
+                    description: "Flag feed rows whose numeric field breaches a threshold: {field, op:'>'|'>='|'<'|'<='|'==', value, label}.",
+                },
+                alert: {
+                    type: "object",
+                    description: "Sentry mode: {sound, flash, say, at}. 'at':N fires once when the match count reaches N; omit to fire on every match.",
+                },
+            },
+            required: ["title", "summary", "source", "viz"],
+        },
+        // Not read-only: it starts a local web server and pushes a spec to it.
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    },
 ];
 /**
  * Check whether a tool call should be blocked by the session gate.
@@ -312,6 +432,11 @@ export function sessionGate(toolName, sessionEnabled) {
     if (toolName === "ping") {
         return null;
     }
+    // open_radar_dashboard launches an independent local web process with its own
+    // device-enable (Reconnect) button, so it does not require the MCP session enabled.
+    if (toolName === "open_radar_dashboard") {
+        return null;
+    }
     if (!sessionEnabled) {
         return {
             content: [

package/dist/shared/android.d.ts

@@ -13,8 +13,9 @@ export declare function resolveAdbPath(): string | null;
 /**
  * Parse the output of `ps -A -o USER,NAME` to extract the Android user ID
  * for the debug build process. When multiple profiles are running, prefers
- * the work profile (user ID > 0) since that's the typical debugging target.
- * Returns "0" for primary user, "10" for work profile, etc.
+ * a secondary user (user ID > 0) since that's the typical debugging target.
+ * Returns "0" for the primary user, or the first secondary user id (commonly
+ * "10", which is often a work profile, but the id alone cannot prove that).
  */
 export declare function parseUserFromPsOutput(psOutput: string): string;
 export declare class AndroidTransport implements DeviceTransport {
@@ -31,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

@@ -61,8 +61,9 @@ const ADB = resolveAdbPath();
 /**
  * Parse the output of `ps -A -o USER,NAME` to extract the Android user ID
  * for the debug build process. When multiple profiles are running, prefers
- * the work profile (user ID > 0) since that's the typical debugging target.
- * Returns "0" for primary user, "10" for work profile, etc.
+ * a secondary user (user ID > 0) since that's the typical debugging target.
+ * Returns "0" for the primary user, or the first secondary user id (commonly
+ * "10", which is often a work profile, but the id alone cannot prove that).
  */
 export function parseUserFromPsOutput(psOutput) {
     if (!psOutput || !psOutput.trim())
@@ -77,9 +78,9 @@ export function parseUserFromPsOutput(psOutput) {
     }
     if (userIds.length === 0)
         return "0";
-    // Prefer work profile (non-zero user ID) when multiple profiles are running
-    const workProfile = userIds.find((id) => id !== "0");
-    return workProfile ?? userIds[0];
+    // Prefer a secondary user (non-zero user ID) when multiple profiles are running
+    const secondaryUser = userIds.find((id) => id !== "0");
+    return secondaryUser ?? userIds[0];
 }
 export class AndroidTransport {
     platform = "android";
@@ -148,6 +149,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();
     }
@@ -228,7 +239,7 @@ export class AndroidTransport {
                     const id = match[1];
                     profiles.push({
                         userId: id,
-                        label: id === "0" ? "Personal (user 0)" : `Work profile (user ${id})`,
+                        label: id === "0" ? "Personal (user 0)" : `Secondary (user ${id}, e.g. a work profile)`,
                     });
                 }
             }

package/dist/shared/constants.d.ts

@@ -4,3 +4,23 @@ export declare const RADAR_PORT = 8099;
 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;

package/dist/shared/constants.js

@@ -4,3 +4,23 @@ export const RADAR_PORT = 8099;
 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;

package/dist/shared/db.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 port-scoped path. Call from the web server on startup. */
+export declare function initializeDatabasePath(port: 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>;
+/**
+ * Run a read-only query against a (lazily pulled) local copy.
+ *
+ * Read-only is NOT just about blocking writes. `sqlite3 -readonly` forbids writes to the
+ * opened DB, but a single SELECT can still READ any host file the process can open, via
+ * `ATTACH '/path' AS x; SELECT * FROM x.t` or `SELECT readfile('/path')` — a confidentiality
+ * bypass (the other plaintext Slack DBs, any file on disk), reachable through the query box
+ * or a pushed db-spec's `sql`. Three layers close this:
+ *   1. `sqlite3 -safe` — engine-level: forbids ATTACH, readfile/writefile/edit, and
+ *      load_extension while still allowing ordinary SELECT/PRAGMA. This is the load-bearing
+ *      control; a keyword denylist alone is whack-a-mole.
+ *   2. the guard below: only a SINGLE SELECT/PRAGMA statement (no `;`-chaining), and an
+ *      explicit reject of attach/readfile/writefile names as defense in depth.
+ *   3. `-readonly` still blocks writes to the opened DB.
+ * 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;