@slack/radar-mcp 1.8.0 → 1.9.0

package/README.md

@@ -87,13 +87,21 @@ Radar starts **disabled** each session. All tools except `ping` return an error
 | `get_rtm_event_detail` | Full RTM event JSON payload for a specific event. |
 | `get_recent_clogs` | Analytics event summaries: name and timestamp. Filterable by event name substring. Persists from app start. |
 | `get_clog_detail` | Full clog JSON payload for a specific event. |
+| `get_recent_traces` | Performance trace/span summaries: trace name, span name, duration. Filterable by name substring. |
+| `get_trace_detail` | Full trace/span detail for a specific trace, including tags. |
 | `wait_for_events` | Block until matching events arrive via SSE stream. Idle-timeout based, not polling. |
-| `search` | Full-text search across network, RTM, and clog buffers. |
+| `search` | Full-text search across network, RTM, clog, and trace buffers. |
 | `get_app_state` | Current Activity/Fragment state via `dumpsys`. Shows visible screen, parameters, tab state. |
 | `get_recent_logs` | Recent device logs, optionally filtered by tag (omit `tag` for all lines). Reads the app's own debug log buffer first, falling back to logcat; the result's `source` field (`app_buffer` / `logcat_capture` / `logcat_ring`) names which one served it. For Timber debug logs (`FKDebug`, `SlackRadar`, etc.). |
+| `list_profiles` | List the Android users and profiles on the device (personal, work, and so on). |
+| `activate_for_user` | Activate radar for a specific Android user or profile. |
+| `capture_snapshot` | Bundle the current network, RTM, clog, and trace buffers, plus an optional screenshot, into one saved snapshot for a bug report or repro. |
 | `screenshot` | Capture device screen as PNG. 720px default, `full_res=true` for full resolution. |
 | `record_screen` | Record short screen video (MP4). Default 5s, max 30s. |
-| `clear_buffers` | Clear all captured network calls and RTM events from device and local buffers. |
+| `list_databases` | List the app's on-device SQLite databases. Read-only. |
+| `list_tables` | List the tables in a given on-device database, with row counts. Read-only. |
+| `query_database` | Run a read-only query (SELECT, WITH, EXPLAIN, VALUES, PRAGMA) against a copy of an on-device database pulled to the host. |
+| `clear_buffers` | Clear all captured buffers (network, RTM, clog, trace) on the device and locally. |
 | `open_radar_dashboard` | Author or refine a custom live dashboard tab from a spec (source, filters, widgets, alerts). Suggested when a request is not covered by the pre-built tabs; not auto-invoked. Returns the dashboard URL; debug builds only, local only. |
 | `_radar_session_enable` | Enable radar for the session. Called by `/radar-enable` skill. |
 | `_radar_session_disable` | Disable radar for the session. Called by `/radar-disable` skill. |
