@myagentroam/agent 0.10.59 → 0.10.60

package/dist/agent-core/session/{jsonl-store.js → store/jsonl-store.js}

@@ -1,26 +1,23 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { constants } from 'node:fs';
-import { copyFile, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { MarAgentError } from '../error.js';
-import { completeToolResultResources, cleanupUnreferencedToolResources, bindToolResultResources, copyToolResultResources, readToolResultResource, toolResultResourceFiles, writeToolResultResource } from './tool-result-resources.js';
-import { acquireFileLock } from '../storage/file-lock.js';
-import { cloneCoreJson } from '../extensions/data.js';
-import { applyCodeModeStateMutations, parseCodeModeStateMutations, restoreCodeModeState } from '../tools/code-mode/state.js';
-import { todoItemsFromSnapshot } from '../tools/agent/todo.js';
-import { contextGcBaseFromRecords, contextGcBaseSequence, contextGcMinimumUsageGrowth, contextGcSourceProjectionHash, latestValidContextGcCheckpoint, normalizeContextGcReplacements, parseContextGcCheckpoint, sameContextGcBase, validateContextGcCheckpoint } from './context-gc-checkpoint.js';
-import { beginSessionStorageTransaction, isUnjournaledTransactionFile, recoverSessionStorageTransaction } from './transaction-recovery.js';
-const MAX_SEGMENT_BYTES = 16 * 1024 * 1024;
-const REVERSE_READ_CHUNK_BYTES = 64 * 1024;
-const MAX_HISTORY_PAGE_FILES = 32;
-const MAX_HISTORY_PAGE_OFFSETS = 128;
-const MAX_INPUT_IMAGES = 5;
-const MAX_INPUT_IMAGE_BYTES = 5 * 1024 * 1024;
-const MAX_INPUT_IMAGES_BYTES = 10 * 1024 * 1024;
+import { MarAgentError } from '../../error.js';
+import { cloneCoreJson } from '../../extensions/data.js';
+import { acquireFileLock } from '../../storage/file-lock.js';
+import { todoItemsFromSnapshot } from '../../tools/agent/todo.js';
+import { applyCodeModeStateMutations, parseCodeModeStateMutations, restoreCodeModeState } from '../../tools/code-mode/state.js';
+import { contextGcBaseFromRecords, contextGcBaseSequence, contextGcMinimumUsageGrowth, latestValidContextGcCheckpoint, normalizeContextGcReplacements, parseContextGcCheckpoint, sameContextGcBase, validateContextGcCheckpoint } from '../context-gc-checkpoint.js';
+import { bindToolResultResources, cleanupUnreferencedToolResources, completeToolResultResources, copyToolResultResources, readToolResultResource, toolResultResourceFiles, writeToolResultResource } from '../tool-result-resources.js';
+import { beginSessionStorageTransaction, isUnjournaledTransactionFile, recoverSessionStorageTransaction } from '../transaction-recovery.js';
+import { extensionCheckpointFromPayload, indexExtensionCheckpoint, restoreExtensionCheckpoint, updateSessionCurrentState } from './current-state.js';
+import { decodeSessionListCursor, encodeSessionListCursor, mergeFirstUserMessagePreviewCache, normalizeSessionSource, persistSessionIndex, readSessionIndex, sessionListFilter, sessionMatchesFilter, sessionTreeIds } from './directory-index.js';
+import { deriveExecutionState, executionModelFromRecord, isCompactCheckpoint, sameResumeIndex, userMessagePreviewFromRecord } from './execution-state.js';
+import { forkedPayload, renameIfExists, restoreRenamedFiles, retainedSessionTitle, stageSessionSegments, stageUnreferencedImages } from './history.js';
+import { MAX_INPUT_IMAGES, copyGeneratedImages, copyInputImages, generatedImageFileNames, inputImageReference, inputImageReferences, inputImageReferencesFromRecords, readInputImageBytes, recoverPendingInputImages, validInputImageFileName, writeInputImages } from './images.js';
+import { MAX_SEGMENT_BYTES, appendRecordBytes, readRecordPageFromTail, readRecords, readRecordsFromHead, readRecordsFromTail, repairSegmentTail, segmentNumberFromPath } from './records.js';
 const MAX_CONTEXTUAL_WORLD_STATE_BYTES = 8 * 1024 * 1024;
 const CONTEXTUAL_WORLD_STATE_FILE = 'context-world-state.json';
-const INPUT_IMAGE_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
 /** SDK-owned JSONL history with per-HOME in-process sharing and cross-process file locks. */
 export class JsonlSessionStore {
     static #instances = new Map();
@@ -435,55 +432,7 @@ export class JsonlSessionStore {
         if (images.length > MAX_INPUT_IMAGES)
             throw new MarAgentError('MAR_AGENT_HOST_LIMIT_EXCEEDED', 'Too many image inputs were provided.');
         const directory = join(this.sessionDirectory(sessionId), 'input_images');
-        await mkdir(directory, { recursive: true, mode: 0o700 });
-        const written = [];
-        const pending = [];
-        let temporary;
-        let totalBytes = 0;
-        try {
-            const metadata = [];
-            for (const image of images) {
-                if (!INPUT_IMAGE_MIME_TYPES.has(image.mimeType))
-                    throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Image input MIME type is unsupported.');
-                const data = Buffer.from(image.dataBase64, 'base64');
-                totalBytes += data.byteLength;
-                if (data.byteLength === 0 ||
-                    data.byteLength > MAX_INPUT_IMAGE_BYTES ||
-                    totalBytes > MAX_INPUT_IMAGES_BYTES)
-                    throw new MarAgentError('MAR_AGENT_HOST_LIMIT_EXCEEDED', 'Image input exceeds the supported size limit.');
-                const fileName = `${randomUUID()}.bin`;
-                temporary = join(directory, `.${fileName}.${randomUUID()}.tmp`);
-                const handle = await open(temporary, 'wx', 0o600);
-                try {
-                    await handle.writeFile(data);
-                    await handle.sync();
-                }
-                finally {
-                    await handle.close();
-                }
-                const marker = join(directory, `.${fileName}.pending`);
-                await writeFile(marker, '', { mode: 0o600, flag: 'wx', flush: true });
-                pending.push(marker);
-                await rename(temporary, join(directory, fileName));
-                temporary = undefined;
-                written.push(fileName);
-                metadata.push({
-                    name: image.name,
-                    mimeType: image.mimeType,
-                    byteSize: data.byteLength,
-                    fileName,
-                    sha256: createHash('sha256').update(data).digest('hex')
-                });
-            }
-            return metadata;
-        }
-        catch (error) {
-            if (temporary !== undefined)
-                await rm(temporary, { force: true }).catch(() => undefined);
-            await Promise.all(pending.map((marker) => rm(marker, { force: true })));
-            await Promise.all(written.map((fileName) => rm(join(directory, fileName), { force: true }).catch(() => undefined)));
-            throw error;
-        }
+        return writeInputImages(directory, images);
     }
     async writeToolResultResource(sessionId, text) {
         this.#assertOpen();
@@ -1036,20 +985,17 @@ export class JsonlSessionStore {
         catch {
             // The first append creates the first segment.
         }
-        const handle = await open(path, 'a', 0o600);
         try {
-            const bytes = Buffer.from(serialized);
-            let offset = 0;
-            while (offset < bytes.length) {
-                const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset);
-                if (bytesWritten === 0)
-                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session append is incomplete.');
-                offset += bytesWritten;
-            }
-            await handle.sync();
+            await appendRecordBytes(path, serialized);
         }
-        finally {
-            await handle.close();
+        catch (error) {
+            // A failed write/sync/close can leave a complete record on disk.
+            const lease = this.#shared.writerLeases.get(sessionId);
+            if (lease) {
+                delete lease.codeState;
+                delete lease.extensionCheckpoints;
+            }
+            throw error;
         }
         // Index refreshes and commits can replace metadata during file I/O. Publish all
         // durable-record metadata onto the current entry without another await boundary.
@@ -1077,6 +1023,7 @@ export class JsonlSessionStore {
             this.#shared.index.revision++;
             this.#markIndexDirty(sessionId);
         }
+        updateSessionCurrentState(this.#shared.writerLeases.get(sessionId), record.type, serialized);
         await completeToolResultResources(this.sessionDirectory(sessionId), record);
         if (record.type === 'turn.user' &&
             isObject(record.payload) &&
@@ -1106,10 +1053,32 @@ export class JsonlSessionStore {
         }
     }
     async readCodeModeState(sessionId) {
-        return restoreCodeModeState(await this.read(sessionId));
+        return this.#serializeRecordOperation(sessionId, () => this.#readCodeModeState(sessionId));
+    }
+    async #readCodeModeState(sessionId) {
+        this.#assertOpen();
+        const lease = this.#shared.writerLeases.get(sessionId);
+        if (lease?.owner === undefined)
+            return restoreCodeModeState(await this.#readRecords(sessionId));
+        lease.codeState ??= restoreCodeModeState(await this.#readRecords(sessionId));
+        return applyCodeModeStateMutations(lease.codeState, []);
     }
     async readExtensionCheckpoint(sessionId, extensionId, key) {
-        return restoreExtensionCheckpoint(await this.read(sessionId), extensionId, key);
+        return this.#serializeRecordOperation(sessionId, () => this.#readExtensionCheckpoint(sessionId, extensionId, key));
+    }
+    async #readExtensionCheckpoint(sessionId, extensionId, key) {
+        this.#assertOpen();
+        const lease = this.#shared.writerLeases.get(sessionId);
+        if (lease?.owner === undefined)
+            return restoreExtensionCheckpoint(await this.#readRecords(sessionId), extensionId, key);
+        if (!lease.extensionCheckpoints) {
+            const index = new Map();
+            for (const record of await this.#readRecords(sessionId))
+                if (record.type === 'extension.checkpoint.updated')
+                    indexExtensionCheckpoint(index, record.payload);
+            lease.extensionCheckpoints = index;
+        }
+        return extensionCheckpointFromPayload(lease.extensionCheckpoints.get(extensionId)?.get(key));
     }
     async writeExtensionCheckpoint(sessionId, extensionId, key, value, expectedRevision, input) {
         if (typeof key !== 'string' ||
@@ -1121,7 +1090,7 @@ export class JsonlSessionStore {
         const release = await this.acquireSessionWriteLease(sessionId, input.owner);
         try {
             return await this.#serializeRecordOperation(sessionId, async () => {
-                const current = restoreExtensionCheckpoint(await this.#readRecords(sessionId), extensionId, key);
+                const current = await this.#readExtensionCheckpoint(sessionId, extensionId, key);
                 if (expectedRevision !== undefined && expectedRevision !== current.revision)
                     throw new MarAgentError('MAR_AGENT_EXTENSION_DATA_CONFLICT', 'Checkpoint revision changed before commit.');
                 input.signal.throwIfAborted();
@@ -1203,70 +1172,61 @@ export class JsonlSessionStore {
     async readContext(sessionId) {
         return (await this.readExecutionState(sessionId)).contextRecords;
     }
-    async contextGcProjectionHash(sessionId, boundarySequence) {
-        this.#assertOpen();
-        const hash = contextGcSourceProjectionHash((await this.readExecutionState(sessionId)).contextRecords, boundarySequence);
-        if (!hash)
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC projection boundary is invalid.');
-        return hash;
-    }
-    /** Recheck a planned GC checkpoint against authoritative records before appending it. */
-    async commitContextGc(sessionId, draft) {
+    /** Compare the planned sequence inside the existing record writer queue. */
+    async commitContextGc(sessionId, draft, planningRecords) {
         this.#assertOpen();
-        const meta = this.#shared.index.sessions.find((item) => item.id === sessionId);
-        if (!meta)
-            throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
-        const records = (await this.readExecutionState(sessionId)).contextRecords;
-        const boundarySequence = records.at(-1)?.sequence;
-        if (boundarySequence === undefined || boundarySequence !== draft.boundarySequence)
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC projection changed before checkpoint commit.');
-        const base = contextGcBaseFromRecords(records, boundarySequence);
-        const sourceProjectionHash = contextGcSourceProjectionHash(records, boundarySequence, draft.base);
-        if (!sameContextGcBase(base, draft.base) ||
-            sourceProjectionHash === undefined ||
-            sourceProjectionHash !== draft.sourceProjectionHash)
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC source projection validation failed.');
-        const previous = latestValidContextGcCheckpoint(records, boundarySequence, meta.workspace);
-        if (previous && !sameContextGcBase(previous.payload.base, draft.base))
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint base changed before commit.');
-        if (previous) {
-            const minimumUsageGrowth = contextGcMinimumUsageGrowth(draft.trigger.contextWindowTokens);
-            if (draft.trigger.normalRolloutOrdinal - previous.payload.trigger.normalRolloutOrdinal < 2 ||
-                draft.trigger.contextInputTokens - previous.payload.trigger.contextInputTokens <
-                    minimumUsageGrowth)
-                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint interval validation failed.');
-        }
-        const plannedReplacements = normalizeContextGcReplacements(draft.replacements);
-        if (!plannedReplacements || plannedReplacements.length === 0)
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint must contain a replacement.');
-        const replacements = normalizeContextGcReplacements([
-            ...(previous?.payload.replacements ?? []),
-            ...plannedReplacements
-        ]);
-        if (!replacements ||
-            (previous && isDeepStrictEqual(replacements, previous.payload.replacements)))
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC replacement map is invalid.');
-        const payload = {
-            ...structuredClone(draft),
-            checkpointId: randomUUID(),
-            generation: (previous?.payload.generation ?? 0) + 1,
-            replacements
-        };
-        const candidate = {
-            schemaVersion: 1,
-            recordId: randomUUID(),
-            sequence: boundarySequence + 1,
-            timestamp: new Date().toISOString(),
-            sessionId,
-            type: 'context.gc.completed',
-            payload
-        };
-        if (Buffer.byteLength(JSON.stringify(payload)) >= MAX_SEGMENT_BYTES ||
-            validateContextGcCheckpoint([...records, candidate], candidate, meta.workspace) === undefined)
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint validation failed.');
-        return this.append(sessionId, {
-            type: 'context.gc.completed',
-            payload
+        const records = planningRecords ?? (await this.readExecutionState(sessionId)).contextRecords;
+        return this.#serializeRecordOperation(sessionId, async () => {
+            const meta = this.#shared.index.sessions.find((item) => item.id === sessionId);
+            if (!meta)
+                throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+            const boundarySequence = meta.nextSequence - 1;
+            if (boundarySequence !== draft.boundarySequence)
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC projection changed before checkpoint commit.');
+            if (records.at(-1)?.sequence !== boundarySequence ||
+                records.at(-1)?.sessionId !== sessionId ||
+                !sameContextGcBase(contextGcBaseFromRecords(records, boundarySequence), draft.base))
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC planning boundary is invalid.');
+            const previous = latestValidContextGcCheckpoint(records, boundarySequence, meta.workspace);
+            if (previous) {
+                const minimumUsageGrowth = contextGcMinimumUsageGrowth(draft.trigger.contextWindowTokens);
+                if (draft.trigger.normalRolloutOrdinal - previous.payload.trigger.normalRolloutOrdinal < 2 ||
+                    draft.trigger.contextInputTokens - previous.payload.trigger.contextInputTokens <
+                        minimumUsageGrowth)
+                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint interval validation failed.');
+            }
+            const plannedReplacements = normalizeContextGcReplacements(draft.replacements);
+            if (!plannedReplacements || plannedReplacements.length === 0)
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint must contain a replacement.');
+            const replacements = normalizeContextGcReplacements([
+                ...(previous?.payload.replacements ?? []),
+                ...plannedReplacements
+            ]);
+            if (!replacements ||
+                (previous && isDeepStrictEqual(replacements, previous.payload.replacements)))
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC replacement map is invalid.');
+            const payload = {
+                ...structuredClone(draft),
+                checkpointId: randomUUID(),
+                generation: (previous?.payload.generation ?? 0) + 1,
+                replacements
+            };
+            const candidate = {
+                schemaVersion: 1,
+                recordId: randomUUID(),
+                sequence: boundarySequence + 1,
+                timestamp: new Date().toISOString(),
+                sessionId,
+                type: 'context.gc.completed',
+                payload
+            };
+            if (Buffer.byteLength(JSON.stringify(payload)) >= MAX_SEGMENT_BYTES ||
+                validateContextGcCheckpoint(records, candidate, meta.workspace, previous?.payload.replacements) === undefined)
+                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Context GC checkpoint validation failed.');
+            return this.#appendRecord(sessionId, {
+                type: 'context.gc.completed',
+                payload
+            });
         });
     }
     async readPage(sessionId, input = {}) {
@@ -1411,6 +1371,8 @@ export class JsonlSessionStore {
             await lease.release();
         }
         finally {
+            delete lease.codeState;
+            delete lease.extensionCheckpoints;
             this.#shared.writerLeases.delete(sessionId);
         }
     }
@@ -1887,67 +1849,6 @@ export class JsonlSessionStore {
         JsonlSessionStore.#instances.delete(this.#shared.root);
     }
 }
-/** Merge a derived cache only onto the unchanged history it was computed from. */
-function mergeFirstUserMessagePreviewCache(current, cached) {
-    if (cached.resume?.firstUserMessageIndexed !== true ||
-        current.nextSequence !== cached.nextSequence ||
-        current.storageTransactionId !== cached.storageTransactionId ||
-        current.resume?.firstUserMessagePreview !== undefined ||
-        (current.resume?.firstUserMessageIndexed === true &&
-            cached.resume.firstUserMessagePreview === undefined))
-        return current;
-    return {
-        ...current,
-        resume: {
-            ...(current.resume ?? { version: 1, todoRevision: 0 }),
-            firstUserMessageIndexed: true,
-            ...(cached.resume?.firstUserMessagePreview === undefined
-                ? {}
-                : { firstUserMessagePreview: cached.resume.firstUserMessagePreview })
-        }
-    };
-}
-async function readSessionIndex(path) {
-    let raw;
-    try {
-        raw = await readFile(path, 'utf8');
-    }
-    catch (cause) {
-        if (cause.code === 'ENOENT')
-            return undefined;
-        throw cause;
-    }
-    try {
-        const value = JSON.parse(raw);
-        if (value?.version !== 1 ||
-            !Number.isSafeInteger(value.revision) ||
-            value.revision < 0 ||
-            !Array.isArray(value.sessions) ||
-            value.sessions.some((session) => typeof session?.id !== 'string' ||
-                !/^[0-9a-f-]{36}$/iu.test(session.id) ||
-                typeof session.title !== 'string' ||
-                typeof session.workspace !== 'string' ||
-                typeof session.createdAt !== 'string' ||
-                typeof session.lastActivityAt !== 'string' ||
-                !Number.isSafeInteger(session.nextSequence) ||
-                session.nextSequence < 1))
-            throw new Error('invalid index shape');
-        return value;
-    }
-    catch (cause) {
-        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is corrupt.', { cause });
-    }
-}
-async function persistSessionIndex(path, index) {
-    const temporary = `${path}.${randomUUID()}.tmp`;
-    try {
-        await writeFile(temporary, JSON.stringify(index), { mode: 0o600, flag: 'wx', flush: true });
-        await rename(temporary, path);
-    }
-    finally {
-        await rm(temporary, { force: true });
-    }
-}
 async function sessionDirectoryExists(path) {
     try {
         await lstat(path);
@@ -1959,17 +1860,6 @@ async function sessionDirectoryExists(path) {
         throw error;
     }
 }
-async function renameIfExists(from, to) {
-    try {
-        await rename(from, to);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return false;
-        throw error;
-    }
-}
 async function recoverContextualWorldStateTransactions(root, meta) {
     const directory = join(root, 'sessions', meta.id);
     let names;
@@ -2002,125 +1892,6 @@ async function recoverContextualWorldStateTransactions(root, meta) {
             await rename(backup, canonical);
     }
 }
-function generatedImageFileNames(records) {
-    const names = new Set();
-    for (const record of records) {
-        if (record.type !== 'tool.completed' || !isObject(record.payload))
-            continue;
-        const artifacts = record.payload.artifacts;
-        if (!Array.isArray(artifacts))
-            continue;
-        for (const artifact of artifacts) {
-            if (!isObject(artifact) ||
-                artifact.kind !== 'image' ||
-                typeof artifact.fileName !== 'string' ||
-                basename(artifact.fileName) !== artifact.fileName ||
-                !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}\.png$/u.test(artifact.fileName))
-                continue;
-            names.add(artifact.fileName);
-        }
-    }
-    return [...names];
-}
-async function stageSessionSegments(sessionDirectory, records, operation = 'rollback') {
-    let group;
-    if (records.length === 0)
-        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.');
-    const transactionId = randomUUID();
-    const files = [];
-    const segments = [];
-    const flush = async () => {
-        if (group === undefined)
-            return;
-        const number = segments.length + 1;
-        const path = join(sessionDirectory, `events-${String(number).padStart(6, '0')}.jsonl`);
-        const temporaryPath = `${path}.${transactionId}.${operation}-tmp`;
-        const handle = await open(temporaryPath, 'wx', 0o600);
-        files.push({ path, temporaryPath });
-        try {
-            await handle.writeFile(group.lines.join(''));
-            await handle.sync();
-        }
-        finally {
-            await handle.close();
-        }
-        segments.push({
-            number,
-            firstSequence: group.firstSequence,
-            lastSequence: group.lastSequence,
-            bytes: group.bytes
-        });
-        group = undefined;
-    };
-    try {
-        for (const record of records) {
-            const line = `${JSON.stringify(record)}\n`;
-            const bytes = Buffer.byteLength(line);
-            if (group !== undefined && group.bytes > 0 && group.bytes + bytes > MAX_SEGMENT_BYTES)
-                await flush();
-            if (group === undefined) {
-                group = {
-                    lines: [],
-                    bytes: 0,
-                    firstSequence: record.sequence,
-                    lastSequence: record.sequence
-                };
-            }
-            group.lines.push(line);
-            group.bytes += bytes;
-            group.lastSequence = record.sequence;
-        }
-        await flush();
-        return { files, segments };
-    }
-    catch (error) {
-        await Promise.all(files.map((item) => rm(item.temporaryPath, { force: true }))).catch(() => undefined);
-        throw error;
-    }
-}
-async function stageUnreferencedImages(sessionDirectory, directoryName, retained, transactionId) {
-    const directory = join(sessionDirectory, directoryName);
-    let names;
-    try {
-        names = await readdir(directory);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw error;
-    }
-    const moved = [];
-    try {
-        for (const name of names) {
-            if (retained.has(name))
-                continue;
-            const from = join(directory, name);
-            const trash = join(directory, `.${name}.${transactionId}.rollback-trash`);
-            await rename(from, trash);
-            moved.push({ from: trash, to: from, trash });
-        }
-        return moved;
-    }
-    catch (error) {
-        await restoreRenamedFiles(moved);
-        throw error;
-    }
-}
-async function restoreRenamedFiles(files) {
-    for (const file of files.toReversed())
-        await rename(file.from, file.to).catch(() => undefined);
-}
-function retainedSessionTitle(records, fallback) {
-    let title = fallback;
-    for (const record of records) {
-        if ((record.type === 'session.created' || record.type === 'session.title.updated') &&
-            isObject(record.payload) &&
-            typeof record.payload.title === 'string' &&
-            record.payload.title.trim().length > 0)
-            title = record.payload.title;
-    }
-    return title;
-}
 function restoreSessionMeta(meta, original) {
     meta.id = original.id;
     meta.title = original.title;
@@ -2145,722 +1916,6 @@ function restoreSessionMeta(meta, original) {
     else
         meta.segments = structuredClone(original.segments);
 }
-async function copyGeneratedImages(sourceSessionDirectory, targetSessionDirectory, fileNames) {
-    if (fileNames.length === 0)
-        return;
-    const source = join(sourceSessionDirectory, 'generated_images');
-    const target = join(targetSessionDirectory, 'generated_images');
-    await mkdir(target, { recursive: true });
-    for (const fileName of fileNames)
-        await copyFile(join(source, fileName), join(target, fileName));
-}
-function inputImageReferencesFromRecords(records) {
-    const references = new Map();
-    for (const record of records) {
-        if (record.type !== 'turn.user' || !isObject(record.payload))
-            continue;
-        for (const reference of inputImageReferences(record.payload.images)) {
-            const existing = references.get(reference.fileName);
-            if (existing !== undefined &&
-                (existing.mimeType !== reference.mimeType ||
-                    existing.byteSize !== reference.byteSize ||
-                    existing.sha256 !== reference.sha256))
-                throw corruptInputImageReference();
-            references.set(reference.fileName, reference);
-        }
-    }
-    return [...references.values()];
-}
-function inputImageReferences(value) {
-    if (!Array.isArray(value))
-        return [];
-    const references = [];
-    let totalBytes = 0;
-    for (const image of value) {
-        const reference = inputImageReference(image);
-        if (reference === undefined)
-            continue;
-        totalBytes += reference.byteSize;
-        if (references.length >= MAX_INPUT_IMAGES || totalBytes > MAX_INPUT_IMAGES_BYTES)
-            throw corruptInputImageReference();
-        references.push(reference);
-    }
-    return references;
-}
-function inputImageReference(value) {
-    if (!isObject(value) || !Object.hasOwn(value, 'fileName'))
-        return undefined;
-    if (typeof value.name !== 'string' ||
-        typeof value.mimeType !== 'string' ||
-        !INPUT_IMAGE_MIME_TYPES.has(value.mimeType) ||
-        typeof value.byteSize !== 'number' ||
-        !Number.isSafeInteger(value.byteSize) ||
-        value.byteSize <= 0 ||
-        value.byteSize > MAX_INPUT_IMAGE_BYTES ||
-        typeof value.fileName !== 'string' ||
-        !validInputImageFileName(value.fileName) ||
-        typeof value.sha256 !== 'string' ||
-        !/^[a-f0-9]{64}$/u.test(value.sha256))
-        throw corruptInputImageReference();
-    return {
-        name: value.name,
-        fileName: value.fileName,
-        mimeType: value.mimeType,
-        byteSize: value.byteSize,
-        sha256: value.sha256
-    };
-}
-function validInputImageFileName(fileName) {
-    return (basename(fileName) === fileName && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}\.bin$/u.test(fileName));
-}
-async function readInputImageBytes(directory, reference) {
-    const path = join(directory, reference.fileName);
-    for (let attempt = 0; attempt < 2; attempt++) {
-        let handle;
-        try {
-            const before = await lstat(path);
-            if (!before.isFile() || before.size !== reference.byteSize)
-                throw corruptInputImageReference();
-            const flags = process.platform === 'win32'
-                ? constants.O_RDONLY
-                : constants.O_RDONLY | constants.O_NOFOLLOW;
-            handle = await open(path, flags);
-            const opened = await handle.stat();
-            if (!opened.isFile() ||
-                opened.size !== reference.byteSize ||
-                opened.dev !== before.dev ||
-                opened.ino !== before.ino)
-                continue;
-            const data = await readExactBytes(handle, reference.byteSize);
-            const after = await handle.stat();
-            if (after.size !== opened.size ||
-                after.mtimeMs !== opened.mtimeMs ||
-                after.ctimeMs !== opened.ctimeMs)
-                continue;
-            if (createHash('sha256').update(data).digest('hex') !== reference.sha256)
-                throw corruptInputImageReference();
-            return data;
-        }
-        catch (cause) {
-            if (cause instanceof MarAgentError)
-                throw cause;
-            throw corruptInputImageReference(cause);
-        }
-        finally {
-            await handle?.close();
-        }
-    }
-    throw corruptInputImageReference();
-}
-async function readExactBytes(handle, byteSize) {
-    const data = Buffer.alloc(byteSize);
-    let offset = 0;
-    while (offset < byteSize) {
-        const { bytesRead } = await handle.read(data, offset, byteSize - offset, offset);
-        if (bytesRead === 0)
-            throw corruptInputImageReference();
-        offset += bytesRead;
-    }
-    const extra = Buffer.allocUnsafe(1);
-    if ((await handle.read(extra, 0, 1, byteSize)).bytesRead !== 0)
-        throw corruptInputImageReference();
-    return data;
-}
-async function copyInputImages(sourceSessionDirectory, targetSessionDirectory, references) {
-    if (references.length === 0)
-        return;
-    const source = join(sourceSessionDirectory, 'input_images');
-    const target = join(targetSessionDirectory, 'input_images');
-    await mkdir(target, { recursive: true, mode: 0o700 });
-    for (const reference of references) {
-        const data = await readInputImageBytes(source, reference);
-        await writeFile(join(target, reference.fileName), data, { mode: 0o600, flag: 'wx' });
-    }
-}
-function corruptInputImageReference(cause) {
-    return new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session input image is corrupt.', {
-        ...(cause === undefined ? {} : { cause })
-    });
-}
 function isObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-function normalizeSessionSource(value) {
-    if (value === undefined || value.type === 'user')
-        return { type: 'user' };
-    if (value.type !== 'subagent' ||
-        typeof value.parentSessionId !== 'string' ||
-        !value.parentSessionId.trim() ||
-        typeof value.rootSessionId !== 'string' ||
-        !value.rootSessionId.trim() ||
-        (!value.parentExecutionId && !value.parentOperationId) ||
-        [
-            value.parentExecutionId,
-            value.parentOperationId,
-            value.ownerInstanceId,
-            value.extensionId
-        ].some((identity) => identity !== undefined && (typeof identity !== 'string' || !identity.trim())) ||
-        ((value.ownerInstanceId !== undefined || value.extensionId !== undefined) &&
-            value.parentOperationId === undefined) ||
-        typeof value.description !== 'string' ||
-        !value.description.trim() ||
-        (value.role !== 'general-purpose' && value.role !== 'explore'))
-        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session source is invalid.');
-    return {
-        type: 'subagent',
-        parentSessionId: value.parentSessionId,
-        rootSessionId: value.rootSessionId,
-        ...(value.parentExecutionId === undefined
-            ? {}
-            : { parentExecutionId: value.parentExecutionId }),
-        ...(value.parentOperationId === undefined
-            ? {}
-            : { parentOperationId: value.parentOperationId }),
-        ...(value.ownerInstanceId === undefined ? {} : { ownerInstanceId: value.ownerInstanceId }),
-        ...(value.extensionId === undefined ? {} : { extensionId: value.extensionId }),
-        role: value.role,
-        description: value.description.trim()
-    };
-}
-function sessionListFilter(input) {
-    const source = input.source ??
-        (input.parentSessionId !== undefined || input.rootSessionId !== undefined
-            ? 'subagent'
-            : 'user');
-    if ((source !== 'user' && source !== 'subagent') ||
-        (input.parentSessionId !== undefined &&
-            (source !== 'subagent' || input.parentSessionId.length === 0)) ||
-        (input.rootSessionId !== undefined &&
-            (source !== 'subagent' || input.rootSessionId.length === 0)))
-        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session list filter is invalid.');
-    return {
-        source,
-        ...(input.parentSessionId === undefined ? {} : { parentSessionId: input.parentSessionId }),
-        ...(input.rootSessionId === undefined ? {} : { rootSessionId: input.rootSessionId })
-    };
-}
-function sessionMatchesFilter(meta, filter) {
-    const source = normalizeSessionSource(meta.source);
-    return (source.type === filter.source &&
-        (filter.parentSessionId === undefined ||
-            (source.type === 'subagent' && source.parentSessionId === filter.parentSessionId)) &&
-        (filter.rootSessionId === undefined ||
-            (source.type === 'subagent' && source.rootSessionId === filter.rootSessionId)));
-}
-function encodeSessionListCursor(revision, offset, filter) {
-    return Buffer.from(JSON.stringify({ version: 1, revision, offset, filter })).toString('base64url');
-}
-function decodeSessionListCursor(cursor, revision, filter) {
-    if (cursor === undefined)
-        return 0;
-    try {
-        const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
-        if (value.version !== 1 ||
-            value.revision !== revision ||
-            !Number.isSafeInteger(value.offset) ||
-            value.offset < 0 ||
-            !isDeepStrictEqual(value.filter, filter))
-            throw new Error('invalid cursor');
-        return value.offset;
-    }
-    catch {
-        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session list cursor is invalid.');
-    }
-}
-function sessionTreeIds(sessions, sessionId) {
-    if (!sessions.some((session) => session.id === sessionId))
-        return [];
-    const ids = [sessionId];
-    for (let index = 0; index < ids.length; index++) {
-        const parentId = ids[index];
-        for (const session of sessions) {
-            const source = normalizeSessionSource(session.source);
-            if (source.type === 'subagent' &&
-                source.parentSessionId === parentId &&
-                !ids.includes(session.id))
-                ids.push(session.id);
-        }
-    }
-    return ids;
-}
-function forkedPayload(type, value, sourceSessionId, targetSessionId, title, identities) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value))
-        return value;
-    const payload = { ...value };
-    if (payload.sessionId === sourceSessionId)
-        payload.sessionId = targetSessionId;
-    const application = (input) => {
-        if (typeof input.inputRef !== 'string')
-            return input;
-        const identity = identities.get(input.inputRef);
-        if (!identity)
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork input reference is missing.');
-        return {
-            ...input,
-            inputRef: identity.recordId,
-            ...(isObject(input.metadata)
-                ? { metadata: { ...input.metadata, recordId: identity.recordId } }
-                : {})
-        };
-    };
-    if (type === 'model.context')
-        return application(payload);
-    if (type === 'compact.completed') {
-        if (Array.isArray(payload.retainedModelContext))
-            payload.retainedModelContext = payload.retainedModelContext.map((item) => isObject(item) ? application(item) : item);
-        if (Array.isArray(payload.pendingInputs))
-            payload.pendingInputs = payload.pendingInputs.map((record) => {
-                const identity = identities.get(record.recordId);
-                if (!identity)
-                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Fork pending input reference is missing.');
-                return { ...record, ...identity, sessionId: targetSessionId };
-            });
-    }
-    if (type === 'session.title.updated') {
-        payload.title = title;
-        payload.automatic = false;
-    }
-    return payload;
-}
-function deriveExecutionState(records) {
-    let automaticTitle = false;
-    let sawUserTurn = false;
-    let compactSequence;
-    let todoSequence;
-    let todoRevision = 0;
-    let todoItems = [];
-    let executionModel;
-    let firstUserMessagePreview;
-    for (const record of records) {
-        firstUserMessagePreview ??= userMessagePreviewFromRecord(record);
-        if (record.type === 'session.created')
-            automaticTitle =
-                record.payload?.automaticTitle === true;
-        else if (record.type === 'turn.user')
-            sawUserTurn = true;
-        else if (record.type === 'session.title.updated')
-            automaticTitle = false;
-        else if (isCompactCheckpoint(record))
-            compactSequence = record.sequence;
-        else if (record.type === 'todo.updated') {
-            const items = todoItemsFromSnapshot(record.payload);
-            if (!items)
-                continue;
-            todoSequence = record.sequence;
-            todoRevision++;
-            todoItems = items;
-        }
-        const candidate = executionModelFromRecord(record);
-        if (candidate !== undefined)
-            executionModel = candidate;
-    }
-    const boundary = records.findLastIndex(isCompactCheckpoint);
-    const checkpoint = latestValidContextGcCheckpoint(records);
-    return {
-        automaticTitlePending: automaticTitle && !sawUserTurn,
-        todo: { revision: todoRevision, items: todoItems },
-        contextRecords: boundary < 0 ? [...records] : records.slice(boundary),
-        resume: {
-            version: 1,
-            ...(compactSequence === undefined ? {} : { compactSequence }),
-            ...(checkpoint === undefined
-                ? {}
-                : {
-                    gcSequence: checkpoint.record.sequence,
-                    gcGeneration: checkpoint.payload.generation,
-                    gcBaseSequence: contextGcBaseSequence(checkpoint.payload.base)
-                }),
-            ...(todoSequence === undefined ? {} : { todoSequence }),
-            todoRevision,
-            executionModelIndexed: true,
-            firstUserMessageIndexed: true,
-            ...(firstUserMessagePreview === undefined ? {} : { firstUserMessagePreview }),
-            ...(executionModel === undefined ? {} : executionModel)
-        }
-    };
-}
-function userMessagePreviewFromRecord(record) {
-    if (record.type !== 'turn.user' ||
-        !isObject(record.payload) ||
-        record.payload.inputSource === 'parent_agent' ||
-        typeof record.payload.prompt !== 'string')
-        return undefined;
-    const preview = record.payload.prompt.trim().replace(/\s+/gu, ' ').slice(0, 160);
-    return preview || undefined;
-}
-function executionModelFromRecord(record) {
-    if (record.type !== 'execution.header' || !isObject(record.payload))
-        return undefined;
-    const modelId = record.payload.modelId;
-    if (typeof modelId !== 'string' || modelId.trim().length === 0)
-        return undefined;
-    const modelName = record.payload.modelName;
-    const reasoningEffort = record.payload.reasoningEffort;
-    return {
-        modelId,
-        ...(typeof modelName === 'string' && modelName.trim().length > 0 ? { modelName } : {}),
-        ...(typeof reasoningEffort === 'string' && reasoningEffort.trim().length > 0
-            ? { reasoningEffort }
-            : {})
-    };
-}
-export function compactSummaryFromCheckpoint(record) {
-    if (record?.type !== 'compact.completed')
-        return undefined;
-    const payload = record.payload;
-    if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
-        return undefined;
-    const summary = payload.summary;
-    return typeof summary === 'string' && summary.trim().length > 0 ? summary : undefined;
-}
-export function replacementHistoryFromCheckpoint(record) {
-    if (compactSummaryFromCheckpoint(record) === undefined)
-        return undefined;
-    const history = record.payload.replacementHistory;
-    if (!Array.isArray(history) ||
-        !history.every((message) => message !== null &&
-            typeof message === 'object' &&
-            message.role === 'user' &&
-            typeof message.content === 'string' &&
-            (message.metadata === undefined ||
-                (parseModelInputMetadata(message.metadata) !== undefined &&
-                    (message.kind === 'extension_input'
-                        ? message.metadata.source === 'extension'
-                        : message.kind === 'user_input' && message.metadata.source !== 'extension'))) &&
-            (message.kind === 'user_input' ||
-                message.kind === 'extension_input' ||
-                (message.kind === 'summary' && message.content.trim().length > 0))) ||
-        history.filter((message) => message.kind === 'summary').length !== 1)
-        return undefined;
-    return history.map(({ role, content, kind, metadata }) => ({
-        role,
-        content,
-        kind,
-        ...(parseModelInputMetadata(metadata) === undefined
-            ? {}
-            : { metadata: parseModelInputMetadata(metadata) })
-    }));
-}
-export function parseModelInputMetadata(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value))
-        return undefined;
-    const metadata = value;
-    if (metadata.source !== 'user' &&
-        metadata.source !== 'parent_agent' &&
-        metadata.source !== 'extension')
-        return undefined;
-    return {
-        source: metadata.source,
-        ...(typeof metadata.recordId === 'string' && metadata.recordId.length <= 128
-            ? { recordId: metadata.recordId }
-            : {}),
-        ...(typeof metadata.extensionId === 'string' && metadata.extensionId.length <= 128
-            ? { extensionId: metadata.extensionId }
-            : {}),
-        ...(metadata.truncated === true ? { truncated: true } : {}),
-        ...(metadata.smartCompaction === true ? { smartCompaction: true } : {})
-    };
-}
-export function inputMetadataFromRecord(record) {
-    const payload = record.payload;
-    const source = payload.source;
-    return {
-        source: record.type === 'extension.input' || payload.inputSource === 'extension'
-            ? 'extension'
-            : payload.inputSource === 'parent_agent'
-                ? 'parent_agent'
-                : 'user',
-        recordId: record.recordId,
-        ...(payload.smartCompaction === true ? { smartCompaction: true } : {}),
-        ...(typeof source?.extensionId === 'string' && source.extensionId.length <= 128
-            ? { extensionId: source.extensionId }
-            : {})
-    };
-}
-function isCompactCheckpoint(record) {
-    return compactSummaryFromCheckpoint(record) !== undefined;
-}
-function sameResumeIndex(left, right) {
-    return (left?.version === right.version &&
-        left.compactSequence === right.compactSequence &&
-        left.gcSequence === right.gcSequence &&
-        left.gcGeneration === right.gcGeneration &&
-        left.gcBaseSequence === right.gcBaseSequence &&
-        left.todoSequence === right.todoSequence &&
-        left.todoRevision === right.todoRevision &&
-        left.executionModelIndexed === right.executionModelIndexed &&
-        left.firstUserMessageIndexed === right.firstUserMessageIndexed &&
-        left.firstUserMessagePreview === right.firstUserMessagePreview &&
-        left.modelId === right.modelId &&
-        left.modelName === right.modelName &&
-        left.reasoningEffort === right.reasoningEffort);
-}
-/** Read only the prefix needed by discovery; never load the entire transcript. */
-async function* readRecordsFromHead(path) {
-    const handle = await open(path, 'r');
-    try {
-        const { size } = await handle.stat();
-        const chunk = Buffer.allocUnsafe(REVERSE_READ_CHUNK_BYTES);
-        let position = 0;
-        let pending = Buffer.alloc(0);
-        while (position < size) {
-            const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, size - position), position);
-            if (bytesRead === 0)
-                break;
-            position += bytesRead;
-            const data = Buffer.concat([pending, chunk.subarray(0, bytesRead)]);
-            let start = 0;
-            for (;;) {
-                const end = data.indexOf(0x0a, start);
-                if (end < 0)
-                    break;
-                const line = data.subarray(start, end).toString('utf8');
-                start = end + 1;
-                if (!line)
-                    continue;
-                let record;
-                try {
-                    record = JSON.parse(line);
-                }
-                catch (cause) {
-                    throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.', {
-                        cause
-                    });
-                }
-                yield record;
-            }
-            pending = Buffer.from(data.subarray(start));
-        }
-        if (pending.length > 0) {
-            let record;
-            try {
-                record = JSON.parse(pending.toString('utf8'));
-            }
-            catch {
-                return; // Readers ignore only an interrupted final line.
-            }
-            yield record;
-        }
-    }
-    finally {
-        await handle.close();
-    }
-}
-async function readRecords(path) {
-    const value = await readFile(path, 'utf8');
-    const lines = value.split('\n');
-    if (lines.at(-1) === '')
-        lines.pop();
-    const records = [];
-    for (const [index, line] of lines.entries()) {
-        if (!line)
-            continue;
-        try {
-            records.push(JSON.parse(line));
-        }
-        catch (cause) {
-            if (index === lines.length - 1 && !value.endsWith('\n'))
-                break;
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.', {
-                cause
-            });
-        }
-    }
-    return records;
-}
-/** A pending marker is removable only after the committed JSONL references are checked. */
-async function recoverPendingInputImages(sessionDirectory, readHistory) {
-    const directory = join(sessionDirectory, 'input_images');
-    let names;
-    try {
-        names = await readdir(directory);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return;
-        throw error;
-    }
-    const pending = names.filter((name) => /^\.[0-9a-f-]{36}\.bin\.pending$/iu.test(name));
-    const temporary = names.filter((name) => /^\.[0-9a-f-]{36}\.bin\.[0-9a-f-]{36}\.tmp$/iu.test(name));
-    if (pending.length === 0 && temporary.length === 0)
-        return;
-    const referenced = pending.length === 0
-        ? new Set()
-        : new Set(inputImageReferencesFromRecords(await readHistory()).map((image) => image.fileName));
-    for (const name of pending) {
-        const fileName = name.slice(1, -'.pending'.length);
-        if (!referenced.has(fileName))
-            await rm(join(directory, fileName), { force: true });
-        await rm(join(directory, name), { force: true });
-    }
-    for (const name of temporary)
-        await rm(join(directory, name), { force: true });
-}
-/** Repair only the final record under the Session writer lock; never skip middle damage. */
-async function repairSegmentTail(path) {
-    const data = await readFile(path);
-    if (data.length === 0 || data.at(-1) === 10)
-        return;
-    const boundary = data.lastIndexOf(10);
-    let complete = false;
-    try {
-        const record = JSON.parse(data.subarray(boundary + 1).toString('utf8'));
-        complete =
-            record?.schemaVersion === 1 &&
-                Number.isSafeInteger(record.sequence) &&
-                typeof record.sessionId === 'string' &&
-                typeof record.type === 'string';
-    }
-    catch {
-        // An interrupted final line is discarded before another record can be appended.
-    }
-    const handle = await open(path, 'r+');
-    try {
-        if (complete) {
-            const { bytesWritten } = await handle.write(Buffer.from('\n'), 0, 1, data.length);
-            if (bytesWritten !== 1)
-                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session tail repair is incomplete.');
-        }
-        else
-            await handle.truncate(boundary + 1);
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
-async function readRecordPageFromTail(path, beforeSequence, limit, positions) {
-    const newestFirst = [];
-    for await (const record of readRecordsFromTail(path, { beforeSequence, limit, positions })) {
-        if (!(record.sequence < beforeSequence))
-            continue;
-        newestFirst.push(record);
-        if (newestFirst.length > limit)
-            break;
-    }
-    return {
-        records: newestFirst.slice(0, limit).reverse(),
-        hasEarlier: newestFirst.length > limit
-    };
-}
-/** Decode complete records newest-first, releasing the file as soon as a reader stops. */
-async function* readRecordsFromTail(path, page) {
-    const handle = await open(path, 'r');
-    try {
-        const metadata = await handle.stat({ bigint: true });
-        const size = Number(metadata.size);
-        let position = size;
-        let cached;
-        if (page !== undefined) {
-            const signature = `${metadata.dev}:${metadata.ino}:${metadata.size}:${metadata.mtimeNs}:${metadata.ctimeNs}`;
-            const previous = page.positions.get(path);
-            cached = previous?.signature === signature ? previous : { signature, offsets: new Map() };
-            page.positions.delete(path);
-            page.positions.set(path, cached);
-            if (page.positions.size > MAX_HISTORY_PAGE_FILES)
-                page.positions.delete(page.positions.keys().next().value);
-            let nearestSequence = Number.POSITIVE_INFINITY;
-            for (const [sequence, offset] of cached.offsets) {
-                if (sequence >= page.beforeSequence && sequence < nearestSequence) {
-                    nearestSequence = sequence;
-                    position = offset;
-                }
-            }
-        }
-        let accepted = 0;
-        const remember = (record, offset) => {
-            if (page === undefined || cached === undefined || record.sequence >= page.beforeSequence)
-                return;
-            if (++accepted !== page.limit)
-                return;
-            cached.offsets.set(record.sequence, offset);
-            if (cached.offsets.size > MAX_HISTORY_PAGE_OFFSETS)
-                cached.offsets.delete(cached.offsets.keys().next().value);
-        };
-        let pendingLineParts = [];
-        let invalidFinalLineMayBeIgnored = false;
-        let inspectedFileEnd = position !== size;
-        const decode = (line, allowInvalidFinalLine) => {
-            if (line.length === 0)
-                return undefined;
-            try {
-                return JSON.parse(line.toString('utf8'));
-            }
-            catch (cause) {
-                if (allowInvalidFinalLine)
-                    return undefined;
-                throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.', {
-                    cause
-                });
-            }
-        };
-        while (position > 0) {
-            const start = Math.max(0, position - REVERSE_READ_CHUNK_BYTES);
-            const chunk = Buffer.allocUnsafe(position - start);
-            let bytesRead = 0;
-            while (bytesRead < chunk.length) {
-                const result = await handle.read(chunk, bytesRead, chunk.length - bytesRead, start + bytesRead);
-                if (result.bytesRead === 0)
-                    break;
-                bytesRead += result.bytesRead;
-            }
-            const value = chunk.subarray(0, bytesRead);
-            if (!inspectedFileEnd) {
-                inspectedFileEnd = true;
-                invalidFinalLineMayBeIgnored = value.at(-1) !== 0x0a;
-            }
-            let lineEnd = value.length;
-            for (let index = value.length - 1; index >= 0; index--) {
-                if (value[index] !== 0x0a)
-                    continue;
-                const currentPart = value.subarray(index + 1, lineEnd);
-                const line = pendingLineParts.length === 0
-                    ? currentPart
-                    : Buffer.concat([currentPart, ...pendingLineParts]);
-                const record = decode(line, invalidFinalLineMayBeIgnored);
-                invalidFinalLineMayBeIgnored = false;
-                pendingLineParts = [];
-                lineEnd = index;
-                if (record !== undefined) {
-                    remember(record, start + index + 1);
-                    yield record;
-                }
-            }
-            if (lineEnd > 0)
-                pendingLineParts.unshift(Buffer.from(value.subarray(0, lineEnd)));
-            position = start;
-        }
-        if (pendingLineParts.length > 0) {
-            const record = decode(Buffer.concat(pendingLineParts), invalidFinalLineMayBeIgnored);
-            if (record !== undefined) {
-                remember(record, 0);
-                yield record;
-            }
-        }
-    }
-    finally {
-        await handle.close();
-    }
-}
-function segmentNumberFromPath(path) {
-    const match = /events-(\d{6})\.jsonl$/.exec(path);
-    return match === null ? undefined : Number(match[1]);
-}
-function restoreExtensionCheckpoint(records, extensionId, key) {
-    for (const record of [...records].reverse()) {
-        if (record.type !== 'extension.checkpoint.updated')
-            continue;
-        const payload = record.payload;
-        if (!payload || payload.extensionId !== extensionId || payload.key !== key)
-            continue;
-        if (typeof payload.revision !== 'number' ||
-            !Number.isSafeInteger(payload.revision) ||
-            payload.revision < 1)
-            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Extension checkpoint revision is corrupt.');
-        return {
-            revision: payload.revision,
-            ...(payload.deleted === true ? {} : { value: cloneCoreJson(payload.value) })
-        };
-    }
-    return { revision: 0 };
-}