@slack/radar-mcp 1.19.0 → 1.20.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.
@@ -1,4 +1,4 @@
1
- import { STREAM_KINDS, DEVICE_STREAM_KINDS, EAGER_CAPTURE_KINDS, isStateSource } from "./registry.js";
1
+ import { STREAM_KINDS, DEVICE_STREAM_KINDS, EAGER_CAPTURE_KINDS, isStateSource, levelRank, FIELD_VALUES } 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
@@ -96,16 +96,54 @@ function canonicalSpecKey(spec) {
96
96
  const cleaned = { ...spec };
97
97
  delete cleaned.title;
98
98
  delete cleaned.summary;
99
+ // A level floor is a way of looking at the same tab, not a different tab: the Logs button
100
+ // stays lit at "level ≥ WARN". `match.package` is deliberately still part of the key, so the app
101
+ // selector next to it does move you off the preset; the two controls are not meant to agree.
102
+ delete cleaned.minLevel;
99
103
  if (Array.isArray(cleaned.viz))
100
104
  cleaned.viz = cleaned.viz.filter((x) => x !== "counter");
101
105
  return JSON.stringify(norm(cleaned));
102
106
  }
107
+ // The spec a PRESET tab pushes. The level floor follows the person between the two tabs that
108
+ // have log rows, and waits out a visit to any other tab (`remembered` is the store's last level
109
+ // on a log-carrying tab), the way the text filter survives every tab switch. It never overrides
110
+ // a level the target already carries, so an agent-authored view keeps its own; the Custom button
111
+ // does not come through here at all.
112
+ export function specForTab(next, current, remembered = "") {
113
+ const logish = (s) => s === "log" || s === "all";
114
+ if (!logish(next.source) || next.minLevel !== undefined)
115
+ return next;
116
+ const min = current && logish(current.source)
117
+ ? (typeof current.minLevel === "string" ? current.minLevel : "")
118
+ : remembered;
119
+ return min ? { ...next, minLevel: min } : next;
120
+ }
103
121
  export function specMatchesMode(spec) {
104
122
  if (!spec || spec.blank)
105
123
  return null;
106
124
  const key = canonicalSpecKey(spec);
107
125
  return MODES.find((m) => canonicalSpecKey(m.spec) === key)?.key ?? null;
108
126
  }
