@slack/radar-mcp 1.18.1 → 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,5 @@
1
1
  import http from "http";
2
+ import type { StatusReason } from "../shared/wire.js";
2
3
  import { type DashboardScreenController } from "../shared/dashboard-screen.js";
3
4
  import type { ProcessState } from "../shared/transport.js";
4
5
  import { type LogFrame } from "./log-session.js";
@@ -40,7 +41,17 @@ export declare function cleanupOnBind(): void;
40
41
  */
41
42
  export declare function registerScreenCleanupOnBind(): void;
42
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;
43
53
  export declare const AUTO_CLOSE_GRACE_MS: number;
54
+ export declare const MCP_IN_USE_MS: number;
44
55
  /**
45
56
  * Pure auto-close decision, mirroring screen.ts's nextViewerAction/shouldRelaunch precedent:
46
57
  * the sweep owns the timestamp bookkeeping, this owns only the yes/no. Close only when there
@@ -49,6 +60,53 @@ export declare const AUTO_CLOSE_GRACE_MS: number;
49
60
  * Exported for unit testing without a clock or a socket.
50
61
  */
51
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";
52
110
  export declare function touchTab(id: string, now?: number): void;
53
111
  /**
54
112
  * Treat an authored MCP write (a /setspec, a successful /enable) as a keep-alive equivalent to
@@ -58,7 +116,7 @@ export declare function touchTab(id: string, now?: number): void;
58
116
  * pin, and the pulled-DB cache. Deliberately does NOT set everSeen: an MCP-only dashboard that
59
117
  * nobody ever opened stays protected by the everSeen guard even after the MCP goes quiet.
60
118
  */
61
- export declare function markKeepAlive(): void;
119
+ export declare function markKeepAlive(now?: number): void;
62
120
  /**
63
121
  * Whether a request may buy the process more life. True for our own client and the MCP, false
64
122
  * for anything else, so a foreign page cannot postpone auto-close forever.
@@ -80,6 +138,43 @@ export declare function isAuthoredRequest(headers: {
80
138
  "x-radar-dashboard"?: string | string[];
81
139
  "content-type"?: string | string[];
82
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;
83
178
  /**
84
179
  * One sweep tick: prune stale tab ids, maintain the emptySince marker across the 1->0 / 0->1
85
180
  * transitions, and return whether the dashboard should auto-close now. Owns all timestamp
@@ -166,10 +261,10 @@ export declare function createServer(onShutdown?: (server: http.Server) => void)
166
261
  * successful re-arm keeps the dashboard alive (an MCP-driven session can re-enable with no tab
167
262
  * open, and that must not let the idle timer fire out from under it).
168
263
  *
169
- * `onEnabled` fires only on a successful probe. The route passes `markKeepAlive` when the
170
- * request was authored (see isAuthoredRequest) and OMITS it otherwise, so an unauthored caller
171
- * gets the same body but buys no extra process life. Injected rather than called directly so
172
- * 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
173
268
  * a real socket to RADAR_HOST:RADAR_PORT, which this function does not touch at all).
174
269
  *
175
270
  * A failed probe gets guidance, not a bare false: the broadcast landed (or exited 0 with no
@@ -182,8 +277,11 @@ export declare function createServer(onShutdown?: (server: http.Server) => void)
182
277
  * through the route cannot cover this — handleEnable's device probe fails with no hardware, which
183
278
  * short-circuits before the hook is ever consulted, so a route-level test passes either way (a
184
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.
185
283
  */
186
- export declare function keepAliveHookFor(authored: boolean): (() => void) | undefined;
284
+ export declare function keepAliveHookFor(authored: boolean, tab?: string): (() => void) | undefined;
187
285
  /**
188
286
  * Whether the dashboard serves this request without proof of origin. Everything else is refused
189
287
  * unless authored. Exported so a test can drive the decision directly, and so the open surface is
@@ -211,9 +309,13 @@ export declare function isOpenToAnyCaller(urlPath: string, method: string | unde
211
309
  */
212
310
  export declare function isLocalHostHeader(host: string | string[] | undefined, allowedHosts?: string | undefined): boolean;
213
311
  export declare function enableResultBody(enabled: boolean, onEnabled?: () => void, processState?: ProcessState): {
214
- enabled: boolean;
215
- error?: string;
312
+ enabled: true;
313
+ } | {
314
+ enabled: false;
315
+ error: string;
316
+ instructs: boolean;
216
317
  };
318
+ export declare function _setEnableFaultForTest(err: Error | null, delayMs?: number): void;
217
319
  export declare const DEVICE_SOURCES: Record<string, {
218
320
  segment: string;
219
321
  arrayKey: string;
@@ -235,4 +337,9 @@ type ParsedLog = LogFrame;
235
337
  * Exported for tests.
236
338
  */
237
339
  export declare function parseLogcat(line: string, resolvePkg?: (pid: number) => string | undefined): ParsedLog | null;
340
+ export declare function _setStreamResponseTimeoutForTest(ms: number | null): void;
341
+ export declare function _setOutageDiagnosisTtlForTest(ms: number | null): void;
342
+ export declare function _setOutageProbeForTest(probe: (() => Promise<"present" | "absent" | "unknown">) | null): void;
343
+ export declare function _diagnoseOutageForTest(): Promise<StatusReason | null>;
344
+ export declare function _invalidateOutageDiagnosisForTest(): void;
238
345
  export { WEB_PORT };