@slack/radar-mcp 1.8.0 → 1.9.0

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/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',
     "",
@@ -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/event-spool.d.ts

@@ -0,0 +1,75 @@
+import type { ParsedSSE } from "./stream.js";
+/**
+ * Point the spool dir at a per-process-unique path. Call once at startup with
+ * process.pid. Mirrors db.ts initializeDatabasePath: every MCP shares one port,
+ * so a pid key is the collision-free scope.
+ */
+export declare function initializeSpoolDir(scopeKey: number): void;
+/**
+ * Delete spool files older than GC_TTL_MS. Runs at session enable. Bounds disk
+ * usage without losing recent session records. dir + now injectable for tests.
+ * Mirrors gcOldCaptures (logcat-capture.ts). Returns the count removed.
+ */
+export declare function gcOldSpools(dir?: string, now?: number): number;
+export declare function buildSpoolFilePath(now?: number): string;
+export declare function epochFromSpoolPath(filePath: string | null): string;
+export declare function isSpooling(): boolean;
+export declare function getSpoolFilePath(): string | null;
+/**
+ * Read the current session spool back into parsed frames, oldest first (append
+ * order). Separate from the write path; reads the live file by its own handle,
+ * never touching the writer's fd or state. Returns [] when no spool is open, the
+ * file is gone, or it cannot be read. Never throws into the caller: a query over
+ * a missing or damaged spool must degrade to empty, not fail the tool.
+ *
+ * Reads the whole file and lets the query shaper's byte cap bound the OUTPUT,
+ * rather than tailing here: a filter can match an old frame near the top, so a
+ * byte-tail read could drop a frame the caller asked for. Rotation already caps
+ * the live file at a normal-session size, so a whole read is safe.
+ *
+ * A torn final line (the process died mid-append, before the newline) is skipped
+ * so one bad tail line never sinks the whole read. Any line that will not parse
+ * is dropped the same way.
+ */
+export declare function readSpool(): ParsedSSE[];
+/**
+ * Open a fresh spool file for append and set module state. Ensures the dir,
+ * runs gcOldSpools first, returns the path (or null on failure). Idempotent: a
+ * second call while a spool is open returns the current path without reopening.
+ */
+export declare function startSpool(now?: number): string | null;
+/**
+ * Append one frame as a single JSONL line. On the hot path (every streamed
+ * event) and inside the wait_for_events notify path. Synchronous on purpose:
+ * a sync append keeps frames in arrival order with no interleave, which an async
+ * write queue would not guarantee. It is also cheap and never lets an error
+ * reach the caller, so a spool write failure can never break bufferEvent or
+ * waiter delivery. No-op if no spool is open. Errors are swallowed after one
+ * breadcrumb.
+ */
+export declare function writeFrame(frame: ParsedSSE): void;
+/**
+ * Close the fd and clear state, but KEEP the file on disk. Called on explicit
+ * disable and on process exit. The file survives so a just-ended session is
+ * still readable; the GC reclaims it after the TTL. This matches logcat, which
+ * also keeps its capture file on disable and lets the GC reclaim it. Never
+ * called on the transient device-error path.
+ */
+export declare function stopSpool(): void;
+/**
+ * If the open file exceeds ROTATION_BYTES, rename it `.rotated-<ts>` (readable
+ * until the GC reclaims it) and open a fresh file. Rotation is the one place
+ * capture-everything yields to bounded disk: a normal session never rotates,
+ * this is only the disk-safety backstop.
+ *
+ * Safe rename-not-truncate, mirroring rotateCaptureIfNeeded: truncating in
+ * place would leave the next append past EOF. No-op if no spool is open or the
+ * file is under cap. Returns the new path, or null when nothing rotated.
+ */
+export declare function rotateSpoolIfNeeded(now?: number, capBytes?: number): string | null;
+export declare function registerCleanup(): void;
+export declare function _setSpoolDirForTest(dir: string): void;
+export declare function _setRotationBytesForTest(n: number): void;
+export declare function _setWriteCountForTest(n: number): void;
+export declare function _getRotationCheckEveryForTest(): number;
+export declare function _closeFdLeavingStateForTest(): void;