@slack/radar-mcp 1.9.0 → 1.10.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
@@ -40,10 +40,11 @@ slack-radar
40
40
 
41
41
  Opens `http://localhost:8100` automatically. Set `SLACK_RADAR_WEB_PORT` to use a different port. (`slack-radar-web` still works as a direct alias.) Tabs:
42
42
 
43
- * **Live** — network, RTM, analytics clogs, and Slack-app logcat in one timeline
43
+ * **Live** — network, RTM, analytics clogs, traces, and Slack-app logcat in one timeline
44
44
  * **Network** — calls per second vs response time, every call listed, slow ones flagged
45
45
  * **RTM** — real-time websocket events
46
46
  * **Clogs** — analytics events, click one to see its payload
47
+ * **Traces** — performance trace spans with durations, click one for its timing and tags
47
48
  * **Logs** — device logcat, filtered to the Slack app (switch app or clear the filter)
48
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.
49
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.
@@ -140,10 +141,10 @@ What gets captured depends on the in-app server implementation. The MCP server i
140
141
  * **Network calls**: OkHttp interceptor. Ring buffer: 400 calls.
141
142
  * **RTM events**: WebSocket listener. Ring buffer: 2000 events.
142
143
  * **Clogs**: Analytics interceptor. Ring buffer: 1000 events. Persists across radar activation cycles.
143
- * **Traces**: Performance span observer. Ring buffer: 1000 spans. Persists across radar activation cycles.
144
+ * **Traces**: Performance span observer. Ring buffer: 2000 spans. Persists across radar activation cycles.
144
145
  * **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.
145
146
 
146
- 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.
147
+ The network, RTM, clog, and trace 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.
147
148
 
148
149
  ### What gets captured, in detail
149
150
 
package/dist/mcp/index.js CHANGED
@@ -668,7 +668,7 @@ async function runMcpServer() {
668
668
  }
669
669
  }
670
670
  // --- MCP Server ---