@@ -129,9 +137,10 @@ All device-specific logic lives behind the `DeviceTransport` interface (`src/sha
 
 What gets captured depends on the in-app server implementation. The MCP server is agnostic to the data source. The Android implementation captures:
 
-* **Network calls**: OkHttp interceptor. Ring buffer: 200 calls.
-* **RTM events**: WebSocket listener. Ring buffer: 500 events.
-* **Clogs**: Analytics interceptor. Ring buffer: 500 events. Persists across radar activation cycles.
+* **Network calls**: OkHttp interceptor. Ring buffer: 400 calls.
+* **RTM events**: WebSocket listener. Ring buffer: 2000 events.
+* **Clogs**: Analytics interceptor. Ring buffer: 1000 events. Persists across radar activation cycles.
+* **Traces**: Performance span observer. Ring buffer: 1000 spans. Persists across radar activation cycles.
 * **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.
 
 The network, RTM, and clog 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.

package/dist/mcp/index.js

@@ -8,11 +8,15 @@ import http from "http";
 import path from "path";
 import { fileURLToPath } from "url";
 import { AndroidTransport } from "../shared/android.js";
-import { RADAR_HOST, RADAR_PORT, WEB_PORT_DEFAULT } from "../shared/constants.js";
+import { RADAR_HOST, RADAR_PORT, WEB_PORT_DEFAULT, MAX_RADAR_RESPONSE_BYTES } from "../shared/constants.js";
 import { stopCapture } from "../shared/logcat-capture.js";
-import { connectStream, destroyStream, waitForEvents, clearLocalBuffers, isStreamConnected, localNetworkBuffer, localRtmBuffer, setTransport, } from "../shared/stream.js";
+import { getSpoolFilePath, epochFromSpoolPath, initializeSpoolDir, readSpool, startSpool, stopSpool, writeFrame, registerCleanup as registerSpoolCleanup, } from "../shared/event-spool.js";
+import { connectStream, destroyStream, waitForEvents, clearLocalBuffers, isStreamConnected, localNetworkBuffer, localRtmBuffer, setTransport, setOnReconnect, } from "../shared/stream.js";
 import { buildBufferPath, createSnapshot } from "./snapshot.js";
 import { clampLogLimit, shapeLogsResult } from "./logs-result.js";
+import { querySession, clampByteCap, toNum } from "./session-query.js";
+import { resolveDetailById } from "./session-detail.js";
+import { backfillSpool, BACKFILL_SOURCES, makeSerializedRunner, } from "./session-backfill.js";
 import { handleListDatabases, handleListTables, handleQueryDatabase, } from "./db-tools.js";
 import { cleanupPulledDatabases, initializeDatabasePath, resetDbState, } from "../shared/db.js";
 import { TOOL_DEFINITIONS, SERVER_INSTRUCTIONS, sessionGate } from "./tools.js";
@@ -200,14 +204,78 @@ async function runMcpServer() {
     for (const sig of ["SIGINT", "SIGTERM", "exit"]) {
         process.once(sig, cleanupPulledDatabases);
     }
+    // Scope the event spool dir to THIS process by pid, same reason as the DB dir:
+    // every MCP shares one RADAR_PORT, so a fixed dir would let two concurrent
+    // servers collide on the same events-<now>.jsonl path and gc each other's
+    // live files.
+    initializeSpoolDir(process.pid);
+    // Close the session event spool on process exit (the file is kept for the GC to
+    // reclaim). Enable opens it, disable and exit close it; the file survives so a
+    // just-ended session stays readable.
+    registerSpoolCleanup();
     let sessionEnabled = false;
+    // The envelope key each device list route wraps its rows in: /api/network -> {calls}, /api/rtm ->
+    // {events}, /api/clogs -> {clogs}, /api/traces -> {traces}. Read once against the same list routes
+    // buildApiPath pins. Defined here (the impure layer) since it is the device-response shape, not
+    // something the pure backfill orchestrator should know.
+    const BACKFILL_ENVELOPE_KEY = {
+        network: "calls",
+        rtm: "events",
+        clog: "clogs",
+        trace: "traces",
+    };
+    // Build the injected seams backfillSpool needs, wiring the real callRadar (through the pinned
+    // buildApiPath list route), readSpool, and writeFrame. fetchList pulls one source's device ring
+    // list and unwraps its envelope array; a device error or a missing or malformed envelope degrades
+    // to an empty list, so a blip on one source simply skips it (backfillSpool swallows the rest).
+    // Per-source backfill limit, matching each device ring cap so a full ring is covered (network 400,
+    // rtm 2000, clog/trace 1000). These mirror DebugSlackRadarServer's *_BUFFER_CAPACITY. Note the device
+    // still caps its response at the 1MB budget, so a very full rtm ring can come back truncated (empty);
+    // that is a bounded gap the read-time dedup and the next reconnect backfill tolerate, not a crash.
+    const BACKFILL_LIMIT = {
+        network: 400,
+        rtm: 2000,
+        clog: 1000,
+        trace: 1000,
+    };
+    function backfillDeps() {
+        return {
+            fetchList: async (source) => {
+                const tool = BACKFILL_SOURCES.get(source);
+                if (tool === undefined)
+                    return [];
+                // Limit per source's ring cap so a full ring is covered; the device still caps its response
+                // at the byte budget, so an overfull ring may return fewer (bounded gap, not a failure).
+                const apiPath = buildApiPath(tool, { limit: BACKFILL_LIMIT[source] ?? 1000 });
+                if (apiPath === null)
+                    return [];
+                const res = await callRadar(apiPath);
+                if (res.error)
+                    return [];
+                const key = BACKFILL_ENVELOPE_KEY[source];
+                const arr = key ? res[key] : undefined;
+                return Array.isArray(arr) ? arr : [];
+            },
+            readSpool,
+            write: writeFrame,
+        };
+    }
+    // One serialized backfill runner for the whole process. Both the enable path and the reconnect hook
+    // call THIS, never backfillSpool directly, so two backfills never overlap and race their `have`
+    // snapshots into a double-write. A reconnect burst coalesces to one run now plus one fresh run after.
+    const runBackfillSerialized = makeSerializedRunner(() => backfillSpool(backfillDeps()).then(() => { }));
+    // Backfill on a stream reconnect so the gap between the drop and the re-established stream is
+    // filled from the device rings. Set once at startup; the enable path backfills the first connect
+    // itself, and noteStreamConnected only fires this on a true reconnect. The runner never throws.
+    setOnReconnect(() => {
+        void runBackfillSerialized();
+    });
     // --- HTTP requests to the on-device radar server ---
-    // Host-side ceiling on a proxied device response. radarRequest forwards the device body straight
-    // into the model context, so an unbounded response (large trace/clog payloads) could flood it.
-    // When the cap trips we stop reading, tear the socket down, and return a truncation marker
-    // rather than a partial JSON blob the parser would choke on. 1MB is generous for a point query;
-    // bulk exports go through capture_snapshot, not this path.
-    const MAX_RADAR_RESPONSE_BYTES = 1024 * 1024;
+    // radarRequest forwards the device body straight into the model context, so an unbounded
+    // response could flood it. When the cap trips we stop reading, tear the socket down, and return
+    // a truncation marker rather than a partial JSON blob the parser would choke on. Bulk exports go
+    // through capture_snapshot, not this path. The ceiling now lives in constants so the device path
+    // and the session-query byte cap share one value.
     function radarRequest(requestPath) {
         return new Promise((resolve, reject) => {
             // settled-guard: req.destroy() on the cap path fires "error" (ECONNRESET) AFTER we have
@@ -325,7 +393,20 @@ async function runMcpServer() {
             }, true);
         }
         device.activate(timeout);
+        // Open the session event spool, then backfill the device rings into it. Note the live SSE push can
+        // start DURING the backfill: the backfill pulls the ring lists via callRadar, which opens the
+        // stream on its first fetch, so the trailing connectStream() below is usually a no-op (it only
+        // opens the stream when the backfill wrote nothing and never called callRadar, e.g. empty rings).
+        // Correctness does NOT rely on connect ordering. It relies on two things: the (source, id) have-set
+        // that skips a row already in the spool, and the unconditional read-time collapse (every read folds
+        // a duplicated id to one frame), so a frame the live push and the backfill both write surfaces once.
+        // Serialized so it cannot overlap a reconnect backfill. Never throws; a device blip just skips it.
+        startSpool();
+        await runBackfillSerialized();
         connectStream();
+        // Open the session event spool so every streamed frame is captured to a host
+        // file for the life of this enabled session.
+        startSpool();
         await new Promise((r) => setTimeout(r, 500));
         try {
             const status = await radarRequest("/api/ping");
@@ -355,6 +436,11 @@ async function runMcpServer() {
         // deliberate user action saying "I am done", which is surprising and
         // wastes disk + an adb logcat child.
         stopCapture();
+        // Explicit disable closes the session event spool but keeps the file so it
+        // stays readable until the GC reclaims it. Only explicit disable and process
+        // exit close it; a transient device error in callRadar must NOT, or a
+        // momentary drop would cut the session record short.
+        stopSpool();
         return textResult({
             enabled: false,
             note: "Radar disabled. Use /radar-enable to reconnect.",
@@ -475,6 +561,39 @@ async function runMcpServer() {
             return textResult({ error: `Log query failed: ${e.message}`, lines: [] }, true);
         }
     }
+    // Derive the paging epoch from the current spool filename via the shared helper (single source of
+    // the events-<ts>.jsonl affix stripping). The <ts> changes on every rotation and re-enable, so it is
+    // a stable identity of the CURRENT file; a cursor minted here is detectably stale after a rotation.
+    function spoolEpoch() {
+        return epochFromSpoolPath(getSpoolFilePath());
+    }
+    async function handleQuerySession(filter) {
+        // Read the whole session spool. No device call on the common path: the spool is a host file.
+        // readSpool degrades to [] on a missing or damaged spool.
+        const frames = readSpool();
+        // Coerce id once here: the SDK does not enforce the input schema, so it can arrive as a digit
+        // string. selectById strict-compares against a numeric frame id, so a raw "5" would match nothing
+        // for a record that exists. querySession's pure path already coerces internally; the live id path
+        // routes here first, so it must coerce too. An unparseable id becomes undefined and falls through
+        // to the list read.
+        const id = toNum(filter.id);
+        // id read: lazy pull-on-open lives in session-detail.ts, with the device fetch and the spool
+        // write injected here (the real callRadar + writeFrame). It prefers a stored detail, pulls a
+        // body once for a summary-only pull-eligible source, caches it, and degrades to the summary on a
+        // pull failure. A single record via the id path is exempt from the newest-first byte budget.
+        if (id !== undefined) {
+            // Pass the caller's byte cap (hard-bounded) so the id path drops an oversized frame with the
+            // same exceeds-cap note the pure id-bypass uses, honoring a caller-lowered cap here too.
+            const result = await resolveDetailById(frames, id, filter.source, { pull: (apiPath) => callRadar(apiPath), write: writeFrame }, clampByteCap(filter.byte_cap));
+            // Emit COMPACT so emitted bytes equal what the cap guard measured; textResult pretty-print
+            // would add whitespace the cap never counted.
+            return textResult(JSON.stringify(result));
+        }
+        // No id: the pure newest-first shaper. querySession is pure, so the epoch (spool-file identity for
+        // the cursor) is derived here and passed in. [] turns into an empty result with a note, so this
+        // never throws a radar-not-enabled query. Emit COMPACT so emitted bytes match the measured cap.
+        return textResult(JSON.stringify(querySession(frames, filter, spoolEpoch())));
+    }
     function handleScreenshot(args) {
         try {
             const fullRes = args?.full_res === true;
@@ -549,7 +668,7 @@ async function runMcpServer() {
         }
     }
     // --- MCP Server ---
-    const server = new Server({ name: "slack-radar", version: "1.8.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+    const server = new Server({ name: "slack-radar", version: "1.9.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: TOOL_DEFINITIONS,
     }));
@@ -618,6 +737,9 @@ async function runMcpServer() {
             const { data, isError } = await handleQueryDatabase(device, db ?? "", sql ?? "", refresh === true);
             return textResult(data, isError);
         }
+        if (name === "query_session") {
+            return await handleQuerySession(toolArgs);
+        }
         const apiPath = buildApiPath(name, toolArgs);
         if (apiPath === null) {
             return textResult(`Unknown tool: ${name}`, true);

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

@@ -0,0 +1,26 @@
+import type { ParsedSSE, RadarEvent } from "../shared/stream.js";
+export declare const BACKFILL_SOURCES: Map<string, string>;
+export interface BackfillDeps {
+    fetchList: (source: string) => Promise<RadarEvent[]>;
+    readSpool: () => ParsedSSE[];
+    write: (frame: ParsedSSE) => void;
+}
+export interface BackfillSummary {
+    written: Record<string, number>;
+}
+/**
+ * Backfill the device rings into the spool.
+ *
+ * For each backfillable source it fetches the device ring list, reads what the spool already holds,
+ * and writes only the rows whose (base source, id) is NOT already present (as a summary OR as a
+ * cached detail). Frames are written in the SAME shape the SSE push produces ({type: source,
+ * event: row}) and oldest-first (ascending id) so the spool stays append-ordered like the live push.
+ *
+ * Never throws: a failed list fetch for one source is swallowed (that source is simply not
+ * backfilled this round) so a device blip cannot break enable or the stream. A row with no numeric
+ * id is written every round, since it cannot be deduped against the spool.
+ *
+ * Returns a per-source count of rows written, for logging and tests. Not forwarded to the model.
+ */
+export declare function backfillSpool(deps: BackfillDeps): Promise<BackfillSummary>;
+export declare function makeSerializedRunner(run: () => Promise<void>): () => Promise<void>;

package/dist/mcp/session-backfill.js

@@ -0,0 +1,156 @@
+import { baseSourceOf } from "./session-query.js";
+// The sources with a device ring and a list endpoint, each paired with the buildApiPath list-tool
+// name so the fetch reuses the pinned device-route table instead of hand-building a path. This is
+// the summary LIST set; keep it separate from session-detail's PULL_ELIGIBLE, which is about
+// pulling DETAIL bodies. All four rings are backfillable here. The frame type (clog, singular)
+// differs from the list tool name (get_recent_clogs); the frame type is the map key.
+export const BACKFILL_SOURCES = new Map([
+    ["network", "get_recent_network_calls"],
+    ["rtm", "get_recent_rtm_events"],
+    ["clog", "get_recent_clogs"],
+    ["trace", "get_recent_traces"],
+]);
+// A read frame's numeric id, or undefined when it carries none. Only rows with a numeric id can be
+// deduped; a row with no id is written every round (it cannot be matched against the spool).
+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;
+}
+// The base source a spooled frame belongs to: a detail tag folds to its base, any other tag is
+// itself. So a network summary and a network_detail share base network, and a cached detail
+// already counts as "have this id". Dedup by base via baseSourceOf, never a source-name switch, so
+// a future source dedups for free.
+function baseSourceOfFrame(frame) {
+    return baseSourceOf(frame.type) ?? frame.type;
+}
+// The dedup key for a (source, id) pair. NUL-separated so an id that contains a source substring
+// cannot collide with a different (source, id) pair.
+// Read a row's numeric id, or undefined. The device rows are plain objects of unknown shape.
+function numId(row) {
+    if (typeof row !== "object" || row === null)
+        return undefined;
+    const raw = row.id;
+    return typeof raw === "number" ? raw : undefined;
+}
+function dedupKey(source, id) {
+    return `${source}\u0000${id}`;
+}
+/**
+ * Backfill the device rings into the spool.
+ *
+ * For each backfillable source it fetches the device ring list, reads what the spool already holds,
+ * and writes only the rows whose (base source, id) is NOT already present (as a summary OR as a
+ * cached detail). Frames are written in the SAME shape the SSE push produces ({type: source,
+ * event: row}) and oldest-first (ascending id) so the spool stays append-ordered like the live push.
+ *
+ * Never throws: a failed list fetch for one source is swallowed (that source is simply not
+ * backfilled this round) so a device blip cannot break enable or the stream. A row with no numeric
+ * id is written every round, since it cannot be deduped against the spool.
+ *
+ * Returns a per-source count of rows written, for logging and tests. Not forwarded to the model.
+ */
+export async function backfillSpool(deps) {
+    const written = {};
+    // Read the spool once and index every id it already holds by base source. A cached detail counts
+    // as having the id, so a later re-enable does not re-write the summary a detail already covers.
+    const have = new Set();
+    for (const frame of deps.readSpool()) {
+        const id = frameId(frame);
+        if (id === undefined)
+            continue;
+        have.add(dedupKey(baseSourceOfFrame(frame), id));
+    }
+    // Fetch all sources in parallel: each is an independent device pull, so running them concurrently
+    // caps the wall time at one fetch, not the sum of four (each callRadar has its own timeout). A
+    // per-source rejection is contained by allSettled so one blip never fails the others or enable.
+    const sources = [...BACKFILL_SOURCES.keys()];
+    const results = await Promise.allSettled(sources.map((source) => deps.fetchList(source)));
+    // Write sequentially over the resolved lists so the shared `have` dedup set is updated race-free.
+    for (let i = 0; i < sources.length; i++) {
+        const source = sources[i];
+        written[source] = 0;
+        const settled = results[i];
+        if (settled.status !== "fulfilled")
+            continue; // a failed source fetch just skips that source
+        const rows = settled.value;
+        if (!Array.isArray(rows))
+            continue;
+        // Append oldest-first so the spool stays append=ascending-id, which the newest-first read walk
+        // and the before_id pager depend on. The device already returns oldest-first, but sort by id
+        // ascending here rather than trust the order, matching the web server's defensive sort; a row
+        // with no numeric id keeps its relative position. This also makes the fetch order irrelevant.
+        const ordered = [...rows]
+            .map((row, idx) => ({ row, idx }))
+            .sort((a, b) => {
+            const ai = numId(a.row);
+            const bi = numId(b.row);
+            if (ai === undefined || bi === undefined)
+                return a.idx - b.idx;
+            return ai - bi;
+        })
+            .map((x) => x.row);
+        for (const row of ordered) {
+            if (typeof row !== "object" || row === null)
+                continue;
+            const id = numId(row);
+            if (id !== undefined) {
+                const key = dedupKey(source, id);
+                if (have.has(key))
+                    continue;
+                // Mark it held so a duplicate id within THIS same list is not written twice either.
+                have.add(key);
+            }
+            deps.write({ type: source, event: row });
+            written[source] += 1;
+        }
+    }
+    return { written };
+}
+// Serialize an async run so two triggers never overlap. The wiring layer (index.ts) calls the real
+// backfill from two places: the enable path and the reconnect hook. If a reconnect fires while a run
+// is still awaiting its device fetches, a second run would snapshot the same point-in-time `have` set
+// and could double-write the same id. This wrapper guarantees at most one run at a time.
+//
+// Coalesce-to-one-follow-up: while a run is in flight, the FIRST new trigger schedules a single fresh
+// run to start after the current one settles; further triggers during the same run return that same
+// pending follow-up instead of stacking N runs. So a burst of reconnects yields one run now and one
+// fresh run after, never a run per reconnect. The wrapped run is treated as never-throwing (backfill
+// swallows its own errors); a rejection is contained so it cannot become an unhandled rejection or
+// wedge the chain.
+//
+// Pure and injectable: it wraps an arbitrary async `run`, holds no fs/device/index reference, and
+// keeps its in-flight state in a closure. index.ts owns the single instance; the guard state lives
+// with the wiring layer, the guard logic is testable here.
+export function makeSerializedRunner(run) {
+    let inFlight = null;
+    let queued = null;
+    const start = () => {
+        const p = Promise.resolve()
+            .then(run)
+            .catch(() => {
+            // The run owns its errors; contain a stray rejection so the chain never wedges.
+        })
+            .finally(() => {
+            if (inFlight === p)
+                inFlight = null;
+        });
+        inFlight = p;
+        return p;
+    };
+    return () => {
+        if (inFlight === null)
+            return start();
+        if (queued === null) {
+            // Schedule exactly one fresh run after the current one settles. Clear the slot the moment it
+            // begins so a later trigger can queue the next follow-up.
+            queued = inFlight.then(() => {
+                queued = null;
+                return start();
+            });
+        }
+        return queued;
+    };
+}

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

@@ -0,0 +1,36 @@
+import type { ParsedSSE } from "../shared/stream.js";
+import { type SessionQueryResult } from "./session-query.js";
+export declare const PULL_ELIGIBLE: Map<string, string>;
+export interface PulledBody {
+    error?: string;
+    _truncated?: boolean;
+    [key: string]: unknown;
+}
+export interface DetailDeps {
+    pull: (apiPath: string) => Promise<PulledBody>;
+    write: (frame: ParsedSSE) => void;
+}
+/**
+ * Resolve an id read against the spool with lazy pull-on-open.
+ *
+ * frames are the spool contents (already read; this layer does not read the file). The flow:
+ *   - no frame carries the id in scope -> a not-found result with a note
+ *   - a stored detail frame is present -> return it (served from file, no pull); this is the
+ *     second-read path and the clog path (the device already pushed clog detail)
+ *   - only a summary is present and the source is pull-eligible -> pull the body once, write it
+ *     back, return the detail
+ *   - the pull is unreachable, or the source is not pull-eligible -> return the summary; a
+ *     pull-eligible source that could not be fetched carries an offline/evicted note
+ *   - the pull is reachable but over budget -> return the summary with a size note pointing at
+ *     capture_snapshot, not a retry
+ *
+ * Every branch that returns a frame is byte-capped by `cap` (the caller's byte_cap, hard-bounded by
+ * clampByteCap). A frame that alone exceeds the cap is dropped for the same exceeds-cap note the
+ * pure id-bypass uses, so a large clog served from file or a device-pushed detail cannot flood the
+ * model context. `cap` defaults to the shared response budget when the handler does not pass one.
+ *
+ * Returns the same SessionQueryResult shape the pure shaper returns, so the handler wraps it the
+ * same way. A single record via the id path is exempt from the newest-first byte packing (PR2), so
+ * this never sets truncated on a found record.
+ */
+export declare function resolveDetailById(frames: ParsedSSE[], id: number, source: string | undefined, deps: DetailDeps, cap?: number): Promise<SessionQueryResult>;

package/dist/mcp/session-detail.js

@@ -0,0 +1,109 @@
+// Lazy pull-on-open for an id read of query_session, split out of the index.ts handler (like
+// session-query.ts and api-paths.ts) so the orchestration is unit-testable without importing
+// index.ts (index connects stdio at load, so a test import would hang). The device fetch and the
+// spool write are INJECTED, mirroring db-tools.ts taking a transport: the pull-eligibility set and
+// the readSpool -> select -> pull-if-needed -> writeFrame -> return flow live here, the real
+// callRadar-backed pull and writeFrame are wired in index.ts.
+//
+// Selection stays in the pure shaper (session-query.selectById); this layer owns only the impure
+// step: when the spool holds a summary and no detail for a pull-eligible source, fetch the body
+// once, cache it, and return it. A pull failure degrades to the summary. It never throws.
+import { MAX_RADAR_RESPONSE_BYTES } from "../shared/constants.js";
+import { buildApiPath } from "./api-paths.js";
+import { detailTypeFor, selectById } from "./session-query.js";
+// Sources whose spool frame is a SUMMARY, so an id read must pull the body from the device once and
+// write it back. The value is the device-detail tool name buildApiPath already knows, so the pull
+// reuses the pinned device-route table instead of hand-building a path. clog is intentionally absent:
+// the device pushes clog detail, so a clog spool frame is already the full record and needs no pull.
+// This is the one place a source list is unavoidable; it lives here, not in the pure shaper.
+export const PULL_ELIGIBLE = new Map([
+    ["network", "get_network_call_detail"],
+    ["rtm", "get_rtm_event_detail"],
+    ["trace", "get_trace_detail"],
+]);
+// Pull one record's full body for a pull-eligible source and shape it as a detail frame carrying
+// the requested id. Returns a reason instead of a bare null so the caller can tell the two failure
+// modes apart: `missing` is unreachable (source not pull-eligible, a device blip, or an evicted
+// record); `too_large` is reachable but over budget (a wire-cap trip, or a parsed body past the
+// shared response budget). Never throws. The size backstop stops an oversized body from being
+// persisted and re-served forever.
+async function pullDetailFrame(source, id, deps) {
+    const detailTool = PULL_ELIGIBLE.get(source);
+    if (detailTool === undefined)
+        return "missing";
+    const apiPath = buildApiPath(detailTool, { id });
+    if (apiPath === null)
+        return "missing";
+    const res = await deps.pull(apiPath);
+    // A wire-cap trip means the body was too big for the device response, not that it is gone.
+    if (res._truncated)
+        return "too_large";
+    // A device blip: the record could not be fetched at all.
+    if (res.error)
+        return "missing";
+    // Backstop: the parsed body must still fit the shared response budget once serialized.
+    if (Buffer.byteLength(JSON.stringify(res)) > MAX_RADAR_RESPONSE_BYTES)
+        return "too_large";
+    // The stored detail MUST carry the requested id so a later id read selects it over the summary.
+    return { type: detailTypeFor(source), event: { ...res, id } };
+}
+/**
+ * Resolve an id read against the spool with lazy pull-on-open.
+ *
+ * frames are the spool contents (already read; this layer does not read the file). The flow:
+ *   - no frame carries the id in scope -> a not-found result with a note
+ *   - a stored detail frame is present -> return it (served from file, no pull); this is the
+ *     second-read path and the clog path (the device already pushed clog detail)
+ *   - only a summary is present and the source is pull-eligible -> pull the body once, write it
+ *     back, return the detail
+ *   - the pull is unreachable, or the source is not pull-eligible -> return the summary; a
+ *     pull-eligible source that could not be fetched carries an offline/evicted note
+ *   - the pull is reachable but over budget -> return the summary with a size note pointing at
+ *     capture_snapshot, not a retry
+ *
+ * Every branch that returns a frame is byte-capped by `cap` (the caller's byte_cap, hard-bounded by
+ * clampByteCap). A frame that alone exceeds the cap is dropped for the same exceeds-cap note the
+ * pure id-bypass uses, so a large clog served from file or a device-pushed detail cannot flood the
+ * model context. `cap` defaults to the shared response budget when the handler does not pass one.
+ *
+ * Returns the same SessionQueryResult shape the pure shaper returns, so the handler wraps it the
+ * same way. A single record via the id path is exempt from the newest-first byte packing (PR2), so
+ * this never sets truncated on a found record.
+ */
+export async function resolveDetailById(frames, id, source, deps, cap = MAX_RADAR_RESPONSE_BYTES) {
+    const hit = selectById(frames, id, source);
+    if (hit === null) {
+        return { frames: [], count: 0, truncated: false, note: "no frame with that id in the spool" };
+    }
+    if (hit.isDetail) {
+        return cappedFrameResult(hit.frame, cap);
+    }
+    const outcome = await pullDetailFrame(hit.frame.type, id, deps);
+    if (outcome === "missing") {
+        const eligible = PULL_ELIGIBLE.has(hit.frame.type);
+        return cappedFrameResult(hit.frame, cap, eligible
+            ? "the body could not be pulled from the device (offline or evicted); returning the summary"
+            : undefined);
+    }
+    if (outcome === "too_large") {
+        return cappedFrameResult(hit.frame, cap, "the full body exceeds the response budget and cannot be inlined; returning the summary. Use capture_snapshot for a bulk export.");
+    }
+    deps.write(outcome);
+    return cappedFrameResult(outcome, cap);
+}
+// Return a found frame as a one-record result, or drop it for the exceeds-cap note when the frame
+// alone is over budget. This is the same guard the pure id-bypass uses (session-query.ts), applied
+// on every id-path branch that returns a frame so an oversized clog or device-pushed detail served
+// from file cannot flood the model context. An optional summary note rides along when the frame
+// still fits; if the frame itself is too big, the exceeds-cap note replaces it.
+function cappedFrameResult(frame, cap, note) {
+    if (Buffer.byteLength(JSON.stringify(frame)) > cap) {
+        return {
+            frames: [],
+            count: 0,
+            truncated: true,
+            note: "the frame with that id alone exceeds the byte cap",
+        };
+    }
+    return { frames: [frame], count: 1, truncated: false, ...(note !== undefined ? { note } : {}) };
+}

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;