@slack/radar-mcp 1.13.0 → 1.17.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.
Files changed (46) hide show
  1. package/README.md +31 -3
  2. package/dist/mcp/db-tools.js +23 -0
  3. package/dist/mcp/dispatch.d.ts +4 -0
  4. package/dist/mcp/dispatch.js +26 -0
  5. package/dist/mcp/index.js +112 -33
  6. package/dist/mcp/platform-detect.d.ts +110 -0
  7. package/dist/mcp/platform-detect.js +246 -0
  8. package/dist/mcp/prefs-tools.d.ts +4 -3
  9. package/dist/mcp/prefs-tools.js +26 -3
  10. package/dist/mcp/session-enable.js +19 -1
  11. package/dist/mcp/snapshot.js +4 -1
  12. package/dist/mcp/sources-gate.js +6 -3
  13. package/dist/mcp/tools.d.ts +11 -0
  14. package/dist/mcp/tools.js +38 -0
  15. package/dist/shared/android.d.ts +40 -1
  16. package/dist/shared/android.js +114 -51
  17. package/dist/shared/constants.d.ts +25 -1
  18. package/dist/shared/constants.js +27 -1
  19. package/dist/shared/db.js +11 -2
  20. package/dist/shared/debug-log.js +6 -1
  21. package/dist/shared/enable-diagnosis.d.ts +28 -0
  22. package/dist/shared/enable-diagnosis.js +41 -0
  23. package/dist/shared/prefs.d.ts +0 -5
  24. package/dist/shared/prefs.js +6 -2
  25. package/dist/shared/screen.d.ts +46 -9
  26. package/dist/shared/screen.js +74 -11
  27. package/dist/shared/transport.d.ts +62 -5
  28. package/dist/shared/webapp.d.ts +50 -0
  29. package/dist/shared/webapp.js +65 -0
  30. package/dist/web/bin.js +16 -6
  31. package/dist/web/install-app.d.ts +87 -0
  32. package/dist/web/install-app.js +703 -0
  33. package/dist/web/macapp/RadarApp.swift +466 -0
  34. package/dist/web/public/icons/radar-1024.png +0 -0
  35. package/dist/web/public/icons/radar.svg +40 -0
  36. package/dist/web/public/index.html +42 -1
  37. package/dist/web/public/next/app.js +42 -1
  38. package/dist/web/public/next/db.js +153 -7
  39. package/dist/web/public/next/feed.js +18 -0
  40. package/dist/web/public/next/hooks.js +10 -1
  41. package/dist/web/public/next/screen.js +156 -46
  42. package/dist/web/public/next/store.js +164 -21
  43. package/dist/web/public/next/toast.js +134 -0
  44. package/dist/web/server.d.ts +151 -1
  45. package/dist/web/server.js +579 -22
  46. package/package.json +2 -2
