sidekick-shared 0.29.1 → 0.30.0

package/dist/providers/compressedRollouts.js

@@ -0,0 +1,380 @@
+"use strict";
+/**
+ * Reads Codex rollouts that Codex compressed.
+ *
+ * Codex compresses older rollouts in place to `rollout-<ts>-<id>.jsonl.zst`
+ * (one Zstandard frame), while its state database keeps the `.jsonl` path.
+ * Node ships `zlib.zstdDecompressSync` from 22.15 / 23.8; on older runtimes
+ * (Node 20, older VS Code Electron builds) compressed rollouts cannot be read
+ * and are skipped, reported once as a `read_failed` diagnostic.
+ *
+ * Every reader here takes either form: a `.jsonl` path reads as before, a
+ * `.jsonl.zst` path is decompressed. Compressed rollouts are complete (Codex
+ * only compresses rollouts it no longer writes), so they are read whole and
+ * never tailed.
+ *
+ * Node-only: reads files.
+ *
+ * @module providers/compressedRollouts
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__compressedRolloutTesting = exports.COMPRESSED_ROLLOUT_SUFFIX = void 0;
+exports.isCompressedRolloutPath = isCompressedRolloutPath;
+exports.isZstdDecompressionAvailable = isZstdDecompressionAvailable;
+exports.canReadCompressedRollouts = canReadCompressedRollouts;
+exports.resetCompressedRolloutDiagnostics = resetCompressedRolloutDiagnostics;
+exports.readRolloutBuffer = readRolloutBuffer;
+exports.readRolloutText = readRolloutText;
+exports.readRolloutBufferAsync = readRolloutBufferAsync;
+exports.readRolloutHead = readRolloutHead;
+exports.readRolloutHeadAsync = readRolloutHeadAsync;
+exports.readRolloutFirstLines = readRolloutFirstLines;
+exports.zstdFrameContentSize = zstdFrameContentSize;
+exports.statRolloutContent = statRolloutContent;
+exports.openRolloutReadHandle = openRolloutReadHandle;
+exports.resolveRolloutPath = resolveRolloutPath;
+const fs = __importStar(require("fs"));
+const zlib = __importStar(require("zlib"));
+/** File-name suffix of a compressed rollout. */
+exports.COMPRESSED_ROLLOUT_SUFFIX = '.jsonl.zst';
+/** `undefined`: use the runtime's; `null`: behave as if the runtime lacked it. */
+let decompressOverride;
+function zstdDecompressSync() {
+    if (decompressOverride !== undefined)
+        return decompressOverride;
+    const fn = zlib.zstdDecompressSync;
+    return typeof fn === 'function' ? fn.bind(zlib) : null;
+}
+/** Test hooks; not part of the public entry points. */
+exports.__compressedRolloutTesting = {
+    /** Replace the runtime's `zstdDecompressSync` (`null` = unavailable, `undefined` = restore). */
+    setDecompress(fn) {
+        decompressOverride = fn;
+    },
+};
+/** Whether a path (or file name) names a compressed rollout (`*.jsonl.zst`). */
+function isCompressedRolloutPath(filePath) {
+    return filePath.endsWith(exports.COMPRESSED_ROLLOUT_SUFFIX);
+}
+/** Whether this runtime can decompress Zstandard (`zlib.zstdDecompressSync`). */
+function isZstdDecompressionAvailable() {
+    return zstdDecompressSync() !== null;
+}
+const UNAVAILABLE_MESSAGE = 'Compressed Codex rollouts (.jsonl.zst) were skipped: this Node.js runtime has no zlib.zstdDecompressSync (Node 22.15 or later).';
+/** The runtime-limit diagnostic is reported once per process unless asked again. */
+let reportedUnavailable = false;
+function reportUnavailable(options) {
+    if (!options?.onDiagnostic || reportedUnavailable)
+        return;
+    reportedUnavailable = true;
+    options.onDiagnostic({
+        providerId: 'codex',
+        kind: 'read_failed',
+        severity: 'info',
+        phase: 'read',
+        message: UNAVAILABLE_MESSAGE,
+    });
+}
+function reportCorrupt(options, error) {
+    options?.onDiagnostic?.({
+        providerId: 'codex',
+        kind: 'read_failed',
+        severity: 'warning',
+        phase: 'read',
+        message: `A compressed Codex rollout could not be decompressed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+}
+/**
+ * Whether compressed rollouts can be read here; when they cannot, reports
+ * the runtime limit through `onDiagnostic` (once per process). Callers that
+ * list rollouts use it to leave `.jsonl.zst` files out instead of listing
+ * sessions they cannot read.
+ */
+function canReadCompressedRollouts(options) {
+    if (zstdDecompressSync())
+        return true;
+    reportUnavailable(options);
+    return false;
+}
+/** @internal Test hook: report the runtime limit again. */
+function resetCompressedRolloutDiagnostics() {
+    reportedUnavailable = false;
+}
+function decompress(input, options) {
+    const fn = zstdDecompressSync();
+    if (!fn) {
+        reportUnavailable(options);
+        return null;
+    }
+    try {
+        return fn(input);
+    }
+    catch (error) {
+        reportCorrupt(options, error);
+        return null;
+    }
+}
+/**
+ * The whole content of a rollout: a `.jsonl` file as stored, a `.jsonl.zst`
+ * file decompressed. `null` when the file cannot be read or decompressed
+ * (the latter reported through `onDiagnostic`).
+ */
+function readRolloutBuffer(filePath, options) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath);
+    }
+    catch {
+        return null;
+    }
+    return isCompressedRolloutPath(filePath) ? decompress(raw, options) : raw;
+}
+/** {@link readRolloutBuffer} decoded as UTF-8. */
+function readRolloutText(filePath, options) {
+    return readRolloutBuffer(filePath, options)?.toString('utf8') ?? null;
+}
+/** Async twin of {@link readRolloutBuffer}; decompression itself is synchronous. */
+async function readRolloutBufferAsync(filePath, options) {
+    let raw;
+    try {
+        raw = await fs.promises.readFile(filePath);
+    }
+    catch {
+        return null;
+    }
+    return isCompressedRolloutPath(filePath) ? decompress(raw, options) : raw;
+}
+/** Compressed bytes read per step while looking for a decompressed prefix. */
+const HEAD_STEP_BYTES = 64 * 1024;
+/**
+ * Decompresses only as much of a compressed prefix as is needed for
+ * `maxBytes` of content: a truncated Zstandard frame decompresses to the
+ * content of its complete blocks.
+ */
+function decompressHead(readCompressed, compressedSize, maxBytes, options) {
+    const fn = zstdDecompressSync();
+    if (!fn) {
+        reportUnavailable(options);
+        return null;
+    }
+    let length = Math.min(compressedSize, HEAD_STEP_BYTES);
+    for (;;) {
+        let out;
+        try {
+            out = fn(readCompressed(length));
+        }
+        catch (error) {
+            if (length >= compressedSize) {
+                reportCorrupt(options, error);
+                return null;
+            }
+            out = Buffer.alloc(0);
+        }
+        if (out.length >= maxBytes || length >= compressedSize)
+            return out.subarray(0, maxBytes);
+        length = Math.min(compressedSize, length * 4);
+    }
+}
+/**
+ * Up to `maxBytes` of a rollout's content from its start (decompressed for
+ * a `.jsonl.zst`). An empty buffer when the file cannot be read.
+ */
+function readRolloutHead(filePath, maxBytes, options) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return Buffer.alloc(0);
+    }
+    try {
+        const size = fs.fstatSync(fd).size;
+        const readPrefix = (length) => {
+            const buffer = Buffer.alloc(length);
+            const bytesRead = fs.readSync(fd, buffer, 0, length, 0);
+            return buffer.subarray(0, bytesRead);
+        };
+        if (!isCompressedRolloutPath(filePath))
+            return readPrefix(Math.min(size, Math.max(0, maxBytes)));
+        return decompressHead(readPrefix, size, Math.max(0, maxBytes), options) ?? Buffer.alloc(0);
+    }
+    catch {
+        return Buffer.alloc(0);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Async twin of {@link readRolloutHead}. */
+async function readRolloutHeadAsync(filePath, maxBytes, options) {
+    if (!isCompressedRolloutPath(filePath)) {
+        let handle = null;
+        try {
+            handle = await fs.promises.open(filePath, 'r');
+            const size = (await handle.stat()).size;
+            const length = Math.min(size, Math.max(0, maxBytes));
+            const buffer = Buffer.alloc(length);
+            const { bytesRead } = await handle.read(buffer, 0, length, 0);
+            return buffer.subarray(0, bytesRead);
+        }
+        catch {
+            return Buffer.alloc(0);
+        }
+        finally {
+            await handle?.close().catch(() => undefined);
+        }
+    }
+    // Compressed prefixes are small; one synchronous read keeps it simple.
+    return readRolloutHead(filePath, maxBytes, options);
+}
+/**
+ * The first `maxLines` complete lines of a rollout (decompressed for a
+ * `.jsonl.zst`) within `maxBytes` of content; a trailing line without a
+ * newline counts when the whole content fit.
+ */
+function readRolloutFirstLines(filePath, maxLines, maxBytes = 256 * 1024, options) {
+    const head = readRolloutHead(filePath, maxBytes + 1, options);
+    const complete = head.length <= maxBytes;
+    const text = head.subarray(0, maxBytes).toString('utf8');
+    const parts = text.split('\n');
+    const tail = parts.pop() ?? '';
+    const lines = parts.slice(0, maxLines);
+    if (lines.length < maxLines && complete && tail.trim())
+        lines.push(tail);
+    return lines;
+}
+/**
+ * The content size a Zstandard frame header declares (`Frame_Content_Size`),
+ * or `null` when the header omits it or is not a Zstandard frame. Skippable
+ * frames before it are not followed.
+ */
+function zstdFrameContentSize(header) {
+    if (header.length < 5 || header.readUInt32LE(0) !== 0xfd2fb528)
+        return null;
+    const descriptor = header[4];
+    const fcsFlag = descriptor >> 6;
+    const singleSegment = (descriptor >> 5) & 1;
+    const dictionaryIdFlag = descriptor & 3;
+    const offset = 5 + (singleSegment ? 0 : 1) + [0, 1, 2, 4][dictionaryIdFlag];
+    const fcsBytes = fcsFlag === 0 ? (singleSegment ? 1 : 0) : [0, 2, 4, 8][fcsFlag];
+    if (fcsBytes === 0 || header.length < offset + fcsBytes)
+        return null;
+    switch (fcsBytes) {
+        case 1:
+            return header[offset];
+        case 2:
+            return header.readUInt16LE(offset) + 256;
+        case 4:
+            return header.readUInt32LE(offset);
+        default: {
+            const value = header.readBigUInt64LE(offset);
+            return value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : null;
+        }
+    }
+}
+/**
+ * Stat of a rollout's content: the file's own for a `.jsonl`; for a
+ * `.jsonl.zst`, the decompressed size (from the frame header, else by
+ * decompressing) with the compressed file's mtime. Rejects like `fs.stat`
+ * when the file is missing; a compressed rollout that cannot be read
+ * rejects too.
+ */
+async function statRolloutContent(filePath, options) {
+    const stat = await fs.promises.stat(filePath);
+    if (!isCompressedRolloutPath(filePath))
+        return { size: stat.size, mtimeMs: stat.mtimeMs };
+    let declared = null;
+    let handle = null;
+    try {
+        handle = await fs.promises.open(filePath, 'r');
+        const header = Buffer.alloc(18);
+        const { bytesRead } = await handle.read(header, 0, header.length, 0);
+        declared = zstdFrameContentSize(header.subarray(0, bytesRead));
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+    if (declared !== null && isZstdDecompressionAvailable()) {
+        return { size: declared, mtimeMs: stat.mtimeMs };
+    }
+    const content = await readRolloutBufferAsync(filePath, options);
+    if (!content)
+        throw new Error('compressed rollout could not be read');
+    return { size: content.length, mtimeMs: stat.mtimeMs };
+}
+/** A read-only handle over a buffer, for scanning decompressed content. */
+function bufferHandle(content) {
+    return {
+        async read(buffer, offset, length, position) {
+            if (position >= content.length || length <= 0)
+                return { bytesRead: 0 };
+            const bytesRead = content.copy(buffer, offset, position, Math.min(content.length, position + length));
+            return { bytesRead };
+        },
+        async close() { },
+    };
+}
+/**
+ * Opens a rollout for positional reads over its content: a file handle for
+ * a `.jsonl`, the decompressed content for a `.jsonl.zst` (with `size`, the
+ * content length). Rejects when the file cannot be opened or decompressed.
+ */
+async function openRolloutReadHandle(filePath, options) {
+    if (!isCompressedRolloutPath(filePath)) {
+        return { handle: await fs.promises.open(filePath, 'r'), size: null };
+    }
+    const content = await readRolloutBufferAsync(filePath, options);
+    if (!content)
+        throw new Error('compressed rollout could not be read');
+    return { handle: bufferHandle(content), size: content.length };
+}
+/**
+ * The path of a rollout as stored now: `filePath` when it exists, else its
+ * compressed sibling (`<filePath>.zst`) when `includeCompressed` is set and
+ * that exists. `null` when neither does.
+ */
+function resolveRolloutPath(filePath, options = {}) {
+    if (!filePath)
+        return null;
+    if (fs.existsSync(filePath))
+        return filePath;
+    if (options.includeCompressed && !isCompressedRolloutPath(filePath)) {
+        const compressed = `${filePath}.zst`;
+        if (filePath.endsWith('.jsonl') && fs.existsSync(compressed))
+            return compressed;
+    }
+    return null;
+}

package/dist/providers/factory.d.ts

@@ -2,6 +2,11 @@ import type { ProviderId, SessionProviderBase, SessionProviderDiagnostic } from
 export interface CreateSessionProvidersOptions {
     providerIds?: readonly ProviderId[];
     onDiagnostic?: (diagnostic: SessionProviderDiagnostic) => void;
+    /**
+     * Codex: also discover and read compressed rollouts (`….jsonl.zst`); see
+     * `CodexProviderOptions.includeCompressedRollouts`. Default false.
+     */
+    includeCompressedRollouts?: boolean;
 }
 export interface CreateSessionProvidersResult {
     providers: SessionProviderBase[];

package/dist/providers/factory.js

@@ -40,7 +40,10 @@ function createSessionProviders(options = {}) {
                 ? new claudeCode_1.ClaudeCodeProvider(providerOptions)
                 : providerId === 'opencode'
                     ? new openCode_1.OpenCodeProvider(providerOptions)
-                    : new codex_1.CodexProvider(providerOptions));
+                    : new codex_1.CodexProvider({
+                        ...providerOptions,
+                        includeCompressedRollouts: options.includeCompressedRollouts === true,
+                    }));
         }
         catch {
             const diagnostic = {

package/dist/providers/rolloutWalker.d.ts

@@ -15,6 +15,10 @@
  * order over the whole history omit both (the `maxFiles` cap still applies);
  * a live session missed this way is picked up by its next watch event.
  *
+ * Codex compresses older rollouts to `rollout-…jsonl.zst`. Those are skipped
+ * unless `includeCompressed` is set; a compressed rollout whose `.jsonl` is
+ * still beside it is skipped either way (the `.jsonl` is the one to read).
+ *
  * The async walker accepts a {@link DirectoryListingCache}: unchanged
  * directories are then one stat each instead of a readdir plus a stat per
  * file, which is what makes repeated discovery over a large history cheap.
@@ -45,6 +49,13 @@ export interface WalkRolloutFilesOptions {
     sessionId?: string;
     /** Include zero-byte files (default false). */
     includeEmpty?: boolean;
+    /**
+     * Also return compressed rollouts (`rollout-…jsonl.zst`; default false).
+     * Reading them needs `zlib.zstdDecompressSync` (see
+     * `providers/compressedRollouts`). A `cache` remembers which names a walk
+     * accepted, so do not share one between walks that differ in this option.
+     */
+    includeCompressed?: boolean;
     /** Reuse directory listings across walks (async walker only). */
     cache?: DirectoryListingCache;
     /** With `cache`: re-stat recently modified files even in unchanged directories. */
@@ -54,11 +65,13 @@ export interface WalkRolloutFilesOptions {
 }
 export declare const DEFAULT_ROLLOUT_WALK_MAX_DEPTH = 6;
 export declare const DEFAULT_ROLLOUT_WALK_MAX_FILES = 20000;
-/** Test if a filename is a Codex rollout file. */
+/** Test if a filename is a Codex rollout file (`rollout-….jsonl`; not compressed ones). */
 export declare function isRolloutFile(filename: string): boolean;
+/** Test if a filename is a compressed Codex rollout (`rollout-….jsonl.zst`). */
+export declare function isCompressedRolloutFile(filename: string): boolean;
 /**
  * Extract the session UUID from a rollout filename.
- * Format: rollout-<timestamp>-<uuid>.jsonl -> <uuid>
+ * Format: rollout-<timestamp>-<uuid>.jsonl (or .jsonl.zst) -> <uuid>
  */
 export declare function extractRolloutSessionId(filename: string): string;
 /**

package/dist/providers/rolloutWalker.js

@@ -16,6 +16,10 @@
  * order over the whole history omit both (the `maxFiles` cap still applies);
  * a live session missed this way is picked up by its next watch event.
  *
+ * Codex compresses older rollouts to `rollout-…jsonl.zst`. Those are skipped
+ * unless `includeCompressed` is set; a compressed rollout whose `.jsonl` is
+ * still beside it is skipped either way (the `.jsonl` is the one to read).
+ *
  * The async walker accepts a {@link DirectoryListingCache}: unchanged
  * directories are then one stat each instead of a readdir plus a stat per
  * file, which is what makes repeated discovery over a large history cheap.
@@ -58,6 +62,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_ROLLOUT_WALK_MAX_FILES = exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH = void 0;
 exports.isRolloutFile = isRolloutFile;
+exports.isCompressedRolloutFile = isCompressedRolloutFile;
 exports.extractRolloutSessionId = extractRolloutSessionId;
 exports.isDatedDirectoryBefore = isDatedDirectoryBefore;
 exports.walkRolloutFiles = walkRolloutFiles;
@@ -66,16 +71,23 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH = 6;
 exports.DEFAULT_ROLLOUT_WALK_MAX_FILES = 20_000;
-/** Test if a filename is a Codex rollout file. */
+/** Test if a filename is a Codex rollout file (`rollout-….jsonl`; not compressed ones). */
 function isRolloutFile(filename) {
     return filename.startsWith('rollout-') && filename.endsWith('.jsonl');
 }
+/** Test if a filename is a compressed Codex rollout (`rollout-….jsonl.zst`). */
+function isCompressedRolloutFile(filename) {
+    return filename.startsWith('rollout-') && filename.endsWith('.jsonl.zst');
+}
 /**
  * Extract the session UUID from a rollout filename.
- * Format: rollout-<timestamp>-<uuid>.jsonl -> <uuid>
+ * Format: rollout-<timestamp>-<uuid>.jsonl (or .jsonl.zst) -> <uuid>
  */
 function extractRolloutSessionId(filename) {
-    const base = path.basename(filename, '.jsonl');
+    const name = path.basename(filename);
+    const base = name.endsWith('.jsonl.zst')
+        ? name.slice(0, -'.jsonl.zst'.length)
+        : path.basename(name, '.jsonl');
     // rollout-YYYYMMDD-HHMMSS-<uuid> or rollout-<timestamp>-<uuid>
     const parts = base.split('-');
     // The UUID is typically the last 5 segments (8-4-4-4-12)
@@ -99,6 +111,7 @@ function walkState(options) {
         since: options.since !== undefined && Number.isFinite(options.since) ? options.since : null,
         sessionId: options.sessionId ? options.sessionId.trim().toLowerCase() : null,
         includeEmpty: options.includeEmpty ?? false,
+        includeCompressed: options.includeCompressed ?? false,
         cache: options.cache ?? null,
         revalidateRecent: options.revalidateRecent ?? false,
         stats: options.stats,
@@ -109,10 +122,15 @@ function byNameDescending(a, b) {
     return b.name.localeCompare(a.name);
 }
 function matchesFilter(state, name) {
-    if (!isRolloutFile(name))
+    if (!isRolloutFile(name) && !(state.includeCompressed && isCompressedRolloutFile(name))) {
         return false;
+    }
     return (state.sessionId === null || extractRolloutSessionId(name).toLowerCase() === state.sessionId);
 }
+/** A compressed rollout whose uncompressed rollout is listed beside it. */
+function shadowedByPlain(name, has) {
+    return isCompressedRolloutFile(name) && has(name.slice(0, -'.zst'.length));
+}
 function record(state, fullPath, name, stat) {
     if (!state.includeEmpty && stat.size <= 0)
         return;
@@ -171,11 +189,14 @@ function visitSync(state, dir, depth, segments) {
         return;
     }
     entries.sort(byNameDescending);
+    const names = state.includeCompressed ? new Set(entries.map((entry) => entry.name)) : null;
     for (const entry of entries) {
         if (state.results.length >= state.cap)
             return;
         if (!entry.isFile() || !matchesFilter(state, entry.name))
             continue;
+        if (names && shadowedByPlain(entry.name, (name) => names.has(name)))
+            continue;
         const fullPath = path.join(dir, entry.name);
         try {
             record(state, fullPath, entry.name, fs.statSync(fullPath));
@@ -226,6 +247,11 @@ async function visitCached(state, cache, dir, depth, segments) {
         const stat = listing.files.get(name);
         if (!stat)
             continue;
+        // The listing may come from a walk with other options: filter again.
+        if (!matchesFilter(state, name))
+            continue;
+        if (shadowedByPlain(name, (other) => listing.files.has(other)))
+            continue;
         record(state, path.join(dir, name), name, { size: stat.sizeBytes, mtimeMs: stat.mtimeMs });
     }
     await yieldToEventLoop();
@@ -250,12 +276,15 @@ async function visitAsync(state, dir, depth, segments) {
         return;
     }
     entries.sort(byNameDescending);
+    const names = state.includeCompressed ? new Set(entries.map((entry) => entry.name)) : null;
     let sinceYield = 0;
     for (const entry of entries) {
         if (state.results.length >= state.cap)
             return;
         if (!entry.isFile() || !matchesFilter(state, entry.name))
             continue;
+        if (names && shadowedByPlain(entry.name, (name) => names.has(name)))
+            continue;
         const fullPath = path.join(dir, entry.name);
         try {
             const stat = await fs.promises.stat(fullPath);

package/dist/providers/types.d.ts

@@ -12,6 +12,7 @@ import type { ReadSessionContextSnapshotOptions, SessionContextSnapshot } from '
 import type { SessionEvent, SubagentStats, TokenUsage, ContextAttribution } from '../types/sessionEvent';
 import { SESSION_PROVIDER_IDS } from '../providerIds';
 import type { AggregatedCostProvenance } from '../aggregation/types';
+import type { JsonlTailResetReason } from '../watchers/jsonlTail';
 /** Stable runtime list for consumers that must enumerate session providers. */
 export { SESSION_PROVIDER_IDS } from '../providerIds';
 export type ProviderId = (typeof SESSION_PROVIDER_IDS)[number];
@@ -163,6 +164,12 @@ export interface ProviderRuntimeStatus {
     kind: 'available' | 'home_unavailable' | 'config_unreadable' | 'db_missing' | 'sqlite_missing' | 'sqlite_blocked' | 'query_failed';
     message?: string;
 }
+/** Why a {@link SessionReader} started over from offset 0 (see `SessionReader.lastReset`). */
+export interface SessionReaderReset {
+    reason: JsonlTailResetReason;
+    /** The committed position (`getPosition()`) before the restart. */
+    previousPosition: number;
+}
 /**
  * Incremental reader for session data.
  *
@@ -184,8 +191,22 @@ export interface SessionReader {
     getPosition(): number;
     /** Seek to a specific position (byte offset for JSONL, timestamp for DB-backed). */
     seekTo(position: number): void;
-    /** Check if file was truncated (size < position). */
+    /**
+     * Whether the last `readNew()` restarted from offset 0 because the file was
+     * truncated, rewritten, or replaced. Its events are then the session from
+     * the beginning: discard anything built from earlier reads before
+     * processing them. (Before 0.30.0 the built-in readers reported only a
+     * file that shrank below the read position.)
+     */
     wasTruncated(): boolean;
+    /**
+     * Why the last `readNew()` restarted from offset 0, and the committed
+     * position it left: `truncated` (the file shrank below the read
+     * position), `rewritten` (its first bytes, or the byte before the resume
+     * point, changed), or `replaced` (another file now has the path). `null`
+     * when it continued where it was. Optional; the JSONL readers implement it.
+     */
+    lastReset?(): SessionReaderReset | null;
     /**
      * Parse state the reader needs, beyond `getPosition()`, to continue
      * correctly after a restart: JSON-serializable data to persist together