@slack/radar-mcp 1.24.0 → 1.25.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
@@ -145,7 +145,7 @@ Radar starts **disabled** each session. All tools except `ping` return an error
145
145
  | `get_recent_traces` | Performance trace/span summaries: trace name, span name, duration. Filterable by name substring. |
146
146
  | `get_trace_detail` | Full trace/span detail for a specific trace, including tags. |
147
147
  | `get_switchboard_sessions` | Slackbot voice (switchboard) sessions the device still holds, newest first: `session_id`, `team_id`, `began_at`, `ended_at`, record and frame counts, the newest state and audio levels, `server_session_id` (the server's own name for the session, null until it names one; absent on an older build), `turns` (turn count, the newest response time and its clock, null before the first turn; absent on an older build), and `saved_turn_counts` (saved turns per outcome; absent on an older build means not counted, not zero). Ids restart with the app process. |
148
- | `get_switchboard_session` | One voice session's summary plus its records, oldest first: `state` transitions, control frames (`frame`) in and out, `player` stutter events, `phase` startup timings, `session` begin/end/ready (`ready` carries `server_session_id`), `levels` (batched mic/playback meter ticks), `turn` (one timed voice turn: `response_ms` and `clock`), and `saved_turn` (whether a spoken turn got saved to the DM: `outcome` (`applied`, `no_line`, `missing_field`, `other_session`) and `has_thread`; the summary's `saved_turn_counts` counts each outcome, and absent on an older device build means not counted, not zero). Narrow with `kind`; `limit` is how many of the newest records come back (default 50, max 2000 per request; the device may hold more, paged with before_id), filtered by kind first, so a kind page is the newest `limit` records of that kind. |
148
+ | `get_switchboard_session` | One voice session's summary plus its records, oldest first: `state` transitions, control frames (`frame`) in and out, `player` stutter events, `phase` startup timings, `session` begin/end/ready (`ready` carries `server_session_id`), `levels` (batched mic/playback meter ticks), `turn` (one timed voice turn: `response_ms` and `clock`), and `saved_turn` (whether a spoken turn got saved to the DM: `outcome` (`applied`, `no_line`, `missing_field`, `other_session`) and `has_thread`; the summary's `saved_turn_counts` counts each outcome, and absent on an older device build means not counted, not zero). Narrow with `kind`; `limit` is how many of the newest records come back (default 50, max 2000 per request; the device may hold more, paged with before_id), filtered by kind first, so a kind page is the newest `limit` records of that kind. `reconnect_try` (one voice reconnect try: `trigger` (`restart`, `drop`, `settings`), `try` and `outcome` (`ready`, `retry`, `refused`, `gave_up`)); a Reconnecting state's cause is its trigger, and the summary's `server_session_ids` lists every ready id. `card` (one move of a voice card the server is waiting on: `card_kind`, `event`, `by`, `card_id`; a card shown or carried with no later record was still up at the session's last record). |
149
149
  | `export_switchboard_session` | Write one voice session's summary and its records to a plain-text report under `~/.slack-radar/exports/`, permissions 0700/0600 like `capture_snapshot`. Pages the device, then merges in the live stream copy; the export can stop early (for example an old build, the 32 MB size cap, the page limit, or the device stopping answering), and the report notes say why anything is missing. An unknown id (404, unreachable, or too large to read) errors unless this process streamed the call live, then the report comes from the live stream copy alone, whichever process ran the export, since this MCP server and the web dashboard each keep their own. Defaults to newest when `id` is omitted; returns the file path and a summary. |
150
150
  | `wait_for_events` | Block until matching events arrive via SSE stream. Idle-timeout based, not polling. |
151
151
  | `search` | Full-text search across network, RTM, clog, and trace buffers. |
@@ -162,7 +162,7 @@ Radar starts **disabled** each session. All tools except `ping` return an error
162
162
  | `list_prefs` | List the app's on-device SharedPreferences files. Read-only. |
163
163
  | `get_prefs` | Read a preferences file's keys and values, optionally filtered to specific keys. |
164
164
  | `search_prefs` | Search preference keys and values across every file by a substring. |
165
- | `list_feature_flags` | List every feature flag with its latest effective value and override status; toggle rows also carry `session_enabled`, the flag's own value fixed for this session. Optionally filtered to just the overridden ones. Boolean toggles carry `enabled`; multi-variant experiments carry `type: "experiment"` and a `group_name` string (the effective variant, e.g. `"treatment_a"`) instead. |
165
+ | `list_feature_flags` | List every feature flag with its latest effective value and override status; toggle rows also carry `session_enabled`, the flag's own value the app runs now: the first-read value for a flag already read this session, or the value a read returns now for one not yet read. Optionally filtered to just the overridden ones. Boolean toggles carry `enabled`; multi-variant experiments carry `type: "experiment"` and a `group_name` string (the effective variant, e.g. `"treatment_a"`) instead. |
166
166
  | `search_feature_flags` | Case-insensitive substring search on feature flag names, against the same live list as `list_feature_flags`. Rows carry the same `type`/`group_name` fields for experiments. |
167
167
  | `get_feature_flag` | Look up one feature flag by its exact key. Returns one row per scope (authenticated/unauthenticated) and per signed-in org, since each workspace resolves its own value; pass `org_id` to narrow to one workspace. An experiment row carries `type: "experiment"` and its `group_name` variant rather than a boolean `enabled`. |
168
168
  | `run_test_case` | Replay a built-in or hand-written case. Pass `case`, optional `repeat` and `rate_per_second` (null for burst). Requires a debug build serving `test_runs`. |
@@ -270,7 +270,7 @@ What gets captured depends on the in-app server implementation. The MCP server i
270
270
  * **Test runs**: Made-up RTM replay frames sent to the app's handler. The device keeps the last ten run summaries, with settled counts and per-type timings.
271
271
  * **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.
272
272
  * **SharedPreferences** (`list_prefs`/`get_prefs`/`search_prefs`, and the Preferences tab): read directly off the device over `adb`, no local copy written. Files can contain feature flag overrides, cached team/org/channel IDs, and other app state.
273
- * **Feature flags** (`list_feature_flags`/`search_feature_flags`/`get_feature_flag`): read directly off the device over `adb`, no local copy written. Shows every flag's latest effective value, the flag's own value fixed for this session where the build reports it, and whether it is locally overridden.
273
+ * **Feature flags** (`list_feature_flags`/`search_feature_flags`/`get_feature_flag`): read directly off the device over `adb`, no local copy written. Shows every flag's latest effective value, the flag's own value the app runs now (the first-read value once a flag has been read this session) where the build reports it, and whether it is locally overridden.
274
274
 
275
275
  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.
276
276
 
@@ -8,7 +8,7 @@
8
8
  // Flags dashboard tab filters client-side after one full fetch. A device-side fix is the real
9
9
  // fix (tracked separately); this stays the correct behavior either way once that ships, since
10
10
  // filtering an already-correct list is a no-op.
11
- import { friendlyFeatureFlagError } from "../shared/feature-flags.js";
11
+ import { flagRestartNote, friendlyFeatureFlagError } from "../shared/feature-flags.js";
12
12
  /**
13
13
  * Shares one in-flight fetch of the flag list across the three tools (a model doing "list,
14
14
  * then search, then get" in one turn would otherwise pay a device round-trip per call).
@@ -57,18 +57,12 @@ function wellFormedRows(response) {
57
57
  .map(dropEmptyOrg)
58
58
  .map(withRestartNote);
59
59
  }
60
- // A flag the app read once keeps that value until restart, so `enabled` (latest or override) can
61
- // differ from what the app runs. Only two real booleans that differ earn a note: an absent or
62
- // non-boolean session_enabled is "not known", and saying nothing there is the honest answer.
63
60
  function withRestartNote(f) {
64
61
  // Dropped first so a device that sent its own note cannot pass it through: only this function
65
62
  // writes it, and only for a real mismatch.
66
63
  const { restart_note: _dropped, ...row } = f;
67
- const { enabled, session_enabled: session } = row;
68
- if (typeof enabled !== "boolean" || typeof session !== "boolean" || enabled === session)
69
- return row;
70
- const source = isOverridden(f) ? "override" : "fetched";
71
- return { ...row, restart_note: `app uses ${session} until restart, ${source} ${enabled}` };
64
+ const note = flagRestartNote(f);
65
+ return note === undefined ? row : { ...row, restart_note: note };
72
66
  }
73
67
  // An empty org id means the same thing as no org id, so it is dropped rather than treated as a
74
68
  // distinct org a caller could match or that an error message would render as a blank name. Same
package/dist/mcp/index.js CHANGED
@@ -50,18 +50,6 @@ import { buildOpenDashboardResult, readDashboardFingerprint } from "./stale-dash
50
50
  // pulled out to a pure function so the bin-name/subcommand rules are unit-testable.
51
51
  const sub = process.argv[2];
52
52
  const { wantsInstallApp, wantsWeb } = computeDispatch(process.argv[1], sub);
53
- // The background check RadarApp.swift spawns on every dock launch (see install-app.ts's
54
- // runSelfHealCheck). A sibling of install-app, not a third dispatch branch: same subcommand,
55
- // different entry point once inside.
56
- const wantsSelfHealCheck = wantsInstallApp && process.argv.includes("--self-heal-check");
57
- // What RadarApp.swift ACTUALLY spawns now (see install-app.ts's runSelfHealPrecheck): a safe
58
- // registry-version precheck that only falls through to --self-heal-check once a real upgrade is
59
- // confirmed. Checked before wantsSelfHealCheck below so the two flags stay mutually exclusive.
60
- const wantsSelfHealPrecheck = wantsInstallApp && process.argv.includes("--self-heal-precheck");
61
- // The two interactive halves of the app's Check for Updates... item: ask whether a newer build is
62
- // published, then install it. Each prints a single JSON line for the app to read.
63
- const wantsCheckUpdate = wantsInstallApp && process.argv.includes("--check-update");
64
- const wantsUpdateNow = wantsInstallApp && process.argv.includes("--update-now");
65
53
  // --- Web dashboard bridge (open_radar_dashboard) ---
66
54
  //
67
55
  // The MCP server and the web dashboard are separate processes. open_radar_dashboard
@@ -217,26 +205,8 @@ async function openDashboardSpec(device, spec, armed) {
217
205
  return { ...r.json, fingerprint };
218
206
  }
219
207
  if (wantsInstallApp) {
220
- if (wantsCheckUpdate) {
221
- const { checkForUpdate } = await import("../web/install-app.js");
222
- console.log(JSON.stringify(await checkForUpdate(process.env.RADAR_APP_VERSION)));
223
- }
224
- else if (wantsUpdateNow) {
225
- const { runUpdateNow } = await import("../web/install-app.js");
226
- await runUpdateNow();
227
- }
228
- else if (wantsSelfHealPrecheck) {
229
- const { runSelfHealPrecheck } = await import("../web/install-app.js");
230
- runSelfHealPrecheck();
231
- }
232
- else if (wantsSelfHealCheck) {
233
- const { runSelfHealCheck } = await import("../web/install-app.js");
234
- runSelfHealCheck();
235
- }
236
- else {
237
- const { runInstallApp } = await import("../web/install-app.js");
238
- runInstallApp();
239
- }
208
+ const { runInstallAppCli } = await import("../web/install-app-cli.js");
209
+ await runInstallAppCli(process.argv);
240
210
  }
241
211
  else if (wantsWeb) {
242
212
  const { startWebServer } = await import("../web/bin.js");
@@ -911,7 +881,7 @@ async function runMcpServer() {
911
881
  }
912
882
  }
913
883
  // --- MCP Server ---
914
- const server = new Server({ name: "slack-radar", version: "1.24.0" }, { capabilities: { tools: {} }, instructions: serverInstructions(device.platform) });
884
+ const server = new Server({ name: "slack-radar", version: "1.25.0" }, { capabilities: { tools: {} }, instructions: serverInstructions(device.platform) });
915
885
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
916
886
  tools: TOOL_DEFINITIONS,
917
887
  }));
package/dist/mcp/tools.js CHANGED
@@ -88,7 +88,7 @@ export function serverInstructions(platform) {
88
88
  ].join("\n");
89
89
  }
90
90
  // Shared by the three flag tools so their wording cannot drift apart.
91
- const SESSION_VALUE_NOTE = "Rows carry session_enabled (the flag's own value fixed for this session) and restart_note when it differs from `enabled`; a row where session_enabled or enabled is absent or not a boolean is not known, never a match; only when both are booleans does a missing restart_note mean they match.";
91
+ const SESSION_VALUE_NOTE = "Rows carry session_enabled (the flag's own value the app runs now: the first-read value for a flag already read this session, or the value a read returns now for one not yet read) and restart_note when it differs from `enabled`; a row where session_enabled or enabled is absent or not a boolean is not known, never a match; only when both are booleans does a missing restart_note mean they match.";
92
92
  export const TOOL_DEFINITIONS = [
93
93
  {
94
94
  name: "ping",
@@ -239,14 +239,14 @@ export const TOOL_DEFINITIONS = [
239
239
  },
240
240
  {
241
241
  name: "get_switchboard_session",
242
- description: "Get one voice session's summary plus the newest `limit` of its records (events), oldest first; events is only the page. Record kinds: state = connection, mic and speaking transitions (state_kind, from, to, cause); frame = control frames in and out (direction, frame_type, bytes), audio frames carry frame_type audio and a byte count, never the audio; player = playback events rearm, jitter_trim, read_stall and pre_ready_drop with gap_ms and bytes_queued; phase = startup phase durations (phase, duration_ms); session = begin and end, plus ready (server_session_id); levels = one meter-tick batch (started_at, sample_count, offsets_ms, mic/playback rms+peak arrays, 0..1); turn = response_ms (end of speech to first reply audio) and clock (no_card, resumed_from_tap, resumed_from_server_answer); saved_turn = outcome (applied, no_line, missing_field, other_session), has_thread. For saved_turn, no_line means no subtitle line still held the item and the turn is still kept; every turn other_session with a null server_session_id usually means session.ready named no session (a ready record with a null id) or never arrived (no ready record). Pass kind to narrow (player for stutter, state for mic and connection, phase for slow start, levels for meter history); the device filters by kind before taking the limit, so the page is the newest limit of that kind, while total_captured still counts every kind. This is a single page, not the whole session; for that use export_switchboard_session or query_session under source switchboard. An unknown id is a device 404.",
242
+ description: "Get one voice session's summary plus the newest `limit` of its records (events), oldest first; events is only the page. Record kinds: state = connection, mic and speaking transitions (state_kind, from, to, cause) with Server:<code> causes; frame = control frames in and out (direction, frame_type, bytes), audio frames carry frame_type audio and a byte count, never the audio; player = playback events rearm, jitter_trim, hold_refuse, reply_hold, reply_unhold, read_stall, pre_ready_drop with gap_ms, bytes_queued; phase = startup phase durations (phase, duration_ms); session = begin, end, ready (server_session_id), config (mic_encoding); levels = one meter-tick batch (started_at, sample_count, offsets_ms, mic/playback rms+peak arrays, 0..1); turn = response_ms (end of speech to first reply audio) and clock (no_card, resumed_from_tap, resumed_from_server_answer); saved_turn = outcome (applied, no_line, missing_field, other_session), has_thread; reconnect_try = trigger (restart, drop, settings), try, outcome (ready, retry, refused, gave_up, where try counts tries made and 0 means the budget was already spent); a Reconnecting state's cause is its trigger; card = card_kind (tool_approval, auth_prompt), event (shown, answered, refused, declined, closed, replaced, expired, cleared, carried), by (tap, server), card_id; a card shown or carried with no later record was still up at the session's last record. Summary server_session_ids lists ready ids. For saved_turn, no_line means no subtitle line still held the item and the turn is still kept; every turn other_session with a null server_session_id usually means session.ready named no session (a ready record with a null id) or never arrived (no ready record). Pass kind to narrow (player for stutter, state for mic and connection, phase for slow start, levels for meter history); the limit applies after the kind filter; total_captured counts every kind. This is a single page, not the whole session; for that use export_switchboard_session or query_session under source switchboard.",
243
243
  inputSchema: {
244
244
  type: "object",
245
245
  properties: {
246
246
  id: { type: "number", description: "The session_id from get_switchboard_sessions" },
247
247
  kind: {
248
248
  type: "string",
249
- enum: ["session", "state", "frame", "phase", "player", "levels", "turn", "saved_turn"],
249
+ enum: ["session", "state", "frame", "phase", "player", "levels", "turn", "saved_turn", "card", "reconnect_try"],
250
250
  description: "Only records of this kind (default: every kind)",
251
251
  },
252
252
  limit: {
@@ -415,13 +415,13 @@ export const TOOL_DEFINITIONS = [
415
415
  source: {
416
416
  type: "string",
417
417
  enum: [...SOURCES],
418
- description: "Which device stream to read. 'all' is a unified timeline mixing network, RTM, clog, trace, log, and switchboard. 'switchboard' is the Slackbot voice transport's own records (kind: session|state|frame|phase|player|levels|turn|saved_turn).",
418
+ description: "Which device stream to read. 'all' is a unified timeline mixing network, RTM, clog, trace, log, and switchboard. 'switchboard' is the Slackbot voice transport's own records (kind: session|state|frame|phase|player|levels|turn|saved_turn|card|reconnect_try).",
419
419
  },
420
420
  match: {
421
421
  type: "object",
422
422
  description: "Case-insensitive substring filter on SUMMARY fields, keyed by source. network: url/method/status_code; " +
423
423
  "rtm: event_type/direction/channel; clog: event_name; trace: trace_name/span_name; " +
424
- "log: tag/level/message/pid/package (iOS also: subsystem/process); switchboard: kind/session_id/direction/frame_type/state_kind/phase/event/clock/outcome. NEVER invent a field " +
424
+ "log: tag/level/message/pid/package (iOS also: subsystem/process); switchboard: kind/session_id/direction/frame_type/state_kind/phase/event/clock/outcome/trigger/card_kind/card_id. NEVER invent a field " +
425
425
  "(a match on an absent field silently matches nothing). For body text use bodyContains instead; for a log level floor use minLevel, not match.level.",
426
426
  },
427
427
  bodyContains: {
@@ -5,3 +5,14 @@
5
5
  * A 401 is not read here; both callers decide it from the HTTP status before this runs.
6
6
  */
7
7
  export declare function friendlyFeatureFlagError(error: unknown): string;
8
+ /**
9
+ * The one sentence for a flag whose latest value differs from what the app runs. A flag the app
10
+ * read once keeps that value until restart, so `enabled` (latest or override) can differ from
11
+ * `session_enabled`. Only two real booleans that differ earn a note: an absent or non-boolean
12
+ * session_enabled is "not known", and saying nothing there is the honest answer.
13
+ */
14
+ export declare function flagRestartNote(row: {
15
+ enabled?: unknown;
16
+ session_enabled?: unknown;
17
+ is_overridden?: unknown;
18
+ }): string | undefined;
@@ -1,7 +1,8 @@
1
- // Shared feature-flag response handling for the two callers that read the device's
2
- // /api/feature_flags route: the MCP tools (flags-tools.ts) and the web dashboard's Flags tab
3
- // (web/server.ts). Both need the same "Not Found" rewrite for builds that predate the
4
- // feature-flag Radar plugin, so it lives here once instead of drifting between two copies.
1
+ // Shared feature-flag response handling for the callers that read the device's
2
+ // /api/feature_flags route: the MCP tools (flags-tools.ts), the web server (web/server.ts) and the
3
+ // dashboard's Flags tab, which gets a mirrored copy of this file (scripts/mirror-shared.mjs). So it
4
+ // must stay import-free. The "Not Found" rewrite and the restart sentence live here once instead
5
+ // of drifting between copies.
5
6
  /**
6
7
  * Rewrite the device's raw "Not Found" into an actionable message. The route 404s as valid
7
8
  * JSON ({"error":"Not Found"}) on builds that predate the feature-flag Radar plugin, which is
@@ -16,3 +17,16 @@ export function friendlyFeatureFlagError(error) {
16
17
  }
17
18
  return error;
18
19
  }
20
+ /**
21
+ * The one sentence for a flag whose latest value differs from what the app runs. A flag the app
22
+ * read once keeps that value until restart, so `enabled` (latest or override) can differ from
23
+ * `session_enabled`. Only two real booleans that differ earn a note: an absent or non-boolean
24
+ * session_enabled is "not known", and saying nothing there is the honest answer.
25
+ */
26
+ export function flagRestartNote(row) {
27
+ const { enabled, session_enabled: session } = row;
28
+ if (typeof enabled !== "boolean" || typeof session !== "boolean" || enabled === session)
29
+ return undefined;
30
+ const source = row.is_overridden === true ? "override" : "fetched";
31
+ return `app uses ${session} until restart, ${source} ${enabled}`;
32
+ }
@@ -1,9 +1,21 @@
1
1
  export declare function capitalizeSwitchboardNote(note: string): string;
2
2
  export declare const CLIP_PEAK = 0.99;
3
+ export declare function micEncodingNote(label: string): string | null;
3
4
  export declare function switchboardClockLabel(clock: string): string;
5
+ export declare const SERVER_SESSION_ID_CAP = 8;
6
+ export declare function reconnectTriggerWord(trigger: string): string;
7
+ export declare function reconnectOutcomeWord(outcome: string): string;
8
+ export declare function reconnectTryLabel(trigger: string, outcome: string, n: number | null | undefined): string;
4
9
  export declare const SAVED_TURN_DROP_OUTCOMES: readonly string[];
5
10
  export declare const SAVED_TURN_KEPT_OUTCOMES: readonly string[];
6
11
  export declare const SAVED_TURN_OUTCOMES: readonly string[];
12
+ export declare function cardKindWord(kind: unknown): string;
13
+ export declare function cardLabel(kind: unknown, event: unknown, by: unknown): string;
14
+ export interface OpenCard {
15
+ kind: string;
16
+ id: string;
17
+ }
18
+ export declare function openCards(records: ReadonlyArray<Record<string, unknown>>): OpenCard[];
7
19
  export declare const SWITCHBOARD_CONTROL_CHARS: RegExp;
8
20
  export declare function stripSwitchboardControlChars(s: string): string;
9
21
  export declare function switchboardDeviceToken(name: string): string;
@@ -13,3 +25,10 @@ export declare function savedTurnCountEntries(counts: unknown): {
13
25
  outcome: string;
14
26
  count: number | null;
15
27
  }[];
28
+ export declare function serverEndedNormally(cause: unknown): boolean;
29
+ export declare function connectionEndedNormally(r: {
30
+ kind?: unknown;
31
+ state_kind?: unknown;
32
+ to?: unknown;
33
+ cause?: unknown;
34
+ }): boolean;
@@ -7,6 +7,16 @@ export function capitalizeSwitchboardNote(note) {
7
7
  // A peak at or above this is clipping. Shared here so the report and the dashboard sparkline use
8
8
  // the same threshold.
9
9
  export const CLIP_PEAK = 0.99;
10
+ // What the mic codec costs on the uplink, for the strip and the report header. The sizes are
11
+ // 24 kHz x 2 bytes x 0.2 s for pcm16, and the provider's own note for adts. An unknown label is
12
+ // the device's to add, so it has no note and prints as sent.
13
+ const MIC_ENCODING_NOTES = {
14
+ pcm16: "raw 24 kHz PCM, about 9.6 KB per 200 ms uplink audio frame",
15
+ adts: "AAC in ADTS frames, uplink audio frames about a tenth of pcm16",
16
+ };
17
+ export function micEncodingNote(label) {
18
+ return Object.hasOwn(MIC_ENCODING_NOTES, label) ? MIC_ENCODING_NOTES[label] : null;
19
+ }
10
20
  // A turn record's `clock` in words. Shared here so the feed row and the report read the same.
11
21
  // An unknown value is the device's to add, so it shows as sent rather than throwing.
12
22
  const TURN_CLOCK_LABELS = {
@@ -17,6 +27,27 @@ const TURN_CLOCK_LABELS = {
17
27
  export function switchboardClockLabel(clock) {
18
28
  return Object.hasOwn(TURN_CLOCK_LABELS, clock) ? TURN_CLOCK_LABELS[clock] : clock;
19
29
  }
30
+ // The most server session ids the device lists in a summary (server_session_ids). The host trims
31
+ // its own lists to the same count, so a summary built here matches one the device sent.
32
+ export const SERVER_SESSION_ID_CAP = 8;
33
+ // The panel's words for a reconnect's trigger and outcome. An unknown token is the device's to add,
34
+ // so it shows as sent rather than throwing; hasOwn keeps a name like "constructor" from finding an
35
+ // Object.prototype member.
36
+ const RECONNECT_TRIGGER_WORDS = { restart: "server restart", drop: "dropped connection", settings: "settings change" };
37
+ const RECONNECT_OUTCOME_WORDS = { ready: "back", retry: "failed, trying again", refused: "refused, call ended" };
38
+ export function reconnectTriggerWord(trigger) {
39
+ return Object.hasOwn(RECONNECT_TRIGGER_WORDS, trigger) ? RECONNECT_TRIGGER_WORDS[trigger] : trigger;
40
+ }
41
+ export function reconnectOutcomeWord(outcome) {
42
+ return Object.hasOwn(RECONNECT_OUTCOME_WORDS, outcome) ? RECONNECT_OUTCOME_WORDS[outcome] : outcome;
43
+ }
44
+ // A reconnect_try record in the export line's words ("drop try 2 ready", "drop gave_up after 2
45
+ // tries"), shared by the feed row and the report. A missing try number reads "?".
46
+ export function reconnectTryLabel(trigger, outcome, n) {
47
+ if (outcome === "gave_up")
48
+ return `${trigger} gave_up after ${n ?? "?"} ${n === 1 ? "try" : "tries"}`;
49
+ return `${trigger} try ${n ?? "?"} ${outcome}`;
50
+ }
20
51
  // The saved_turn outcomes, the one list the feed row, the panel and the report read. `applied`
21
52
  // (a subtitle line still held the frame's item) and `no_line` (no line held it any more, a normal
22
53
  // late save, still kept) keep the turn; the drop reasons lose it. The words are the row's and the
@@ -33,6 +64,40 @@ export const SAVED_TURN_DROP_OUTCOMES = Object.keys(SAVED_TURN_DROPS);
33
64
  export const SAVED_TURN_KEPT_OUTCOMES = Object.keys(SAVED_TURN_KEPT);
34
65
  // The four a revision 3 build always counts, in the order the panel and the report list them.
35
66
  export const SAVED_TURN_OUTCOMES = [...Object.keys(SAVED_TURN_KEPT), ...SAVED_TURN_DROP_OUTCOMES];
67
+ // A card record in words, shared by the feed row, the voice panel and the report. A kind or event
68
+ // the device adds later shows as sent, and a missing field reads "?", so nothing throws.
69
+ const CARD_KIND_WORDS = { tool_approval: "tool approval", auth_prompt: "connect prompt" };
70
+ // An event in this set takes the card down; "shown" and "carried" put it up.
71
+ const CARD_CLOSING_EVENTS = ["answered", "refused", "declined", "closed", "replaced", "expired", "cleared"];
72
+ const CARD_OPENING_EVENTS = ["shown", "carried"];
73
+ export function cardKindWord(kind) {
74
+ if (typeof kind !== "string" || !kind)
75
+ return "?";
76
+ return Object.hasOwn(CARD_KIND_WORDS, kind) ? CARD_KIND_WORDS[kind] : kind;
77
+ }
78
+ export function cardLabel(kind, event, by) {
79
+ const eventWord = typeof event === "string" && event ? event : "?";
80
+ return `${cardKindWord(kind)} ${eventWord}${typeof by === "string" && by ? ` by ${by}` : ""}`;
81
+ }
82
+ // The cards still up after these records, in the order they came up. Shown or carried puts a card
83
+ // up (a re-sent one keeps its place), the closing events take it down, and an event it does not
84
+ // know changes nothing, so a newer device build cannot make a card look gone.
85
+ export function openCards(records) {
86
+ const open = new Map();
87
+ for (const r of records) {
88
+ if (r.kind !== "card" || typeof r.card_kind !== "string" || typeof r.card_id !== "string" || typeof r.event !== "string")
89
+ continue;
90
+ const key = `${r.card_kind}\u0000${r.card_id}`;
91
+ if (CARD_OPENING_EVENTS.includes(r.event)) {
92
+ if (!open.has(key))
93
+ open.set(key, { kind: r.card_kind, id: r.card_id });
94
+ }
95
+ else if (CARD_CLOSING_EVENTS.includes(r.event)) {
96
+ open.delete(key);
97
+ }
98
+ }
99
+ return [...open.values()];
100
+ }
36
101
  // Code points a free-form device string could use to fake a line break, a report boundary, or a
37
102
  // hidden direction override: controls, bidi marks, zero-width characters, U+2028/2029 (a newline
38
103
  // to a browser), and the BOM. Here rather than in the report so the panel strips the same set.
@@ -90,3 +155,14 @@ export function savedTurnCountEntries(counts) {
90
155
  out.push({ outcome: k, count: read(k) });
91
156
  return out;
92
157
  }
158
+ // The server endings that are a normal end, not a fault. Matches the device's `endsNormally`. An
159
+ // older device build sends plain "Server" for these too, and that stays an error since nothing
160
+ // says which ending it was.
161
+ const NORMAL_SERVER_ENDINGS = ["Server:live_session_limit", "Server:session_limit", "Server:live_idle_timeout", "Server:live_call_ended"];
162
+ export function serverEndedNormally(cause) {
163
+ return typeof cause === "string" && NORMAL_SERVER_ENDINGS.includes(cause);
164
+ }
165
+ // A connection state record that moved to Failed on a normal server ending.
166
+ export function connectionEndedNormally(r) {
167
+ return r.kind === "state" && r.state_kind === "connection" && r.to === "Failed" && serverEndedNormally(r.cause);
168
+ }
@@ -1,7 +1,7 @@
1
1
  // Pure text builder for one switchboard (Slackbot voice) session report. Input is read
2
2
  // defensively: it crossed the device wire, and one odd or older-build field must never throw.
3
3
  import { SWITCHBOARD_DEVICE_RING_CAP, SWITCHBOARD_EXPORT_SAFETY_CAP_BYTES, SWITCHBOARD_EXPORT_WALK_DEADLINE_MS, switchboardWalkStopNote, } from "./switchboard.js";
4
- import { CLIP_PEAK, SAVED_TURN_OUTCOMES, savedTurnCountEntries, savedTurnLabel, stripSwitchboardControlChars, switchboardClockLabel, switchboardDeviceToken, } from "./switchboard-note.js";
4
+ import { CLIP_PEAK, micEncodingNote, openCards, SAVED_TURN_OUTCOMES, reconnectTryLabel, savedTurnCountEntries, savedTurnLabel, serverEndedNormally, stripSwitchboardControlChars, switchboardClockLabel, switchboardDeviceToken, } from "./switchboard-note.js";
5
5
  const refusedPhrase = (sendsToken) => sendsToken ? "the device refused this Radar session's token" : "the device refused the request (HTTP 401)";
6
6
  const againPhrase = (surface) => surface === "dashboard" ? "press Reconnect and export again for the device copy" : "run /radar-enable and export again for the device copy";
7
7
  // Re-exported so the existing callers keep their import; the set itself lives in the note.
@@ -90,14 +90,17 @@ function recordLine(r) {
90
90
  case "session": {
91
91
  const event = str(r.event) ?? "?";
92
92
  const serverId = str(r.server_session_id);
93
- return `${head} ${event}${serverId ? ` server_session_id=${serverId}` : ""}`;
93
+ const micEncoding = str(r.mic_encoding);
94
+ return `${head} ${event}${serverId ? ` server_session_id=${serverId}` : ""}${micEncoding ? ` mic_encoding=${micEncoding}` : ""}`;
94
95
  }
95
96
  case "state": {
96
97
  const stateKind = str(r.state_kind) ?? "?";
97
98
  const from = str(r.from) ?? "?";
98
99
  const to = str(r.to) ?? "?";
99
100
  const cause = str(r.cause);
100
- return `${head} ${stateKind} ${from} -> ${to}${cause ? ` (${cause})` : ""}`;
101
+ // A goodbye or a limit still reads Failed on the wire; say it was a normal end.
102
+ const normal = stateKind === "connection" && to === "Failed" && serverEndedNormally(cause) ? ", a normal end" : "";
103
+ return `${head} ${stateKind} ${from} -> ${to}${cause ? ` (${cause}${normal})` : ""}`;
101
104
  }
102
105
  case "frame": {
103
106
  const direction = str(r.direction) ?? "?";
@@ -144,6 +147,16 @@ function recordLine(r) {
144
147
  const clock = str(r.clock);
145
148
  return `${head} ${fmtMs(r.response_ms)}, ${clock ? reportClockLabel(clock) : "?"}`;
146
149
  }
150
+ case "reconnect_try": {
151
+ const trigger = str(r.trigger) ?? "?";
152
+ const outcome = str(r.outcome) ?? "?";
153
+ return `${head} ${reconnectTryLabel(trigger, outcome, num(r.try))}`;
154
+ }
155
+ case "card": {
156
+ // The wire labels, not the panel's words, so a reader can grep the export for them.
157
+ const by = str(r.by);
158
+ return `${head} ${str(r.card_kind) ?? "?"} ${str(r.event) ?? "?"}${by ? ` by ${by}` : ""} card_id=${str(r.card_id) ?? "?"}`;
159
+ }
147
160
  case "saved_turn": {
148
161
  // Raw, not stripped: known or unknown is decided on what the device sent, so "applied" plus a
149
162
  // hidden character is an unknown outcome, quoted, and never "saved, thread".
@@ -220,6 +233,9 @@ export function buildSwitchboardReport(assembly, now = Date.now()) {
220
233
  const deviceOnlyCount = deviceEventCount !== null ? deviceEventCount : events.length - hostStreamCount;
221
234
  const streamedDuringExport = deviceEventCount !== null ? Math.max(0, events.length - hostStreamCount - deviceEventCount) : 0;
222
235
  const fetchIncomplete = deviceOnlyCount > 0 && totalCaptured !== null && deviceOnlyCount < totalCaptured;
236
+ // One completeness rule for the cards_open line and the stream-copy note. A short fetch the live
237
+ // stream copy filled is not missing records, and the stream-copy note says so.
238
+ const holdsEveryRecord = !startMissing && gapCount === 0 && (!fetchIncomplete || hostStreamCount > 0);
223
239
  // Suggestive, not proof, that the ring lost the start, so it only earns the soft phrasing. The
224
240
  // oldest-timestamp signal counts only when the walk reached the end of the device's range.
225
241
  const oldestTimestampIsRingEvidence = walkStopReason === null || walkStopReason === "done";
@@ -231,6 +247,26 @@ export function buildSwitchboardReport(assembly, now = Date.now()) {
231
247
  // live device connection to promise one.
232
248
  const serverSessionIdText = serverSessionId ?? (!deviceGone && live && hasServerSessionIdKey ? "pending" : "(not reported)");
233
249
  lines.push(`server_session_id: ${serverSessionIdText}`);
250
+ // A reconnect can bring a new server id; older builds send no list, so they print as before.
251
+ const allServerIds = Array.isArray(d.server_session_ids) ? d.server_session_ids.map(str).filter((x) => x !== null) : [];
252
+ if (allServerIds.length >= 2)
253
+ lines.push(`server_session_ids: ${allServerIds.join(", ")}`);
254
+ // The summary's label outlives the config record's eviction, and a host-only report already
255
+ // gets it from hostOnlySwitchboardDetail. A build that sends no label prints no line.
256
+ const micEncoding = str(d.mic_encoding);
257
+ if (micEncoding !== null) {
258
+ const micNote = micEncodingNote(micEncoding);
259
+ lines.push(`mic_encoding: ${micEncoding}${micNote ? ` (${micNote})` : ""}`);
260
+ }
261
+ // Only rows with a card record get the line; none printed means no card record in these rows, not
262
+ // that no card is up.
263
+ if (events.some((e) => e.kind === "card")) {
264
+ const up = openCards(events).map((c) => `${stripSwitchboardControlChars(c.kind)} ${stripSwitchboardControlChars(c.id)}`);
265
+ // A card shown in a record this report lacks looks closed or never up, so say so.
266
+ const partial = !holdsEveryRecord;
267
+ const note = partial ? "shown or carried with no later record, among the records this report holds" : "shown or carried with no later record";
268
+ lines.push(`cards_open: ${up.length ? `${up.join(", ")} (${note})` : partial ? "none seen (the report does not hold every record)" : "none"}`);
269
+ }
234
270
  lines.push(`team_id: ${teamId ?? "(none)"}`);
235
271
  lines.push(`began_at: ${isoOrRaw(beganAt)}`);
236
272
  // A host-only report with no end record is not evidence the call is still live.
@@ -285,7 +321,7 @@ export function buildSwitchboardReport(assembly, now = Date.now()) {
285
321
  }
286
322
  lines.push(`exported_at: ${isoOrRaw(now)}`);
287
323
  // A host copy with a mid-call gap did not really supply the older records.
288
- const hostFilledStart = !startMissing && hostStreamCount > 0 && gapCount === 0;
324
+ const hostFilledStart = holdsEveryRecord && hostStreamCount > 0;
289
325
  const hostWalkNote = hostFilledWalkNoteText(walkStopReason, hostFilledStart, refused, again);
290
326
  // "up to": ids come from one counter shared across sessions, so gapCount is an upper bound.
291
327
  const gapNote = (cause) => `the report reaches the call's start, but up to ${gapCount} record${gapCount === 1 ? "" : "s"} in the middle may be missing: ${cause}`;
@@ -3,7 +3,7 @@ export declare const SWITCHBOARD_KIND = "switchboard";
3
3
  export declare const SWITCHBOARD_BACKFILL_SESSIONS = 3;
4
4
  export declare const SWITCHBOARD_BACKFILL_DEADLINE_MS: number;
5
5
  export declare function switchboardListPath(): string;
6
- export declare const SWITCHBOARD_KINDS: readonly ["session", "state", "frame", "phase", "player", "levels", "turn", "saved_turn"];
6
+ export declare const SWITCHBOARD_KINDS: readonly ["session", "state", "frame", "phase", "player", "levels", "turn", "saved_turn", "card", "reconnect_try"];
7
7
  export type SwitchboardKind = (typeof SWITCHBOARD_KINDS)[number];
8
8
  export declare function switchboardSessionPath(sessionId: number, limit: number, kind?: SwitchboardKind, beforeId?: number): string;
9
9
  export declare function newestSwitchboardSessionIds(list: unknown): number[];
@@ -7,6 +7,7 @@
7
7
  // is absent, so the limit is forwarded per session or a talkative session replays as its last few
8
8
  // seconds).
9
9
  import { lastHeaderBuildFailure, unauthorizedMessageFor, } from "./radar-token.js";
10
+ import { SERVER_SESSION_ID_CAP } from "./switchboard-note.js";
10
11
  export const SWITCHBOARD_KIND = "switchboard";
11
12
  // Sessions replayed per backfill. Bounds the round trips (one list plus one fetch per session).
12
13
  export const SWITCHBOARD_BACKFILL_SESSIONS = 3;
@@ -20,7 +21,7 @@ export function switchboardListPath() {
20
21
  }
21
22
  // The record kinds the plugin emits, the closed set a `kind` query may name. Shared so the path
22
23
  // builder below takes the type and never sees raw input.
23
- export const SWITCHBOARD_KINDS = ["session", "state", "frame", "phase", "player", "levels", "turn", "saved_turn"];
24
+ export const SWITCHBOARD_KINDS = ["session", "state", "frame", "phase", "player", "levels", "turn", "saved_turn", "card", "reconnect_try"];
24
25
  // beforeId asks for records with id < beforeId. An older device ignores it and repeats the newest
25
26
  // page; walkSwitchboardExportPages detects that.
26
27
  export function switchboardSessionPath(sessionId, limit, kind, beforeId) {
@@ -382,12 +383,19 @@ export function hostOnlySwitchboardDetail(sessionId, hostRecords) {
382
383
  : null;
383
384
  let teamId = null;
384
385
  let serverSessionId = null;
386
+ const serverSessionIds = [];
385
387
  let endedAt = null;
388
+ let micEncoding = null;
386
389
  for (const e of records) {
387
390
  if (teamId === null && typeof e.team_id === "string")
388
391
  teamId = e.team_id;
389
- if (serverSessionId === null && e.kind === "session" && e.event === "ready" && typeof e.server_session_id === "string")
392
+ if (e.kind === "session" && e.event === "ready" && typeof e.server_session_id === "string") {
390
393
  serverSessionId = e.server_session_id;
394
+ if (!serverSessionIds.includes(e.server_session_id))
395
+ serverSessionIds.push(e.server_session_id);
396
+ }
397
+ if (e.kind === "session" && e.event === "config" && typeof e.mic_encoding === "string")
398
+ micEncoding = e.mic_encoding;
391
399
  if (endedAt === null && e.kind === "session" && e.event === "end" && typeof e.timestamp === "number" && Number.isFinite(e.timestamp))
392
400
  endedAt = e.timestamp;
393
401
  }
@@ -402,6 +410,10 @@ export function hostOnlySwitchboardDetail(sessionId, hostRecords) {
402
410
  };
403
411
  if (serverSessionId !== null)
404
412
  detail.server_session_id = serverSessionId;
413
+ if (serverSessionIds.length > 0)
414
+ detail.server_session_ids = serverSessionIds.slice(-SERVER_SESSION_ID_CAP);
415
+ if (micEncoding !== null)
416
+ detail.mic_encoding = micEncoding;
405
417
  return detail;
406
418
  }
407
419
  export function oldestSwitchboardTimestamp(events) {
@@ -57,12 +57,14 @@ export interface SwitchboardSessionSummary {
57
57
  total_captured: number;
58
58
  levels: SwitchboardLevels | null;
59
59
  server_session_id?: string | null;
60
+ server_session_ids?: string[];
60
61
  turns?: {
61
62
  count: number;
62
63
  last_response_ms: number;
63
64
  last_clock: string;
64
65
  } | null;
65
66
  saved_turn_counts?: Record<string, number>;
67
+ mic_encoding?: string | null;
66
68
  }
67
69
  export interface SwitchboardSessionDetail extends SwitchboardSessionSummary {
68
70
  events: Record<string, unknown>[];
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export declare function runInstallAppCli(argv: string[]): Promise<void>;
@@ -0,0 +1,60 @@
1
+ #!/usr/bin/env node
2
+ // The install-app flag dispatch, pulled out of mcp/index.ts so the app can spawn it without the
3
+ // MCP SDK. Imports only node builtins and ./install-app.js (which imports only from ../shared),
4
+ // so a copy of dist/ plus package.json is enough to run it.
5
+ //
6
+ // The argv shape is what RadarApp.swift spawns: `<bin> install-app [flag]`.
7
+ import { realpathSync } from "fs";
8
+ import { fileURLToPath } from "url";
9
+ export async function runInstallAppCli(argv) {
10
+ // The background rebuild RadarApp.swift runs once the precheck confirms a newer version (see
11
+ // install-app.ts's runSelfHealCheck).
12
+ const wantsSelfHealCheck = argv.includes("--self-heal-check");
13
+ // What RadarApp.swift ACTUALLY spawns now (see install-app.ts's runSelfHealPrecheck): a safe
14
+ // registry-version precheck that only falls through to --self-heal-check once a real upgrade is
15
+ // confirmed. Checked before wantsSelfHealCheck below so the two flags stay mutually exclusive.
16
+ const wantsSelfHealPrecheck = argv.includes("--self-heal-precheck");
17
+ // The two interactive halves of the app's Check for Updates... item: ask whether a newer build is
18
+ // published, then install it. Each prints a single JSON line for the app to read.
19
+ const wantsCheckUpdate = argv.includes("--check-update");
20
+ const wantsUpdateNow = argv.includes("--update-now");
21
+ if (wantsCheckUpdate) {
22
+ const { checkForUpdate } = await import("./install-app.js");
23
+ console.log(JSON.stringify(await checkForUpdate(process.env.RADAR_APP_VERSION)));
24
+ }
25
+ else if (wantsUpdateNow) {
26
+ const { runUpdateNow } = await import("./install-app.js");
27
+ await runUpdateNow();
28
+ }
29
+ else if (wantsSelfHealPrecheck) {
30
+ const { runSelfHealPrecheck } = await import("./install-app.js");
31
+ runSelfHealPrecheck();
32
+ }
33
+ else if (wantsSelfHealCheck) {
34
+ const { runSelfHealCheck } = await import("./install-app.js");
35
+ runSelfHealCheck();
36
+ }
37
+ else {
38
+ const { runInstallApp } = await import("./install-app.js");
39
+ runInstallApp();
40
+ }
41
+ }
42
+ // Same bin-vs-import test as bin.ts: realpathSync resolves an npm bin symlink to the real path.
43
+ function invokedDirectly() {
44
+ const arg = process.argv[1];
45
+ if (!arg)
46
+ return false;
47
+ try {
48
+ return fileURLToPath(import.meta.url) === realpathSync(arg);
49
+ }
50
+ catch {
51
+ return false;
52
+ }
53
+ }
54
+ if (invokedDirectly()) {
55
+ if (process.argv[2] !== "install-app") {
56
+ console.error("usage: install-app-cli install-app [--check-update|--update-now|--self-heal-precheck|--self-heal-check]");
57
+ process.exit(1);
58
+ }
59
+ await runInstallAppCli(process.argv);
60
+ }