@@ -0,0 +1,246 @@
1
+ /**
2
+ * Auto-detect decision logic for createTransport()'s no-flag path, split out of index.ts (like
3
+ * session-detail.ts, session-query.ts, api-paths.ts) so it is unit-testable: index.ts connects
4
+ * stdio at module load, so importing it directly from a test would hang. The device-attached
5
+ * check and the webapp reachability check are INJECTED (mirroring db-tools.ts taking a
6
+ * `transport`), so decidePlatform() itself does no I/O and needs neither a real adb device nor
7
+ * a real running webapp server to test.
8
+ *
9
+ * Probe order:
10
+ * 1. An adb device is CONFIRMED attached and usable -> android, exactly like today. A device
11
+ * being attached is the right signal even before Radar has been activated on it (that happens
12
+ * later, in session-enable.ts), so this only needs a device LISTING, not a live radar ping.
13
+ * 2. adb listed a device that is not usable (an unaccepted debugging prompt, offline) -> android
14
+ * with a note. A device on the cable is the same statement of intent whether or not it has
15
+ * been authorised yet, and "no usable device" is emphatically not "no device".
16
+ * 3. The probe could not tell (adb missing, timed out, errored) -> android as well. Only a
17
+ * confirmed "nothing attached at all" may fall through to the webapp probe; see below.
18
+ * 4. Else, something answering /api/ping on the webapp default port that looks like Radar's
19
+ * shape -> webapp. Skipped entirely when an explicit SLACK_RADAR_DEVICE_PORT is already
20
+ * set: that env var already states which port the caller wants, so it wins over
21
+ * auto-detection the same way --platform= wins over it.
22
+ * 5. Else, fall through to android -- this preserves today's exact no-flag behavior (and
23
+ * exact error message) for a session with neither available.
24
+ *
25
+ * Why an inconclusive android probe must NOT fall through to webapp: the two probes are not
26
+ * equally strong evidence, and the cost of being wrong is asymmetric. Picking android when a
27
+ * webapp Radar was available is a clear, immediate failure the user can read and correct with
28
+ * --platform=webapp. Picking webapp when a phone was attached is SILENT: ping, clogs, rtm,
29
+ * search and query_session all answer successfully against the browser's telemetry, so a
30
+ * session opened to debug a phone quietly reports another system's data, and createTransport()
31
+ * runs once so there is no recovery short of a restart.
32
+ *
33
+ * Deliberate policy, not an oversight: an attached device wins even when no debug build is
34
+ * running on it, which is weaker evidence than a shape-verified webapp Radar response. A phone
35
+ * on the end of a cable is a strong statement of intent, and this preserves the behaviour every
36
+ * existing android user already has. --platform=webapp is the documented override.
37
+ */
38
+ import { execSync } from "child_process";
39
+ import http from "http";
40
+ import { parseAdbDevicesOutput, resolveAdbPath } from "../shared/android.js";
41
+ /**
42
+ * Read ceiling for the webapp reachability probe. Generous next to a real Radar ping (a few
43
+ * hundred bytes) and small enough that an unidentified server cannot make startup buffer without
44
+ * bound.
45
+ */
46
+ const MAX_PING_PROBE_BYTES = 64 * 1024;
47
+ /**
48
+ * The guard for open_radar_dashboard: its success copy assumes a device dashboard ("Slack Radar
49
+ * must be enabled on it", "the dashboard has its own Reconnect button if the device is not yet
50
+ * armed"), but WebappTransport.activate() is a documented no-op with no device/arming concept, so a
51
+ * transport without one must be turned away with a clean error instead. Split out here (mirroring
52
+ * decidePlatform above) so index.ts's handler logic is unit-testable without importing index.ts
53
+ * itself, which connects stdio at module load.
54
+ *
55
+ * Keyed on the CAPABILITY, not on the platform name, for the reason stated on DeviceTransport: a
56
+ * `platform !== "android"` check rejects every future transport by construction rather than by an
57
+ * actual gap. The platform name is still taken, for the message only.
58
+ *
59
+ * Returns null when it is fine to proceed, or the error string to surface when it is not.
60
+ */
61
+ export function dashboardPlatformError(transport) {
62
+ return transport.supportsDeviceDashboard
63
+ ? null
64
+ : `Dashboard access not supported on platform ${transport.platform}`;
65
+ }
66
+ /**
67
+ * The one wording for "this transport does not do that", used by every handler guarding an
68
+ * optional DeviceTransport capability. The rejection was previously spelled three different ways
69
+ * across eleven sites, and on the four device-operation tools it arrived wrapped in a
70
+ * failure-sounding prefix ("Screenshot failed: Screenshot not supported on...") because the
71
+ * transport threw and the handler's catch treated it as a runtime error. It is not a failure; the
72
+ * capability was never there.
73
+ *
74
+ * @param platform The transport's platform name, for the message only.
75
+ * @param what Sentence-leading description of the capability, e.g. "Screenshot".
76
+ */
77
+ export function unsupportedCapabilityError(platform, what) {
78
+ return `${what} not supported on platform ${platform}`;
79
+ }
80
+ /**
81
+ * Decide which platform createTransport() should instantiate, and whether it should call
82
+ * setRadarPort() first. Pure decision logic: the caller (index.ts) wires the real
83
+ * androidDeviceAttached/webappReachable probes and the real setRadarPort()/transport
84
+ * construction based on the returned decision.
85
+ */
86
+ export async function decidePlatform(input) {
87
+ const { explicitPlatform, envPortOverride, androidDeviceState, webappReachable } = input;
88
+ // Explicit --platform= wins over auto-detection entirely, per today's behavior.
89
+ if (explicitPlatform !== undefined) {
90
+ if (explicitPlatform === "android")
91
+ return { platform: "android" };
92
+ if (explicitPlatform === "webapp") {
93
+ return { platform: "webapp", setPort: !envPortOverride };
94
+ }
95
+ return { platform: "unsupported", requested: explicitPlatform };
96
+ }
97
+ // Each state is answered on its own terms. Only "none" is evidence a webapp Radar is what the
98
+ // user meant. Every other state lands on android and says why.
99
+ const androidState = androidDeviceState();
100
+ switch (androidState) {
101
+ // 1. A device being attached is the right signal even if Radar has not been activated yet.
102
+ case "attached":
103
+ return { platform: "android" };
104
+ // 2. adb answered clearly and what it said was "attached, not usable". Say exactly that: the
105
+ // fix is on the phone, and a note about adb being slow would send the user hunting the wrong
106
+ // thing.
107
+ case "unusable":
108
+ return {
109
+ platform: "android",
110
+ note: "an Android device is attached but not ready for debugging (for example a USB debugging " +
111
+ "prompt that has not been accepted yet), so defaulting to android. Accept the prompt on " +
112
+ "the device, or pass --platform=webapp to target a webapp Radar instead.",
113
+ };
114
+ // 3. Inconclusive is NOT "no device" (see the file header for why the asymmetry matters). Land
115
+ // on android and say so, because this is the one path where a user with a running webapp Radar
116
+ // gets android and has no way to guess why.
117
+ case "unknown":
118
+ return {
119
+ platform: "android",
120
+ note: "could not tell whether an Android device is attached (adb missing, slow, or failing), " +
121
+ "so defaulting to android. Pass --platform=webapp to target a webapp Radar instead.",
122
+ };
123
+ case "none":
124
+ break;
125
+ default: {
126
+ // A state added to DeviceAttachState later must not reach the webapp probe just by being
127
+ // unhandled, which is the exact failure this function exists to prevent. The never
128
+ // assignment makes adding one a COMPILE error here rather than a silent fall-through, and
129
+ // if an unrecognised value somehow arrives at runtime it lands on android like every other
130
+ // state we cannot read as a confirmed empty cable.
131
+ const unhandled = androidState;
132
+ void unhandled;
133
+ return {
134
+ platform: "android",
135
+ note: "could not classify what adb reported about attached devices, so defaulting to " +
136
+ "android. Pass --platform=webapp to target a webapp Radar instead.",
137
+ };
138
+ }
139
+ }
140
+ // 4. Skipped entirely when an explicit port override is already set (see file header).
141
+ if (!envPortOverride && (await webappReachable())) {
142
+ return { platform: "webapp", setPort: true };
143
+ }
144
+ // 5. Preserves today's exact no-flag, no-device fallback.
145
+ return { platform: "android" };
146
+ }
147
+ /**
148
+ * The real (non-injected) android-device-attached probe for createTransport()'s no-flag
149
+ * auto-detect path. Deliberately separate from AndroidTransport.listDevices() (shared/android.ts):
150
+ * that method keeps its existing 5000ms timeout because its other callers (selectDevice(), run
151
+ * from an explicit user action) legitimately want to wait that long, and this probe runs on
152
+ * EVERY no-flag startup before the server can even connect, so it needs a short ceiling instead.
153
+ * Matches pingLooksLikeWebappRadar's 800ms default so the two auto-detect probes cost about the
154
+ * same. Reuses parseAdbDevicesOutput (shared/android.ts) for the actual line parsing -- same
155
+ * source of truth listDevices() uses, so a future adb output-format change only needs fixing in
156
+ * one place.
157
+ *
158
+ * Reports "unknown", not "none", when it could not tell. The 800ms ceiling is SHORTER than a cold
159
+ * adb daemon's real startup (measured ~3.1s cold, and it is daemon startup rather than enumeration,
160
+ * so an empty device list costs the same), so a timeout here is an ordinary event on the first
161
+ * call after a reboot, not an exotic one. Reporting that as an absence made a slow success
162
+ * indistinguishable from a confirmed absence, and decidePlatform went on to pick webapp with a
163
+ * phone plugged in.
164
+ *
165
+ * "unusable" is the same mistake one level in: a listing that holds only unauthorized or offline
166
+ * entries is a confirmed answer, but the answer is "there is a phone here", not "there is no
167
+ * phone". An unaccepted debugging prompt is the ordinary case on a fresh machine, a new cable, or
168
+ * after an adb key reset, and it used to select webapp silently.
169
+ */
170
+ export function quickAndroidDeviceState(timeoutMs = 800) {
171
+ const adb = resolveAdbPath();
172
+ if (!adb)
173
+ return "unknown";
174
+ let raw;
175
+ try {
176
+ raw = execSync(`${adb} devices -l`, {
177
+ timeout: timeoutMs,
178
+ encoding: "utf-8",
179
+ stdio: ["ignore", "pipe", "ignore"],
180
+ });
181
+ }
182
+ catch {
183
+ return "unknown";
184
+ }
185
+ const devices = parseAdbDevicesOutput(raw);
186
+ if (devices.some((d) => d.state === "device"))
187
+ return "attached";
188
+ // Anything listed but not in state "device" is attached-and-not-drivable: unauthorized, offline,
189
+ // authorizing, bootloader, recovery, sideload, no permissions. Enumerating the usable state and
190
+ // treating every other listed entry as unusable means a state adb adds later lands here rather
191
+ // than silently counting as an empty cable.
192
+ if (devices.length > 0)
193
+ return "unusable";
194
+ // An empty parse is only an empty CABLE if adb actually produced its listing. A zero-exit call
195
+ // with empty or unrecognised stdout parses to zero devices too, and reporting that as a confirmed
196
+ // absence is the same error one layer out, since stderr is discarded here. Requiring the header
197
+ // keeps "adb said nothing" apart from "adb said nothing is attached".
198
+ return raw.includes("List of devices attached") ? "none" : "unknown";
199
+ }
200
+ /**
201
+ * The real (non-injected) webapp reachability probe: a short-timeout GET against
202
+ * `http://<host>:<port>/api/ping`. Any response at all proves something is listening, but this
203
+ * only commits to "looks like Radar" when the parsed body has the `ok`/`target` shape Radar's
204
+ * own /api/ping returns -- a stray dev server answering something else on the same port must
205
+ * not be mistaken for Radar. host/port are parameters (not read from shared/constants.ts)
206
+ * so tests can point this at a real ephemeral local server instead of the hardcoded
207
+ * WEBAPP_DEFAULT_PORT.
208
+ */
209
+ export function pingLooksLikeWebappRadar(host, port, timeoutMs = 800) {
210
+ return new Promise((resolve) => {
211
+ const req = http.request({ host, port, path: "/api/ping", method: "GET", timeout: timeoutMs }, (res) => {
212
+ let body = "";
213
+ res.on("data", (chunk) => {
214
+ // Whatever is listening on this port is unidentified by definition -- deciding what it
215
+ // is is the entire job of this probe. So read only enough to answer that, and hang up
216
+ // on anything larger rather than buffering a stranger's response without limit. A real
217
+ // Radar ping is a few hundred bytes; the rest of the repo caps reads the same way
218
+ // (radarRequest's MAX_RADAR_RESPONSE_BYTES).
219
+ if (body.length + chunk.length > MAX_PING_PROBE_BYTES) {
220
+ req.destroy();
221
+ resolve(false);
222
+ return;
223
+ }
224
+ body += chunk;
225
+ });
226
+ res.on("end", () => {
227
+ try {
228
+ const parsed = JSON.parse(body);
229
+ resolve(typeof parsed === "object" &&
230
+ parsed !== null &&
231
+ "ok" in parsed &&
232
+ "target" in parsed);
233
+ }
234
+ catch {
235
+ resolve(false);
236
+ }
237
+ });
238
+ });
239
+ req.on("error", () => resolve(false));
240
+ req.on("timeout", () => {
241
+ req.destroy();
242
+ resolve(false);
243
+ });
244
+ req.end();
245
+ });
246
+ }
@@ -1,15 +1,16 @@
1
1
  /**
2
2
  * Handler dispatch for the three prefs tools: list_prefs, get_prefs, search_prefs.
3
3
  */
