@abot-ai/runtime 1.6.0 → 1.8.0

package/dist/src/sessions/metadata/publication.js

@@ -0,0 +1,78 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { withFileLock } from "../../runtime/adapters/long-term-memory/file-lock.js";
+const pendingPublications = new Map();
+export function isMissingSessionFile(error) {
+    return error?.code === "ENOENT";
+}
+export function sessionSourceStamp(source) {
+    return `${source.dev}:${source.ino}:${source.size}:${source.mtimeNs}`;
+}
+export async function currentSourceStamp(path) {
+    try {
+        return sessionSourceStamp(await stat(path, { bigint: true }));
+    }
+    catch (error) {
+        if (isMissingSessionFile(error))
+            return null;
+        throw error;
+    }
+}
+export function reportMetadataFailure(sessionId, error) {
+    process.emitWarning(`Session metadata update failed for ${sessionId}: ${String(error)}`, {
+        code: "SESSION_METADATA_WRITE_FAILED",
+    });
+}
+/** Only the derived index is expendable; canonical session read failures still propagate. */
+export async function readMetadataJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (isMissingSessionFile(error))
+            return null;
+        if (error instanceof SyntaxError)
+            return null;
+        reportMetadataFailure(path, error);
+        return null;
+    }
+}
+/** Serialize index publication/deletion by session, never across unrelated sessions. */
+export async function publishSessionMetadata(path, operation) {
+    const key = resolve(path);
+    const previous = pendingPublications.get(key) ?? Promise.resolve();
+    const pending = previous.then(operation).catch((error) => reportMetadataFailure(path, error));
+    pendingPublications.set(key, pending);
+    try {
+        await pending;
+    }
+    finally {
+        if (pendingPublications.get(key) === pending)
+            pendingPublications.delete(key);
+    }
+}
+/** List backfills and the Runtime owner may run in different processes. */
+export async function publishSessionProjection(path, operation) {
+    return publishSessionMetadata(path, async () => {
+        await mkdir(dirname(path), { recursive: true });
+        await withFileLock(`${path}.lock`, operation);
+    });
+}
+export async function writeMetadataJson(target, value, sourcePath, source) {
+    if (await currentSourceStamp(sourcePath) !== source)
+        return false;
+    await mkdir(dirname(target), { recursive: true });
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(value), { encoding: "utf8", mode: 0o600 });
+        // Validate at publication too: the canonical file may change while writing the temporary.
+        if (await currentSourceStamp(sourcePath) !== source)
+            return false;
+        await rename(temporary, target);
+        return true;
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/src/sessions/metadata/source-receipt.d.ts

@@ -0,0 +1,5 @@
+import type { SessionMetadata } from "./projection.js";
+export type SessionMetadataChange = "projection" | "request-only";
+export declare function writeSourceReceipt(path: string, sourcePath: string, source: string, updatedAt: string, previousSource?: string): Promise<void>;
+/** Bind request-only changes to the exact projection they left unchanged. */
+export declare function applySourceReceipt(path: string, record: SessionMetadata, source: string): Promise<SessionMetadata | null>;

package/dist/src/sessions/metadata/source-receipt.js

