@slack/radar-mcp 1.10.0 → 1.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -49,7 +49,7 @@ Opens `http://localhost:8100` automatically. Set `SLACK_RADAR_WEB_PORT` to use a
49
49
  * **Database** — read-only browser for the on-device SQLite stores (pick a database, then a table, or run a read-only query). See the data-handling note below.
50
50
  * **Custom** — a tab Claude builds on request. Ask a Claude Code session in your terminal for a view the pre-built tabs do not cover (e.g. "graph calls per second and flag the slow ones"); it authors the view via the `open_radar_dashboard` tool and it appears here. Persists until you refresh the page.
51
51
 
52
- Each tab has a 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. The dashboard follows your system light/dark setting by default; the theme toggle in the header overrides it and is remembered.
52
+ Each tab has a rate, sparkline, graph, a filter / sort / pause feed, and a payload inspector. The filter box takes space-separated terms that must all match, `-term` to exclude, `/pattern/` for regex, and `"quoted phrases"` for spaces or a literal `-` or `/`. Committed terms turn into removable pills; a leading `-` is now the exclude operator (the old box matched it as plain text), and quoting restores the literal. Regex flags are optional and short (i/m/s/g, 1-2 letters only, so an ambiguous tail like `/api/im` reads as flags, noted in the tooltip); typos like `/error/x` become part of the pattern and match literally, and quoting any `/…/` term matches it literally. Invalid regexes and incomplete typing (e.g. `/foo(`) are ignored (the term turns amber) instead of blanking the feed. On the Live tab a kind name (`log`, `clog`, `trace`, `rtm`, `network`) also matches rows of that type, and its `-kind` form excludes by row type only, so `-log` hides logcat lines without touching a `logout` clog (quote it, `-"log"`, to exclude by text instead). 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. The dashboard follows your system light/dark setting by default; the theme toggle in the header overrides it and is remembered.
53
53
 
54
54
  ### Screen overlay
55
55
 
@@ -81,7 +81,7 @@ Radar starts **disabled** each session. All tools except `ping` return an error
81
81
 
82
82
  | Tool | Description |
83
83
  |---|---|
84
- | `ping` | Health check. Returns uptime, buffer sizes, remaining session time, stream status, and which app/profile is bound (`android_user_id`, `profile` personal/secondary, `package`). Use `timeout_minutes` to extend sessions. |
84
+ | `ping` | Health check. Returns uptime, buffer sizes, remaining session time, stream status, the Radar MCP version (`mcp_version`), and which app/profile is bound (`android_user_id`, `profile` personal/secondary, `package`). Use `timeout_minutes` to extend sessions. |
85
85
  | `get_recent_network_calls` | HTTP call summaries: method, URL, status code, duration. Filterable by URL substring and status code. |
86
86
  | `get_network_call_detail` | Full request/response headers and bodies for a specific call (gzip/brotli decompressed). |
87
87
  | `get_recent_rtm_events` | RTM event summaries: type, direction, channel, timestamp. Filterable by type, direction, channel. Uses subtypes (e.g. `message_changed`, not `message`). |
package/dist/mcp/index.js CHANGED
@@ -8,7 +8,7 @@ import http from "http";
8
8
  import path from "path";
9
9
  import { fileURLToPath } from "url";
10
10
  import { AndroidTransport } from "../shared/android.js";
11
- import { RADAR_HOST, RADAR_PORT, WEB_PORT_DEFAULT, MAX_RADAR_RESPONSE_BYTES } from "../shared/constants.js";
11
+ import { RADAR_HOST, RADAR_PORT, RADAR_VERSION, WEB_PORT_DEFAULT, MAX_RADAR_RESPONSE_BYTES } from "../shared/constants.js";
12
12
  import { stopCapture } from "../shared/logcat-capture.js";
13
13
  import { getSpoolFilePath, epochFromSpoolPath, initializeSpoolDir, readSpool, startSpool, stopSpool, writeFrame, registerCleanup as registerSpoolCleanup, } from "../shared/event-spool.js";
