@myagentroam/agent 0.11.32 → 0.11.34

package/dist/session/store/execution-state.js

@@ -0,0 +1,103 @@
+import { compactSummaryFromCheckpoint } from '../record-projection.js';
+import { todoItemsFromSnapshot } from '../todo.js';
+export function deriveExecutionState(records) {
+    let automaticTitle = false;
+    let sawUserTurn = false;
+    let compactSequence;
+    let todoSequence;
+    let todoRevision = 0;
+    let todoItems = [];
+    let executionModel;
+    let firstUserMessagePreview;
+    let userTurns = 0;
+    for (const record of records) {
+        if (isNativeUserTurn(record))
+            userTurns++;
+        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);
+    return {
+        automaticTitlePending: automaticTitle && !sawUserTurn,
+        todo: { revision: todoRevision, items: todoItems },
+        contextRecords: boundary < 0 ? [...records] : records.slice(boundary),
+        resume: {
+            version: 1,
+            userTurns,
+            ...(compactSequence === undefined ? {} : { compactSequence }),
+            ...(todoSequence === undefined ? {} : { todoSequence }),
+            todoRevision,
+            executionModelIndexed: true,
+            firstUserMessageIndexed: true,
+            ...(firstUserMessagePreview === undefined ? {} : { firstUserMessagePreview }),
+            ...(executionModel === undefined ? {} : executionModel)
+        }
+    };
+}
+export function isNativeUserTurn(record) {
+    return (record.type === 'turn.user' &&
+        record.payload.inputSource === undefined);
+}
+export 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;
+}
+export 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 isCompactCheckpoint(record) {
+    return compactSummaryFromCheckpoint(record) !== undefined;
+}
+export function sameResumeIndex(left, right) {
+    return (left?.version === right.version &&
+        left.userTurns === right.userTurns &&
+        left.compactSequence === right.compactSequence &&
+        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);
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/session/store/index.d.ts

@@ -0,0 +1,4 @@
+export type { SessionListInput, SessionSource } from '../types.js';
+export { compactSummaryFromCheckpoint, inputMetadataFromRecord, parseModelInputMetadata, replacementHistoryFromCheckpoint } from '../record-projection.js';
+export { JsonlSessionStore } from './jsonl/jsonl-store.js';
+export type { CompactHistoryMessage, CompactUserInput, RestoredSessionInputImage, SessionExecutionState, SessionInputImage, SessionInputImageData, SessionInputImageMetadata, SessionRecord } from './types.js';

package/dist/session/store/index.js

@@ -0,0 +1,2 @@
+export { compactSummaryFromCheckpoint, inputMetadataFromRecord, parseModelInputMetadata, replacementHistoryFromCheckpoint } from '../record-projection.js';
+export { JsonlSessionStore } from './jsonl/jsonl-store.js';

package/dist/session/store/jsonl/directory-index.d.ts

@@ -0,0 +1,26 @@
+import type { SessionListInput, SessionSource } from '../../types.js';
+import type { SessionIndex, SessionMeta } from '../types.js';
+/** Root format fence; history and directory revision are unchanged. */
+export declare function upgradeSessionIndex(index: SessionIndex): SessionIndex;
+/** Merge only derived fields, and only onto the history they were computed from. */
+export declare function mergeSessionDerivedCache(current: SessionMeta, cached: SessionMeta): SessionMeta;
+/** Restore the same entry object while the index serialization queue is held. */
+export declare function restoreSessionIndexMeta(meta: SessionMeta, original: SessionMeta): void;
+/** Prepare one committed index from a locked disk snapshot and the caller's dirty snapshot. */
+export declare function prepareSessionIndexCommit(disk: SessionIndex, local: SessionIndex, dirty: ReadonlyMap<string, number>, derivedOnly: ReadonlySet<string>, deletedIds: string | readonly string[] | undefined, createdIds: readonly string[]): SessionIndex;
+export declare function readSessionIndex(path: string): Promise<SessionIndex | undefined>;
+export declare function persistSessionIndex(path: string, index: SessionIndex): Promise<void>;
+/** The format-selection commit needs both the file and its directory entry durable. */
+export declare function persistFormatSelection(path: string, index: SessionIndex): Promise<void>;
+export declare function normalizeSessionSource(value: SessionSource | undefined): SessionSource;
+interface SessionListFilter {
+    readonly source: SessionSource['type'];
+    readonly parentSessionId?: string;
+    readonly rootSessionId?: string;
+}
+export declare function sessionListFilter(input: SessionListInput): SessionListFilter;
+export declare function sessionMatchesFilter(meta: SessionMeta, filter: SessionListFilter): boolean;
+export declare function encodeSessionListCursor(revision: number, offset: number, filter: SessionListFilter): string;
+export declare function decodeSessionListCursor(cursor: string | undefined, revision: number, filter: SessionListFilter): number;
+export declare function sessionTreeIds(sessions: readonly SessionMeta[], sessionId: string): string[];
+export {};

package/dist/session/store/jsonl/directory-index.js

@@ -0,0 +1,283 @@
+import { randomUUID } from 'node:crypto';
+import { open, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { AgentError } from '../../../error.js';
+/** Root format fence; history and directory revision are unchanged. */
+export function upgradeSessionIndex(index) {
+    if (index.version === 2)
+        return index;
+    return {
+        ...index,
+        version: 2,
+        sessions: index.sessions.map((session) => ({ ...session, storage: { encoding: 1 } }))
+    };
+}
+/** Merge only derived fields, and only onto the history they were computed from. */
+export function mergeSessionDerivedCache(current, cached) {
+    if (current.nextSequence !== cached.nextSequence ||
+        current.storageTransactionId !== cached.storageTransactionId)
+        return current;
+    const preview = cached.resume?.firstUserMessageIndexed === true &&
+        current.resume?.firstUserMessagePreview === undefined &&
+        !(current.resume?.firstUserMessageIndexed === true &&
+            cached.resume.firstUserMessagePreview === undefined);
+    const count = current.resume?.userTurns === undefined && cached.resume?.userTurns !== undefined;
+    if (!preview && !count)
+        return current;
+    return {
+        ...current,
+        resume: {
+            ...(current.resume ?? { version: 1, todoRevision: 0 }),
+            ...(count ? { userTurns: cached.resume.userTurns } : {}),
+            ...(preview ? { firstUserMessageIndexed: true } : {}),
+            ...(!preview || cached.resume?.firstUserMessagePreview === undefined
+                ? {}
+                : { firstUserMessagePreview: cached.resume.firstUserMessagePreview })
+        }
+    };
+}
+/** Restore the same entry object while the index serialization queue is held. */
+export function restoreSessionIndexMeta(meta, original) {
+    if (original.storage === undefined)
+        delete meta.storage;
+    else
+        meta.storage = structuredClone(original.storage);
+    meta.id = original.id;
+    meta.title = original.title;
+    meta.workspace = original.workspace;
+    meta.createdAt = original.createdAt;
+    meta.lastActivityAt = original.lastActivityAt;
+    if (original.source === undefined)
+        delete meta.source;
+    else
+        meta.source = structuredClone(original.source);
+    meta.nextSequence = original.nextSequence;
+    if (original.storageTransactionId === undefined)
+        delete meta.storageTransactionId;
+    else
+        meta.storageTransactionId = original.storageTransactionId;
+    if (original.automaticTitlePending === undefined)
+        delete meta.automaticTitlePending;
+    else
+        meta.automaticTitlePending = original.automaticTitlePending;
+    if (original.resume === undefined)
+        delete meta.resume;
+    else
+        meta.resume = structuredClone(original.resume);
+    if (original.segments === undefined)
+        delete meta.segments;
+    else
+        meta.segments = structuredClone(original.segments);
+}
+/** Prepare one committed index from a locked disk snapshot and the caller's dirty snapshot. */
+export function prepareSessionIndexCommit(disk, local, dirty, derivedOnly, deletedIds, createdIds) {
+    const sessions = new Map(disk.sessions.map((session) => [session.id, session]));
+    const created = new Set(createdIds);
+    for (const session of local.sessions) {
+        const current = sessions.get(session.id);
+        // Disk membership is authoritative: a stale in-memory snapshot cannot revive a deletion.
+        if (created.has(session.id) || (current && dirty.has(session.id)))
+            sessions.set(session.id, current && derivedOnly.has(session.id)
+                ? mergeSessionDerivedCache(current, session)
+                : {
+                    ...structuredClone(session),
+                    ...(current?.storage === undefined ? {} : { storage: current.storage })
+                });
+    }
+    for (const deletedId of typeof deletedIds === 'string' ? [deletedIds] : (deletedIds ?? []))
+        sessions.delete(deletedId);
+    return {
+        version: disk.version,
+        revision: createdIds.length > 0 ||
+            deletedIds !== undefined ||
+            [...dirty.keys()].some((id) => !derivedOnly.has(id))
+            ? Math.max(disk.revision, local.revision) + 1
+            : disk.revision,
+        sessions: [...sessions.values()]
+    };
+}
+export 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 (Number.isSafeInteger(value?.version) && value.version !== 1 && value.version !== 2)
+            throw new AgentError('MAR_AGENT_SESSION_VERSION_UNSUPPORTED', 'Session encoding is unsupported.');
+        if (value?.version === 2 && Array.isArray(value.sessions))
+            for (const session of value.sessions) {
+                const encoding = session?.storage?.encoding;
+                if (Number.isSafeInteger(encoding) && encoding !== 1 && encoding !== 2)
+                    throw new AgentError('MAR_AGENT_SESSION_VERSION_UNSUPPORTED', 'Session encoding is unsupported.');
+            }
+        if ((value?.version !== 1 && value?.version !== 2) ||
+            !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 ||
+                (value.version === 2 &&
+                    session.storage?.encoding !== 1 &&
+                    (session.storage?.encoding !== 2 ||
+                        !/^[0-9a-f-]{36}$/iu.test(session.storage.generation))) ||
+                (session.resume?.userTurns !== undefined &&
+                    (!Number.isSafeInteger(session.resume.userTurns) || session.resume.userTurns < 0))))
+            throw new Error('invalid index shape');
+        return value;
+    }
+    catch (cause) {
+        if (cause instanceof AgentError && cause.code === 'MAR_AGENT_SESSION_VERSION_UNSUPPORTED')
+            throw cause;
+        throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is corrupt.', { cause });
+    }
+}
+export async function persistSessionIndex(path, index) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    let failure;
+    try {
+        await writeFile(temporary, JSON.stringify(index), { mode: 0o600, flag: 'wx', flush: true });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        if (failure !== undefined)
+            await rm(temporary, { force: true }).catch(() => undefined);
+        else
+            await rm(temporary, { force: true });
+    }
+}
+/** The format-selection commit needs both the file and its directory entry durable. */
+export async function persistFormatSelection(path, index) {
+    await persistSessionIndex(path, index);
+    if (process.platform === 'win32')
+        return;
+    const directory = await open(dirname(path), 'r');
+    let failure;
+    try {
+        await directory.sync();
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        if (failure !== undefined)
+            await directory.close().catch(() => undefined);
+        else
+            await directory.close();
+    }
+}
+export 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 AgentError('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()
+    };
+}
+export 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 AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session list filter is invalid.');
+    return {
+        source,
+        ...(input.parentSessionId === undefined ? {} : { parentSessionId: input.parentSessionId }),
+        ...(input.rootSessionId === undefined ? {} : { rootSessionId: input.rootSessionId })
+    };
+}
+export 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)));
+}
+export function encodeSessionListCursor(revision, offset, filter) {
+    return Buffer.from(JSON.stringify({ version: 1, revision, offset, filter })).toString('base64url');
+}
+export 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 AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session list cursor is invalid.');
+    }
+}
+export 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;
+}