@@ -0,0 +1,42 @@
+import { toEpochMs } from "../record/projection.js";
+import { readMetadataJson, writeMetadataJson } from "./publication.js";
+function isSourceReceipt(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const receipt = value;
+    if (receipt.version !== 1)
+        return false;
+    if (typeof receipt.source !== "string")
+        return false;
+    if (typeof receipt.projectionSource !== "string")
+        return false;
+    return typeof receipt.updatedAt === "string";
+}
+async function receiptProjectionSource(path, source, previousSource) {
+    if (previousSource === undefined)
+        return source;
+    const previous = await readMetadataJson(path);
+    if (!isSourceReceipt(previous))
+        return previousSource;
+    if (previous.source !== previousSource)
+        return previousSource;
+    return previous.projectionSource;
+}
+export async function writeSourceReceipt(path, sourcePath, source, updatedAt, previousSource) {
+    const projectionSource = await receiptProjectionSource(path, source, previousSource);
+    await writeMetadataJson(path, { version: 1, source, projectionSource, updatedAt }, sourcePath, source);
+}
+/** Bind request-only changes to the exact projection they left unchanged. */
+export async function applySourceReceipt(path, record, source) {
+    const receipt = await readMetadataJson(path);
+    if (!isSourceReceipt(receipt))
+        return null;
+    if (receipt.source !== source)
+        return null;
+    if (receipt.projectionSource !== record.source)
+        return null;
+    return {
+        ...record, source, updatedAt: receipt.updatedAt,
+        summary: { ...record.summary, updatedAt: toEpochMs(receipt.updatedAt) },
+    };
+}

package/dist/src/sessions/metadata/store.d.ts

@@ -0,0 +1,7 @@
+import type { SessionRecord } from "../types.js";
+import { type SessionMetadata } from "./projection.js";
+export { currentSourceStamp, sessionSourceStamp } from "./publication.js";
+/** The canonical session has already committed. A derived-index failure cannot undo it. */
+export declare function updateSessionMetadata(sessionsDir: string, session: SessionRecord, source: string, previousSource?: string | null): Promise<void>;
+export declare function deleteSessionMetadata(sessionsDir: string, sessionId: string): Promise<void>;
+export declare function listSessionMetadata(sessionsDir: string): Promise<SessionMetadata[]>;

package/dist/src/sessions/metadata/store.js

