@slack/radar-mcp 1.7.0 → 1.9.0

package/dist/mcp/session-query.d.ts

@@ -0,0 +1,57 @@
+import type { ParsedSSE } from "../shared/stream.js";
+export interface SessionQueryFilter {
+    source?: string;
+    id?: number;
+    cursor?: string;
+    url_filter?: string;
+    status_code?: number;
+    event_type?: string;
+    channel?: string;
+    name?: string;
+    text?: string;
+    limit?: number;
+    byte_cap?: number;
+}
+export interface SessionQueryResult {
+    frames: ParsedSSE[];
+    count: number;
+    truncated: boolean;
+    cursor?: string;
+    note?: string;
+}
+export declare function clampByteCap(byteCap: number | undefined): number;
+export declare function toNum(v: unknown): number | undefined;
+export declare function detailTypeFor(source: string): `${string}_detail`;
+export declare function baseSourceOf(type: string): string | null;
+export interface DetailSelection {
+    frame: ParsedSSE;
+    isDetail: boolean;
+}
+export declare function selectById(frames: ParsedSSE[], id: number, source?: string): DetailSelection | null;
+/**
+ * Shape parsed spool frames into a byte-capped result.
+ *
+ * frames arrive oldest-first (spool append order). Two paths:
+ *
+ * 1. id-bypass: when `id` is set (optionally scoped by `source`), return the single whole matching
+ *    record regardless of age or byte budget. This is the detail-by-id path; a caller asking for a
+ *    specific record wants that record, not the newest N.
+ *
+ * 2. newest-first packing: filter, walk newest-first, and accumulate serialized bytes; stop BEFORE
+ *    a frame would push the running size over the cap. `truncated` is true when the cap or `limit`
+ *    left older matches unreturned; only then is `cursor` (the "<epoch>:<seq>" token for the oldest
+ *    frame returned) set, so a caller pages older by passing it back as `cursor`. Returned frames
+ *    stay newest-first. Paging keys off append position, not device id: each source has its own id
+ *    namespace so ids overlap and are not globally ordered, but append order is one monotonic key
+ *    across every source, so a cursor pages the whole session cleanly.
+ *
+ * `epoch` identifies the spool file the caller read. It is baked into every emitted cursor and
+ * checked on every incoming one: a cursor whose epoch does not match came from a rotated or
+ * re-enabled spool (whose seq indexes a different file), so it is rejected with a note rather than
+ * applied to the wrong file. querySession stays PURE: the caller derives epoch from the spool path
+ * and passes it in; this function reads no fs.
+ *
+ * A caller cannot exceed the hard cap: clampByteCap bounds byte_cap to the shared response budget.
+ * An empty frame list returns an empty result with a note so a missing spool reads clearly.
+ */
+export declare function querySession(frames: ParsedSSE[], rawFilter: SessionQueryFilter, epoch: string): SessionQueryResult;

package/dist/mcp/session-query.js