package/dist/session/store/jsonl/fs-durability.d.ts

@@ -0,0 +1,3 @@
+import { open } from 'node:fs/promises';
+export declare function syncJsonlDirectory(path: string): Promise<void>;
+export declare function syncAndClose(handle: Awaited<ReturnType<typeof open>>): Promise<void>;

package/dist/session/store/jsonl/fs-durability.js

@@ -0,0 +1,17 @@
+import { open } from 'node:fs/promises';
+export async function syncJsonlDirectory(path) {
+    if (process.platform === 'win32')
+        return;
+    const handle = await open(path, 'r');
+    await syncAndClose(handle);
+}
+export async function syncAndClose(handle) {
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+    await handle.close();
+}

package/dist/session/store/jsonl/history-replacement.d.ts

@@ -0,0 +1,48 @@
+import { deriveExecutionState } from '../execution-state.js';
+import type { SessionMeta, SessionRecord } from '../types.js';
+interface HistoryReplacementContext {
+    readonly directory: string;
+    readonly sessionDirectory: string;
+    readonly targetGeneration?: string;
+    segmentPaths(): Promise<string[]>;
+    settleIndex(request: HistoryIndexRequest, recover: (committed: boolean) => Promise<void>): Promise<HistoryIndexOutcome>;
+}
+interface HistoryIndexBase {
+    readonly transactionId: string;
+    readonly nextSequence: number;
+    readonly segments: NonNullable<SessionMeta['segments']>;
+    readonly targetGeneration?: string;
+}
+type HistoryIndexChange = HistoryIndexBase & ({
+    readonly kind: 'rollback';
+    readonly title?: string;
+    readonly state: ReturnType<typeof deriveExecutionState>;
+} | {
+    readonly kind: 'clear';
+    readonly clearedAt: string;
+});
+type HistoryIndexRequest = {
+    readonly kind: 'apply';
+    readonly change: HistoryIndexChange;
+} | {
+    readonly kind: 'recover';
+    readonly transactionId: string;
+    readonly error: unknown;
+};
+export type HistoryIndexOutcome = {
+    readonly status: 'committed';
+    readonly meta: SessionMeta;
+    readonly error?: unknown;
+    readonly recoveryRequired?: true;
+} | {
+    readonly status: 'not-committed' | 'unknown';
+    readonly error: unknown;
+};
+/** Execute one rollback/clear transaction while its caller holds maintenance. */
+export declare function replaceSessionHistory(meta: SessionMeta, retained: readonly SessionRecord[], operation: {
+    kind: 'rollback';
+} | {
+    kind: 'clear';
+    clearedAt: string;
+}, context: HistoryReplacementContext): Promise<HistoryIndexOutcome>;
+export {};