4
- export declare function handleListPrefs(user?: string): Promise<{
4
+ import type { DeviceTransport } from "../shared/transport.js";
5
+ export declare function handleListPrefs(transport: DeviceTransport, user?: string): Promise<{
5
6
  data: unknown;
6
7
  isError: boolean;
7
8
  }>;
8
- export declare function handleGetPrefs(file: string, user?: string, keys?: string[]): Promise<{
9
+ export declare function handleGetPrefs(transport: DeviceTransport, file: string, user?: string, keys?: string[]): Promise<{
9
10
  data: unknown;
10
11
  isError: boolean;
11
12
  }>;
12
- export declare function handleSearchPrefs(query: string, user?: string): Promise<{
13
+ export declare function handleSearchPrefs(transport: DeviceTransport, query: string, user?: string): Promise<{
13
14
  data: unknown;
14
15
  isError: boolean;
15
16
  }>;
@@ -53,7 +53,18 @@ function capPrefsEntries(entries, file, user) {
53
53
  }
54
54
  return { entries: kept, truncated: kept.length < entries.length, droppedKeys };
55
55
  }
56
- export async function handleListPrefs(user) {
56
+ export async function handleListPrefs(transport, user) {
57
+ // These handlers call resolveAdbPath()/shared/prefs.ts directly, bypassing the transport
58
+ // interface entirely, so a transport that cannot reach on-device files must be turned away here
59
+ // rather than falling through to a resolveAdbPath() call that assumes adb exists. Keyed on the
60
+ // CAPABILITY, not on the platform name, so a future transport that CAN serve prefs is not
61
+ // rejected just for having a different name.
62
+ if (!transport.supportsLocalFileAccess) {
63
+ return {
64
+ data: { error: `Preferences access not supported on platform ${transport.platform}` },
65
+ isError: true,
66
+ };
67
+ }
57
68
  const adbPath = resolveAdbPath();
58
69
  if (!adbPath) {
59
70
  return {
@@ -91,13 +102,19 @@ export async function handleListPrefs(user) {
91
102
  };
92
103
  }
93
104
  }
94
- export async function handleGetPrefs(file, user, keys) {
105
+ export async function handleGetPrefs(transport, file, user, keys) {
95
106
  if (!file) {
96
107
  return {
97
108
  data: { error: "file parameter is required" },
98
109
  isError: true,
99
110
  };
100
111
  }
112
+ if (!transport.supportsLocalFileAccess) {
113
+ return {
114
+ data: { error: `Preferences access not supported on platform ${transport.platform}` },
115
+ isError: true,
116
+ };
117
+ }
101
118
  const adbPath = resolveAdbPath();
102
119
  if (!adbPath) {
103
120
  return {
@@ -160,13 +177,19 @@ export async function handleGetPrefs(file, user, keys) {
160
177
  };
161
178
  }
162
179
  }
163
- export async function handleSearchPrefs(query, user) {
180
+ export async function handleSearchPrefs(transport, query, user) {
164
181
  if (!query) {
165
182
  return {
166
183
  data: { error: "query parameter is required" },
167
184
  isError: true,
168
185
  };
169
186
  }
187
+ if (!transport.supportsLocalFileAccess) {
188
+ return {
189
+ data: { error: `Preferences access not supported on platform ${transport.platform}` },
190
+ isError: true,
191
+ };
192
+ }
170
193
  const adbPath = resolveAdbPath();
171
194
  if (!adbPath) {
172
195
  return {
@@ -1,3 +1,14 @@
1
+ // The _radar_session_enable orchestration, split out of the index.ts handler (like
2
+ // session-backfill.ts) so the enable flow is unit-testable without importing index.ts
3
+ // (index connects stdio at load, so a test import would hang). Every effect is INJECTED;
4
+ // index.ts wires the real transport, stream, spool, backfill, and ping.
5
+ //
6
+ // The flow's one job beyond sequencing: never report enabled:true unless the device
7
+ // server actually answered a ping. The two silent-failure classes this kills:
8
+ // an adb-level broadcast failure (previously swallowed entirely), and a broadcast
9
+ // that exits 0 with no receiver (radar modules missing, wrong profile), which the
10
+ // old code reported as enabled:true with a failing ping.
11
+ import { deviceServerSilentError, readProcessState, } from "../shared/enable-diagnosis.js";
1
12
  // Ping-verify cadence: first probe fast (a healthy server answers immediately;
2
13
  // this is the whole latency of a normal enable), then two patient retries to
3
14
  // absorb real server startup.
@@ -97,10 +108,17 @@ export async function runSessionEnable(timeoutMinutes, deviceSerial, deps) {
97
108
  }
98
109
  if (status === null) {
99
110
  destroyStream();
111
+ // Checked fresh, not from a cache, but only here, seconds after the broadcast: backfill,
112
+ // stream connect, and three ping retries have already run. A confirmed "stopped" does not
113
+ // prove the app was never launched. It is equally consistent with the app receiving the
114
+ // broadcast, then crashing during Radar's own activation before the first successful ping.
115
+ // The message states the fact without asserting which of those happened, and names the
116
+ // crash case as its own signal instead of presenting it as the same fix as a launch.
117
+ const error = deviceServerSilentError(readProcessState(device));
100
118
  return {
101
119
  enabled: false,
102
120
  body: {
103
- error: "Radar broadcast sent but the device server did not respond. Is a debug build with the slack-radar modules installed and running on the active profile?",
121
+ error,
104
122
  enabled: false,
105
123
  platform: device.platform,
106
124
  },
@@ -195,7 +195,10 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
195
195
  // Screenshot. 720px default is plenty for bug reports; full-res is
196
196
  // 5-8x larger on disk and rarely adds forensic value.
197
197
  let screenshotCaptured = false;
198
- if (includeScreenshot) {
198
+ // A transport with no screen to capture simply contributes no screenshot to the bundle. The rest
199
+ // of the snapshot (buffers, state) is still worth writing, so this is a skip rather than an
200
+ // error, and screenshotCaptured already reports the omission to the caller.
201
+ if (includeScreenshot && device.screenshot) {
199
202
  try {
200
203
  const tmp = device.screenshot(false);
201
204
  const dest = path.join(dir, "screenshot.png");
@@ -3,13 +3,16 @@
3
3
  // This module caches that list per session and blocks tools whose source the device declared
4
4
  // absent, turning a raw route 404 into one uniform, actionable error.
5
5
  //
6
- // Only sources that ship as plugins on the device are gateable. Sources still hardcoded in the
7
- // device core (network/rtm/clog) are absent from `sources` on every build today, so their tools
8
- // must pass through; each entry joins GATEABLE_SOURCES when its device-side migration lands.
6
+ // Only sources that ship as plugins on the device are gateable. Network capture is still
7
+ // hardcoded in the device core, so it never appears in `sources` and its tools always pass
8
+ // through; it joins TOOL_SOURCE when its device-side migration lands. RTM ships as a plugin now
9
+ // but gating it is a deliberate follow-up, not yet done: it joins TOOL_SOURCE in that PR.
9
10
  // A build that predates the seam sends no `sources` at all, which disables gating entirely.
10
11
  // Tool name -> the ping `sources` name that must be present for the tool to work. Every key
11
12
  // must name a real tool in TOOL_DEFINITIONS (pinned by test).
12
13
  export const TOOL_SOURCE = {
14
+ get_recent_clogs: "clogs",
15
+ get_clog_detail: "clogs",
13
16
  get_recent_traces: "traces",
14
17
  get_trace_detail: "traces",
15
18
  list_feature_flags: "feature_flags",
@@ -1,4 +1,15 @@
1
1
  export declare const SERVER_INSTRUCTIONS: string;
2
+ /**
3
+ * The instructions the model actually receives, for the platform this session resolved to.
4
+ *
5
+ * SERVER_INSTRUCTIONS above is written for Android over adb throughout: it tells the model to run
6
+ * /radar-enable, to reach for screenshots and device logs, and to reason about a connected device.
7
+ * On webapp none of that holds -- there is no adb, no arming broadcast, and four of those tools
8
+ * have no implementation at all -- so sending it unchanged coaches the model straight into calls
9
+ * that can only fail. Rather than fork the whole document per platform, state the differences once
10
+ * up front, where they override what follows.
11
+ */
12
+ export declare function serverInstructions(platform: string): string;
2
13
  export interface ToolDefinition {
3
14
  name: string;
4
15
  description: string;
package/dist/mcp/tools.js CHANGED
@@ -126,6 +126,44 @@ export const SERVER_INSTRUCTIONS = [
126
126
  " 6. If result.errors is non-empty, enumerate which parts failed so the user",
127
127
  " knows what is missing before they ship the bundle.",
128
128
  ].join("\n");
129
+ /**
130
+ * The instructions the model actually receives, for the platform this session resolved to.
131
+ *
132
+ * SERVER_INSTRUCTIONS above is written for Android over adb throughout: it tells the model to run
133
+ * /radar-enable, to reach for screenshots and device logs, and to reason about a connected device.
134
+ * On webapp none of that holds -- there is no adb, no arming broadcast, and four of those tools
135
+ * have no implementation at all -- so sending it unchanged coaches the model straight into calls
136
+ * that can only fail. Rather than fork the whole document per platform, state the differences once
137
+ * up front, where they override what follows.
138
+ */
139
+ export function serverInstructions(platform) {
140
+ if (platform === "android")
141
+ return SERVER_INSTRUCTIONS;
142
+ if (platform === "webapp") {
143
+ return [
144
+ "PLATFORM: webapp (a local Slack webapp dev server, NOT an Android device over adb).",
145
+ "This overrides anything below that assumes a device:",
146
+ "- There is no adb and no device. Ignore adb instructions and device-connection advice.",
147
+ "- Radar is reachable over plain HTTP on localhost; there is no activation broadcast, so",
148
+ " enable cannot fail for a device-arming reason.",
149
+ "- NOT available on this platform, do not call them: screenshot, record_screen,",
150
+ " get_app_state, get_recent_logs, the database tools, the preferences tools, and",
151
+ " open_radar_dashboard. They return a clean 'not supported on platform webapp'.",
152
+ "- Available and behaving as documented below: ping, network calls, RTM events, clogs,",
153
+ " traces, search, query_session, wait_for_events, clear_buffers, capture_snapshot",
154
+ " (without a screenshot), and the feature-flag tools.",
155
+ "",
156
+ SERVER_INSTRUCTIONS,
157
+ ].join("\n");
158
+ }
159
+ return [
160
+ `PLATFORM: ${platform}. Anything below that assumes an Android device over adb may not apply.`,
161
+ "A tool with no implementation on this platform returns a clean 'not supported' error rather",
162
+ "than failing; treat that as a capability gap, not a fault to retry.",
163
+ "",
164
+ SERVER_INSTRUCTIONS,
165
+ ].join("\n");
166
+ }
129
167
  export const TOOL_DEFINITIONS = [
130
168
  {
131
169
  name: "ping",
@@ -1,4 +1,4 @@
1
- import type { DeviceInfo, DeviceTransport, LogResult } from "./transport.js";
1
+ import type { DeviceInfo, DeviceTransport, LogResult, ProcessState } from "./transport.js";
2
2
  /**
3
3
  * Resolve the adb binary. MCP servers spawned from GUI launchers (Spotlight,
4
4
  * Raycast, Dock) do not inherit the user's shell PATH, so a bare `adb` call
@@ -33,6 +33,8 @@ export declare function parseAdbDevicesOutput(raw: string): {
33
33
  }[];
34
34
  export declare class AndroidTransport implements DeviceTransport {
35
35
  readonly platform = "android";
36
+ readonly supportsLocalFileAccess = true;
37
+ readonly supportsDeviceDashboard = true;
36
38
  private portForwarded;
37
39
  private detectedUserId;
38
40
  private currentTimeoutMinutes;
@@ -85,5 +87,42 @@ export declare class AndroidTransport implements DeviceTransport {
85
87
  label: string;
86
88
  } | null;
87
89
  private pin;
90
+ /**
91
+ * Fresh `ps` probe for debug-build Slack processes. Reports what it could establish,
92
+ * not a yes/no: "stopped" only when the device answered and matched nothing, "unknown"
93
+ * when it could not answer at all.
94
+ *
95
+ * Two details carry that distinction, and both are load-bearing.
96
+ *
97
+ * The trailing `|| true` keeps a grep no-match from looking like a failure. Without it,
98
+ * grep's exit 1 arrives as an execSync throw, identical to a detached device, an
99
+ * unauthorized device, a missing adb and a timeout, so every one of them would read as
100
+ * "not running".
101
+ *
102
+ * Running `ps` through a command substitution and exiting 9 when it fails keeps the
103
+ * opposite mistake from happening. Piping `ps` straight into grep discards ps's own exit
104
+ * status, so a device whose `ps` rejects `-o USER,NAME` produced empty output and exit 0
105
+ * and read as a CONFIRMED stop, which is precisely the failure class this return type
106
+ * exists to rule out. Exit 9 throws instead, landing on "unknown".
107
+ *
108
+ * @param timeoutMs Ceiling for the adb round trip. Callers diagnosing an already-known
109
+ * failure should pass something short; see DIAGNOSTIC_PS_TIMEOUT_MS in web/server.ts.
110
+ */
111
+ private psDebugBuildProbe;
112
+ /** Raw `ps` lines for running debug-build Slack processes, or null if there are none. */
113
+ private psDebugBuildLine;
88
114
  private detectDebugBuildUser;
115
+ /**
116
+ * State of the debug-build Slack process, checked fresh via `ps` (independent of
117
+ * detectDebugBuildUser's cache, so a process that died after the cache was set still
118
+ * reads as stopped). Lets the enable flow tell a confirmed stop apart from a probe
119
+ * that could not reach the device, which is the difference between naming the fix and
120
+ * guessing at it.
121
+ *
122
+ * @param timeoutMs Optional ceiling for the adb round trip, defaulting to
123
+ * PS_PROBE_TIMEOUT_MS. A caller that is only explaining a failure it has already
124
+ * detected should pass something shorter, so the explanation cannot cost more than
125
+ * the operation it explains.
126
+ */
127
+ processState(timeoutMs?: number): ProcessState;
89
128
  }