127
+ /**
128
+ * This page's presence id, taken from the URL when whoever opened the page supplied one.
129
+ *
130
+ * The dock app supplies one. It has to know this page's id before the page exists, because the
131
+ * question it asks the server is "is anyone other than my own window using this dashboard", and a page
132
+ * that mints its own id in here leaves the app no way to name it. A plain browser tab arrives with no
133
+ * parameter and mints its own, exactly as every tab did before.
134
+ *
135
+ * `presence`, not `tab`, because the dashboard's own tabs (Live, Network, Clogs) are the other thing
136
+ * `?tab=` would read as, and this is not one of those.
137
+ *
138
+ * Exported so a test can drive the URL branch without a browser.
139
+ */
140
+ export function pageTabId(search) {
141
+ const query = search ?? (typeof location !== "undefined" ? location.search : "");
142
+ const supplied = new URLSearchParams(query).get("presence");
143
+ if (supplied)
144
+ return supplied;
145
+ return typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Math.random()).slice(2);
146
+ }
109
147
  class Store {
110
148
  spec = { blank: true, viz: [] };
111
149
  conn = { state: "waiting", msg: "connecting…" };
@@ -400,6 +438,10 @@ class Store {
400
438
  dbSerialVersion = 0;
401
439
  customActive = false;
402
440
  lastCustomSpec = null;
441
+ // The level floor last seen on a log-carrying tab ("" when none), so a trip through Network
442
+ // and back to Logs lands on the same level. Read by specForTab. Any log-carrying spec counts,
443
+ // an agent-authored one included: a log view Claude pushes with no level is the last level seen.
444
+ lastLogLevel = "";
403
445
  detailCache = new Map();
404
446
  _capSeen = new Set();
405
447
  _capQueue = [];
@@ -430,13 +472,31 @@ class Store {
430
472
  // and reads as a genuine new frame to a paused/frozen feed subscriber.
431
473
  _rafHandle = null;
432
474
  _intervals = [];
433
- // Per-tab presence id, generated once when this Store is constructed. Rides pollProfile's 5s
475
+ // Per-tab presence id, settled once when this Store is constructed. Rides pollProfile's 5s
434
476
  // /health fetch (below) so the server can tell how many tabs are live and auto-close when the
435
- // last one is gone. In-memory only, never persisted: a page reload naturally gets a fresh id,
436
- // which is fine — the old id ages out of the server's presence map. Rides pollProfile, NOT
437
- // pollHealth: pollHealth early-returns without fetching while a stream is busy (<6s since the
438
- // last event), so a user actively watching a chatty stream would send zero presence signals.
439
- _tabId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Math.random()).slice(2);
477
+ // last one is gone. In-memory only, never persisted. A reload of a page the dock app opened keeps
478
+ // the same id, because it comes from the URL; a reload of a plain browser tab gets a fresh one and
479
+ // the old id ages out of the server's presence map, which is what always happened. Rides
480
+ // pollProfile, NOT pollHealth: pollHealth early-returns without fetching while a stream is busy
481
+ // (<6s since the last event), so a user actively watching a chatty stream would send zero presence
482
+ // signals.
483
+ _tabId = pageTabId();
484
+ /**
485
+ * The headers an authored write carries: the proof the server's gate wants, plus which tab is
486
+ * writing.
487
+ *
488
+ * The pair has to travel together, and a method rather than four header literals is how that stays
489
+ * true. An authored write that proves it came from a dashboard but not WHICH one is credited to an
490
+ * agent session (see the server's creditAuthoredWrite), and a session claim is the one thing the
491
+ * dock app never overrides: it would refuse to replace a stale dashboard, and refuse to stop its own
492
+ * server on quit, because this window changed a filter.
493
+ *
494
+ * Sent on the writes the server CREDITS, which is /setspec and /enable. A db query or a screen
495
+ * consent buys no keep-alive, so it needs no identity.
496
+ */
497
+ authoredHeaders(extra = {}) {
498
+ return { "X-Radar-Dashboard": "1", "X-Radar-Tab": this._tabId, ...extra };
499
+ }
440
500
  // ---- shared detail cache (bounded FIFO) ----
441
501
  cacheDetail(kind, id, detail) {
442
502
  const key = kind + ":" + id;
@@ -515,6 +575,7 @@ class Store {
515
575
  // them). Deliberately NOT reset: subscribers, live timers and stream handles (start() and
516
576
  // openStream() own those lifecycles), and _tabId, which identifies the page for its whole life.
517
577
  _resetForTest() {
578
+ this.lastLogLevel = "";
518
579
  this.spec = { blank: true, viz: [] };
519
580
  this.conn = { state: "waiting", msg: "connecting…" };
520
581
  this.selfHeal = null;
@@ -829,7 +890,7 @@ class Store {
829
890
  // before its own first pollSpec() runs, so that later read confirms the same spec
830
891
  // rather than racing this one and overwriting it back to blank.
831
892
  this.applySpec(MODES[0].spec);
832
- await fetch("/setspec", { method: "POST", headers: { "Content-Type": "application/json", "X-Radar-Dashboard": "1" }, body: JSON.stringify(MODES[0].spec) }).catch(() => { });
893
+ await fetch("/setspec", { method: "POST", headers: this.authoredHeaders({ "Content-Type": "application/json" }), body: JSON.stringify(MODES[0].spec) }).catch(() => { });
833
894
  }
834
895
  }
835
896
  catch {
@@ -875,8 +936,9 @@ class Store {
875
936
  this.markLocalPush(spec);
876
937
  try {
877
938
  // X-Radar-Dashboard marks this as an authored write (see the server's handleSetSpec): it is
878
- // what lets the write count as a keep-alive, and a foreign origin cannot forge it.
879
- return await (await fetch("/setspec", { method: "POST", headers: { "Content-Type": "application/json", "X-Radar-Dashboard": "1" }, body: JSON.stringify(spec) })).json();
939
+ // what lets the write count as a keep-alive, and a foreign origin cannot forge it. X-Radar-Tab
940
+ // says the keep-alive is THIS window's rather than an agent session's.
941
+ return await (await fetch("/setspec", { method: "POST", headers: this.authoredHeaders({ "Content-Type": "application/json" }), body: JSON.stringify(spec) })).json();
880
942
  }
881
943
  catch {
882
944
  return { ok: false, error: "request failed" };
@@ -890,6 +952,9 @@ class Store {
890
952
  // backfill the device ring. Mirrors vanilla build(spec).
891
953
  applySpec(spec) {
892
954
  this.spec = spec || { blank: true, viz: [] };
955
+ if (this.spec.source === "log" || this.spec.source === "all") {
956
+ this.lastLogLevel = typeof this.spec.minLevel === "string" ? this.spec.minLevel : "";
957
+ }
893
958
  this.total = 0;
894
959
  this.liveMatches = 0;
895
960
  this.times = [];
@@ -1057,9 +1122,8 @@ class Store {
1057
1122
  }
1058
1123
  }
1059
1124
  candidates(field) {
1060
- const fixed = { direction: ["OUTGOING", "INCOMING"], level: ["VERBOSE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"], method: ["GET", "POST", "PUT", "DELETE", "PATCH"] };
1061
- if (fixed[field])
1062
- return fixed[field].slice();
1125
+ if (FIELD_VALUES[field])
1126
+ return FIELD_VALUES[field].slice();
1063
1127
  const seen = this.seen[field];
1064
1128
  return seen ? [...seen].sort() : [];
1065
1129
  }
@@ -1222,6 +1286,12 @@ class Store {
1222
1286
  this.selectedDevice === null);
1223
1287
  }
1224
1288
  matches(ev) {
1289
+ // The lowest priority to show. Only log rows carry one, so on the "all" timeline network,
1290
+ // rtm, clog and trace rows pass untouched, the same carve-out `package` gets below. A row whose
1291
+ // priority the order does not know ranks -1 and is hidden (see levelRank).
1292
+ const min = this.spec.minLevel;
1293
+ if (typeof min === "string" && min && ev._type === "log" && levelRank(ev.level) < levelRank(min))
1294
+ return false;
1225
1295
  const m = this.spec.match;
1226
1296
  if (!m)
1227
1297
  return true;
@@ -1498,9 +1568,9 @@ class Store {
1498
1568
  //
1499
1569
  // A reply that will not PARSE is a third case, and it must not be worded like the second. Not
1500
1570
  // being able to read the answer says nothing about the device, so it does not get to blame one.
1501
- // That is the repo's stated convention, in CLAUDE.md under the inconclusive-probe section: "A
1502
- // probe that cannot always tell must say so in its return type. Never collapse 'could not tell'
1503
- // into 'no'." So this reports the read failure, and the caller's device-blaming fallback is
1571
+ // A probe that cannot always tell says so in its return type, and "could not tell" never collapses
1572
+ // into "no"; every probe in RadarApp.swift follows the same rule. So this reports the read failure,
1573
+ // and the caller's device-blaming fallback is
1504
1574
  // reserved for a reply that parsed and simply carried no reason of its own.
1505
1575
  async readEnableResult(r, fallback) {
1506
1576
  const body = (await r.json().catch(() => null));
@@ -1537,7 +1607,7 @@ class Store {
1537
1607
  // device list is refreshed so the dropdown is current and the user can pick a valid device.
1538
1608
  async selectDevice(serial) {
1539
1609
  try {
1540
- const r = await fetch("/enable?device_serial=" + encodeURIComponent(serial), { method: "POST", headers: { "X-Radar-Dashboard": "1" } });
1610
+ const r = await fetch("/enable?device_serial=" + encodeURIComponent(serial), { method: "POST", headers: this.authoredHeaders() });
1541
1611
  // Any reply that did not arm the device takes the failure path, not just the 409. A 200 whose
1542
1612
  // body says enabled:false used to fall through here as a success: it cleared deviceError,
1543
1613
  // recorded the serial as switched-to, and resynced a stream against a device holding no
@@ -1840,7 +1910,7 @@ class Store {
1840
1910
  let replySwitched = false;
1841
1911
  let outcome;
1842
1912
  try {
1843
- const r = await fetch(auto ? "/enable?auto=1" : "/enable", { method: "POST", headers: { "X-Radar-Dashboard": "1" } });
1913
+ const r = await fetch(auto ? "/enable?auto=1" : "/enable", { method: "POST", headers: this.authoredHeaders() });
1844
1914
  const { enabled, error, instructs, serial, refusal } = await this.readEnableResult(r, "Reconnect failed. Is a device attached with a debug build of the Slack app running?");
1845
1915
  // The reply names the device this press pinned, and the route pins before it arms, so a
1846
1916
  // failing press can itself move the pin (first sight, or a switch to freshly attached
@@ -1975,6 +2045,8 @@ export function describeConstraints(spec) {
1975
2045
  parts.push("where " + Object.entries(spec.match).map(([k, v]) => k + "=" + v).join(", "));
1976
2046
  if (spec.bodyContains)
1977
2047
  parts.push('body contains "' + spec.bodyContains + '"');
2048
+ if (typeof spec.minLevel === "string" && spec.minLevel)
2049
+ parts.push("level ≥ " + spec.minLevel);
1978
2050
  if (spec.highlight && spec.highlight.field)
1979
2051
  parts.push("flag " + spec.highlight.field + " " + (spec.highlight.op || ">") + " " + spec.highlight.value + (spec.highlight.label ? " (" + spec.highlight.label + ")" : ""));
1980
2052
  if (Array.isArray(spec.series) && spec.series.length)
@@ -41,7 +41,17 @@ export declare function cleanupOnBind(): void;
41
41
  */
42
42
  export declare function registerScreenCleanupOnBind(): void;
43
43
  export declare const TAB_LIVENESS_MS = 75000;
44
+ /**
45
+ * How recently a tab must have polled to count as SOMEONE USING the dashboard, which is a different
46
+ * question from whether it is stale enough to auto-close, and takes a much tighter answer.
47
+ *
48
+ * Three of the dashboard's own five second profile polls. Generous enough that a live tab never
49
+ * flickers out of it, tight enough that closing a window releases the port in seconds rather than in
50
+ * the minute and a quarter TAB_LIVENESS_MS would impose.
51
+ */
52
+ export declare const TAB_IN_USE_MS = 15000;
44
53
  export declare const AUTO_CLOSE_GRACE_MS: number;
54
+ export declare const MCP_IN_USE_MS: number;
45
55
  /**
46
56
  * Pure auto-close decision, mirroring screen.ts's nextViewerAction/shouldRelaunch precedent:
47
57
  * the sweep owns the timestamp bookkeeping, this owns only the yes/no. Close only when there
@@ -50,6 +60,53 @@ export declare const AUTO_CLOSE_GRACE_MS: number;
50
60
  * Exported for unit testing without a clock or a socket.
51
61
  */
52
62
  export declare function shouldAutoClose(liveTabs: number, everSeen: boolean, msSinceEmpty: number | null): boolean;
63
+ /**
64
+ * Whether anyone is using this dashboard RIGHT NOW, which is a different question from
65
+ * shouldAutoClose() above and deliberately not the same answer.
66
+ *
67
+ * shouldAutoClose adds the grace window, because a process deciding to end itself should be slow
68
+ * about it. This is read by a DIFFERENT process deciding whether it may take the port, and there the
69
+ * grace window is exactly wrong: the five minutes after a dock app quits and its tab closes is the
70
+ * window an upgrade lands in, and a leftover nobody is looking at is the thing that most needs
71
+ * replacing.
72
+ *
73
+ * So: a live tab counts, and an MCP session with no tab open counts (markKeepAlive clears the empty
74
+ * marker without setting everSeen, which is what keeps an hour-long debugging session alive), but a
75
+ * dashboard whose last tab has gone does not.
76
+ *
77
+ * Exported for unit testing without a clock or a socket, same as shouldAutoClose.
78
+ */
79
+ export declare function isInUse(now?: number): boolean;
80
+ /**
81
+ * Which decision an in-use answer is about to inform.
82
+ *
83
+ * `take` is a caller asking whether it may take a port it does not own. `stop` is a caller asking whether
84
+ * it may stop a server it started itself. The two get different answers on purpose, and the reasons are at
85
+ * the two places inUseReason branches on this: a guess that protects a port must not also protect a
86
+ * process from its own parent, and a window sized so a closed tab stops blocking a replacement is too
87
+ * tight for deciding whether somebody is still reading a page.
88
+ */
89
+ export type InUseDecision = "take" | "stop";
90
+ /**
91
+ * WHY this dashboard is in use, not merely whether, because the two claims are worth different
92
+ * decisions to the process asking.
93
+ *
94
+ * A "tab" claim is a window someone has open. A "mcp" claim is an agent session driving this
95
+ * dashboard with no window of its own, and stopping that costs the session's pulled databases, its
96
+ * device pin and its logcat ring, none of which it can get back. A single yes/no cannot tell those
97
+ * apart, so a launcher had to treat them the same, and the only safe reading of "the same" is the
98
+ * cautious one, which then blocks the upgrade this whole path exists to perform.
99
+ *
100
+ * Priority is deliberate: an mcp claim outranks a tab claim, because the app's OWN window is a tab
101
+ * and a decision about whether to disturb someone else must not be answered by our own presence.
102
+ *
103
+ * `ignoreTab` is how a caller asks the narrower question it actually has: is anyone OTHER than my own
104
+ * window using this. The dock app generates the presence id, hands it to the page it loads, and sends
105
+ * it back here, so its own window stops answering for everybody else. Without it the app could not
106
+ * tell its own tab from a real second browser tab, and had to guess; guessing either way is wrong,
107
+ * because one reading kills a page someone is reading and the other never stops anything.
108
+ */
109
+ export declare function inUseReason(now?: number, ignoreTab?: string, decision?: InUseDecision): "tab" | "mcp" | "no";
53
110
  export declare function touchTab(id: string, now?: number): void;
54
111
  /**
55
112
  * Treat an authored MCP write (a /setspec, a successful /enable) as a keep-alive equivalent to
@@ -59,7 +116,7 @@ export declare function touchTab(id: string, now?: number): void;
59
116
  * pin, and the pulled-DB cache. Deliberately does NOT set everSeen: an MCP-only dashboard that
60
117
  * nobody ever opened stays protected by the everSeen guard even after the MCP goes quiet.
61
118
  */
62
- export declare function markKeepAlive(): void;
119
+ export declare function markKeepAlive(now?: number): void;
63
120
  /**
64
121
  * Whether a request may buy the process more life. True for our own client and the MCP, false
65
122
  * for anything else, so a foreign page cannot postpone auto-close forever.
@@ -81,6 +138,43 @@ export declare function isAuthoredRequest(headers: {
81
138
  "x-radar-dashboard"?: string | string[];
82
139
  "content-type"?: string | string[];
83
140
  }): boolean;
141
+ /**
142
+ * "This request comes FROM the tab with this id." Sent by the dashboard page on its own authored
143
+ * writes, so a write can be credited to the window that made it.
144
+ */
145
+ export declare function readTabIdentity(headers: http.IncomingHttpHeaders): string | undefined;
146
+ /**
147
+ * "Leave this id out of the answer." Sent by a launcher asking whether anyone OTHER than the window it
148
+ * owns is using this dashboard.
149
+ *
150
+ * A separate header from the identity one above, carrying the same value, and deliberately so: the app
151
+ * that sends this is NOT the tab. Its window may have failed to load, or may be showing the failure
152
+ * page. One header would invite a future route to treat the app's own probe as proof that its tab is
153
+ * live, which would record presence for a window that does not exist. Two names make that impossible
154
+ * rather than merely discouraged.
155
+ */
156
+ export declare function readIgnoredTab(headers: http.IncomingHttpHeaders): string | undefined;
157
+ /**
158
+ * Which decision the caller says it is about to make. Anything other than the one recognised value reads as
159
+ * `take`, which is both the back-compatible answer (no installed launcher sends this) and the conservative
160
+ * one: it is the reading that protects a port rather than the one that permits a stop.
161
+ */
162
+ export declare function readInUseDecision(headers: http.IncomingHttpHeaders): InUseDecision;
163
+ /**
164
+ * Credit an authored write to whoever made it: a tab that named itself, or an agent session.
165
+ *
166
+ * The distinction is load-bearing, and getting it wrong was a real bug. `markKeepAlive` is what makes
167
+ * inUseReason answer "mcp", and the dashboard PAGE makes authored writes too: `bootDefault` posts
168
+ * /setspec on any page load that finds a blank spec, and every mode switch and filter Apply posts
169
+ * another. So a person opening the dock app and clicking one tab made the server report an agent
170
+ * session for the next MCP_IN_USE_MS, and "mcp" is the one claim nothing overrides — the launcher
171
+ * refuses to replace it and the quit path refuses to stop it. The app then left its own server running
172
+ * on quit, which is the exact leak the quit path exists to close, reachable by ordinary use.
173
+ *
174
+ * A tab's write is credited as presence instead, which is both true and stronger: it is the same thing
175
+ * the tab's own /health poll records. Only a write from something with no tab at all is a session.
176
+ */
177
+ export declare function creditAuthoredWrite(tab: string | undefined, now?: number): void;
84
178
  /**
85
179
  * One sweep tick: prune stale tab ids, maintain the emptySince marker across the 1->0 / 0->1
86
180
  * transitions, and return whether the dashboard should auto-close now. Owns all timestamp
@@ -167,10 +261,10 @@ export declare function createServer(onShutdown?: (server: http.Server) => void)
167
261
  * successful re-arm keeps the dashboard alive (an MCP-driven session can re-enable with no tab
168
262
  * open, and that must not let the idle timer fire out from under it).
169
263
  *
170
- * `onEnabled` fires only on a successful probe. The route passes `markKeepAlive` when the
171
- * request was authored (see isAuthoredRequest) and OMITS it otherwise, so an unauthored caller
172
- * gets the same body but buys no extra process life. Injected rather than called directly so
173
- * the keep-alive wiring is testable without a real device probe (handleEnable's ping goes over
264
+ * `onEnabled` fires only on a successful probe. The route passes a hook that credits the WRITER
265
+ * (creditAuthoredWrite) when the request was authored (see isAuthoredRequest) and OMITS it otherwise, so
266
+ * an unauthored caller gets the same body but buys no extra process life. Injected rather than called
267
+ * directly so the keep-alive wiring is testable without a real device probe (handleEnable's ping goes over
174
268
  * a real socket to RADAR_HOST:RADAR_PORT, which this function does not touch at all).
175
269
  *
176
270
  * A failed probe gets guidance, not a bare false: the broadcast landed (or exited 0 with no
@@ -183,8 +277,11 @@ export declare function createServer(onShutdown?: (server: http.Server) => void)
183
277
  * through the route cannot cover this — handleEnable's device probe fails with no hardware, which
184
278
  * short-circuits before the hook is ever consulted, so a route-level test passes either way (a
185
279
  * mutation deleting the gate survived the whole suite before this existed).
280
+ *
281
+ * `tab` is the writer, and it decides WHICH credit the hook applies: a re-arm pressed in the dashboard
282
+ * is a window's, not an agent session's. See creditAuthoredWrite.
186
283
  */
187
- export declare function keepAliveHookFor(authored: boolean): (() => void) | undefined;
284
+ export declare function keepAliveHookFor(authored: boolean, tab?: string): (() => void) | undefined;
188
285
  /**
189
286
  * Whether the dashboard serves this request without proof of origin. Everything else is refused
190
287
  * unless authored. Exported so a test can drive the decision directly, and so the open surface is