package/dist/session/store/jsonl/history-replacement.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import { readdir, rename, rm } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { toolResultResourceFiles } from '../../tool-result-resources.js';
+import { beginSessionStorageTransaction, retiredSessionTrashPath, recoverSessionStorageTransaction } from './transaction-recovery.js';
+import { deriveExecutionState } from '../execution-state.js';
+import { renameIfExists, retainedSessionTitle, stageSessionSegments, stageUnreferencedImages } from './history.js';
+import { generatedImageFileNames } from './images.js';
+import { CONTEXTUAL_WORLD_STATE_FILE } from './open-recovery.js';
+import { resourceFiles } from './resources.js';
+import { syncJsonlDirectory } from './fs-durability.js';
+/** Execute one rollback/clear transaction while its caller holds maintenance. */
+export async function replaceSessionHistory(meta, retained, operation, context) {
+    const targetDirectory = context.targetGeneration === undefined
+        ? context.directory
+        : join(context.sessionDirectory, 'v2', context.targetGeneration);
+    const staged = await stageSessionSegments(targetDirectory, retained);
+    const transactionId = randomUUID();
+    const targetNextSequence = operation.kind === 'clear' ? 2 : (retained.at(-1)?.sequence ?? 0) + 1;
+    const contextualWorldStatePath = join(context.directory, CONTEXTUAL_WORLD_STATE_FILE);
+    const contextualWorldStateBackup = `${contextualWorldStatePath}.${targetNextSequence}.${transactionId}.${operation.kind}-backup`;
+    const originalTransactionId = meta.storageTransactionId;
+    const originalPaths = await context.segmentPaths();
+    const retiredPaths = await retiredSessionPaths(context.sessionDirectory, context.directory, targetDirectory);
+    const backups = originalPaths.map((path) => ({
+        path,
+        backup: `${path}.${transactionId}.${operation.kind}-backup`
+    }));
+    const transaction = {
+        version: 1,
+        id: transactionId,
+        kind: operation.kind,
+        originalSegments: originalPaths.map((path) => basename(path)),
+        stagedSegments: staged.files.map((item) => ({
+            path: basename(item.path),
+            temporary: basename(item.temporaryPath)
+        })),
+        sidecarBackup: basename(contextualWorldStateBackup),
+        retiredPaths,
+        ...(context.targetGeneration === undefined
+            ? {}
+            : { targetGeneration: context.targetGeneration })
+    };
+    let committed = false;
+    let uncertain = false;
+    const recover = (selected) => recoverSessionStorageTransaction(context.directory, selected ? transactionId : originalTransactionId, context.sessionDirectory);
+    try {
+        await beginSessionStorageTransaction(context.directory, transaction);
+        await syncJsonlDirectory(context.directory);
+        await renameIfExists(contextualWorldStatePath, contextualWorldStateBackup);
+        await stageUnreferencedImages(context.sessionDirectory, 'generated_images', operation.kind === 'rollback' ? new Set(generatedImageFileNames(retained)) : new Set(), transactionId);
+        await stageUnreferencedImages(context.directory, 'resources', operation.kind === 'rollback' ? resourceFiles(retained) : new Set(), transactionId);
+        await stageUnreferencedImages(context.directory, 'tool_results', operation.kind === 'rollback' ? toolResultResourceFiles(retained) : new Set(), transactionId);
+        for (const path of retiredPaths)
+            await renameIfExists(join(context.sessionDirectory, path), retiredSessionTrashPath(context.sessionDirectory, path, transactionId));
+        for (const item of backups)
+            await rename(item.path, item.backup);
+        for (const item of staged.files) {
+            await rename(item.temporaryPath, item.path);
+        }
+        for (const directory of new Set([
+            context.directory,
+            context.sessionDirectory,
+            targetDirectory,
+            join(context.sessionDirectory, 'v2'),
+            join(context.sessionDirectory, 'generated_images'),
+            join(context.directory, 'resources'),
+            join(context.directory, 'tool_results')
+        ])) {
+            try {
+                await syncJsonlDirectory(directory);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        const title = operation.kind === 'rollback' ? retainedSessionTitle(retained, '') : '';
+        const outcome = await context.settleIndex({
+            kind: 'apply',
+            change: {
+                transactionId,
+                nextSequence: targetNextSequence,
+                segments: staged.segments,
+                ...(context.targetGeneration === undefined
+                    ? {}
+                    : { targetGeneration: context.targetGeneration }),
+                ...(operation.kind === 'rollback'
+                    ? {
+                        kind: 'rollback',
+                        state: deriveExecutionState(retained),
+                        ...(title ? { title } : {})
+                    }
+                    : { kind: 'clear', clearedAt: operation.clearedAt })
+            }
+        }, recover);
+        if (outcome.status !== 'committed' || outcome.error !== undefined) {
+            uncertain =
+                outcome.status === 'unknown' ||
+                    (outcome.status === 'committed' && outcome.recoveryRequired === true);
+            return outcome;
+        }
+        committed = true;
+        try {
+            await recover(true);
+            return outcome;
+        }
+        catch (error) {
+            uncertain = true;
+            return { status: 'committed', meta: outcome.meta, error, recoveryRequired: true };
+        }
+    }
+    catch (error) {
+        if (committed) {
+            uncertain = true;
+            return { status: 'unknown', error };
+        }
+        const outcome = await context.settleIndex({ kind: 'recover', transactionId, error }, recover);
+        uncertain =
+            outcome.status === 'unknown' ||
+                (outcome.status === 'committed' && outcome.recoveryRequired === true);
+        return outcome;
+    }
+    finally {
+        if (!uncertain)
+            await Promise.all(staged.files.map((item) => rm(item.temporaryPath, { force: true }))).catch(() => undefined);
+    }
+}
+async function retiredSessionPaths(root, active, target) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const paths = entries
+        .filter((entry) => root !== active &&
+        ((entry.isFile() &&
+            (/^events-\d{6}\.jsonl$/u.test(entry.name) ||
+                entry.name === 'context-world-state.json')) ||
+            (entry.isDirectory() && ['resources', 'tool_results'].includes(entry.name))))
+        .map((entry) => entry.name);
+    const generations = await readdir(join(root, 'v2'), { withFileTypes: true });
+    for (const entry of generations) {
+        if (!entry.isDirectory() || !/^[0-9a-f-]{36}$/u.test(entry.name))
+            continue;
+        const relative = `v2/${entry.name}`;
+        if (join(root, relative) !== active && join(root, relative) !== target)
+            paths.push(relative);
+    }
+    return paths;
+}

package/dist/session/store/jsonl/history.d.ts

@@ -0,0 +1,25 @@
+import type { SessionMeta, SessionRecord } from '../types.js';
+export declare function renameIfExists(from: string, to: string): Promise<boolean>;
+interface StagedSessionSegments {
+    readonly files: readonly {
+        readonly path: string;
+        readonly temporaryPath: string;
+    }[];
+    readonly segments: NonNullable<SessionMeta['segments']>;
+}
+export declare function stageSessionSegments(sessionDirectory: string, records: readonly SessionRecord[], operation?: 'rollback' | 'fork'): Promise<StagedSessionSegments>;
+export declare function stageUnreferencedImages(sessionDirectory: string, directoryName: 'generated_images' | 'tool_results' | 'resources', retained: ReadonlySet<string>, transactionId: string): Promise<Array<{
+    from: string;
+    to: string;
+    trash: string;
+}>>;
+export declare function restoreRenamedFiles(files: readonly {
+    readonly from: string;
+    readonly to: string;
+}[]): Promise<void>;
+export declare function retainedSessionTitle(records: readonly SessionRecord[], fallback: string): string;
+export declare function forkedPayload(type: string, value: unknown, sourceSessionId: string, targetSessionId: string, title: string, identities: ReadonlyMap<string, {
+    recordId: string;
+    sequence: number;
+}>): unknown;
+export {};