@@ -0,0 +1,119 @@
+import { mkdir, open, readdir, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { compareSessionMetadata, isCurrentSessionMetadata, projectSessionMetadata, } from "./projection.js";
+import { currentSourceStamp, isMissingSessionFile, publishSessionMetadata, publishSessionProjection, readMetadataJson, reportMetadataFailure, sessionSourceStamp, writeMetadataJson, } from "./publication.js";
+import { applySourceReceipt, writeSourceReceipt } from "./source-receipt.js";
+export { currentSourceStamp, sessionSourceStamp } from "./publication.js";
+const pendingLists = new Map();
+const concurrentMetadataReads = 4;
+function metadataPath(sessionsDir, sessionId) {
+    return join(sessionsDir, ".metadata", `${sessionId}.json`);
+}
+async function writeMetadata(sessionsDir, record) {
+    const target = metadataPath(sessionsDir, record.summary.id);
+    const sourcePath = join(sessionsDir, `${record.summary.id}.json`);
+    await publishSessionProjection(target, async () => {
+        if (!await writeMetadataJson(target, record, sourcePath, record.source))
+            return;
+        // The full projection already carries its source; only request-only changes need a receipt.
+        await rm(`${target}.source`, { force: true });
+    });
+}
+/** The canonical session has already committed. A derived-index failure cannot undo it. */
+export async function updateSessionMetadata(sessionsDir, session, source, previousSource) {
+    if (previousSource) {
+        const target = metadataPath(sessionsDir, session.id);
+        return publishSessionMetadata(target, () => writeSourceReceipt(`${target}.source`, join(sessionsDir, `${session.id}.json`), source, session.updatedAt, previousSource));
+    }
+    try {
+        await writeMetadata(sessionsDir, projectSessionMetadata(session, source));
+    }
+    catch (error) {
+        reportMetadataFailure(session.id, error);
+    }
+}
+export async function deleteSessionMetadata(sessionsDir, sessionId) {
+    const target = metadataPath(sessionsDir, sessionId);
+    await publishSessionProjection(target, async () => {
+        await rm(target, { force: true });
+        await rm(`${target}.source`, { force: true });
+    });
+}
+async function readSourceMetadata(path) {
+    const handle = await open(path, "r").catch((error) => {
+        if (isMissingSessionFile(error))
+            return null;
+        throw error;
+    });
+    if (!handle)
+        return null;
+    try {
+        const source = sessionSourceStamp(await handle.stat({ bigint: true }));
+        const session = JSON.parse(await handle.readFile("utf8"));
+        return projectSessionMetadata(session, source);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readCurrentMetadata(target, sessionId, source) {
+    const stored = await readMetadataJson(target);
+    if (isCurrentSessionMetadata(stored, sessionId, source))
+        return stored;
+    const projectionSource = stored?.source;
+    if (typeof projectionSource !== "string")
+        return null;
+    if (!isCurrentSessionMetadata(stored, sessionId, projectionSource))
+        return null;
+    return applySourceReceipt(`${target}.source`, stored, source);
+}
+async function loadMetadata(sessionsDir, sessionId) {
+    const path = join(sessionsDir, `${sessionId}.json`);
+    const source = await currentSourceStamp(path);
+    if (source === null)
+        return null;
+    const current = await readCurrentMetadata(metadataPath(sessionsDir, sessionId), sessionId, source);
+    if (current)
+        return current;
+    const rebuilt = await readSourceMetadata(path);
+    if (!rebuilt)
+        return null;
+    await writeMetadata(sessionsDir, rebuilt);
+    return rebuilt;
+}
+function settledMetadata(result) {
+    if (result.status === "rejected")
+        throw result.reason;
+    return result.value;
+}
+/**
+ * Each atomically published record completes its own backfill. Restarts reuse
+ * those records; interrupted backfills only rebuild missing/stale entries.
+ * Source stamps also detect older writers and a crash between the two commits.
+ */
+async function readMetadataList(sessionsDir) {
+    await mkdir(sessionsDir, { recursive: true });
+    const names = (await readdir(sessionsDir)).filter((name) => name.endsWith(".json"));
+    const records = [];
+    for (let offset = 0; offset < names.length; offset += concurrentMetadataReads) {
+        // Bound disk fan-out and drain the batch before propagating a canonical read failure.
+        const batch = await Promise.allSettled(names.slice(offset, offset + concurrentMetadataReads)
+            .map((name) => loadMetadata(sessionsDir, name.slice(0, -5))));
+        records.push(...batch.map(settledMetadata).filter((record) => record !== null));
+    }
+    return records.sort(compareSessionMetadata);
+}
+export async function listSessionMetadata(sessionsDir) {
+    const directory = resolve(sessionsDir);
+    const existing = pendingLists.get(directory);
+    if (existing)
+        return existing;
+    const pending = readMetadataList(directory);
+    pendingLists.set(directory, pending);
+    try {
+        return await pending;
+    }
+    finally {
+        pendingLists.delete(directory);
+    }
+}

package/dist/src/sessions/prepared-session-replacement.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Windows replacement can be denied while another reader holds the destination.
+ * EPERM can also be permanent: bounded failure retains the latest filesystem error.
+ * Only retry publication of this prepared file; callers retain cleanup and durability.
+ */
+export declare function replacePreparedSessionFile(temporary: string, target: string, assertCurrent?: () => void): Promise<void>;

package/dist/src/sessions/prepared-session-replacement.js

@@ -0,0 +1,46 @@
+import { rename } from "node:fs/promises";
+import { performance } from "node:perf_hooks";
+const WINDOWS_REPLACEMENT_WAIT_MS = 1_000;
+const WINDOWS_REPLACEMENT_DELAY_MS = 25;
+const MAX_REPLACEMENT_ATTEMPTS = 41;
+function isRetryableWindowsReplacementError(error) {
+    if (process.platform !== "win32")
+        return false;
+    if (error === null || typeof error !== "object")
+        return false;
+    return "code" in error && error.code === "EPERM";
+}
+function canWaitForSessionReplacement(attempts, deadline) {
+    if (attempts >= MAX_REPLACEMENT_ATTEMPTS)
+        return false;
+    return performance.now() < deadline;
+}
+/**
+ * Windows replacement can be denied while another reader holds the destination.
+ * EPERM can also be permanent: bounded failure retains the latest filesystem error.
+ * Only retry publication of this prepared file; callers retain cleanup and durability.
+ */
+export async function replacePreparedSessionFile(temporary, target, assertCurrent) {
+    const deadline = performance.now() + WINDOWS_REPLACEMENT_WAIT_MS;
+    let attempts = 0;
+    for (;;) {
+        // A guard failure is never a filesystem contention error, even if coded EPERM.
+        assertCurrent?.();
+        attempts += 1;
+        try {
+            await rename(temporary, target);
+            return;
+        }
+        catch (error) {
+            if (!isRetryableWindowsReplacementError(error))
+                throw error;
+            if (!canWaitForSessionReplacement(attempts, deadline))
+                throw error;
+            const delayMs = Math.min(WINDOWS_REPLACEMENT_DELAY_MS, deadline - performance.now());
+            await new Promise((resolve) => setTimeout(resolve, Math.max(0, delayMs)));
+            // Timer scheduling can run late. Do not begin another attempt beyond the bound.
+            if (performance.now() >= deadline)
+                throw error;
+        }
+    }
+}

package/dist/src/sessions/record/projection.d.ts

@@ -7,10 +7,12 @@ export declare function normalizeAfterSeq(afterSeq: number): number;
 export declare function toEpochMs(timestamp: string): number;
 export declare function toClientReplayEvent(event: SessionRuntimeEvent): Record<string, unknown>;
 export declare function getRequestFinalState(request: SessionRequestRecord): SessionRequestReplay["finalState"];
+export declare function toMessageIdForUi(id: string): string | number;
 export declare function isSameMessageId(messageId: string, requestedId: string): boolean;
 export declare function filterMessagesAfter(messages: SessionRecord["messages"], afterMessageId: string | number | null | undefined): SessionRecord["messages"];
 export declare function clientVisibleMessages(messages: SessionRecord["messages"]): SessionRecord["messages"];
-export declare function toSnapshotMessage(sessionId: string, message: SessionRecord["messages"][number], requests: SessionRequestRecord[]): SessionSnapshotMessage;
+export declare function toSnapshotMessage(sessionId: string, message: SessionRecord["messages"][number], requests: SessionRequestRecord[], resolveRequestId?: (message: SessionRecord["messages"][number]) => string | null): SessionSnapshotMessage;
+export declare function createMessageRequestIdResolver(requests: SessionRequestRecord[]): (message: SessionRecord["messages"][number]) => string | null;
 export declare function toSnapshotRequest(request: SessionRequestRecord): SessionSnapshotRequest;
 export declare function normalizeSessionTitle(title: string): string;
 export declare function toSessionListItem(session: SessionRecord): {

package/dist/src/sessions/record/projection.js

@@ -1,4 +1,4 @@
-import { isAssistantInitiativeMessage } from "../assistant-initiative.js";
+import { isAssistantInitiativeMessage } from "../assistant-initiative-message.js";
 import { projectSessionRequestLifecycle } from "../request-lifecycle/projection.js";
 function getRequestEventCompactionKey(payload) {
     const type = typeof payload.type === "string" ? payload.type : "";
@@ -87,7 +87,7 @@ export function getRequestFinalState(request) {
     }
     return null;
 }
-function toMessageIdForUi(id) {
+export function toMessageIdForUi(id) {
     const match = /^msg-(\d+)$/.exec(id);
     if (match) {
         return Number(match[1]);
@@ -143,7 +143,7 @@ function messageSource(message) {
     }
     return message.role === "user" ? "user" : "request";
 }
-export function toSnapshotMessage(sessionId, message, requests) {
+export function toSnapshotMessage(sessionId, message, requests, resolveRequestId = createMessageRequestIdResolver(requests)) {
     return {
         ...(message.kind ? { kind: message.kind } : {}),
         ...(message.approvalRequest
@@ -155,7 +155,7 @@ export function toSnapshotMessage(sessionId, message, requests) {
         text: message.content,
         source: messageSource(message),
         createdAt: toEpochMs(message.createdAt),
-        requestId: message.requestId ?? inferMessageRequestId(message, requests),
+        requestId: resolveRequestId(message),
         cronJobId: message.cronJobId ?? null,
         ...(message.initiative ? { initiative: message.initiative } : {}),
         ...(message.schedule ? { schedule: message.schedule } : {}),
@@ -166,22 +166,30 @@ export function toSnapshotMessage(sessionId, message, requests) {
             : {}),
     };
 }
-function inferMessageRequestId(message, requests) {
-    if (isAssistantInitiativeMessage(message))
-        return null;
-    if (message.role !== "assistant") {
-        return null;
-    }
-    for (let index = requests.length - 1; index >= 0; index -= 1) {
-        const request = requests[index];
+export function createMessageRequestIdResolver(requests) {
+    let completedOutputs;
+    return (message) => {
+        if (message.requestId != null)
+            return message.requestId;
+        if (isAssistantInitiativeMessage(message))
+            return null;
+        if (message.role !== "assistant")
+            return null;
+        completedOutputs ??= indexCompletedRequestOutputs(requests);
+        return completedOutputs.get(message.content) ?? null;
+    };
+}
+function indexCompletedRequestOutputs(requests) {
+    const outputs = new Map();
+    for (const request of requests) {
         const finalState = getRequestFinalState(request);
-        if (finalState?.status === "completed" &&
-            typeof finalState.output === "string" &&
-            finalState.output === message.content) {
-            return request.requestId;
-        }
+        if (finalState?.status !== "completed")
+            continue;
+        if (typeof finalState.output !== "string")
+            continue;
+        outputs.set(finalState.output, request.requestId);
     }
-    return null;
+    return outputs;
 }
 export function toSnapshotRequest(request) {
     return {

package/dist/src/sessions/request-lifecycle/service.js

@@ -10,7 +10,7 @@ import { acceptedLifecycle, appendLifecycleEvent, lifecycleRequest, rejectLifecy
 /** Commands share SessionService's queue and file, never a parallel checkpoint store. */
 export function createSessionRequestLifecycle(dependencies) {
     const blobs = createSessionContinuationBlobs(dependencies.sessionsDir);
-    async function mutate(sessionId, operation) {
+    async function mutate(sessionId, operation, metadataChange = "projection") {
         assertValidSessionId(sessionId);
         return dependencies.enqueue(sessionId, async () => {
             const session = await dependencies.read(sessionId);
@@ -24,7 +24,7 @@ export function createSessionRequestLifecycle(dependencies) {
             });
             if (!result.accepted || result.duplicate)
                 return result;
-            await saveDurableSessionFile(dependencies.sessionsDir, session);
+            await saveDurableSessionFile(dependencies.sessionsDir, session, undefined, metadataChange);
             await cleanupConsumedSessionContinuations(dependencies.sessionsDir, session, previousBlobs);
             return result;
         });
@@ -59,7 +59,7 @@ export function createSessionRequestLifecycle(dependencies) {
             return acceptedLifecycle(request, [
                 appendLifecycleEvent(context, request, command.payload),
             ]);
-        }),
+        }, "request-only"),
         async get(sessionId, requestId) {
             const request = await readRequest(sessionId, requestId);
             return request ? (projectSessionRequestLifecycle(request) ?? null) : null;

package/dist/src/sessions/session-service.d.ts

@@ -1,3 +1,4 @@
+import { type SessionSnapshotOptions } from "./snapshot.js";
 import { type AutomationSessionHandle, type AutomationSessionOrigin } from "./automation-session-origin.js";
 import type { SessionRequestLifecycleStore } from "./request-lifecycle/contracts.js";
 import { type CreateAssistantConversationInput } from "./assistant-initiative.js";
@@ -31,10 +32,7 @@ export declare class SessionService {
         cursor?: string | null;
     }): Promise<SessionListResult>;
     getSessionById(sessionId: string): Promise<SessionRecord | null>;
-    getSessionSnapshot(sessionId: string, options?: {
-        afterMessageId?: string | number | null;
-        includeRequests?: boolean;
-    }): Promise<SessionSnapshot | null>;
+    getSessionSnapshot(sessionId: string, options?: SessionSnapshotOptions): Promise<SessionSnapshot | null>;
     getRequestReplayById(requestId: string, afterSeq?: number): Promise<SessionRequestReplay | null>;
     deleteSession(sessionId: string): Promise<boolean>;
     deleteSessionWithStats(sessionId: string): Promise<SessionDeleteResult>;

package/dist/src/sessions/session-service.js

@@ -1,3 +1,4 @@
+import { projectSessionSnapshot } from "./snapshot.js";
 import { randomUUID } from "node:crypto";
 import { AutomationSessionLockedError, createAutomationSessionAccess, hasAutomationSessionOrigin, } from "./automation-session-origin.js";
 import { createAutomationSessionStore } from "./automation-session-store.js";
@@ -9,7 +10,7 @@ import { createAssistantConversationRecord, } from "./assistant-initiative.js";
 import { assertSessionProjectUnchanged, copySessionProject, } from "./project-binding.js";
 import { getDefaultSessionsDir } from "../runtime/config/layout.js";
 import { assertValidSessionArtifactPathInputs, upsertSessionArtifactPaths, } from "./artifact-paths.js";
-import { clientVisibleMessages, compactRequestEvents, filterMessagesAfter, getRequestFinalState, getSessionRequest, isSameMessageId, normalizeAfterSeq, normalizeCursor, normalizeLimit, normalizeSessionTitle, toClientReplayEvent, toEpochMs, toSessionListItem, toSnapshotMessage, toSnapshotRequest, } from "./record/projection.js";
+import { compactRequestEvents, getRequestFinalState, getSessionRequest, isSameMessageId, normalizeAfterSeq, normalizeCursor, normalizeLimit, normalizeSessionTitle, toClientReplayEvent, toEpochMs, toSessionListItem, } from "./record/projection.js";
 import { assertValidRequestId, assertValidSessionId, createContextEntryId, defaultCreateMessageId, pruneSupersededContextEntries, } from "./record/rules.js";
 import { deleteSessionFile, ensureSessionsDir, loadAllSessionFiles, loadSessionFile, saveSessionFile, } from "./session-store.js";
 import { resolveSessionMemoryCheckpointCommit } from "./memory/rules.js";
@@ -115,20 +116,7 @@ export class SessionService {
     }
     async getSessionSnapshot(sessionId, options = {}) {
         const session = await this.getSessionById(sessionId);
-        if (!session) {
-            return null;
-        }
-        return {
-            sessionId,
-            ...(session.kind ? { kind: session.kind } : {}),
-            ...(session.project ? { project: session.project } : {}),
-            title: session.title,
-            messages: filterMessagesAfter(clientVisibleMessages(session.messages), options.afterMessageId).map((message) => toSnapshotMessage(sessionId, message, session.requests ?? [])),
-            requests: options.includeRequests === false
-                ? []
-                : (session.requests ?? []).map(toSnapshotRequest),
-            nextCursor: null,
-        };
+        return session ? projectSessionSnapshot(session, options) : null;
     }
     async getRequestReplayById(requestId, afterSeq = 0) {
         assertValidRequestId(requestId);
@@ -440,7 +428,7 @@ export class SessionService {
                 request.status = "streaming";
             }
             session.updatedAt = timestamp;
-            await saveSessionFile(this.sessionsDir, session);
+            await saveSessionFile(this.sessionsDir, session, undefined, "request-only");
             return session;
         });
     }

package/dist/src/sessions/session-store.d.ts

@@ -1,6 +1,7 @@
 import type { SessionRecord } from "./types.js";
+import type { SessionMetadataChange } from "./metadata/source-receipt.js";
 export declare function ensureSessionsDir(sessionsDir: string): Promise<void>;
 export declare function loadSessionFile(sessionsDir: string, sessionId: string): Promise<SessionRecord | null>;
-export declare function saveSessionFile(sessionsDir: string, session: SessionRecord, assertCurrent?: () => void): Promise<void>;
+export declare function saveSessionFile(sessionsDir: string, session: SessionRecord, assertCurrent?: () => void, metadataChange?: SessionMetadataChange): Promise<void>;
 export declare function deleteSessionFile(sessionsDir: string, sessionId: string): Promise<boolean>;
 export declare function loadAllSessionFiles(sessionsDir: string): Promise<SessionRecord[]>;

package/dist/src/sessions/session-store.js

@@ -1,8 +1,10 @@
-import { mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat, writeFile, } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
+import { replacePreparedSessionFile } from "./prepared-session-replacement.js";
 import { saveDurableSessionFile, syncSessionDirectory, } from "./durable-session-commit.js";
 import { cleanupSessionContinuations } from "./request-lifecycle/continuation-cleanup.js";
+import { currentSourceStamp, deleteSessionMetadata, sessionSourceStamp, updateSessionMetadata } from "./metadata/store.js";
 function getSessionFilePath(sessionsDir, sessionId) {
     return join(sessionsDir, `${sessionId}.json`);
 }
@@ -22,27 +24,31 @@ export async function loadSessionFile(sessionsDir, sessionId) {
         throw error;
     }
 }
-export async function saveSessionFile(sessionsDir, session, assertCurrent) {
+export async function saveSessionFile(sessionsDir, session, assertCurrent, metadataChange = "projection") {
     if (session.requests?.some((request) => request.lifecycle)) {
-        return saveDurableSessionFile(sessionsDir, session, assertCurrent);
+        return saveDurableSessionFile(sessionsDir, session, assertCurrent, metadataChange);
     }
     const filePath = getSessionFilePath(sessionsDir, session.id);
+    const previousSource = metadataChange === "request-only" ? await currentSourceStamp(filePath) : undefined;
     const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    let source;
     try {
         await writeFile(tempPath, JSON.stringify(session, null, 2), "utf-8");
-        assertCurrent?.();
-        await rename(tempPath, filePath);
+        source = sessionSourceStamp(await stat(tempPath, { bigint: true }));
+        await replacePreparedSessionFile(tempPath, filePath, assertCurrent);
     }
     catch (error) {
         await rm(tempPath, { force: true }).catch(() => undefined);
         throw error;
     }
+    await updateSessionMetadata(sessionsDir, session, source, previousSource);
 }
 export async function deleteSessionFile(sessionsDir, sessionId) {
     const filePath = getSessionFilePath(sessionsDir, sessionId);
     try {
         await rm(filePath);
         await syncSessionDirectory(sessionsDir);
+        await deleteSessionMetadata(sessionsDir, sessionId);
         await cleanupSessionContinuations(sessionsDir, sessionId);
         return true;
     }

package/dist/src/sessions/snapshot.d.ts

@@ -0,0 +1,17 @@
+import type { SessionRecord, SessionSnapshot, SessionSnapshotMessage } from "./types.js";
+export type SessionMessageIdentity = Pick<SessionSnapshotMessage, "id" | "role" | "createdAt" | "requestId">;
+export type SessionSnapshotOptions = {
+    afterMessageId?: string | number | null;
+    includeRequests?: boolean;
+    /** Web read receipts need identities, never message bodies or request events. */
+    identitiesOnly?: boolean;
+    page?: {
+        limit: number;
+        cursor?: string | null;
+        targetMessageId?: string;
+        targetCreatedAt?: number;
+        targetRequestId?: string;
+        waitingRequestId?: string;
+    };
+};
+export declare function projectSessionSnapshot(session: SessionRecord, options?: SessionSnapshotOptions): SessionSnapshot;