@@ -0,0 +1,327 @@
+// Pure shaper for the query_session tool, split out of the index.ts handler (like logs-result.ts
+// and api-paths.ts) so it can be unit-tested without importing index.ts. No fs, no device, no
+// index import: it takes already-parsed spool frames plus a filter and returns a byte-capped
+// result. The reader (event-spool.readSpool) and the dispatch (index.ts) live elsewhere.
+//
+// The type tag is OPAQUE. A frame is matched by `frame.type === filter.source` as a plain string
+// compare; this module never enumerates or switches on the known source names, so a future plugin
+// source matches for free. Do not add a source name switch here.
+import { MAX_RADAR_RESPONSE_BYTES } from "../shared/constants.js";
+// Clamp the requested output ceiling. Default AND hard cap are the shared response budget: a
+// caller cannot raise byte_cap above it, so a query can never flood the model context. Mirrors
+// clampLogLimit's shape (default when unset, hard ceiling always).
+export function clampByteCap(byteCap) {
+    const cap = byteCap && byteCap > 0 ? byteCap : MAX_RADAR_RESPONSE_BYTES;
+    return Math.min(cap, MAX_RADAR_RESPONSE_BYTES);
+}
+// Read a frame's numeric id if it carries one. Frames are objects of unknown shape; the summary
+// frames and clog detail frames all carry `event.id` today, but treat its absence as "no id".
+function frameId(frame) {
+    const event = frame?.event;
+    if (typeof event !== "object" || event === null)
+        return undefined;
+    const raw = event.id;
+    return typeof raw === "number" ? raw : undefined;
+}
+// Coerce a filter value that should be numeric. The MCP SDK does not enforce the input schema, so
+// id / status_code can arrive as a digit string; accept a clean digit string and treat anything
+// else as unset, mirroring detailPath in api-paths.ts. Without this, id:"2" strict-compares against
+// a numeric id and silently returns nothing. cursor is a string token, not a number, so it does not
+// pass through here.
+export function toNum(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    if (typeof v === "string" && /^\d+$/.test(v.trim()))
+        return Number(v.trim());
+    return undefined;
+}
+// Parse an opaque "<epoch>:<seq>" cursor token. epoch is everything before the first colon (it may
+// hold characters, so split once, not by every colon) and must be non-empty; a real token is minted
+// against a spool file whose <ts> epoch is never empty. seq is the rest and must be all digits. A
+// bare number, empty string, empty epoch, or a non-numeric seq returns undefined so the caller never
+// applies a guessed seq. This never throws.
+function parseCursor(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const colon = v.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    const epoch = v.slice(0, colon);
+    const seqStr = v.slice(colon + 1);
+    if (!/^\d+$/.test(seqStr))
+        return undefined;
+    return { epoch, seq: Number(seqStr) };
+}
+// The spool tag for a pulled body of a summary source. A `network` summary's pulled detail is
+// stored under `network_detail`, and so on. Pure string building; the impure layer (index.ts)
+// owns the device pull and the write-back, this only names the tag both sides agree on.
+export function detailTypeFor(source) {
+    return `${source}_detail`;
+}
+// The base source a detail tag came from, or null if the tag is not a detail tag. Inverse of
+// detailTypeFor. `network_detail` -> `network`; a plain `network` -> null.
+export function baseSourceOf(type) {
+    return type.endsWith("_detail") ? type.slice(0, -"_detail".length) : null;
+}
+// The base source a frame belongs to: a detail tag folds to its base, any other tag is itself. So a
+// `network` summary and its `network_detail` share base `network`, but a `clog` stays `clog`.
+function baseSourceOfFrame(frame) {
+    return baseSourceOf(frame.type) ?? frame.type;
+}
+// After a lazy pull the spool holds BOTH a summary and its `<source>_detail` for the same id, so an
+// unfiltered list read would show that id twice. Collapse each (base source, id) pair to one frame,
+// preferring the detail (the fuller record). A frame with no numeric id, or whose (base, id) pair
+// appears once, passes through untouched. Order is preserved so the newest-first walk is unaffected.
+// Pure: it only reshapes the frame list. The dedup is by base source via baseSourceOfFrame, never a
+// hard-coded source-name switch, so a future plugin source dedups for free.
+function dedupSummaryDetail(frames) {
+    // First pass: for each (base source, id) key, remember the LAST frame that carried it. Append
+    // order means the last write wins, so a reused id resolves to its freshest record, not a stale
+    // detail. Mirrors selectById's recency rule.
+    const winner = new Map();
+    for (const frame of frames) {
+        const id = frameId(frame);
+        if (id === undefined)
+            continue;
+        winner.set(`${baseSourceOfFrame(frame)}\u0000${id}`, frame);
+    }
+    // Second pass: keep no-id frames as-is; for id-bearing frames emit only the winner, at the
+    // position of the key's FIRST appearance so the newest-first walk order stays stable.
+    const emitted = new Set();
+    const out = [];
+    for (const frame of frames) {
+        const id = frameId(frame);
+        if (id === undefined) {
+            out.push(frame);
+            continue;
+        }
+        const key = `${baseSourceOfFrame(frame)}\u0000${id}`;
+        if (emitted.has(key))
+            continue;
+        emitted.add(key);
+        out.push(winner.get(key));
+    }
+    return out;
+}
+export function selectById(frames, id, source) {
+    // Return the LAST-appended in-scope frame for the id. The spool is append-ordered, so the newest
+    // record wins: in the normal case a detail is appended after its summary and still wins, and after
+    // an app restart reuses an id (the device id counter is per-process) the newer summary wins instead
+    // of a stale cached detail shadowing it. A detail frame is served whole (isDetail true); a plain
+    // summary/clog frame is served as a summary (isDetail false).
+    let picked;
+    let pickedIsDetail = false;
+    for (const frame of frames) {
+        if (frameId(frame) !== id)
+            continue;
+        const base = baseSourceOf(frame.type);
+        if (base !== null) {
+            // A stored detail frame. In scope when unscoped, or its base equals the requested source.
+            if (source === undefined || base === source) {
+                picked = frame;
+                pickedIsDetail = true;
+            }
+            continue;
+        }
+        // A plain (summary or clog) frame. In scope when unscoped or its type equals the source.
+        if (source !== undefined && frame.type !== source)
+            continue;
+        picked = frame;
+        pickedIsDetail = false;
+    }
+    return picked ? { frame: picked, isDetail: pickedIsDetail } : null;
+}
+// Case-insensitive substring test that tolerates a non-string field value.
+function includesCI(haystack, needle) {
+    if (typeof haystack !== "string")
+        return false;
+    return haystack.toLowerCase().includes(needle.toLowerCase());
+}
+// Does one frame pass every SET filter field? Unset fields do not constrain. `source` is the
+// opaque tag compare. The field filters read whatever the frame's event carries; a filter on a
+// field a given frame lacks simply fails to match that frame (never throws).
+function matchesFilter(frame, f) {
+    // A non-object frame (should not occur post-readSpool guard, but querySession is also called
+    // directly) carries no fields to match, so it passes only an all-unset filter's other checks.
+    if (typeof frame !== "object" || frame === null)
+        return false;
+    if (f.source !== undefined && frame.type !== f.source)
+        return false;
+    // A malformed frame (event missing or not an object) is not a real record: drop it so it never
+    // appears in results and the field reads below never throw.
+    const ev = frame?.event;
+    if (typeof ev !== "object" || ev === null)
+        return false;
+    const e = ev;
+    if (f.url_filter !== undefined && !includesCI(e.url, f.url_filter))
+        return false;
+    if (f.status_code !== undefined && e.status_code !== f.status_code)
+        return false;
+    if (f.event_type !== undefined && e.event_type !== f.event_type)
+        return false;
+    if (f.channel !== undefined && e.channel !== f.channel)
+        return false;
+    if (f.name !== undefined && !includesCI(e.name, f.name))
+        return false;
+    // `text` searches the whole serialized frame, so it catches content in any field including the
+    // clog detail payload, not just the named summary fields above.
+    if (f.text !== undefined && !JSON.stringify(frame).toLowerCase().includes(f.text.toLowerCase())) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Shape parsed spool frames into a byte-capped result.
+ *
+ * frames arrive oldest-first (spool append order). Two paths:
+ *
+ * 1. id-bypass: when `id` is set (optionally scoped by `source`), return the single whole matching
+ *    record regardless of age or byte budget. This is the detail-by-id path; a caller asking for a
+ *    specific record wants that record, not the newest N.
+ *
+ * 2. newest-first packing: filter, walk newest-first, and accumulate serialized bytes; stop BEFORE
+ *    a frame would push the running size over the cap. `truncated` is true when the cap or `limit`
+ *    left older matches unreturned; only then is `cursor` (the "<epoch>:<seq>" token for the oldest
+ *    frame returned) set, so a caller pages older by passing it back as `cursor`. Returned frames
+ *    stay newest-first. Paging keys off append position, not device id: each source has its own id
+ *    namespace so ids overlap and are not globally ordered, but append order is one monotonic key
+ *    across every source, so a cursor pages the whole session cleanly.
+ *
+ * `epoch` identifies the spool file the caller read. It is baked into every emitted cursor and
+ * checked on every incoming one: a cursor whose epoch does not match came from a rotated or
+ * re-enabled spool (whose seq indexes a different file), so it is rejected with a note rather than
+ * applied to the wrong file. querySession stays PURE: the caller derives epoch from the spool path
+ * and passes it in; this function reads no fs.
+ *
+ * A caller cannot exceed the hard cap: clampByteCap bounds byte_cap to the shared response budget.
+ * An empty frame list returns an empty result with a note so a missing spool reads clearly.
+ */
+export function querySession(frames, rawFilter, epoch) {
+    if (frames.length === 0) {
+        return {
+            frames: [],
+            count: 0,
+            truncated: false,
+            note: "no session spool; is radar enabled?",
+        };
+    }
+    // Normalize numeric fields once so a digit-string arg (the SDK does not enforce the schema)
+    // matches; an unparseable value becomes unset rather than a silent no-match. cursor is a string
+    // token parsed separately below, not coerced here.
+    const filter = {
+        ...rawFilter,
+        id: toNum(rawFilter.id),
+        status_code: toNum(rawFilter.status_code),
+    };
+    // id-bypass, PURE mirror of the id path. In production handleQuerySession resolves an id read via
+    // resolveDetailById (which does the lazy device pull) before this function is reached, so this
+    // branch does not run for the MCP tool. It stays as the pure, no-pull reference the unit tests
+    // exercise: same selectById + byte-cap semantics, minus the device fetch. Keep the two in step.
+    // Prefer a stored detail frame over a summary; honor the hard cap so no single id floods context.
+    if (filter.id !== undefined) {
+        const idCap = clampByteCap(filter.byte_cap);
+        const hit = selectById(frames, filter.id, filter.source);
+        if (hit) {
+            if (Buffer.byteLength(JSON.stringify(hit.frame)) > idCap) {
+                return {
+                    frames: [],
+                    count: 0,
+                    truncated: true,
+                    note: "the frame with that id alone exceeds the byte cap",
+                };
+            }
+            return { frames: [hit.frame], count: 1, truncated: false };
+        }
+        return { frames: [], count: 0, truncated: false, note: "no frame with that id in the spool" };
+    }
+    const hardCap = clampByteCap(filter.byte_cap);
+    const limit = filter.limit && filter.limit > 0 ? filter.limit : undefined;
+    // The handler emits this result compact, so measured bytes must budget for the wrapper the
+    // frames sit inside, not the frames alone. Reserve the largest wrapper this call can emit
+    // (count, truncated, plus a cursor token and the byte-cap note) so JSON.stringify(result) stays
+    // under the cap. The cursor is now a "<epoch>:<seq>" STRING, longer than the old int, so reserve
+    // for the biggest realistic token: both segments at the max safe integer. Overshooting the
+    // reserve only truncates a touch early, never over the cap.
+    const cursorReserve = String(Number.MAX_SAFE_INTEGER) + ":" + String(Number.MAX_SAFE_INTEGER);
+    const wrapperReserve = Buffer.byteLength(JSON.stringify({
+        frames: [],
+        count: Number.MAX_SAFE_INTEGER,
+        truncated: true,
+        cursor: cursorReserve,
+        note: "the newest matching frame alone exceeds the byte cap; fetch it by id",
+    }));
+    const cap = Math.max(0, hardCap - wrapperReserve);
+    // Tag each frame with its append position before filtering so paging keys off spool order, not
+    // device id. seq is the incoming index (oldest = 0); it survives filtering unchanged.
+    const tagged = frames.map((frame, seq) => ({ frame, seq }));
+    // Field filter first: keep only entries whose frame passes every set field. Both the frame and
+    // its seq survive as Seqd so seq is available at pack time and in the returned cursor.
+    let matched = tagged.filter((t) => matchesFilter(t.frame, filter));
+    // Collapse each (base source, id) to one frame on EVERY read (scoped or not): after a lazy pull the
+    // spool holds a summary and its detail for one id, and a backfill that races the live SSE push can
+    // append a second summary for an id. Deduping unconditionally means no read path can ever return a
+    // duplicated id, whatever write race produced it. Reuse the pure dedupSummaryDetail over the matched
+    // frames, then keep the tagged tuples whose frame survived so seq (append position) is preserved for
+    // paging.
+    const kept = new Set(dedupSummaryDetail(matched.map((t) => t.frame)));
+    matched = matched.filter((t) => kept.has(t.frame));
+    // The cursor page-older cut. A cursor is applied only when it parses AND its epoch matches the
+    // current spool file. A bad or stale cursor never applies a guessed seq: it degrades to the
+    // newest page (no cut) with a note, so the agent sees a signal rather than a silent wrong page.
+    let cursorNote;
+    if (rawFilter.cursor !== undefined) {
+        const parsed = parseCursor(rawFilter.cursor);
+        if (parsed === undefined) {
+            cursorNote =
+                "cursor was not a valid paging token; paging from the newest page. A cursor is the opaque token from a truncated result, not an id or a count.";
+        }
+        else if (parsed.epoch !== epoch) {
+            cursorNote =
+                "cursor is from a previous spool session (a rotation or re-enable reset it); start paging again from the newest page.";
+        }
+        else {
+            matched = matched.filter((t) => t.seq < parsed.seq);
+        }
+    }
+    const picked = [];
+    let bytes = 0;
+    let truncated = false;
+    // The comma between array entries costs a byte per frame after the first; count it so the packed
+    // size tracks the eventual serialized array, not a per-frame sum that would under-count.
+    for (let idx = matched.length - 1; idx >= 0; idx--) {
+        if (limit !== undefined && picked.length >= limit) {
+            truncated = true;
+            break;
+        }
+        const entry = matched[idx];
+        const size = Buffer.byteLength(JSON.stringify(entry.frame)) + (picked.length > 0 ? 1 : 0);
+        if (bytes + size > cap) {
+            // This frame does not fit. Older frames are even further back, so stop and flag truncation.
+            truncated = true;
+            break;
+        }
+        bytes += size;
+        picked.push(entry);
+    }
+    // A single frame larger than the cap would leave picked empty with truncated true; surface that
+    // rather than a silent empty, so the caller knows a record exists but could not fit. A bad or
+    // stale cursor note takes precedence: it explains why the caller is looking at the newest page.
+    let note = cursorNote;
+    if (note === undefined && picked.length === 0 && matched.length > 0) {
+        note = "the newest matching frame alone exceeds the byte cap; fetch it by id";
+    }
+    // cursor is emitted only when truncated, so a caller sees an actionable pager token exactly when
+    // older frames remain. It is the "<epoch>:<seq>" token for the oldest frame returned (the last
+    // pushed): epoch pins it to this spool file, seq is that frame's append position, so the next
+    // call pages strictly older across all sources and a token from a later rotation is detectably
+    // stale. A complete result pages nothing.
+    const cursor = truncated && picked.length > 0 ? epoch + ":" + picked[picked.length - 1].seq : undefined;
+    // Strip seq: the returned frames are the bare frames, seq is internal to paging.
+    return {
+        frames: picked.map((t) => t.frame),
+        count: picked.length,
+        truncated,
+        ...(cursor !== undefined ? { cursor } : {}),
+        ...(note !== undefined ? { note } : {}),
+    };
+}

package/dist/mcp/snapshot.d.ts

@@ -13,6 +13,7 @@ export interface SnapshotResult {
         network: number;
         rtm: number;
         clogs: number;
+        traces: number;
         log_lines: number;
         log_lines_truncated: boolean;
         screenshot: boolean;
@@ -21,6 +22,7 @@ export interface SnapshotResult {
         network: boolean;
         rtm: boolean;
         clogs: boolean;
+        traces: boolean;
     };
     errors: string[];
     privacy_notice: string;
@@ -35,7 +37,7 @@ export declare function buildSnapshotDir(now?: number, root?: string): string;
  * intentionally larger than point-query defaults — snapshots are bulk
  * exports and the device-side ring buffers cap their own responses.
  */
-export declare function buildBufferPath(kind: "network" | "rtm" | "clogs"): string;
+export declare function buildBufferPath(kind: "network" | "rtm" | "clogs" | "traces"): string;
 export interface LogTailResult {
     text: string;
     truncated: boolean;
@@ -60,4 +62,4 @@ export declare function readRecentLogTail(requestedLimit?: number): LogTailResul
  * snapshot still lands on disk with whatever succeeded; failures are
  * collected in `result.errors` so the model can tell the user.
  */
-export declare function createSnapshot(device: DeviceTransport, fetchBuffer: (kind: "network" | "rtm" | "clogs") => Promise<unknown>, opts?: SnapshotOptions, now?: number, snapshotRoot?: string): Promise<SnapshotResult>;
+export declare function createSnapshot(device: DeviceTransport, fetchBuffer: (kind: "network" | "rtm" | "clogs" | "traces") => Promise<unknown>, opts?: SnapshotOptions, now?: number, snapshotRoot?: string): Promise<SnapshotResult>;

package/dist/mcp/snapshot.js

@@ -10,7 +10,7 @@ import { getCaptureFilePath, readTailBytes } from "../shared/logcat-capture.js";
  * tool outputs.
  *
  * Snapshot contents:
- *   - `bundle.json` — device-side buffers (net + RTM + clogs) plus metadata
+ *   - `bundle.json` — device-side buffers (net + RTM + clogs + traces) plus metadata
  *   - `screenshot.png` — current screen (optional)
  *   - `logcat.tail.log` — last N lines of the active capture file (optional)
  *
@@ -33,19 +33,19 @@ const BUNDLE_README = `Slack Radar snapshot
 This directory is a point-in-time bundle of Radar state.
 
 Files:
-- bundle.json: device-side network/RTM/clog buffers, counts, and metadata.
+- bundle.json: device-side network/RTM/clog/trace buffers, counts, and metadata.
 - logcat.tail.log (optional): last N lines of the on-device logcat capture.
 - screenshot.png (optional): current screen.
 
 Privacy: bundle.json contains raw API request/response bodies (auth headers,
-tokens), RTM message content, user IDs, channel IDs, and clog payloads.
-Review before sharing externally. This bundle lives on your local disk only;
-nothing is uploaded anywhere by Radar.
+tokens), RTM message content, user IDs, channel IDs, clog payloads, and
+performance trace spans. Review before sharing externally. This bundle lives
+on your local disk only; nothing is uploaded anywhere by Radar.
 
 To inspect: cat bundle.json | jq .
 To share: zip -r snapshot.zip . then attach the zip.
 `;
-const PRIVACY_NOTICE = "bundle.json contains raw API request/response bodies (including auth headers), RTM message content, user IDs, and clog payloads. Review before sharing externally.";
+const PRIVACY_NOTICE = "bundle.json contains raw API request/response bodies (including auth headers), RTM message content, user IDs, clog payloads, and performance trace spans. Review before sharing externally.";
 /**
  * Resolve the output directory for a snapshot. Exported for tests.
  */
@@ -137,7 +137,8 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
     let network = null;
     let rtm = null;
     let clogs = null;
-    const fetched = { network: false, rtm: false, clogs: false };
+    let traces = null;
+    const fetched = { network: false, rtm: false, clogs: false, traces: false };
     // Device-side buffers. Failures are individually caught so one failing
     // buffer does not nuke the whole snapshot. `fetched` distinguishes
     // "empty because the buffer was empty" from "null because the fetch
@@ -163,6 +164,17 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
     catch (e) {
         errors.push(`clog buffer: ${e.message}`);
     }
+    // Traces capture from app start (like clogs), so they are worth
+    // bundling. An older debug build without the /api/traces route fails
+    // this one fetch and it is recorded in errors[] like any other buffer;
+    // the rest of the snapshot still lands.
+    try {
+        traces = await fetchBuffer("traces");
+        fetched.traces = true;
+    }
+    catch (e) {
+        errors.push(`trace buffer: ${e.message}`);
+    }
     // Logcat tail.
     let logTail = { text: "", truncated: false };
     if (includeLogs) {
@@ -221,6 +233,7 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
         network: countItems(network),
         rtm: countItems(rtm),
         clogs: countItems(clogs),
+        traces: countItems(traces),
         log_lines: logTail.text
             ? logTail.text.split("\n").filter(Boolean).length
             : 0,
@@ -228,12 +241,12 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
         screenshot: screenshotCaptured,
     };
     const bundle = {
-        version: 1,
+        version: 2,
         timestamp: now,
         platform: device.platform,
         active_user_id: device.getActiveUserId(),
         capture_file: getCaptureFilePath(),
-        buffers: { network, rtm, clogs },
+        buffers: { network, rtm, clogs, traces },
         counts,
         fetched,
         errors,
@@ -285,14 +298,14 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
 }
 /**
  * Count items inside a buffer response. Handles the `{ calls: [...] }`,
- * `{ events: [...] }`, `{ clogs: [...] }` shapes the radar HTTP server
- * uses. Falls back to 0 on malformed responses.
+ * `{ events: [...] }`, `{ clogs: [...] }`, `{ traces: [...] }` shapes the
+ * radar HTTP server uses. Falls back to 0 on malformed responses.
  */
 function countItems(body) {
     if (!body || typeof body !== "object")
         return 0;
     const b = body;
-    for (const key of ["calls", "events", "clogs", "items"]) {
+    for (const key of ["calls", "events", "clogs", "traces", "items"]) {
         const v = b[key];
         if (Array.isArray(v))
             return v.length;

package/dist/mcp/tools.js

@@ -23,6 +23,7 @@ export const SERVER_INSTRUCTIONS = [
     '- "why is this slow" / "how long did X take" / "show me the traces" / "check performance" -> get_recent_traces(name="...") then get_trace_detail',
     '- "what API call was that" -> get_recent_network_calls then get_network_call_detail',
     '- "did I get X" / "did X happen" -> search(query="X") across ALL buffers, not just one',
+    '- "everything since I enabled" / "the whole session" / "what did I miss" -> query_session',
     '- "check the debug logs" -> get_recent_logs (tag is OPTIONAL: pass tag="FKDebug" to filter, or omit it for all recent lines)',
     '- "save this" / "file this as a bug" / "share this" / "bundle this" / "attach to ticket" / "give me a repro" / "snapshot this" / "preserve this" / "hold this state" / "save what you just saw" -> capture_snapshot',
     "",
@@ -102,10 +103,10 @@ export const SERVER_INSTRUCTIONS = [
     "When capture_snapshot returns, tell the user:",
     "  1. The result.zip_path if non-null (the single shareable file). Fall back to",
     "     result.path (a directory) if zip_path is null.",
-    "  2. A one-line summary of counts (network/rtm/clogs/log_lines/screenshot).",
+    "  2. A one-line summary of counts (network/rtm/clogs/traces/log_lines/screenshot).",
     "  3. Print this EXACT sentence as the privacy line, verbatim — no paraphrase, no",
     "     compression, no skipping even under time pressure:",
-    '     "Privacy: bundle.json contains raw API request/response bodies (including auth headers), RTM message content, user IDs, and clog payloads. Review before sharing externally."',
+    '     "Privacy: bundle.json contains raw API request/response bodies (including auth headers), RTM message content, user IDs, clog payloads, and performance trace spans. Review before sharing externally."',
     "  4. If result.log_lines_truncated is true, say: 'you got fewer log lines than",
     "     requested because the 1 MB read cap was the limiting factor.'",
     "  5. If the user's original ask was 'file this as a bug' / 'attach to ticket' /",
@@ -302,7 +303,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "capture_snapshot",
-        description: "Bundle the current Radar state into a single on-disk artifact for sharing. Writes four files to ~/.slack-radar/snapshots/snapshot-<ts>/: bundle.json (network + RTM + clog buffers, up to 1000 items each — a bulk export, much larger than point queries like get_network_call_detail), logcat.tail.log (last N lines of the active capture), screenshot.png (current screen), and README.txt (receiver-facing explainer). Use when the user says 'save this', 'file this as a bug', 'share this', 'bundle this up', 'attach to a ticket', 'make me a repro', or otherwise wants a shareable reproducible handoff. PRIVACY: bundle.json contains raw API request/response bodies including auth headers, RTM message content, user/team/channel IDs, and clog payloads — review before sharing externally.",
+        description: "Bundle the current Radar state into a single on-disk artifact for sharing. Writes four files to ~/.slack-radar/snapshots/snapshot-<ts>/: bundle.json (network + RTM + clog + trace buffers, up to 1000 items each — a bulk export, much larger than point queries like get_network_call_detail), logcat.tail.log (last N lines of the active capture), screenshot.png (current screen), and README.txt (receiver-facing explainer). Use when the user says 'save this', 'file this as a bug', 'share this', 'bundle this up', 'attach to a ticket', 'make me a repro', or otherwise wants a shareable reproducible handoff. PRIVACY: bundle.json contains raw API request/response bodies including auth headers, RTM message content, user/team/channel IDs, clog payloads, and performance trace spans — review before sharing externally.",
         inputSchema: {
             type: "object",
             properties: {
@@ -481,6 +482,27 @@ export const TOOL_DEFINITIONS = [
         },
         annotations: { readOnlyHint: true },
     },
+    {
+        name: "query_session",
+        description: "Read the whole current Radar session from the host event spool (every network/RTM/clog/trace frame captured since radar was enabled), filtered and byte-capped so it cannot flood the model context. Covers network/rtm/clog/trace; device logs are not the spool's primary source, use get_recent_logs for those. Use it for 'everything since I enabled', 'the whole session', or 'what did I miss': the get_recent_* tools read the device rings, which drop the oldest events on a long session, while the spool keeps the full session record. A list read (no id) returns SUMMARY fields for network/RTM/trace and full clog records inline. An id read returns the FULL record: for network/RTM/trace the body (request/response, headers, full payload) is pulled from the device on first open and cached in the spool, so a later id read of the same record is served from the file with no device round-trip; clog is already the full record inline. If the body cannot be pulled (device offline, aged out of the ring, or a single body over the byte budget) the id read falls back to the summary with a note. Frames come back newest-first; when truncated:true the result carries an opaque cursor STRING token, which you pass back verbatim as cursor to page strictly older across all sources. Do not build or change the token; it is not an id and not a count. A token from before a spool rotation or a re-enable is rejected with a note (bounded; a normal session never rotates), and you start paging from the newest page again. Pass id (optionally with source) to fetch one whole record by id regardless of age. Ids are per-source, so an unsourced id can match more than one ring; pass source to disambiguate, and the returned frame type tells you which ring answered. A list read scoped to a plain source (source network) returns summaries; to list cached full bodies for a source, scope to its detail tag (source network_detail). An unscoped list read and an id read already prefer the cached full body. When id is set, all filters except source are ignored. Returns an empty result with a note when no spool exists (radar not enabled).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                source: { type: "string", description: "Opaque frame type tag to match, e.g. network, rtm, clog, trace (or a future source). Matched exactly, not enumerated." },
+                id: { type: "number", description: "Return the single whole frame with this id, bypassing the newest-first byte budget. Optionally scope with source. id addresses one record and is unrelated to cursor; there is no older-than-id filter, page with cursor instead." },
+                cursor: { type: "string", description: "An OPAQUE paging token returned by a prior truncated result; pass it back verbatim to get the next older page across all sources. It is NOT an event id and NOT a count; do not construct or modify it. A token from before a spool rotation or a re-enable is rejected with a note, and you start paging from the newest page again." },
+                url_filter: { type: "string", description: "Keep frames whose url contains this substring." },
+                status_code: { type: "number", description: "Keep frames with this exact HTTP status code." },
+                event_type: { type: "string", description: "Keep frames with this exact event_type (RTM)." },
+                channel: { type: "string", description: "Keep frames with this exact channel id (RTM)." },
+                name: { type: "string", description: "Keep frames whose name contains this substring (clog/trace)." },
+                text: { type: "string", description: "Keep frames whose serialized JSON contains this substring anywhere (searches the whole frame, including clog detail)." },
+                limit: { type: "number", description: "Max frames to return; newest kept first." },
+                byte_cap: { type: "number", description: "Max serialized output bytes. Defaults to and is hard-capped at the response budget; a larger value is clamped down." },
+            },
+        },
+        annotations: { readOnlyHint: true },
+    },
 ];
 /**
  * Check whether a tool call should be blocked by the session gate.

package/dist/shared/constants.d.ts

@@ -39,3 +39,11 @@ export declare const WEB_PORT_DEFAULT = 8100;
  * on a debuggable build. Defined once here so the two readers cannot drift.
  */
 export declare const SLACK_DEBUG_PKG = "com.Slack.internal.debug";
+/**
+ * Host-side ceiling on a single response we forward into the model context. A
+ * proxied device response (large trace/clog payloads) or a session-spool query
+ * could otherwise flood it. Point queries live under this; bulk exports go
+ * through capture_snapshot. Defined once here so the device-response path and
+ * the session-query byte cap share one ceiling and cannot drift.
+ */
+export declare const MAX_RADAR_RESPONSE_BYTES: number;

package/dist/shared/constants.js

@@ -48,3 +48,11 @@ export const WEB_PORT_DEFAULT = 8100;
  * on a debuggable build. Defined once here so the two readers cannot drift.
  */
 export const SLACK_DEBUG_PKG = "com.Slack.internal.debug";
+/**
+ * Host-side ceiling on a single response we forward into the model context. A
+ * proxied device response (large trace/clog payloads) or a session-spool query
+ * could otherwise flood it. Point queries live under this; bulk exports go
+ * through capture_snapshot. Defined once here so the device-response path and
+ * the session-query byte cap share one ceiling and cannot drift.
+ */
+export const MAX_RADAR_RESPONSE_BYTES = 1024 * 1024;

package/dist/shared/db.d.ts

@@ -77,6 +77,19 @@ export declare function pullDatabase(name: string, user?: string | null, force?:
  * (1) and (2), not from the open mode.
  */
 export declare function assertReadOnlyQuery(sql: string): void;
+/**
+ * True for EXPLAIN / EXPLAIN QUERY PLAN, which sqlite3 prints as a text table (ignoring -json).
+ * Leading-token match; assertReadOnlyQuery gates the same leading keyword, so both reject on
+ * comment-prefixed queries before this routing matters.
+ */
+export declare function isExplainQuery(sql: string): boolean;
+/**
+ * sqlite3 ignores -json for EXPLAIN (prints text table instead of JSON).
+ * Shape it into row objects so the web grid renders the plan readably.
+ */
+export declare function parseExplainOutput(out: string): {
+    plan: string;
+}[];
 /**
  * Run a read-only query against a (lazily pulled) local copy. The query is gated by
  * assertReadOnlyQuery (see there for the full read-only/exfil rationale). Surfaces sqlite's