14
14
  import { connectStream, destroyStream, waitForEvents, clearLocalBuffers, isStreamConnected, localNetworkBuffer, localRtmBuffer, setTransport, setOnReconnect, } from "../shared/stream.js";
@@ -16,8 +16,10 @@ import { buildBufferPath, createSnapshot } from "./snapshot.js";
16
16
  import { clampLogLimit, shapeLogsResult } from "./logs-result.js";
17
17
  import { querySession, clampByteCap, toNum } from "./session-query.js";
18
18
  import { resolveDetailById } from "./session-detail.js";
19
+ import { runSessionEnable } from "./session-enable.js";
19
20
  import { backfillSpool, BACKFILL_SOURCES, makeSerializedRunner, } from "./session-backfill.js";
20
21
  import { handleListDatabases, handleListTables, handleQueryDatabase, } from "./db-tools.js";
22
+ import { handleListPrefs, handleGetPrefs, handleSearchPrefs, } from "./prefs-tools.js";
21
23
  import { cleanupPulledDatabases, initializeDatabasePath, resetDbState, } from "../shared/db.js";
22
24
  import { TOOL_DEFINITIONS, SERVER_INSTRUCTIONS, sessionGate } from "./tools.js";
23
25
  import { buildApiPath } from "./api-paths.js";