671
- const server = new Server({ name: "slack-radar", version: "1.9.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
671
+ const server = new Server({ name: "slack-radar", version: "1.10.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
672
672
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
673
673
  tools: TOOL_DEFINITIONS,
674
674
  }));
@@ -161,8 +161,16 @@ function matchesFilter(frame, f) {
161
161
  return false;
162
162
  if (f.channel !== undefined && e.channel !== f.channel)
163
163
  return false;
164
- if (f.name !== undefined && !includesCI(e.name, f.name))
165
- return false;
164
+ // "name" spans the per-source name fields: clogs carry event_name, traces carry
165
+ // trace_name/span_name; no source emits a literal `name` field. A hit on any counts.
166
+ if (f.name !== undefined) {
167
+ const nameHit = includesCI(e.name, f.name) ||
168
+ includesCI(e.event_name, f.name) ||
169
+ includesCI(e.trace_name, f.name) ||
170
+ includesCI(e.span_name, f.name);
171
+ if (!nameHit)
172
+ return false;
173
+ }
166
174
  // `text` searches the whole serialized frame, so it catches content in any field including the
167
175
  // clog detail payload, not just the named summary fields above.
168
176
  if (f.text !== undefined && !JSON.stringify(frame).toLowerCase().includes(f.text.toLowerCase())) {
package/dist/mcp/tools.js CHANGED
@@ -45,7 +45,7 @@ export const SERVER_INSTRUCTIONS = [
45
45
  "",
46
46
  "WEB DASHBOARD (/radar-ui):",
47
47
  "A browser-based dashboard (http://localhost:8100) shows the same live device data as",
48
- "tabs: Live (everything), Network, RTM, Clogs, and Logs, each with counters, a graph, a",
48
+ "tabs: Live (everything), Network, RTM, Clogs, Traces, and Logs, each with counters, a graph, a",
49
49
  "filterable feed, and a payload inspector. Launched via the /radar-ui skill, which runs",
50
50
  "`npx @slack/radar-mcp web` (a global install also exposes it as `slack-radar`).",
51
51
  "",
@@ -75,7 +75,7 @@ export const SERVER_INSTRUCTIONS = [
75
75
  "screen.installHint, so you can check before suggesting.",
76
76
  "",
77
77
  "CUSTOM DASHBOARD (open_radar_dashboard):",
78
- "The pre-built tabs (Live/Network/RTM/Clogs/Logs) cover the common cases. When the user",
78
+ "The pre-built tabs (Live/Network/RTM/Clogs/Traces/Logs) cover the common cases. When the user",
79
79
  "describes a live view the tabs do not show, SUGGEST building it; invoke open_radar_dashboard",
80
80
  "only after they agree or explicitly ask for a custom view/dashboard (same discipline as",
81
81
  "/radar-ui). To build, translate their words into a spec and call the tool; it renders your",
@@ -86,9 +86,10 @@ export const SERVER_INSTRUCTIONS = [
86
86
  '- "show only RTM events on channel C... and let me click each for its payload"',
87
87
  '- "watch network calls whose body contains <substring>"',
88
88
  "Authoring rules:",
89
- "- source is one of network/rtm/clog/log/all ('all' = one unified timeline).",
89
+ "- source is one of network/rtm/clog/trace/log/all ('all' = one unified timeline).",
90
90
  "- match filters on SUMMARY fields only, by source: network=url/method/status_code,",
91
- " rtm=event_type/direction/channel, clog=event_name, log=tag/level/message/pid/package.",
91
+ " rtm=event_type/direction/channel, clog=event_name, trace=trace_name/span_name,",
92
+ " log=tag/level/message/pid/package.",
92
93
  " NEVER invent a field; a match on a field the stream does not carry silently matches",
93
94
  " nothing. To filter on body text use bodyContains (network/all only), which fetches detail.",
94
95
  "- viz composes counter/rate/sparkline/feed/inspector/graph. graph needs a series array",
@@ -373,7 +374,7 @@ export const TOOL_DEFINITIONS = [
373
374
  {
374
375
  name: "open_radar_dashboard",
375
376
  description: "Build or refine a custom live dashboard tab in the Slack Radar web UI from a spec YOU author. " +
376
- "Suggest this when the user describes a live view the pre-built tabs (Live/Network/RTM/Clogs/Logs) do not cover " +
377
+ "Suggest this when the user describes a live view the pre-built tabs (Live/Network/RTM/Clogs/Traces/Logs) do not cover " +
377
378
  "(e.g. 'graph calls per second vs response time and flag slow ones', 'beep when I get a DM'); invoke it once they agree. " +
378
379
  "Translate the request into the spec fields below and call this tool; it ensures the web dashboard is " +
379
380
  "running (default http://localhost:8100) and renders your spec as a 'Custom' tab, then returns the URL to share. " +
@@ -390,12 +391,12 @@ export const TOOL_DEFINITIONS = [
390
391
  source: {
391
392
  type: "string",
392
393
  enum: [...SOURCES],
393
- description: "Which device stream to read. 'all' is a unified timeline mixing network, RTM, and clog.",
394
+ description: "Which device stream to read. 'all' is a unified timeline mixing network, RTM, clog, trace, and log.",
394
395
  },
395
396
  match: {
396
397
  type: "object",
397
398
  description: "Case-insensitive substring filter on SUMMARY fields, keyed by source. network: url/method/status_code; " +
398
- "rtm: event_type/direction/channel; clog: event_name; log: tag/level/package. NEVER invent a field " +
399
+ "rtm: event_type/direction/channel; clog: event_name; trace: trace_name/span_name; log: tag/level/package. NEVER invent a field " +
399
400
  "(a match on an absent field silently matches nothing). For body text use bodyContains instead.",
400
401
  },
401
402
  bodyContains: {
@@ -102,6 +102,28 @@ export declare function pickDisplay(displays: DisplayInfo[]): {
102
102
  };
103
103
  /** Strip any text prefix (e.g. a multi-display warning) before the PNG magic header. */
104
104
  export declare function stripPngPrefix(raw: Buffer): Buffer;
105
+ /**
106
+ * Clamp a requested frame rate to a safe positive integer for use in an ffmpeg `fps=` filter.
107
+ * The rate ultimately comes from a client-controlled `?fps=` query param, and a raw number
108
+ * threaded into `fps=${n}` is a footgun: a negative or Infinity value makes ffmpeg write a
109
+ * 0-byte file (silent no-recording), a fractional value produces a stuttering near-empty clip,
110
+ * and a huge value hangs ffmpeg (a leaked, never-exiting encoder). Round to an integer and bound
111
+ * to [MIN_FPS, MAX_FPS]; anything non-finite or out of range falls back to DEFAULT_FPS.
112
+ */
113
+ export declare function clampFps(fps: number): number;
114
+ /**
115
+ * ffmpeg args for the record-to-mp4 pipeline: the live cast's concatenated JPEG stream on
116
+ * stdin -> a wall-clock-timed, constant-fps H.264 mp4 at `out`. Pure + exported so the arg
117
+ * SHAPE is unit-testable: the recording is a spawned subprocess with no device-free way to
118
+ * assert timing, and two arg bugs have hidden here — a fixed input `-r` (stamped every frame
119
+ * at 1/fps, slow motion) and `-use_wallclock_as_timestamps` paired with `-f image2pipe`
120
+ * (which ignores the flag and re-stamps a synthetic rate). The invariants the test pins:
121
+ * no `-r` before `-i`; the wallclock flag paired with the mjpeg demuxer that honors it (NOT
122
+ * image2pipe); and an output `fps` resample so playback is real-time and CFR. fps is clamped
123
+ * defensively here too, so the filter string is always a safe integer even if a caller skips
124
+ * the boundary clamp.
125
+ */
126
+ export declare function recordingArgs(fps: number, out: string): string[];
105
127
  /** Detect (and cache) the active display id. resetScreenState() forces a re-detect. */
106
128
  export declare function detectDisplay(): Promise<string | null>;
107
129
  export declare function displayNote(): string;
@@ -120,7 +142,33 @@ interface LiveCast {
120
142
  recording: Recording | null;
121
143
  fps: number;
122
144
  keepalive: NodeJS.Timeout | null;
145
+ orphanTimer: NodeJS.Timeout | null;
123
146
  }
147
+ /**
148
+ * Is this viewer's socket still open and writable? A closed/destroyed response is dead.
149
+ * Exported for unit testing: this predicate decides whether pushFrame prunes a viewer,
150
+ * so a regression here would either leak (never prune) or drop live viewers (prune too eagerly).
151
+ */
152
+ export declare function viewerAlive(r: NodeJS.WritableStream): boolean;
153
+ /**
154
+ * Pure decision for what to do once a viewer is gone, given how many viewers remain and
155
+ * whether a recording is running. Extracted from afterViewerRemoved so the loop-closing
156
+ * logic is unit-testable without spawning: this is the gate that decides between leaking
157
+ * (keep the cast) and reaping. "watched" = a viewer is still attached, keep the cast as-is;
158
+ * "arm-grace" = unwatched but recording, hold briefly for a clean stop; "reap" = nothing
159
+ * left, tear down now.
160
+ */
161
+ export declare function nextViewerAction(viewers: number, recording: boolean): "watched" | "arm-grace" | "reap";
162
+ /**
163
+ * The literal respawn root cause, as a pure predicate: on a screenrecord/ffmpeg exit, relaunch
164
+ * a fresh cast ONLY while a viewer is still watching. This is the exact gate onExit turns on
165
+ * ("if (viewers.size || recording) relaunch" was the bug — a recording alone respawned forever
166
+ * with no viewer). Extracted pure so the root-cause line is unit-testable, not only device-verified.
167
+ * Note the asymmetry with nextViewerAction: a recording does NOT keep the cast alive here (onExit
168
+ * lets cleanupLive finalize the clip + reap); it only defers reaping in the viewer-removal path
169
+ * via the orphan grace. So relaunch depends on viewers ALONE.
170
+ */
171
+ export declare function shouldRelaunch(viewers: number): boolean;
124
172
  /**
125
173
  * Start (or return the existing) live cast. Returns null if ffmpeg is unavailable
126
174
  * — callers must degrade rather than assume a stream. The boundary string is
@@ -230,6 +230,53 @@ export function stripPngPrefix(raw) {
230
230
  const off = raw.indexOf(PNG_MAGIC);
231
231
  return off > 0 ? raw.subarray(off) : raw;
232
232
  }
233
+ // Bounds for a recording/live-cast frame rate. Client-controlled (?fps=), so clampFps holds
234
+ // the range in one place. MAX 60 = the device panel refresh ceiling (screenrecord cannot feed
235
+ // faster); MIN 1 = a valid non-degenerate rate; DEFAULT 20 = the measured sweet spot the UI
236
+ // uses and the fallback for any out-of-range/non-finite request.
237
+ const MIN_FPS = 1;
238
+ const MAX_FPS = 60;
239
+ const DEFAULT_FPS = 20;
240
+ /**
241
+ * Clamp a requested frame rate to a safe positive integer for use in an ffmpeg `fps=` filter.
242
+ * The rate ultimately comes from a client-controlled `?fps=` query param, and a raw number
243
+ * threaded into `fps=${n}` is a footgun: a negative or Infinity value makes ffmpeg write a
244
+ * 0-byte file (silent no-recording), a fractional value produces a stuttering near-empty clip,
245
+ * and a huge value hangs ffmpeg (a leaked, never-exiting encoder). Round to an integer and bound
246
+ * to [MIN_FPS, MAX_FPS]; anything non-finite or out of range falls back to DEFAULT_FPS.
247
+ */
248
+ export function clampFps(fps) {
249
+ const n = Math.round(fps);
250
+ return Number.isFinite(n) && n >= MIN_FPS && n <= MAX_FPS ? n : DEFAULT_FPS;
251
+ }
252
+ /**
253
+ * ffmpeg args for the record-to-mp4 pipeline: the live cast's concatenated JPEG stream on
254
+ * stdin -> a wall-clock-timed, constant-fps H.264 mp4 at `out`. Pure + exported so the arg
255
+ * SHAPE is unit-testable: the recording is a spawned subprocess with no device-free way to
256
+ * assert timing, and two arg bugs have hidden here — a fixed input `-r` (stamped every frame
257
+ * at 1/fps, slow motion) and `-use_wallclock_as_timestamps` paired with `-f image2pipe`
258
+ * (which ignores the flag and re-stamps a synthetic rate). The invariants the test pins:
259
+ * no `-r` before `-i`; the wallclock flag paired with the mjpeg demuxer that honors it (NOT
260
+ * image2pipe); and an output `fps` resample so playback is real-time and CFR. fps is clamped
261
+ * defensively here too, so the filter string is always a safe integer even if a caller skips
262
+ * the boundary clamp.
263
+ */
264
+ export function recordingArgs(fps, out) {
265
+ return [
266
+ "-hide_banner", "-loglevel", "error", "-y",
267
+ // Raw MJPEG demuxer (not image2pipe): only this demuxer honors
268
+ // -use_wallclock_as_timestamps on a piped JPEG stream, stamping each frame by its true
269
+ // arrival time regardless of frame size. image2pipe stamps a synthetic fixed rate.
270
+ "-f", "mjpeg",
271
+ "-use_wallclock_as_timestamps", "1",
272
+ "-i", "pipe:0",
273
+ // Resample the real arrival timeline to a constant fps so the mp4 is CFR (smooth/seekable
274
+ // everywhere) and its duration matches wall-clock.
275
+ "-vf", `fps=${clampFps(fps)}`,
276
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", "-preset", "veryfast",
277
+ out,
278
+ ];
279
+ }
233
280
  // ---- active-display detection ------------------------------------------------
234
281
  let scDisplay = null;
235
282
  let scDetected = false;
@@ -275,6 +322,95 @@ export function captureScreenshot() {
275
322
  });
276
323
  }
277
324
  let scLive = null;
325
+ // When the last viewer leaves while a recording is running, wait this long for a clean
326
+ // /screen/record/stop before treating the recording as orphaned (tab closed/crashed
327
+ // before its stop POST landed). The clean stop POST arrives in well under a second; this
328
+ // window comfortably clears it while bounding an orphaned cast to a few seconds instead
329
+ // of looping screenrecord until its next self-exit (or forever, via relaunch).
330
+ const ORPHAN_GRACE_MS = 8000;
331
+ /**
332
+ * Is this viewer's socket still open and writable? A closed/destroyed response is dead.
333
+ * Exported for unit testing: this predicate decides whether pushFrame prunes a viewer,
334
+ * so a regression here would either leak (never prune) or drop live viewers (prune too eagerly).
335
+ */
336
+ export function viewerAlive(r) {
337
+ const w = r;
338
+ return w.writable !== false && w.writableEnded !== true && w.destroyed !== true;
339
+ }
340
+ /**
341
+ * Arm the orphan-grace timer: if no viewer returns and no clean stop arrives, finalize the
342
+ * orphaned recording (saved to disk) and reap the cast so screenrecord stops looping. Idempotent
343
+ * — a second call while armed is a no-op. unref'd so it never keeps the process alive on its own.
344
+ */
345
+ function armOrphanGrace(L) {
346
+ if (L.orphanTimer)
347
+ return;
348
+ L.orphanTimer = setTimeout(() => {
349
+ L.orphanTimer = null;
350
+ if (scLive === L && !L.viewers.size && L.recording) {
351
+ // .catch is defensive: stopRecording never rejects and reapLiveIfIdle is sync/guarded
352
+ // today, but this runs in a bare timer callback where an unhandled rejection would be
353
+ // process-wide, so a future edit that lets either throw must not escape here.
354
+ void stopRecording(L)
355
+ .then(() => reapLiveIfIdle())
356
+ .catch(() => {
357
+ /* best-effort orphan reap; nothing to recover to */
358
+ });
359
+ }
360
+ }, ORPHAN_GRACE_MS);
361
+ if (typeof L.orphanTimer.unref === "function")
362
+ L.orphanTimer.unref();
363
+ }
364
+ function clearOrphanGrace(L) {
365
+ if (L.orphanTimer) {
366
+ clearTimeout(L.orphanTimer);
367
+ L.orphanTimer = null;
368
+ }
369
+ }
370
+ /**
371
+ * Pure decision for what to do once a viewer is gone, given how many viewers remain and
372
+ * whether a recording is running. Extracted from afterViewerRemoved so the loop-closing
373
+ * logic is unit-testable without spawning: this is the gate that decides between leaking
374
+ * (keep the cast) and reaping. "watched" = a viewer is still attached, keep the cast as-is;
375
+ * "arm-grace" = unwatched but recording, hold briefly for a clean stop; "reap" = nothing
376
+ * left, tear down now.
377
+ */
378
+ export function nextViewerAction(viewers, recording) {
379
+ if (viewers > 0)
380
+ return "watched";
381
+ return recording ? "arm-grace" : "reap";
382
+ }
383
+ /**
384
+ * The literal respawn root cause, as a pure predicate: on a screenrecord/ffmpeg exit, relaunch
385
+ * a fresh cast ONLY while a viewer is still watching. This is the exact gate onExit turns on
386
+ * ("if (viewers.size || recording) relaunch" was the bug — a recording alone respawned forever
387
+ * with no viewer). Extracted pure so the root-cause line is unit-testable, not only device-verified.
388
+ * Note the asymmetry with nextViewerAction: a recording does NOT keep the cast alive here (onExit
389
+ * lets cleanupLive finalize the clip + reap); it only defers reaping in the viewer-removal path
390
+ * via the orphan grace. So relaunch depends on viewers ALONE.
391
+ */
392
+ export function shouldRelaunch(viewers) {
393
+ return viewers > 0;
394
+ }
395
+ /**
396
+ * Called after a viewer is removed (leave or dead-viewer prune). If the cast is now
397
+ * unwatched, either arm the orphan grace (a recording is still running) or reap it outright
398
+ * (nothing left to keep it alive). This is the single "is anyone still watching?" gate.
399
+ */
400
+ function afterViewerRemoved() {
401
+ if (!scLive)
402
+ return;
403
+ switch (nextViewerAction(scLive.viewers.size, scLive.recording !== null)) {
404
+ case "watched":
405
+ return;
406
+ case "arm-grace":
407
+ armOrphanGrace(scLive);
408
+ return;
409
+ case "reap":
410
+ reapLiveIfIdle();
411
+ return;
412
+ }
413
+ }
278
414
  function screenrecordArgs() {
279
415
  const a = ["exec-out", "screenrecord", "--output-format=h264", "--size", SC_SIZE, "--bit-rate", SC_BITRATE];
280
416
  if (scDisplay)
@@ -300,16 +436,32 @@ async function primeFrame(ffmpeg) {
300
436
  function pushFrame(L, frame) {
301
437
  const head = Buffer.from(`--${SC_BOUNDARY}\r\nContent-Type: image/jpeg\r\nContent-Length: ${frame.length}\r\n\r\n`);
302
438
  const tail = Buffer.from("\r\n");
439
+ // Prune viewers whose socket died without firing req.on("close") — a half-open TCP
440
+ // connection (host sleep, network drop, killed browser) leaves the response object in
441
+ // the set but not writable. Without pruning, a dead viewer keeps the cast "watched"
442
+ // forever and relaunch respawns screenrecord on every self-exit. This frame loop is the
443
+ // heartbeat that detects the dead socket. Collect first, mutate the set after iterating.
444
+ let dead = null;
303
445
  for (const r of L.viewers) {
446
+ if (!viewerAlive(r)) {
447
+ (dead ??= []).push(r);
448
+ continue;
449
+ }
304
450
  try {
305
451
  r.write(head);
306
452
  r.write(frame);
307
453
  r.write(tail);
308
454
  }
309
455
  catch {
310
- // viewer disconnected; harmless
456
+ // write threw on a socket that looked alive; treat it as dead too
457
+ (dead ??= []).push(r);
311
458
  }
312
459
  }
460
+ if (dead) {
461
+ for (const r of dead)
462
+ L.viewers.delete(r);
463
+ afterViewerRemoved();
464
+ }
313
465
  if (L.recording) {
314
466
  try {
315
467
  L.recording.proc.stdin?.write(frame);
@@ -358,6 +510,7 @@ function reapCastProcesses(L) {
358
510
  clearInterval(L.keepalive);
359
511
  L.keepalive = null;
360
512
  }
513
+ clearOrphanGrace(L);
361
514
  L.lastFrame = null;
362
515
  try {
363
516
  L.sr.kill("SIGKILL");
@@ -383,10 +536,14 @@ export function startLive(fps) {
383
536
  const ffmpeg = resolveFfmpeg();
384
537
  if (!ffmpeg)
385
538
  return null;
539
+ // Clamp once at the boundary: fps comes from a client-controlled ?fps= param, and it is used
540
+ // both in the live filter below and (via scLive.fps) by the recording. A negative/fractional/
541
+ // huge value would break either pipeline. Store and use only the clamped value.
542
+ const safeFps = clampFps(fps);
386
543
  const sr = spawn(adb(), screenrecordArgs(), { stdio: ["ignore", "pipe", "ignore"] });
387
544
  const ff = spawn(ffmpeg, [
388
545
  "-hide_banner", "-loglevel", "error", "-f", "h264", "-probesize", "64k", "-i", "pipe:0",
389
- "-vf", `format=yuvj420p,fps=${fps || 20}`, "-q:v", "6", "-flush_packets", "1",
546
+ "-vf", `format=yuvj420p,fps=${safeFps}`, "-q:v", "6", "-flush_packets", "1",
390
547
  "-f", "image2pipe", "-c:v", "mjpeg", "pipe:1",
391
548
  ], { stdio: ["pipe", "pipe", "ignore"] });
392
549
  sr.stdout?.pipe(ff.stdin);
@@ -397,8 +554,9 @@ export function startLive(fps) {
397
554
  lastFrame: null,
398
555
  lastFrameTs: 0,
399
556
  recording: null,
400
- fps: fps || 20,
557
+ fps: safeFps,
401
558
  keepalive: null,
559
+ orphanTimer: null,
402
560
  };
403
561
  let acc = Buffer.alloc(0);
404
562
  ff.stdout?.on("data", (chunk) => {
@@ -426,7 +584,21 @@ export function startLive(fps) {
426
584
  const onExit = () => {
427
585
  if (scLive === L) {
428
586
  scLive = null;
429
- if (L.viewers.size || L.recording)
587
+ // Relaunch ONLY while a viewer is actually watching (shouldRelaunch). A recording with
588
+ // no viewers must NOT relaunch: that is the orphaned-recording respawn loop (a tab closed
589
+ // mid-record before its stop POST landed kept screenrecord self-exiting and relaunching
590
+ // forever). With no viewers, cleanupLive finalizes the in-progress recording (the clip is
591
+ // saved, not lost) and reaps the pipeline. The orphan-grace timer normally reaps this
592
+ // within a few seconds, before screenrecord even self-exits.
593
+ //
594
+ // Edge (dead-viewer + fully static screen): if the only remaining viewer is a half-open
595
+ // dead socket, viewers.size is still 1 here, so we relaunch. The dead-viewer prune runs
596
+ // inside pushFrame, so it needs at least one frame from the fresh cast to fire. A newly
597
+ // spawned screenrecord emits a startup keyframe even on a static screen (see the module
598
+ // header's DOZE-panel note), so the fresh cast produces a frame, pushFrame prunes the dead
599
+ // viewer, and afterViewerRemoved reaps. Worst case is a single bounded relaunch cycle, not
600
+ // an unbounded loop.
601
+ if (shouldRelaunch(L.viewers.size))
430
602
  relaunch(L);
431
603
  else
432
604
  cleanupLive(L);
@@ -455,13 +627,16 @@ export function startLive(fps) {
455
627
  }
456
628
  /** Attach an HTTP response as a viewer of the live cast (after the multipart headers are written). */
457
629
  export function addViewer(L, res) {
630
+ // A viewer returned; if the orphan-grace timer was counting down (last viewer had left
631
+ // while a recording ran), cancel it — the cast is watched again.
632
+ clearOrphanGrace(L);
458
633
  L.viewers.add(res);
459
634
  }
460
635
  export function removeViewer(res) {
461
636
  if (!scLive)
462
637
  return;
463
638
  scLive.viewers.delete(res);
464
- reapLiveIfIdle();
639
+ afterViewerRemoved();
465
640
  }
466
641
  /**
467
642
  * Tear down the live cast when nothing is keeping it alive: no viewers AND no active
@@ -521,7 +696,20 @@ export function startRecording() {
521
696
  }
522
697
  const safe = new Date().toISOString().replace(/[:.]/g, "-");
523
698
  const out = path.join(SC_TMP, `radar_screen_${safe}.mp4`);
524
- const rec = spawn(ffmpeg, ["-hide_banner", "-loglevel", "error", "-y", "-f", "image2pipe", "-r", String(scLive.fps), "-c:v", "mjpeg", "-i", "pipe:0", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-preset", "veryfast", out], { stdio: ["pipe", "ignore", "ignore"] });
699
+ // Time the recording by real frame arrival, not a fixed input rate (the arg shape + the
700
+ // reasons it must be exactly this are in recordingArgs). The old args stamped every frame
701
+ // at a fixed 1/fps, so a clip recorded over N real seconds played back as frames/fps
702
+ // seconds — slow motion by the real-fps/target ratio.
703
+ const rec = spawn(ffmpeg, recordingArgs(scLive.fps, out), { stdio: ["pipe", "ignore", "ignore"] });
704
+ // A ChildProcess with no 'error' listener throws an unhandled 'error' (crashing the process)
705
+ // if the spawn itself fails — e.g. ffmpeg was removed between resolveFfmpeg() and here, or an
706
+ // EAGAIN under load. resolveFfmpeg() just succeeded so this is unlikely, but a recording is a
707
+ // best-effort debug convenience and must never take the server down. Swallow it; the frame
708
+ // tee in pushFrame already tolerates a dead stdin, and the user simply gets no clip.
709
+ rec.on("error", () => {
710
+ if (scLive?.recording?.proc === rec)
711
+ scLive.recording = null;
712
+ });
525
713
  scLive.recording = { proc: rec, path: out };
526
714
  return out;
527
715
  }
@@ -530,6 +718,7 @@ export function stopRecording(L = scLive) {
530
718
  return Promise.resolve(null);
531
719
  const r = L.recording;
532
720
  L.recording = null;
721
+ clearOrphanGrace(L);
533
722
  return new Promise((resolve) => {
534
723
  let done = false;
535
724
  const fin = () => {
@@ -22,7 +22,7 @@
22
22
  --warn:#ffb454; --warn-2:#ffd479; --error:#ff6b60; --error-2:#ff5b50;
23
23
  --hover:#11202e; --sel:#1d3a52; --hover-soft:#172230; --sel-soft:#1d2c3e;
24
24
  --shadow:rgba(0,0,0,.5); --overlay:rgba(0,0,0,.45);
25
- --chip-net-bg:#13314a; --chip-rtm-bg:#2c1f47; --chip-clog-bg:#10332a; --chip-log-bg:#2a2a2a; --chip-log-fg:#b0b0b0;
25
+ --chip-net-bg:#13314a; --chip-rtm-bg:#2c1f47; --chip-clog-bg:#10332a; --chip-trace-bg:#3a2f10; --chip-log-bg:#2a2a2a; --chip-log-fg:#b0b0b0;
26
26
  --lvl-err-bg:#3a1513; --lvl-warn-bg:#3a2f10; --lvl-info-bg:#10283a; --lvl-dbg-bg:#222;
27
27
  --copybtn-bg:#172a1f; --copybtn-border:#2c5a3e; --copybtn-fg:#7fd6a3;
28
28
  --j-key:#7fb0ff; --j-str:#9fe8bd; --j-num:#ffd479; --j-bool:#c39bff; --j-null:#7e8a99;
@@ -37,7 +37,7 @@
37
37
  --warn:#b06c00; --warn-2:#8a5a00; --error:#d83a30; --error-2:#e0473d;
38
38
  --hover:#eaf1f8; --sel:#d4e6f7; --hover-soft:#eaf1f8; --sel-soft:#dbe9f7;
39
39
  --shadow:rgba(20,40,70,.18); --overlay:rgba(20,30,45,.28);
40
- --chip-net-bg:#dbeafe; --chip-rtm-bg:#ecddfb; --chip-clog-bg:#d6f3e6; --chip-log-bg:#e7ebf0; --chip-log-fg:#4a5666;
40
+ --chip-net-bg:#dbeafe; --chip-rtm-bg:#ecddfb; --chip-clog-bg:#d6f3e6; --chip-trace-bg:#faedcf; --chip-log-bg:#e7ebf0; --chip-log-fg:#4a5666;
41
41
  --lvl-err-bg:#fbdcd9; --lvl-warn-bg:#faedcf; --lvl-info-bg:#dbeafe; --lvl-dbg-bg:#e7ebf0;
42
42
  --copybtn-bg:#dcf3e7; --copybtn-border:#9cd6b8; --copybtn-fg:#0a7d56;
43
43
  --j-key:#1d6fd0; --j-str:#0a7d56; --j-num:#9a6700; --j-bool:#7a3fd0; --j-null:#8a96a3;
@@ -151,11 +151,14 @@
151
151
  .stchip { font-size:10px; font-weight:700; padding:1px 6px; border-radius:4px; font-variant-numeric:tabular-nums; }
152
152
  .stchip.st2 { background:var(--chip-clog-bg); color:var(--accent); } .stchip.st3 { background:var(--lvl-info-bg); color:var(--blue); }
153
153
  .stchip.st4 { background:var(--lvl-warn-bg); color:var(--warn-2); } .stchip.st5 { background:var(--lvl-err-bg); color:var(--error); }
154
- .t-network{ background:var(--chip-net-bg); color:var(--blue); } .t-rtm{ background:var(--chip-rtm-bg); color:var(--purple); } .t-clog{ background:var(--chip-clog-bg); color:var(--accent); } .t-log{ background:var(--chip-log-bg); color:var(--chip-log-fg); }
154
+ .t-network{ background:var(--chip-net-bg); color:var(--blue); } .t-rtm{ background:var(--chip-rtm-bg); color:var(--purple); } .t-clog{ background:var(--chip-clog-bg); color:var(--accent); } .t-trace{ background:var(--chip-trace-bg); color:var(--warn); } .t-log{ background:var(--chip-log-bg); color:var(--chip-log-fg); }
155
155
  .lvl { font-size:10px; font-weight:700; padding:1px 5px; border-radius:4px; }
156
156
  .lvl-ERROR,.lvl-FATAL{ background:var(--lvl-err-bg); color:var(--error); } .lvl-WARN{ background:var(--lvl-warn-bg); color:var(--warn-2); } .lvl-INFO{ background:var(--lvl-info-bg); color:var(--blue); } .lvl-DEBUG,.lvl-VERBOSE{ background:var(--lvl-dbg-bg); color:var(--muted-2); }
157
157
  .logpkg { color:var(--blue-2); background:var(--surface-3); font-size:10.5px; padding:1px 6px; border-radius:4px; white-space:nowrap; max-width:130px; overflow:hidden; text-overflow:ellipsis; }
158
158
  .logtag { color:var(--muted-2); font-weight:600; } .logmsg { color:var(--text-2); overflow:hidden; text-overflow:ellipsis; }
159
+ .durchip { font-size:10px; font-weight:700; padding:1px 6px; border-radius:4px; background:var(--chip-trace-bg); color:var(--warn); font-variant-numeric:tabular-nums; white-space:nowrap; }
160
+ .tracename { color:var(--text-2); font-weight:600; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; max-width:40%; }
161
+ .spanname { color:var(--muted-2); overflow:hidden; text-overflow:ellipsis; }
159
162
  .breachbadge { margin-left:auto; background:var(--lvl-err-bg); color:var(--error); font-weight:700; font-size:11.5px; padding:2px 9px; border-radius:999px; white-space:nowrap; }
160
163
  .pill { position:absolute; left:50%; transform:translateX(-50%); top:10px; background:var(--sel); color:var(--text); border:1px solid var(--accent); border-radius:18px; padding:5px 14px; cursor:pointer; box-shadow:0 2px 10px var(--shadow); font-size:12px; z-index:6; }
161
164
  .pill-bottom { top:auto; bottom:14px; background:var(--surface); border-color:var(--border-3); color:var(--muted-2); }
@@ -137,7 +137,7 @@ function StreamView({ spec }) {
137
137
  `;
138
138
  }
139
139
  function Blank() {
140
- return html `<div class="sub"><span class="summary">Pick a dashboard above.</span><span class="tech">Live, Network, RTM, Clogs, Logs — or ask a terminal Claude Code session to build a custom view.</span></div>`;
140
+ return html `<div class="sub"><span class="summary">Pick a dashboard above.</span><span class="tech">Live, Network, RTM, Clogs, Traces, Logs — or ask a terminal Claude Code session to build a custom view.</span></div>`;
141
141
  }
142
142
  function App() {
143
143
  const spec = useStoreValue(store, "spec", () => store.spec);
@@ -21,7 +21,7 @@ function sortOptionsFor(source) {
21
21
  { key: "oldest", label: "oldest first", get: (e) => e.timestamp || 0, dir: "asc" },
22
22
  ];
23
23
  if (source === "all")
24
- opts.push({ key: "type", label: "group by type", get: (e) => ({ network: 0, rtm: 1, clog: 2, log: 3 }[e._type || ""] ?? 9), dir: "asc" });
24
+ opts.push({ key: "type", label: "group by type", get: (e) => ({ network: 0, rtm: 1, clog: 2, trace: 3, log: 4 }[e._type || ""] ?? 9), dir: "asc" });
25
25
  if (source === "network") {
26
26
  opts.push({ key: "slow", label: "slowest (response time)", get: (e) => Number(e.duration_ms), dir: "desc" });
27
27
  opts.push({ key: "status", label: "status code (high→low)", get: (e) => Number(e.status_code), dir: "desc" });
@@ -32,6 +32,10 @@ function sortOptionsFor(source) {
32
32
  opts.push({ key: "evtype", label: "event type (A→Z)", get: (e) => e.event_type || "", dir: "asc" });
33
33
  if (source === "clog")
34
34
  opts.push({ key: "name", label: "clog name (A→Z)", get: (e) => e.event_name || "", dir: "asc" });
35
+ if (source === "trace") {
36
+ opts.push({ key: "slow", label: "slowest (duration)", get: (e) => Number(e.duration_ms), dir: "desc" });
37
+ opts.push({ key: "name", label: "trace name (A→Z)", get: (e) => e.trace_name || "", dir: "asc" });
38
+ }
35
39
  return opts;
36
40
  }
37
41
  // The spec of the tab `dir` steps away from the active one (clamped). Used by the filter box's
@@ -51,6 +55,8 @@ function neighborTabSpec(dir) {
51
55
  function searchText(ev) {
52
56
  if ((ev._type || "") === "log")
53
57
  return [ev.level, ev.package, ev.tag, ev.message].filter(Boolean).join(" ").toLowerCase();
58
+ if ((ev._type || "") === "trace")
59
+ return [ev.trace_name, ev.span_name].filter(Boolean).join(" ").toLowerCase();
54
60
  return [ev.direction, ev.method, ev.event_type, ev.event_name, shortUrl(ev.url), ev.channel].filter(Boolean).join(" ").toLowerCase();
55
61
  }
56
62
  // One raw copy line per frame (Logcat-style), pulled from the ring on copy.
@@ -60,6 +66,8 @@ function rawLine(ev) {
60
66
  return `${t} ${(ev.level || "").toUpperCase()}/${ev.tag || ""}: ${ev.message || ""}`;
61
67
  if (ev._type === "network")
62
68
  return `${t} ${ev.method || "GET"} ${shortUrl(ev.url)} ${ev.status_code ?? ""} ${ev.duration_ms ?? ""}ms`;
69
+ if (ev._type === "trace")
70
+ return `${t} ${ev.trace_name || ""} ${ev.span_name || ""} ${ev.duration_ms ?? ""}ms`;
63
71
  return `${t} ${ev._type} ${ev.event_type || ev.event_name || ""} ${ev.channel || ""}`.trimEnd();
64
72
  }
65
73
  function statusBand(c) {
@@ -90,6 +98,10 @@ function RowBody({ ev, source, highlight }) {
90
98
  const lv = (ev.level || "").toUpperCase();
91
99
  return html `<span class="t">${t}</span>${typeChip}<span class=${"lvl lvl-" + lv}>${lv || "LOG"}</span>${ev.package ? html `<span class="logpkg" title=${ev.package}>${shortPkg(ev.package)}</span>` : null}<span class="logtag">${ev.tag || ""}</span><span class="logmsg">${ev.message || ""}</span>`;
92
100
  }
101
+ if ((ev._type || source) === "trace") {
102
+ const breach = highlight && store.breaches(ev);
103
+ return html `<span class="t">${t}</span>${typeChip}${ev.duration_ms != null ? html `<span class="durchip">${fmtNum(Number(ev.duration_ms))} ms</span>` : null}<span class="tracename">${ev.trace_name || ""}</span><span class="spanname">${ev.span_name || ""}</span>${breach && highlight ? html `<span class="breachbadge">${breachBadge(ev, highlight)}</span>` : null}`;
104
+ }
93
105
  const breach = highlight && store.breaches(ev);
94
106
  const isNet = (ev._type || source) === "network" || ev.url != null;
95
107
  const code = Number(ev.status_code);
@@ -6,7 +6,7 @@ import { html } from "./html.js";
6
6
  import { useState, useEffect } from "preact/hooks";
7
7
  import { esc } from "./esc.js";
8
8
  import { shortUrl, store } from "./store.js";
9
- import { hasDetailEndpoint } from "./registry.js";
9
+ import { hasDetailEndpoint, SOURCES } from "./registry.js";
10
10
  function shq(s) {
11
11
  return "'" + String(s).replace(/'/g, "'\\''") + "'";
12
12
  }
@@ -141,7 +141,7 @@ export function Inspector({ ev, onClose }) {
141
141
  .then((d) => {
142
142
  if (!live)
143
143
  return;
144
- // {error:"Not Found"} = the id was evicted from the device ring (older than ~200). Do
144
+ // {error:"Not Found"} = the id was evicted from the device ring (see SOURCES ringSize). Do
145
145
  // NOT overwrite the good summary; keep the feed row + flag the body is gone.
146
146
  if (d && d.error && d.url == null && d.method == null) {
147
147
  setEvicted(true);
@@ -159,7 +159,7 @@ export function Inspector({ ev, onClose }) {
159
159
  }, [ev]);
160
160
  const kind = ev._type || "";
161
161
  const isNet = kind === "network" || detail.url != null || detail.method != null;
162
- const title = ev.event_name || ev.event_type || shortUrl(ev.url) || kind || "detail";
162
+ const title = ev.trace_name || ev.event_name || ev.event_type || shortUrl(ev.url) || kind || "detail";
163
163
  const copy = (which, e) => {
164
164
  let text = "";
165
165
  if (which === "json")
@@ -201,6 +201,12 @@ export function Inspector({ ev, onClose }) {
201
201
  if (ev.event_name)
202
202
  badges.push(html `<span class="ibadge">${ev.event_name}</span>`);
203
203
  }
204
+ else if (kind === "trace") {
205
+ if (detail.duration_ms != null)
206
+ badges.push(html `<span class="ibadge">${detail.duration_ms} ms</span>`);
207
+ if (ev.span_name)
208
+ badges.push(html `<span class="ibadge">${ev.span_name}</span>`);
209
+ }
204
210
  else if (kind === "log") {
205
211
  if (ev.level)
206
212
  badges.push(html `<span class=${"ibadge lvl-" + String(ev.level).toUpperCase()}>${ev.level}</span>`);
@@ -215,13 +221,19 @@ export function Inspector({ ev, onClose }) {
215
221
  const resHeaders = (detail.response_headers || detail.responseHeaders);
216
222
  const data = parseBody(detail.data);
217
223
  const logMessage = kind === "log" ? detail.message || ev.message : null;
224
+ // Trace tags arrive as a JSON object from the device detail; give them their own section so
225
+ // the interesting payload is not buried in the generic "other fields" dump.
226
+ const traceTags = kind === "trace" && detail.tags != null ? parseBody(detail.tags) : null;
218
227
  // generic "other fields" dump, minus the specially-rendered ones
219
228
  const omit = new Set([
220
229
  "_type", "id", "timestamp", "url", "method", "status_code", "duration_ms",
221
230
  "request_body", "requestBody", "response_body", "responseBody",
222
231
  "request_headers", "requestHeaders", "response_headers", "responseHeaders",
223
232
  "data", "message", "event_type", "event_name", "direction", "channel", "level", "tag", "package", "pid", "tid", "log_ts",
233
+ "trace_name", "span_name", // shown in the title + badges already
224
234
  ]);
235
+ if (traceTags)
236
+ omit.add("tags"); // rendered in its own section below
225
237
  const rest = {};
226
238
  for (const k of Object.keys(detail))
227
239
  if (!omit.has(k))
@@ -235,7 +247,7 @@ export function Inspector({ ev, onClose }) {
235
247
  </div>
236
248
  <div class="ibadges">${badges}</div>
237
249
  ${isNet && detail.url ? html `<div class="iurl" title=${detail.url}>${detail.url}</div>` : null}
238
- ${evicted ? html `<div class="trunc">This call scrolled off the device buffer (it keeps only the last ~200), so the full request/response body is no longer available. The summary above is from the live feed. Open a call sooner to capture its body.</div>` : null}
250
+ ${evicted ? html `<div class="trunc">This ${kind === "network" ? "call" : "record"} scrolled off the device buffer (it keeps the last ~${SOURCES[kind]?.ringSize ?? 200} ${kind} records), so ${SOURCES[kind]?.detailNoun ?? "the full detail"} is no longer available. The summary above is from the live feed.</div>` : null}
239
251
  <div class="copybar">
240
252
  <button class="copybtn" onClick=${(e) => copy("json", e)}>Copy JSON</button>
241
253
  ${isNet ? html `<button class="copybtn" onClick=${(e) => copy("body", e)}>Copy body</button><button class="copybtn" onClick=${(e) => copy("curl", e)}>Copy cURL</button>` : null}
@@ -248,6 +260,7 @@ export function Inspector({ ev, onClose }) {
248
260
  ${reqBody.value != null ? html `<${Section} title="request body"><${Body} parsed=${reqBody} /><//>` : null}
249
261
  ${resBody.value != null ? html `<${Section} title="response body"><${Body} parsed=${resBody} /><//>` : null}
250
262
  ${data.value != null ? html `<${Section} title="data"><${Body} parsed=${data} /><//>` : null}
263
+ ${traceTags && traceTags.value != null ? html `<${Section} title="tags"><${Body} parsed=${traceTags} /><//>` : null}
251
264
  ${reqHeaders ? html `<${Section} title="request headers" sub=${Object.keys(reqHeaders).length} open=${false}><${KV} map=${reqHeaders} /><//>` : null}
252
265
  ${resHeaders ? html `<${Section} title="response headers" sub=${Object.keys(resHeaders).length} open=${false}><${KV} map=${resHeaders} /><//>` : null}
253
266
  ${hasRest ? html `<${Section} title="other fields" open=${!isNet}><${Body} parsed=${{ value: rest, truncated: false }} /><//>` : null}
@@ -8,6 +8,7 @@ export const MATCH_FIELDS = {
8
8
  network: ["url", "method", "status_code"],
9
9
  rtm: ["event_type", "direction", "channel"],
10
10
  clog: ["event_name"],
11
+ trace: ["trace_name", "span_name"],
11
12
  log: ["tag", "level", "message", "pid", "package"],
12
13
  };
13
14
  // `all` = the union of every streaming source's fields (deduped, order-stable). Derived, not
@@ -15,7 +16,7 @@ export const MATCH_FIELDS = {
15
16
  MATCH_FIELDS.all = (() => {
16
17
  const seen = new Set();
17
18
  const out = [];
18
- for (const src of ["network", "rtm", "clog", "log"]) {
19
+ for (const src of ["network", "rtm", "clog", "trace", "log"]) {
19
20
  for (const f of MATCH_FIELDS[src])
20
21
  if (!seen.has(f)) {
21
22
  seen.add(f);
@@ -33,9 +34,10 @@ export const FIELD_VALUES = {
33
34
  // SOURCE registry: one row per source. `kind` routes the view (streaming feed vs the
34
35
  // point-in-time DB browser) without a hardcoded source check.
35
36
  export const SOURCES = {
36
- network: { label: "Network", kind: "stream", hasDetailEndpoint: true },
37
- rtm: { label: "RTM", kind: "stream", hasDetailEndpoint: true },
38
- clog: { label: "Clogs", kind: "stream", hasDetailEndpoint: true },
37
+ network: { label: "Network", kind: "stream", hasDetailEndpoint: true, eagerCapture: true, ringSize: 400, detailNoun: "the full request/response body" },
38
+ rtm: { label: "RTM", kind: "stream", hasDetailEndpoint: true, eagerCapture: true, ringSize: 2000, detailNoun: "the full payload" },
39
+ clog: { label: "Clogs", kind: "stream", hasDetailEndpoint: true, eagerCapture: true, ringSize: 1000, detailNoun: "the full payload" },
40
+ trace: { label: "Traces", kind: "stream", hasDetailEndpoint: true, ringSize: 2000, detailNoun: "the span timing and tag detail" },
39
41
  log: { label: "Logs", kind: "stream", hasDetailEndpoint: false },
40
42
  all: { label: "Live", kind: "stream" },
41
43
  db: { label: "Database", kind: "db" },
@@ -45,11 +47,16 @@ export const SOURCES = {
45
47
  export const STREAM_KINDS = Object.entries(SOURCES)
46
48
  .filter(([k, v]) => v.kind === "stream" && k !== "all")
47
49
  .map(([k]) => k);
48
- // The kinds that have a /detail endpoint (eager body capture + inspector fetch). Derived from
50
+ // The kinds that have a /detail endpoint (inspector click-fetch). Derived from
49
51
  // hasDetailEndpoint so adding a detailable source is one SOURCES edit.
50
52
  export const DETAILABLE_KINDS = Object.entries(SOURCES)
51
53
  .filter(([, v]) => v.hasDetailEndpoint)
52
54
  .map(([k]) => k);
55
+ // The kinds the store eagerly pre-fetches detail for (see eagerCapture above). A subset of
56
+ // DETAILABLE_KINDS; derived so the two flags cannot drift apart silently.
57
+ export const EAGER_CAPTURE_KINDS = Object.entries(SOURCES)
58
+ .filter(([, v]) => v.hasDetailEndpoint && v.eagerCapture)
59
+ .map(([k]) => k);
53
60
  export function hasDetailEndpoint(kind) {
54
61
  return !!SOURCES[kind]?.hasDetailEndpoint;
55
62
  }
@@ -58,7 +65,7 @@ export function hasDetailEndpoint(kind) {
58
65
  // see widgets.ts). A new widget = one key here + one component.
59
66
  export const WIDGETS = ["counter", "rate", "sparkline", "graph"];
60
67
  // Source order for the modebar / global tab-switch (matches the MODES preset order).
61
- export const SOURCE_ORDER = ["all", "network", "rtm", "clog", "log", "db"];
68
+ export const SOURCE_ORDER = ["all", "network", "rtm", "clog", "trace", "log", "db"];
62
69
  // The source options the Filters panel offers: every streaming source (db is its own container,
63
70
  // not a feed filter). Derived from SOURCES so adding a streaming source surfaces it in Filters
64
71
  // with no edit there. Ordered by SOURCE_ORDER (the modebar order) for a stable, familiar list.
@@ -1,4 +1,4 @@
1
- import { STREAM_KINDS, DETAILABLE_KINDS } from "./registry.js";
1
+ import { STREAM_KINDS, EAGER_CAPTURE_KINDS } from "./registry.js";
2
2
  // Logcat-scale retention. At the live firehose (~400+ events/sec on the unified Live tab) a
3
3
  // small ring recycles in seconds, so a rare signal (a once-per-5s heartbeat) gets evicted
4
4
  // before you can filter for it. Android Studio / Flipper keep the whole session and filter
@@ -10,7 +10,7 @@ import { STREAM_KINDS, DETAILABLE_KINDS } from "./registry.js";
10
10
  // the retention rationale stays attached to the numbers.
11
11
  const CACHE_CAP = 100000;
12
12
  const CACHE_TTL_MS = 60 * 60 * 1000;
13
- const DETAILABLE = new Set(DETAILABLE_KINDS); // sources with a server /detail endpoint
13
+ const EAGER_CAPTURE = new Set(EAGER_CAPTURE_KINDS); // sources whose detail is pre-fetched per frame
14
14
  const DETAIL_CACHE_CAP = 1500; // bounded full-detail cache (eager-captured + click-fetched)
15
15
  const CAPTURE_CONCURRENCY = 3; // max parallel background /detail fetches
16
16
  const CAP_SEEN_CAP = 4000; // bound on the dedup set for eager capture
@@ -19,16 +19,17 @@ const POLL_HEALTH_MS = 2000;
19
19
  const POLL_PROFILE_MS = 5000;
20
20
  const GRAPH_N = 60;
21
21
  const PERSEC_N = 30;
22
- const SUGGEST_FIELDS = ["event_type", "event_name", "tag", "status_code", "channel", "url", "package"];
22
+ const SUGGEST_FIELDS = ["event_type", "event_name", "tag", "status_code", "channel", "url", "package", "trace_name", "span_name"];
23
23
  const PACKAGE_CAP = 1000; // package values learned off the stream; bounded (was Infinity in the PoC, B4)
24
24
  // ---- pre-built dashboards: one tab each. Presets carry only generic placeholders; real
25
25
  // endpoints/channels/event-names are learned LIVE from the device stream. The one baked value
26
26
  // is com.Slack.internal.debug (the debug build's package), which is already public. ----
27
27
  export const MODES = [
28
- { key: "all", label: "Live", spec: { title: "Live", summary: "Live: network, RTM, analytics clogs, and Slack-app logcat in one timeline. (Logs filtered to the Slack app; clear the package chip for all apps.)", source: "all", viz: ["rate", "sparkline", "feed", "inspector"], match: { package: "com.Slack.internal.debug" } } },
28
+ { key: "all", label: "Live", spec: { title: "Live", summary: "Live: network, RTM, analytics clogs, traces, and Slack-app logcat in one timeline. (Logs filtered to the Slack app; clear the package chip for all apps.)", source: "all", viz: ["rate", "sparkline", "feed", "inspector"], match: { package: "com.Slack.internal.debug" } } },
29
29
  { key: "network", label: "Network", spec: { title: "Network", summary: "Network calls per second vs average response time, every call listed, slow ones flagged.", source: "network", viz: ["rate", "graph", "feed", "inspector"], series: [{ metric: "ratePerSec", label: "calls/s", unit: "/s" }, { metric: "avg", field: "duration_ms", label: "avg ms", unit: "ms" }], highlight: { field: "duration_ms", op: ">", value: 800, label: "slow (>800ms)" }, rateWindowSec: 10 } },
30
30
  { key: "rtm", label: "RTM", spec: { title: "RTM", summary: "Real-time websocket events as they happen.", source: "rtm", viz: ["rate", "feed", "inspector"] } },
31
31
  { key: "clog", label: "Clogs", spec: { title: "Clogs", summary: "Analytics clog events, click any to see its full payload.", source: "clog", viz: ["rate", "feed", "inspector"] } },
32
+ { key: "trace", label: "Traces", spec: { title: "Traces", summary: "Performance trace spans, click to see timing details and tags.", source: "trace", viz: ["rate", "graph", "feed", "inspector"], series: [{ metric: "ratePerSec", label: "spans/s", unit: "/s" }, { metric: "avg", field: "duration_ms", label: "avg ms", unit: "ms" }] } },
32
33
  { key: "log", label: "Logs", spec: { title: "Device Logs", summary: "Live Slack app logcat, color-coded by level. Scroll the full session buffer, select a range, copy raw lines.", source: "log", viz: ["feed", "inspector"], match: { package: "com.Slack.internal.debug" } } },
33
34
  { key: "db", label: "Database", spec: { title: "Device DB", summary: "Browse the on-device SQLite databases (read-only snapshot).", source: "db" } },
34
35
  ];
@@ -119,8 +120,8 @@ class Store {
119
120
  getDetail(kind, id) {
120
121
  return this.detailCache.get(kind + ":" + id);
121
122
  }
122
- // ---- eager body capture (any DETAILABLE tab, while it is open) ----
123
- // The device keeps only the last ~200 network calls, so a row clicked later is gone. While a
123
+ // ---- eager body capture (any EAGER_CAPTURE tab, while it is open) ----
124
+ // The device ring evicts old records (network keeps 400), so a row clicked later is gone. While a
124
125
  // detailable tab is active we proactively fetch each NEW frame's full body in the background
125
126
  // (concurrency-bounded) and cache it, so clicking an old row never hits eviction. Off on
126
127
  // every other tab (mirrors Flipper's shouldStripResponseBody). Forward-only: no backfill.
@@ -131,7 +132,7 @@ class Store {
131
132
  maybeCapture(ev) {
132
133
  const src = this.spec.source;
133
134
  const kind = ev._type || "";
134
- if (ev.id == null || !DETAILABLE.has(kind))
135
+ if (ev.id == null || !EAGER_CAPTURE.has(kind))
135
136
  return;
136
137
  if (src !== "all" && src !== kind)
137
138
  return;
@@ -30,6 +30,10 @@ export declare function seedInitialSpec(): void;
30
30
  */
31
31
  export declare function cleanupOnBind(): void;
32
32
  export declare function createServer(): http.Server;
33
+ export declare const DEVICE_SOURCES: Record<string, {
34
+ segment: string;
35
+ arrayKey: string;
36
+ }>;
33
37
  /**
34
38
  * Finish a /detail proxy response after an upstream error or timeout. The success
35
39
  * callback streams the upstream response, so headers may already be sent when a later
@@ -489,15 +489,20 @@ function handleEnable(res) {
489
489
  });
490
490
  probe.end();
491
491
  }
492
- const SOURCE_ARRAY_KEY = {
493
- network: "calls",
494
- rtm: "events",
495
- clog: "clogs",
492
+ // The device-buffered source kinds, in one table so a new source is one row here: the
493
+ // device API route segment (clog and trace pluralize; the rest match the kind name) and
494
+ // the array key its list response wraps the records in. Backfill and the /detail proxy
495
+ // both read this, so the two cannot drift apart. Logs are host-side and absent by design.
496
+ export const DEVICE_SOURCES = {
497
+ network: { segment: "network", arrayKey: "calls" },
498
+ rtm: { segment: "rtm", arrayKey: "events" },
499
+ clog: { segment: "clogs", arrayKey: "clogs" },
500
+ trace: { segment: "traces", arrayKey: "traces" },
496
501
  };
497
502
  /**
498
503
  * Replay the device's recent ring buffers for a source so a freshly-built tab
499
504
  * shows history immediately instead of filling only going forward. The device is
500
- * the source of truth. "all" pulls network+rtm+clog and merges them oldest->newest;
505
+ * the source of truth. "all" pulls network+rtm+clog+trace and merges them oldest->newest;
501
506
  * "log" is host-side (no device buffer) and so has nothing to replay. Returns
502
507
  * `[{type, event}]` frames mirroring the stream shape.
503
508
  */
@@ -506,10 +511,10 @@ function handleBackfill(req, res) {
506
511
  const src = u.searchParams.get("source") ?? "network";
507
512
  const limit = Math.min(500, Number(u.searchParams.get("limit")) || 200);
508
513
  const kinds = src === "all"
509
- ? ["network", "rtm", "clog"]
510
- : [src].filter((k) => k !== "log" && k in SOURCE_ARRAY_KEY);
514
+ ? Object.keys(DEVICE_SOURCES)
515
+ : [src].filter((k) => Object.hasOwn(DEVICE_SOURCES, k));
511
516
  const fetchKind = (kind) => new Promise((resolve) => {
512
- const apiPath = `/api/${kind === "clog" ? "clogs" : kind}?limit=${limit}`;
517
+ const apiPath = `/api/${DEVICE_SOURCES[kind].segment}?limit=${limit}`;
513
518
  const rq = http.request({
514
519
  host: RADAR_HOST,
515
520
  port: RADAR_PORT,
@@ -522,7 +527,7 @@ function handleBackfill(req, res) {
522
527
  up.on("end", () => {
523
528
  try {
524
529
  const j = JSON.parse(b);
525
- const arr = j[SOURCE_ARRAY_KEY[kind]] ?? [];
530
+ const arr = j[DEVICE_SOURCES[kind].arrayKey] ?? [];
526
531
  resolve(arr.map((e) => ({ type: kind, event: e })));
527
532
  }
528
533
  catch {
@@ -546,13 +551,6 @@ function handleBackfill(req, res) {
546
551
  })
547
552
  .catch(() => sendJson(res, 200, { frames: [] }));
548
553
  }
549
- // Detail kinds the inspector may request, mapped to their device route segment. The
550
- // device serves clog detail at /api/clogs/ (plural); the rest match the kind name.
551
- const DETAIL_ROUTES = {
552
- network: "network",
553
- rtm: "rtm",
554
- clog: "clogs",
555
- };
556
554
  /**
557
555
  * Finish a /detail proxy response after an upstream error or timeout. The success
558
556
  * callback streams the upstream response, so headers may already be sent when a later
@@ -578,7 +576,7 @@ function handleDetail(req, res) {
578
576
  const u = new URL(req.url ?? "", `http://localhost:${WEB_PORT}`);
579
577
  const id = u.searchParams.get("id");
580
578
  const kind = u.searchParams.get("kind") ?? "network";
581
- const route = DETAIL_ROUTES[kind];
579
+ const route = DEVICE_SOURCES[kind]?.segment;
582
580
  if (!id || !route) {
583
581
  res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
584
582
  res.end("{}");
@@ -762,6 +760,13 @@ function handleScreen(req, res) {
762
760
  return;
763
761
  }
764
762
  const fps = Number(new URL(url, `http://localhost:${WEB_PORT}`).searchParams.get("fps")) || 20;
763
+ // Register the disconnect handler BEFORE the await. A client that aborts during
764
+ // detectDisplay() would otherwise become a phantom viewer whose close never fires, and
765
+ // on a static screen (no frames flowing) the frame-loop dead-viewer prune cannot catch
766
+ // it either — so it would hold the cast and respawn screenrecord. removeViewer is safe
767
+ // to call whether or not the response ever became a viewer (delete on an absent member
768
+ // is a no-op), so wiring it early costs nothing when the stream fails to start.
769
+ req.on("close", () => removeViewer(res));
765
770
  void (async () => {
766
771
  await detectDisplay();
767
772
  const L = startLive(fps);
@@ -769,13 +774,20 @@ function handleScreen(req, res) {
769
774
  sendJson(res, 501, { error: "ffmpeg not installed", installHint: ffmpegInstallHint() });
770
775
  return;
771
776
  }
777
+ // The client may have aborted during the await above (its close handler, wired before
778
+ // the await, already ran). Do not resurrect a dead socket as a viewer — that would be
779
+ // the very phantom viewer this reordering prevents. Reap in case startLive spun a cast
780
+ // up for a viewer that is already gone.
781
+ if (res.writableEnded || res.destroyed) {
782
+ reapLiveIfIdle();
783
+ return;
784
+ }
772
785
  res.writeHead(200, {
773
786
  "Content-Type": `multipart/x-mixed-replace; boundary=${SCREEN_BOUNDARY}`,
774
787
  "Cache-Control": "no-cache",
775
788
  Connection: "keep-alive",
776
789
  });
777
790
  addViewer(L, res);
778
- req.on("close", () => removeViewer(res));
779
791
  void primeIfNeeded();
780
792
  })();
781
793
  return;
@@ -5,17 +5,17 @@
5
5
  * and the same validate/coerce pass runs on every push so a malformed spec surfaces
6
6
  * an error instead of rendering silent zeros.
7
7
  *
8
- * Most sources are live STREAMS (network/rtm/clog/log/all). `db` is the odd one out:
8
+ * Most sources are live STREAMS (network/rtm/clog/trace/log/all). `db` is the odd one out:
9
9
  * a read-only, point-in-time SQLite BROWSER over the on-device databases, with no viz /
10
10
  * series / match (it has its own list -> tables -> query-grid view). The coerce and
11
11
  * validate passes short-circuit for `db` accordingly.
12
12
  */
13
13
  /**
14
- * Sources the dashboard can read. The first five are live streams; "all" is their unified
14
+ * Sources the dashboard can read. The first six are live streams; "all" is their unified
15
15
  * timeline. "db" is a read-only on-device SQLite browser (a point-in-time snapshot, not a
16
16
  * stream) and is handled as a distinct view.
17
17
  */
18
- export declare const SOURCES: readonly ["rtm", "network", "clog", "log", "all", "db"];
18
+ export declare const SOURCES: readonly ["rtm", "network", "clog", "trace", "log", "all", "db"];
19
19
  export type Source = (typeof SOURCES)[number];
20
20
  /** Widgets a spec may compose. */
21
21
  export declare const VIZ: readonly ["counter", "rate", "sparkline", "feed", "inspector", "graph"];
package/dist/web/spec.js CHANGED
@@ -5,17 +5,17 @@
5
5
  * and the same validate/coerce pass runs on every push so a malformed spec surfaces
6
6
  * an error instead of rendering silent zeros.
7
7
  *
8
- * Most sources are live STREAMS (network/rtm/clog/log/all). `db` is the odd one out:
8
+ * Most sources are live STREAMS (network/rtm/clog/trace/log/all). `db` is the odd one out:
9
9
  * a read-only, point-in-time SQLite BROWSER over the on-device databases, with no viz /
10
10
  * series / match (it has its own list -> tables -> query-grid view). The coerce and
11
11
  * validate passes short-circuit for `db` accordingly.
12
12
  */
13
13
  /**
14
- * Sources the dashboard can read. The first five are live streams; "all" is their unified
14
+ * Sources the dashboard can read. The first six are live streams; "all" is their unified
15
15
  * timeline. "db" is a read-only on-device SQLite browser (a point-in-time snapshot, not a
16
16
  * stream) and is handled as a distinct view.
17
17
  */
18
- export const SOURCES = ["rtm", "network", "clog", "log", "all", "db"];
18
+ export const SOURCES = ["rtm", "network", "clog", "trace", "log", "all", "db"];
19
19
  /** Widgets a spec may compose. */
20
20
  export const VIZ = [
21
21
  "counter",
@@ -65,7 +65,9 @@ export function coerceSpec(input) {
65
65
  ? "event_type"
66
66
  : s.source === "clog"
67
67
  ? "event_name"
68
- : "url";
68
+ : s.source === "trace"
69
+ ? "trace_name"
70
+ : "url";
69
71
  s.match = { [field]: s.match };
70
72
  }
71
73
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@slack/radar-mcp",
3
- "version": "1.9.0",
3
+ "version": "1.10.0",
4
4
  "description": "MCP server and web dashboard for on-device debugging of the Slack Android app via ADB",
5
5
  "type": "module",
6
6
  "main": "dist/mcp/index.js",