@@ -276,7 +278,7 @@ async function runMcpServer() {
276
278
  // a truncation marker rather than a partial JSON blob the parser would choke on. Bulk exports go
277
279
  // through capture_snapshot, not this path. The ceiling now lives in constants so the device path
278
280
  // and the session-query byte cap share one value.
279
- function radarRequest(requestPath) {
281
+ function radarRequest(requestPath, timeoutMs = 10000) {
280
282
  return new Promise((resolve, reject) => {
281
283
  // settled-guard: req.destroy() on the cap path fires "error" (ECONNRESET) AFTER we have
282
284
  // already resolved the truncation, so every settle goes through these wrappers and the
@@ -298,7 +300,7 @@ async function runMcpServer() {
298
300
  host: RADAR_HOST,
299
301
  port: RADAR_PORT,
300
302
  path: requestPath,
301
- timeout: 10000,
303
+ timeout: timeoutMs,
302
304
  }, (res) => {
303
305
  let data = "";
304
306
  let bytes = 0;
@@ -329,8 +331,16 @@ async function runMcpServer() {
329
331
  });
330
332
  });
331
333
  }
334
+ // Reassert the shared adb forward before every HTTP-based device read. Prefer
335
+ // reassertForward() (repoints the shared port at OUR pinned device even if a separate
336
+ // process silently moved it) over plain ensureForward() (trusts a same-process cache
337
+ // that cannot see another process's repoint). Platforms without a shared host-level
338
+ // forward may omit reassertForward, so this falls back to ensureForward.
339
+ function forwardForRead() {
340
+ return device.reassertForward?.() ?? device.ensureForward();
341
+ }
332
342
  async function callRadar(requestPath) {
333
- if (!device.ensureForward()) {
343
+ if (!forwardForRead()) {
334
344
  return {
335
345
  error: "Port forwarding failed. Ensure a device is connected and the debug build is running.",
336
346
  };
@@ -376,55 +386,51 @@ async function runMcpServer() {
376
386
  // --- Tool handlers ---
377
387
  async function handleSessionEnable(args) {
378
388
  const timeout = args?.timeout_minutes || 5;
379
- sessionEnabled = true;
380
- // A re-enable may be a different device or a re-armed profile, so drop the cached DB
381
- // user set + sqlite path; the next DB tool call re-detects the profiles fresh. Mirrors
382
- // the web server's handleEnable (server.ts), which resets for the same reason.
383
- resetDbState();
384
- const forwarded = device.ensureForward();
385
- if (!forwarded) {
386
- sessionEnabled = false;
387
- const reason = device.getLastForwardError?.() ?? null;
388
- return textResult({
389
- error: reason ??
390
- "Port forwarding failed. Ensure a device is connected.",
391
- enabled: false,
392
- platform: device.platform,
393
- }, true);
394
- }
395
- device.activate(timeout);
396
- // Open the session event spool, then backfill the device rings into it. Note the live SSE push can
397
- // start DURING the backfill: the backfill pulls the ring lists via callRadar, which opens the
398
- // stream on its first fetch, so the trailing connectStream() below is usually a no-op (it only
399
- // opens the stream when the backfill wrote nothing and never called callRadar, e.g. empty rings).
400
- // Correctness does NOT rely on connect ordering. It relies on two things: the (source, id) have-set
401
- // that skips a row already in the spool, and the unconditional read-time collapse (every read folds
402
- // a duplicated id to one frame), so a frame the live push and the backfill both write surfaces once.
403
- // Serialized so it cannot overlap a reconnect backfill. Never throws; a device blip just skips it.
404
- startSpool();
405
- await runBackfillSerialized();
406
- connectStream();
407
- // Open the session event spool so every streamed frame is captured to a host
408
- // file for the life of this enabled session.
409
- startSpool();
410
- await new Promise((r) => setTimeout(r, 500));
389
+ const deviceSerial = args?.device_serial ?? null;
390
+ // The orchestration lives in session-enable.ts (testable without the stdio
391
+ // server this module starts at load); this handler wires the real effects
392
+ // and owns the session flag. sessionEnabled goes true up front so the
393
+ // backfill's device pulls pass the session gate, then follows the outcome.
394
+ // The catch covers a future refactor introducing a rejecting await: without
395
+ // it the gate would stay open (sessionEnabled true) on a half-torn session
396
+ // while the SDK reports an opaque error.
411
397
  try {
412
- const status = await radarRequest("/api/ping");
413
- return textResult({
414
- enabled: true,
415
- platform: device.platform,
416
- stream_connected: isStreamConnected(),
417
- ...status,
398
+ sessionEnabled = true;
399
+ const outcome = await runSessionEnable(timeout, deviceSerial, {
400
+ device,
401
+ destroyStream,
402
+ connectStream,
403
+ isStreamConnected,
404
+ resetDbState,
405
+ startSpool,
406
+ runBackfill: runBackfillSerialized,
407
+ // A health ping does not need the default 10s: a half-alive server
408
+ // (accepts TCP, never answers) would otherwise stretch the verify loop
409
+ // past the MCP client's 60s tool-call timeout, and the crafted error
410
+ // would never reach the user. 2s keeps worst-case enable wall time far
411
+ // under that ceiling.
412
+ ping: () => radarRequest("/api/ping", 2000),
413
+ sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
414
+ // Only fires on a switch to a different device: the prior device's buffers,
415
+ // spool, capture, and pulled DBs are stale for the new hardware.
416
+ onDeviceSwitch: () => {
417
+ clearLocalBuffers();
418
+ stopSpool();
419
+ stopCapture();
420
+ cleanupPulledDatabases();
421
+ },
418
422
  });
423
+ sessionEnabled = outcome.enabled;
424
+ return textResult(outcome.body, !outcome.enabled);
419
425
  }
420
- catch {
426
+ catch (e) {
427
+ sessionEnabled = false;
428
+ destroyStream();
421
429
  return textResult({
422
- enabled: true,
430
+ error: `Enable failed unexpectedly: ${e.message}`,
431
+ enabled: false,
423
432
  platform: device.platform,
424
- stream_connected: isStreamConnected(),
425
- ping: "failed",
426
- note: "Radar activated but ping failed. Device may need a moment.",
427
- });
433
+ }, true);
428
434
  }
429
435
  }
430
436
  function handleSessionDisable() {
@@ -448,7 +454,7 @@ async function runMcpServer() {
448
454
  }
449
455
  async function handleWaitForEvents(args) {
450
456
  if (!isStreamConnected()) {
451
- if (!device.ensureForward()) {
457
+ if (!forwardForRead()) {
452
458
  return textResult({ error: "Not connected. Ensure device is connected and radar is enabled." }, true);
453
459
  }
454
460
  device.activate(device.getTimeoutMinutes());
@@ -635,6 +641,10 @@ async function runMcpServer() {
635
641
  device.activate(args.timeout_minutes);
636
642
  }
637
643
  const result = await callRadar("/api/ping");
644
+ // Version is a property of this process, not the device, so it is reported
645
+ // even when the device probe fails — the error path is exactly when a
646
+ // reviewer needs to correlate a report against a known-bad release.
647
+ result.mcp_version = RADAR_VERSION;
638
648
  if (!result.error) {
639
649
  result.stream_connected = isStreamConnected();
640
650
  result.local_network_buffer = localNetworkBuffer.length;
@@ -668,7 +678,7 @@ async function runMcpServer() {
668
678
  }
669
679
  }
670
680
  // --- MCP Server ---
671
- const server = new Server({ name: "slack-radar", version: "1.10.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
681
+ const server = new Server({ name: "slack-radar", version: "1.12.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
672
682
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
673
683
  tools: TOOL_DEFINITIONS,
674
684
  }));
@@ -740,6 +750,21 @@ async function runMcpServer() {
740
750
  if (name === "query_session") {
741
751
  return await handleQuerySession(toolArgs);
742
752
  }
753
+ if (name === "list_prefs") {
754
+ const { user } = toolArgs;
755
+ const { data, isError } = await handleListPrefs(user);
756
+ return textResult(data, isError);
757
+ }
758
+ if (name === "get_prefs") {
759
+ const { file, user, keys } = toolArgs;
760
+ const { data, isError } = await handleGetPrefs(file ?? "", user, keys);
761
+ return textResult(data, isError);
762
+ }
763
+ if (name === "search_prefs") {
764
+ const { query, user } = toolArgs;
765
+ const { data, isError } = await handleSearchPrefs(query ?? "", user);
766
+ return textResult(data, isError);
767
+ }
743
768
  const apiPath = buildApiPath(name, toolArgs);
744
769
  if (apiPath === null) {
745
770
  return textResult(`Unknown tool: ${name}`, true);
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Handler dispatch for the three prefs tools: list_prefs, get_prefs, search_prefs.
3
+ */
4
+ export declare function handleListPrefs(user?: string): Promise<{
5
+ data: unknown;
6
+ isError: boolean;
7
+ }>;
8
+ export declare function handleGetPrefs(file: string, user?: string, keys?: string[]): Promise<{
9
+ data: unknown;
10
+ isError: boolean;
11
+ }>;
12
+ export declare function handleSearchPrefs(query: string, user?: string): Promise<{
13
+ data: unknown;
14
+ isError: boolean;
15
+ }>;
@@ -0,0 +1,204 @@
1
+ /**
2
+ * Handler dispatch for the three prefs tools: list_prefs, get_prefs, search_prefs.
3
+ */
4
+ import { listPrefsFiles, readPrefsFile, parsePrefsXml, searchPrefs, } from "../shared/prefs.js";
5
+ import { resolveAdbPath } from "../shared/android.js";
6
+ import { availableUsers } from "../shared/db.js";
7
+ import { MAX_PREFS_RESPONSE_BYTES } from "../shared/constants.js";
8
+ /**
9
+ * Bound entries to the 64KB response budget with a single forward pass (the db-tools
10
+ * capQueryRows shape, see db-tools.ts:55-88, reimplemented here for the prefs entry type).
11
+ * Sizes against the WORST-CASE envelope (both truncation flags + the longest note text) so
12
+ * the fixed fields around `entries` never eat into a budget calculated for the untruncated
13
+ * case, which would either overrun MAX_PREFS_RESPONSE_BYTES or (the original bug) silently drop
14
+ * entries without setting response_truncated. Returns the entries to actually return, whether
15
+ * the cap tripped, and the keys of any entries dropped for being individually oversized (a
16
+ * single entry bigger than the WHOLE budget, e.g. one huge JSON-blob value) so the caller can
17
+ * name them rather than silently returning zero entries with no way to retrieve that key even
18
+ * via the `keys` filter, since `keys` filters BEFORE this cap runs.
19
+ */
20
+ function capPrefsEntries(entries, file, user) {
21
+ const overhead = JSON.stringify({
22
+ file,
23
+ user,
24
+ entries: [],
25
+ total_entries: entries.length,
26
+ returned_entries: 0,
27
+ device_read_truncated: true,
28
+ response_truncated: true,
29
+ note: "Device file exceeded 256KB and was truncated. Response truncated to 64KB. Use keys parameter to filter to specific entries or search_prefs to find what you need.",
30
+ dropped_keys: entries.map((e) => e.key),
31
+ privacy_note: "Preference values can include user, team, and org identifiers; review before sharing.",
32
+ }).length;
33
+ const entryBudget = MAX_PREFS_RESPONSE_BYTES - overhead;
34
+ const kept = [];
35
+ const droppedKeys = [];
36
+ let bytes = 0;
37
+ for (const entry of entries) {
38
+ // +1 for the joining comma between array elements.
39
+ const sz = Buffer.byteLength(JSON.stringify(entry), "utf8") + 1;
40
+ if (bytes + sz > entryBudget) {
41
+ // A single entry bigger than the WHOLE remaining budget can never fit by itself either
42
+ // (the budget only shrinks as more is kept, never grows), so record it as dropped and
43
+ // keep scanning for smaller entries that still fit, rather than stopping at the first
44
+ // oversized one. This is what makes an oversized key nameable instead of silently
45
+ // vanishing: `keys` filters before this cap runs, so without this the caller has no way
46
+ // to ever retrieve that key, even by asking for it directly.
47
+ if (sz > entryBudget)
48
+ droppedKeys.push(entry.key);
49
+ continue;
50
+ }
51
+ kept.push(entry);
52
+ bytes += sz;
53
+ }
54
+ return { entries: kept, truncated: kept.length < entries.length, droppedKeys };
55
+ }
56
+ export async function handleListPrefs(user) {
57
+ const adbPath = resolveAdbPath();
58
+ if (!adbPath) {
59
+ return {
60
+ data: {
61
+ error: "adb not found. Set ANDROID_HOME or install Android SDK platform-tools.",
62
+ },
63
+ isError: true,
64
+ };
65
+ }
66
+ try {
67
+ const result = listPrefsFiles(adbPath, user);
68
+ if (!result) {
69
+ const available = availableUsers();
70
+ return {
71
+ data: {
72
+ error: `Failed to list prefs files for user ${user ?? "(any)"}. Is the debug build installed and is a device connected? Available users: ${available.join(", ")}`,
73
+ },
74
+ isError: true,
75
+ };
76
+ }
77
+ return {
78
+ data: {
79
+ user: result.user,
80
+ available_users: availableUsers(),
81
+ files: result.files,
82
+ privacy_note: "Preference values can include user, team, and org identifiers; review before sharing.",
83
+ },
84
+ isError: false,
85
+ };
86
+ }
87
+ catch (e) {
88
+ return {
89
+ data: { error: e instanceof Error ? e.message : String(e) },
90
+ isError: true,
91
+ };
92
+ }
93
+ }
94
+ export async function handleGetPrefs(file, user, keys) {
95
+ if (!file) {
96
+ return {
97
+ data: { error: "file parameter is required" },
98
+ isError: true,
99
+ };
100
+ }
101
+ const adbPath = resolveAdbPath();
102
+ if (!adbPath) {
103
+ return {
104
+ data: {
105
+ error: "adb not found. Set ANDROID_HOME or install Android SDK platform-tools.",
106
+ },
107
+ isError: true,
108
+ };
109
+ }
110
+ try {
111
+ const readResult = await readPrefsFile(adbPath, file, user);
112
+ if ("error" in readResult) {
113
+ return {
114
+ data: { error: readResult.error },
115
+ isError: true,
116
+ };
117
+ }
118
+ const parseResult = parsePrefsXml(readResult.xml);
119
+ if ("parseError" in parseResult) {
120
+ return {
121
+ data: { error: parseResult.parseError },
122
+ isError: true,
123
+ };
124
+ }
125
+ let entries = parseResult.entries;
126
+ // Filter to specified keys if provided.
127
+ if (keys && keys.length > 0) {
128
+ const keySet = new Set(keys);
129
+ entries = entries.filter((e) => keySet.has(e.key));
130
+ }
131
+ // Total = entries after the keys filter (the set the user actually asked for);
132
+ // returned = what survived the 64KB byte cap below.
133
+ const totalEntries = entries.length;
134
+ const deviceTruncated = !!readResult.truncated;
135
+ const { entries: returnedEntries, truncated: responseTruncated, droppedKeys } = capPrefsEntries(entries, file, readResult.user);
136
+ return {
137
+ data: {
138
+ file,
139
+ user: readResult.user,
140
+ entries: returnedEntries,
141
+ total_entries: totalEntries,
142
+ returned_entries: returnedEntries.length,
143
+ ...(deviceTruncated ? { device_read_truncated: true } : {}),
144
+ ...(responseTruncated ? { response_truncated: true } : {}),
145
+ ...(droppedKeys.length > 0 ? { dropped_keys: droppedKeys } : {}),
146
+ ...(deviceTruncated || responseTruncated
147
+ ? {
148
+ note: `${deviceTruncated ? "Device file exceeded 256KB and was truncated. " : ""}${responseTruncated ? "Response truncated to 64KB. " : ""}${droppedKeys.length > 0 ? `${droppedKeys.length} entries were individually too large to include (see dropped_keys). ` : ""}Use keys parameter to filter to specific entries or search_prefs to find what you need.`,
149
+ }
150
+ : {}),
151
+ privacy_note: "Preference values can include user, team, and org identifiers; review before sharing.",
152
+ },
153
+ isError: false,
154
+ };
155
+ }
156
+ catch (e) {
157
+ return {
158
+ data: { error: e instanceof Error ? e.message : String(e) },
159
+ isError: true,
160
+ };
161
+ }
162
+ }
163
+ export async function handleSearchPrefs(query, user) {
164
+ if (!query) {
165
+ return {
166
+ data: { error: "query parameter is required" },
167
+ isError: true,
168
+ };
169
+ }
170
+ const adbPath = resolveAdbPath();
171
+ if (!adbPath) {
172
+ return {
173
+ data: {
174
+ error: "adb not found. Set ANDROID_HOME or install Android SDK platform-tools.",
175
+ },
176
+ isError: true,
177
+ };
178
+ }
179
+ try {
180
+ const { results, truncated, skipped, user: resolvedUser } = await searchPrefs(adbPath, query, user);
181
+ const response = {
182
+ query,
183
+ user: resolvedUser,
184
+ available_users: availableUsers(),
185
+ results,
186
+ };
187
+ if (truncated)
188
+ response.truncated = true;
189
+ if (skipped && skipped.length > 0)
190
+ response.skipped = skipped;
191
+ response.privacy_note =
192
+ "Preference values can include user, team, and org identifiers; review before sharing.";
193
+ return {
194
+ data: response,
195
+ isError: false,
196
+ };
197
+ }
198
+ catch (e) {
199
+ return {
200
+ data: { error: e instanceof Error ? e.message : String(e) },
201
+ isError: true,
202
+ };
203
+ }
204
+ }
@@ -0,0 +1,18 @@
1
+ import type { DeviceTransport } from "../shared/transport.js";
2
+ export interface EnableDeps {
3
+ device: DeviceTransport;
4
+ destroyStream: () => void;
5
+ connectStream: () => void;
6
+ isStreamConnected: () => boolean;
7
+ resetDbState: () => void;
8
+ startSpool: () => void;
9
+ runBackfill: () => Promise<unknown>;
10
+ ping: () => Promise<Record<string, unknown>>;
11
+ sleep: (ms: number) => Promise<void>;
12
+ onDeviceSwitch: () => void;
13
+ }
14
+ export interface EnableOutcome {
15
+ body: Record<string, unknown>;
16
+ enabled: boolean;
17
+ }
18
+ export declare function runSessionEnable(timeoutMinutes: number, deviceSerial: string | null, deps: EnableDeps): Promise<EnableOutcome>;
@@ -0,0 +1,131 @@
1
+ // Ping-verify cadence: first probe fast (a healthy server answers immediately;
2
+ // this is the whole latency of a normal enable), then two patient retries to
3
+ // absorb real server startup.
4
+ const PING_WAITS_MS = [500, 1000, 1000];
5
+ export async function runSessionEnable(timeoutMinutes, deviceSerial, deps) {
6
+ const { device, destroyStream, connectStream, isStreamConnected, resetDbState, startSpool, runBackfill, ping, sleep, onDeviceSwitch, } = deps;
7
+ // Tear down the old stream (and its reconnect loop) FIRST, then drop all cached
8
+ // transport state so this enable starts clean. Without the reset, a stale adb
9
+ // forward (device end dead after an idle timeout or a replug) makes ensureForward()
10
+ // a cached no-op, and a user id cached from an earlier detect can pin the enable
11
+ // broadcast to the wrong profile. The web server's handleEnable (server.ts) has
12
+ // always reset for the same reason; the MCP path was missing it.
13
+ destroyStream();
14
+ device.resetState();
15
+ // A re-enable may be a different device or a re-armed profile, so drop the cached DB
16
+ // user set + sqlite path; the next DB tool call re-detects the profiles fresh.
17
+ resetDbState();
18
+ // Pin which device this session targets BEFORE any adb call. selectDevice sets
19
+ // process.env.ANDROID_SERIAL once; every later adb call site inherits it. An ambiguous
20
+ // choice (multiple devices, no serial) or an unattached explicit serial short-circuits
21
+ // here with the device list, before ensureForward touches the wrong device.
22
+ const selection = device.selectDevice?.(deviceSerial);
23
+ if (selection && !selection.ok) {
24
+ return {
25
+ enabled: false,
26
+ body: {
27
+ // The transport error is a neutral core; the MCP body appends agent-facing retry guidance.
28
+ error: `${selection.error} Retry _radar_session_enable with device_serial set to one of them. If you cannot tell which device the user wants, ask them before retrying.`,
29
+ devices: selection.devices,
30
+ enabled: false,
31
+ platform: device.platform,
32
+ },
33
+ };
34
+ }
35
+ // A switch to a different device makes the prior session's device-scoped state
36
+ // (buffers, spool, capture, pulled DBs) belong to the wrong hardware, so reset it
37
+ // before forwarding. A same-device re-enable skips this: spool continuity is intended.
38
+ if (selection && selection.ok && selection.switched) {
39
+ onDeviceSwitch();
40
+ }
41
+ if (!device.ensureForward()) {
42
+ const reason = device.getLastForwardError?.() ?? null;
43
+ return {
44
+ enabled: false,
45
+ body: {
46
+ error: reason ?? "Port forwarding failed. Ensure a device is connected.",
47
+ enabled: false,
48
+ platform: device.platform,
49
+ },
50
+ };
51
+ }
52
+ device.activate(timeoutMinutes);
53
+ const activateError = device.getLastActivateError?.() ?? null;
54
+ if (activateError) {
55
+ // The broadcast failed at the adb level. The device server may STILL be alive
56
+ // (armed by a prior session, or the broadcast timed out on a loaded device
57
+ // after landing), so probe before failing: a working server beats a pedantic
58
+ // error, and a dead one gets a real error instead of the old silent
59
+ // enabled:true + failing tools.
60
+ try {
61
+ await ping();
62
+ }
63
+ catch {
64
+ return {
65
+ enabled: false,
66
+ body: {
67
+ error: `Radar activation broadcast failed: ${activateError}. Is the device connected? Check adb devices.`,
68
+ enabled: false,
69
+ platform: device.platform,
70
+ },
71
+ };
72
+ }
73
+ }
74
+ // Open the session event spool, then backfill the device rings into it. The live
75
+ // SSE push can start DURING the backfill (the backfill pulls via the injected
76
+ // fetch, which opens the stream on its first call), so the trailing
77
+ // connectStream() is usually a no-op. Correctness does not rely on connect
78
+ // ordering: the (source, id) have-set and the read-time collapse fold any
79
+ // frame both paths write into one.
80
+ startSpool();
81
+ await runBackfill();
82
+ connectStream();
83
+ // Verify the device server actually came up. A broadcast can land nowhere and
84
+ // still exit 0 (no receiver: radar modules missing from the build, or a
85
+ // wrong-profile target). Retry to absorb real startup latency before
86
+ // declaring it dead.
87
+ let status = null;
88
+ for (const waitMs of PING_WAITS_MS) {
89
+ await sleep(waitMs);
90
+ try {
91
+ status = await ping();
92
+ break;
93
+ }
94
+ catch {
95
+ // Retry until the waits are exhausted.
96
+ }
97
+ }
98
+ if (status === null) {
99
+ destroyStream();
100
+ return {
101
+ enabled: false,
102
+ body: {
103
+ error: "Radar broadcast sent but the device server did not respond. Is a debug build with the slack-radar modules installed and running on the active profile?",
104
+ enabled: false,
105
+ platform: device.platform,
106
+ },
107
+ };
108
+ }
109
+ const selected = device.getSelectedDevice?.() ?? null;
110
+ return {
111
+ enabled: true,
112
+ body: {
113
+ enabled: true,
114
+ platform: device.platform,
115
+ stream_connected: isStreamConnected(),
116
+ ...(selected
117
+ ? { device_serial: selected.serial, device_label: selected.label }
118
+ : {}),
119
+ // The broadcast failed but the server answered (armed by a prior session).
120
+ // activate()'s success branch never ran, so the logcat capture is not
121
+ // armed: get_recent_logs degrades to the device ring for this session.
122
+ // Named so the degradation is visible instead of silent.
123
+ ...(activateError
124
+ ? {
125
+ logcat_capture: "not started (activation broadcast failed; logs fall back to the device ring)",
126
+ }
127
+ : {}),
128
+ ...status,
129
+ },
130
+ };
131
+ }
@@ -2,6 +2,7 @@ import { spawnSync } from "child_process";
2
2
  import fs from "fs";
3
3
  import os from "os";
4
4
  import path from "path";
5
+ import { RADAR_VERSION } from "../shared/constants.js";
5
6
  import { getCaptureFilePath, readTailBytes } from "../shared/logcat-capture.js";
6
7
  /**
7
8
  * `capture_snapshot` composer: bundles everything Radar has seen into a
@@ -34,6 +35,7 @@ This directory is a point-in-time bundle of Radar state.
34
35
 
35
36
  Files:
36
37
  - bundle.json: device-side network/RTM/clog/trace buffers, counts, and metadata.
38
+ Its mcp_version field records which @slack/radar-mcp produced this bundle.
37
39
  - logcat.tail.log (optional): last N lines of the on-device logcat capture.
38
40
  - screenshot.png (optional): current screen.
39
41
 
@@ -241,7 +243,10 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
241
243
  screenshot: screenshotCaptured,
242
244
  };
243
245
  const bundle = {
244
- version: 2,
246
+ // Format version of this bundle's schema — not the Radar version, which
247
+ // is mcp_version below. Named to keep the two unmistakable in a shared file.
248
+ bundle_format_version: 2,
249
+ mcp_version: RADAR_VERSION,
245
250
  timestamp: now,
246
251
  platform: device.platform,
247
252
  active_user_id: device.getActiveUserId(),