open-multi-agent-kit 0.90.8 → 0.91.0

package/dist/core/session-manager.js

@@ -1,5 +1,5 @@
-import { randomUUID } from "crypto";
-import { appendFileSync, closeSync, createReadStream, existsSync, mkdirSync, openSync, readdirSync, readSync, renameSync, statSync, writeFileSync, } from "fs";
+import { createHash, randomUUID } from "crypto";
+import { closeSync, createReadStream, existsSync, openSync, readdirSync, readSync, renameSync, statSync } from "fs";
 import { readdir, stat } from "fs/promises";
 import { uuidv7 } from "omk-agent-core";
 import { join, resolve } from "path";
@@ -7,7 +7,16 @@ import { createInterface } from "readline";
 import { StringDecoder } from "string_decoder";
 import { getAgentDir as getDefaultAgentDir, getSessionsDir } from "../config.js";
 import { normalizePath, resolvePath } from "../utils/paths.js";
+import { atomicRewriteFileSync } from "./atomic-session-file.js";
+import { createSessionRevisionToken, } from "./compaction/transaction.js";
+import { acquireDurableFileMutationLockSync } from "./durable-file-identity.js";
+import { appendFileDurablySync, ensureDurableDirectorySync } from "./durable-file-io.js";
+import { enforcePrivateFileModeSync } from "./durable-file-mode.js";
 import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "./messages.js";
+import { rebindBranchedCompactionEnvelopes, validatePersistedCompactionEnvelopes } from "./session-file-compaction.js";
+import { quarantineSessionTrailingFragment, SessionManagerStaleWriteError, sameDurableSessionHead, sessionDurableHeadFromFile, sessionDurableHeadFromSnapshot, } from "./session-file-persistence.js";
+import { assertSessionOwnerRecoveryAllowedUnlockedSync } from "./session-owner-lease.js";
+export { SessionManagerStaleWriteError };
 export const CURRENT_SESSION_VERSION = 3;
 function createSessionId() {
     return uuidv7();
@@ -98,8 +107,9 @@ export function parseSessionEntries(content) {
             const entry = JSON.parse(line);
             entries.push(entry);
         }
-        catch {
-            // Skip malformed lines
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
         }
     }
     return entries;
@@ -225,9 +235,8 @@ function getDefaultSessionDirPath(cwd, agentDir = getDefaultAgentDir()) {
 }
 export function getDefaultSessionDir(cwd, agentDir = getDefaultAgentDir()) {
     const sessionDir = getDefaultSessionDirPath(cwd, agentDir);
-    if (!existsSync(sessionDir)) {
-        mkdirSync(sessionDir, { recursive: true });
-    }
+    if (!existsSync(sessionDir))
+        ensureDurableDirectorySync(sessionDir);
     return sessionDir;
 }
 const SESSION_READ_BUFFER_SIZE = 1024 * 1024;
@@ -269,10 +278,9 @@ export function loadEntriesFromFile(filePath) {
             }
             pending = pending.slice(lineStart);
         }
-        pending += decoder.end();
-        const finalEntry = parseSessionEntryLine(pending);
-        if (finalEntry)
-            entries.push(finalEntry);
+        // Complete-prefix semantics: bytes after the final newline are never
+        // parsed here. SessionManager.open() quarantines them before loading.
+        decoder.end();
     }
     finally {
         closeSync(fd);
@@ -286,6 +294,9 @@ export function loadEntriesFromFile(filePath) {
     }
     return entries;
 }
+function serializeFileEntries(entries) {
+    return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
+}
 /**
  * Preserve a corrupt (non-empty, headerless) session file by renaming it to
  * `<file>.corrupt-<timestamp>` so recovery never destroys user data.
@@ -312,25 +323,35 @@ function backupCorruptSessionFile(filePath) {
 function readSessionHeader(filePath) {
     try {
         const fd = openSync(filePath, "r");
-        const buffer = Buffer.alloc(512);
-        const bytesRead = readSync(fd, buffer, 0, 512, 0);
-        closeSync(fd);
+        const buffer = Buffer.alloc(64 * 1024);
+        let bytesRead;
+        try {
+            bytesRead = readSync(fd, buffer, 0, buffer.byteLength, 0);
+        }
+        finally {
+            closeSync(fd);
+        }
         const firstLine = buffer.toString("utf8", 0, bytesRead).split("\n")[0];
         if (!firstLine)
             return null;
         const header = JSON.parse(firstLine);
-        if (header.type !== "session" || typeof header.id !== "string") {
+        if (header.type !== "session" || typeof header.id !== "string")
             return null;
-        }
-        return header;
+        return {
+            type: "session",
+            id: header.id,
+            timestamp: typeof header.timestamp === "string" ? header.timestamp : "",
+            cwd: typeof header.cwd === "string" ? header.cwd : "",
+            ...(typeof header.version === "number" ? { version: header.version } : {}),
+            ...(typeof header.parentSession === "string" ? { parentSession: header.parentSession } : {}),
+        };
     }
     catch {
         return null;
     }
 }
 function getSessionHeaderCwd(header) {
-    const cwd = header.cwd;
-    return typeof cwd === "string" ? cwd : undefined;
+    return header.cwd;
 }
 function sessionCwdMatches(cwd, resolvedCwd) {
     return cwd !== undefined && cwd !== "" && resolvePath(cwd) === resolvedCwd;
@@ -508,8 +529,9 @@ async function listSessionsFromDir(dir, onProgress, progressOffset = 0, progress
             }
         }
     }
-    catch {
-        // Return empty list on error
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
     }
     return sessions;
 }
@@ -536,13 +558,16 @@ export class SessionManager {
     labelsById = new Map();
     labelTimestampsById = new Map();
     leafId = null;
+    sessionFileLockDepth = 0;
+    acceptedDurableHead = null;
+    quarantineReport = null;
+    ownerLease;
     constructor(cwd, sessionDir, sessionFile, persist, newSessionOptions) {
         this.cwd = resolvePath(cwd);
         this.sessionDir = normalizePath(sessionDir);
         this.persist = persist;
-        if (persist && this.sessionDir && !existsSync(this.sessionDir)) {
-            mkdirSync(this.sessionDir, { recursive: true });
-        }
+        if (persist && this.sessionDir && !existsSync(this.sessionDir))
+            ensureDurableDirectorySync(this.sessionDir);
         if (sessionFile) {
             this.setSessionFile(sessionFile);
         }
@@ -550,41 +575,76 @@ export class SessionManager {
             this.newSession(newSessionOptions);
         }
     }
-    /** Switch to a different session file (used for resume and branching) */
+    /** Switch to a different session file (used for resume and branching). */
     setSessionFile(sessionFile) {
-        this.sessionFile = resolvePath(sessionFile);
-        if (existsSync(this.sessionFile)) {
-            this.fileEntries = loadEntriesFromFile(this.sessionFile);
-            // If file was empty or corrupted (no valid header), start fresh to avoid
-            // appending messages without a session header (which breaks the session).
-            // Never destroy existing data: if the file has content, preserve the
-            // original as a .corrupt-* backup before rewriting.
-            if (this.fileEntries.length === 0) {
-                const explicitPath = this.sessionFile;
-                if (this.persist) {
-                    backupCorruptSessionFile(explicitPath);
+        const explicitPath = resolvePath(sessionFile);
+        if (!existsSync(explicitPath)) {
+            this.newSession();
+            this.sessionFile = explicitPath;
+            return;
+        }
+        const loaded = this._withSessionPathLock(explicitPath, () => {
+            enforcePrivateFileModeSync(explicitPath);
+            const quarantine = quarantineSessionTrailingFragment(explicitPath);
+            let entries = loadEntriesFromFile(explicitPath);
+            if (entries.length === 0) {
+                if (statSync(explicitPath).nlink > 1) {
+                    throw new Error("Session recovery refused for a target with more than one hard link");
                 }
-                this.newSession();
-                this.sessionFile = explicitPath;
-                this._rewriteFile();
-                this.flushed = true;
-                return;
+                if (this.persist)
+                    backupCorruptSessionFile(explicitPath);
+                const timestamp = new Date().toISOString();
+                const sessionId = createSessionId();
+                entries = [{ type: "session", version: CURRENT_SESSION_VERSION, id: sessionId, timestamp, cwd: this.cwd }];
+                atomicRewriteFileSync(explicitPath, serializeFileEntries(entries));
+                return {
+                    entries,
+                    sessionId,
+                    quarantineReport: quarantine.report,
+                    acceptedDurableHead: sessionDurableHeadFromFile(explicitPath, null, entries),
+                };
             }
-            const header = this.fileEntries.find((e) => e.type === "session");
-            this.sessionId = header?.id ?? createSessionId();
-            if (migrateToCurrentVersion(this.fileEntries)) {
-                this._rewriteFile();
+            const header = entries[0];
+            if (header.type !== "session")
+                throw new Error("Session file has no valid header");
+            const sessionId = header.id;
+            const lastLoaded = entries.at(-1);
+            const loadedLeafId = lastLoaded && lastLoaded.type !== "session" && typeof lastLoaded.id === "string" ? lastLoaded.id : null;
+            const needsMigration = (header.version ?? 1) < CURRENT_SESSION_VERSION;
+            const acceptedBeforeMigration = needsMigration
+                ? quarantine.snapshot
+                    ? sessionDurableHeadFromSnapshot(quarantine.snapshot, loadedLeafId, entries)
+                    : sessionDurableHeadFromFile(explicitPath, loadedLeafId, entries)
+                : null;
+            validatePersistedCompactionEnvelopes(explicitPath, entries, sessionId);
+            const migrated = migrateToCurrentVersion(entries);
+            if (migrated) {
+                const current = sessionDurableHeadFromFile(explicitPath, loadedLeafId, loadEntriesFromFile(explicitPath));
+                if (!sameDurableSessionHead(current, acceptedBeforeMigration))
+                    throw new SessionManagerStaleWriteError();
+                atomicRewriteFileSync(explicitPath, serializeFileEntries(entries));
             }
-            this._buildIndex();
-            this.flushed = true;
-        }
-        else {
-            const explicitPath = this.sessionFile;
-            this.newSession();
-            this.sessionFile = explicitPath; // preserve explicit path from --session flag
-        }
+            const lastEntry = entries.at(-1);
+            const leafId = lastEntry && lastEntry.type !== "session" ? lastEntry.id : null;
+            return {
+                entries,
+                sessionId,
+                quarantineReport: quarantine.report,
+                acceptedDurableHead: !migrated && quarantine.snapshot
+                    ? sessionDurableHeadFromSnapshot(quarantine.snapshot, leafId, entries)
+                    : sessionDurableHeadFromFile(explicitPath, leafId, entries),
+            };
+        });
+        this.fileEntries = loaded.entries;
+        this.sessionId = loaded.sessionId;
+        this.quarantineReport = loaded.quarantineReport;
+        this._buildIndex();
+        this.flushed = true;
+        this.acceptedDurableHead = loaded.acceptedDurableHead;
+        this.sessionFile = explicitPath;
     }
     newSession(options) {
+        this.quarantineReport = null;
         if (options?.id !== undefined) {
             assertValidSessionId(options.id);
         }
@@ -601,8 +661,10 @@ export class SessionManager {
         this.fileEntries = [header];
         this.byId.clear();
         this.labelsById.clear();
+        this.labelTimestampsById.clear();
         this.leafId = null;
         this.flushed = false;
+        this.acceptedDurableHead = null;
         if (this.persist) {
             const fileTimestamp = timestamp.replace(/[:.]/g, "-");
             this.sessionFile = join(this.getSessionDir(), `${fileTimestamp}_${this.sessionId}.jsonl`);
@@ -631,19 +693,59 @@ export class SessionManager {
             }
         }
     }
-    _rewriteFile() {
-        if (!this.persist || !this.sessionFile)
-            return;
-        const fd = openSync(this.sessionFile, "w");
+    _withSessionPathLock(sessionFile, fn) {
+        if (!this.persist || this.sessionFileLockDepth > 0)
+            return fn();
+        const lock = acquireDurableFileMutationLockSync(sessionFile);
+        this.sessionFileLockDepth += 1;
         try {
-            for (const entry of this.fileEntries) {
-                writeFileSync(fd, `${JSON.stringify(entry)}\n`);
-            }
+            assertSessionOwnerRecoveryAllowedUnlockedSync(sessionFile, this.ownerLease);
+            return fn();
         }
         finally {
-            closeSync(fd);
+            this.sessionFileLockDepth -= 1;
+            lock.release();
+        }
+    }
+    _withSessionFileLock(fn) {
+        return this.sessionFile ? this._withSessionPathLock(this.sessionFile, fn) : fn();
+    }
+    _assertAcceptedDurableHead() {
+        if (!this.sessionFile)
+            return;
+        const current = sessionDurableHeadFromFile(this.sessionFile, this.leafId, loadEntriesFromFile(this.sessionFile));
+        if ((current === null && existsSync(this.sessionFile)) ||
+            !sameDurableSessionHead(current, this.acceptedDurableHead)) {
+            throw new SessionManagerStaleWriteError();
         }
     }
+    /** Reread the interprocess-visible session head while holding the shared file lock. */
+    getDurableHeadToken() {
+        return this._withSessionFileLock(() => {
+            if (this.sessionFile) {
+                const durable = sessionDurableHeadFromFile(this.sessionFile, this.leafId, loadEntriesFromFile(this.sessionFile));
+                if (durable)
+                    return durable.revision;
+                if (existsSync(this.sessionFile)) {
+                    throw new SessionManagerStaleWriteError("Session file no longer has an accepted durable identity");
+                }
+            }
+            const bytes = new TextEncoder().encode(serializeFileEntries(this.fileEntries));
+            const lastEntry = this.fileEntries.at(-1);
+            return createSessionRevisionToken({
+                sessionId: this.sessionId,
+                completeBytes: bytes.byteLength,
+                recordCount: this.fileEntries.length,
+                leafId: this.leafId,
+                lastEntryId: lastEntry && lastEntry.type !== "session" ? lastEntry.id : null,
+                completePrefixSha256: createHash("sha256").update(bytes).digest("hex"),
+            });
+        });
+    }
+    /** Serialize compaction compare-and-append with every SessionManager writer for this file. */
+    withCompactionCommitLock(fn) {
+        return this._withSessionFileLock(fn);
+    }
     isPersisted() {
         return this.persist;
     }
@@ -662,41 +764,46 @@ export class SessionManager {
     getSessionFile() {
         return this.sessionFile;
     }
-    _persist(entry) {
-        if (!this.persist || !this.sessionFile)
-            return;
-        const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message.role === "assistant");
-        if (!hasAssistant) {
-            if (this.flushed) {
-                appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
-            }
-            else {
-                // Mark as not flushed so when assistant arrives, all entries get written
-                this.flushed = false;
-            }
+    getQuarantineReport() {
+        return this.quarantineReport;
+    }
+    setOwnerLease(lease) {
+        if (lease && this.sessionFile && !lease.owns(this.sessionFile)) {
+            throw new TypeError("Session owner lease does not identify this session file");
+        }
+        this.ownerLease = lease;
+    }
+    _appendEntry(entry) {
+        if (!this.persist || !this.sessionFile) {
+            this.fileEntries.push(entry);
+            this.byId.set(entry.id, entry);
+            this.leafId = entry.id;
             return;
         }
-        if (!this.flushed) {
-            const fd = openSync(this.sessionFile, "wx");
-            try {
-                for (const e of this.fileEntries) {
-                    writeFileSync(fd, `${JSON.stringify(e)}\n`);
-                }
+        const sessionFile = this.sessionFile;
+        this._withSessionFileLock(() => {
+            this._assertAcceptedDurableHead();
+            const candidateEntries = [...this.fileEntries, entry];
+            const hasAssistant = candidateEntries.some((candidate) => candidate.type === "message" && candidate.message.role === "assistant");
+            let nextDurableHead = this.acceptedDurableHead;
+            let flushed = this.flushed;
+            if (flushed) {
+                appendFileDurablySync(sessionFile, Buffer.from(`${JSON.stringify(entry)}\n`, "utf8"));
+                nextDurableHead = sessionDurableHeadFromFile(sessionFile, entry.id, candidateEntries);
             }
-            finally {
-                closeSync(fd);
+            else if (hasAssistant) {
+                atomicRewriteFileSync(sessionFile, serializeFileEntries(candidateEntries));
+                this.ownerLease?.refresh(true);
+                nextDurableHead = sessionDurableHeadFromFile(sessionFile, entry.id, candidateEntries);
+                flushed = true;
             }
-            this.flushed = true;
-        }
-        else {
-            appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
-        }
-    }
-    _appendEntry(entry) {
-        this.fileEntries.push(entry);
-        this.byId.set(entry.id, entry);
-        this.leafId = entry.id;
-        this._persist(entry);
+            // Accept memory only after every required persistence step succeeds.
+            this.fileEntries.push(entry);
+            this.byId.set(entry.id, entry);
+            this.leafId = entry.id;
+            this.acceptedDurableHead = nextDurableHead;
+            this.flushed = flushed;
+        });
     }
     /** Append a message as child of current leaf, then advance leaf. Returns entry id.
      * Does not allow writing CompactionSummaryMessage and BranchSummaryMessage directly.
@@ -929,6 +1036,8 @@ export class SessionManager {
         // Build tree
         for (const entry of entries) {
             const node = nodeMap.get(entry.id);
+            if (!node)
+                continue;
             if (entry.parentId === null || entry.parentId === entry.id) {
                 roots.push(node);
             }
@@ -948,6 +1057,8 @@ export class SessionManager {
         const stack = [...roots];
         while (stack.length > 0) {
             const node = stack.pop();
+            if (!node)
+                continue;
             node.children.sort((a, b) => new Date(a.entry.timestamp).getTime() - new Date(b.entry.timestamp).getTime());
             stack.push(...node.children);
         }
@@ -985,7 +1096,6 @@ export class SessionManager {
         if (branchFromId !== null && !this.byId.has(branchFromId)) {
             throw new Error(`Entry ${branchFromId} not found`);
         }
-        this.leafId = branchFromId;
         const entry = {
             type: "branch_summary",
             id: generateId(this.byId),
@@ -1005,13 +1115,10 @@ export class SessionManager {
      * Returns the new session file path, or undefined if not persisting.
      */
     createBranchedSession(leafId) {
-        const previousSessionFile = this.sessionFile;
         const path = this.getBranch(leafId);
         if (path.length === 0) {
             throw new Error(`Entry ${leafId} not found`);
         }
-        // Filter out LabelEntry from path - we'll recreate them from the resolved map
-        const pathWithoutLabels = path.filter((e) => e.type !== "label");
         const newSessionId = createSessionId();
         const timestamp = new Date().toISOString();
         const fileTimestamp = timestamp.replace(/[:.]/g, "-");
@@ -1022,14 +1129,19 @@ export class SessionManager {
             id: newSessionId,
             timestamp,
             cwd: this.cwd,
-            parentSession: this.persist ? previousSessionFile : undefined,
+            parentSession: this.persist ? this.sessionFile : undefined,
         };
+        const pathWithoutLabels = rebindBranchedCompactionEnvelopes(header, path);
         // Collect labels for entries in the path
         const pathEntryIds = new Set(pathWithoutLabels.map((e) => e.id));
+        const preservedLabels = new Map(pathWithoutLabels
+            .filter((entry) => entry.type === "label")
+            .map((entry) => [entry.targetId, entry.label]));
         const labelsToWrite = [];
         for (const [targetId, label] of this.labelsById) {
-            if (pathEntryIds.has(targetId)) {
-                labelsToWrite.push({ targetId, label, timestamp: this.labelTimestampsById.get(targetId) });
+            const labelTimestamp = this.labelTimestampsById.get(targetId);
+            if (pathEntryIds.has(targetId) && labelTimestamp && preservedLabels.get(targetId) !== label) {
+                labelsToWrite.push({ targetId, label, timestamp: labelTimestamp });
             }
         }
         if (this.persist) {
@@ -1050,23 +1162,28 @@ export class SessionManager {
                 labelEntries.push(labelEntry);
                 parentId = labelEntry.id;
             }
-            this.fileEntries = [header, ...pathWithoutLabels, ...labelEntries];
+            const candidateEntries = [header, ...pathWithoutLabels, ...labelEntries];
+            const hasAssistant = candidateEntries.some((entry) => entry.type === "message" && entry.message.role === "assistant");
+            let acceptedDurableHead = null;
+            if (hasAssistant) {
+                const lock = acquireDurableFileMutationLockSync(newSessionFile);
+                try {
+                    if (existsSync(newSessionFile))
+                        throw new SessionManagerStaleWriteError("Branched session path already exists");
+                    atomicRewriteFileSync(newSessionFile, serializeFileEntries(candidateEntries));
+                    acceptedDurableHead = sessionDurableHeadFromFile(newSessionFile, labelEntries.at(-1)?.id ?? lastEntryId, candidateEntries);
+                }
+                finally {
+                    lock.release();
+                }
+            }
+            // Switch accepted memory only after the optional rewrite succeeds.
+            this.fileEntries = candidateEntries;
             this.sessionId = newSessionId;
             this.sessionFile = newSessionFile;
             this._buildIndex();
-            // Only write the file now if it contains an assistant message.
-            // Otherwise defer to _persist(), which creates the file on the
-            // first assistant response, matching the newSession() contract
-            // and avoiding the duplicate-header bug when _persist()'s
-            // no-assistant guard later resets flushed to false.
-            const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message.role === "assistant");
-            if (hasAssistant) {
-                this._rewriteFile();
-                this.flushed = true;
-            }
-            else {
-                this.flushed = false;
-            }
+            this.acceptedDurableHead = acceptedDurableHead;
+            this.flushed = hasAssistant;
             return newSessionFile;
         }
         // In-memory mode: replace current session with the path + labels
@@ -1106,9 +1223,7 @@ export class SessionManager {
      */
     static open(path, sessionDir, cwdOverride) {
         const resolvedPath = resolvePath(path);
-        // Extract cwd from session header if possible, otherwise use process.cwd()
-        const entries = loadEntriesFromFile(resolvedPath);
-        const header = entries.find((e) => e.type === "session");
+        const header = readSessionHeader(resolvedPath);
         const cwd = cwdOverride ?? header?.cwd ?? process.cwd();
         // If no sessionDir provided, derive from file's parent directory
         const dir = sessionDir ? normalizePath(sessionDir) : resolve(resolvedPath, "..");
@@ -1151,9 +1266,8 @@ export class SessionManager {
             throw new Error(`Cannot fork: source session has no header: ${resolvedSourcePath}`);
         }
         const dir = sessionDir ? normalizePath(sessionDir) : getDefaultSessionDir(resolvedTargetCwd);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
+        if (!existsSync(dir))
+            ensureDurableDirectorySync(dir);
         // Create new session file with new ID but forked content
         if (options?.id !== undefined) {
             assertValidSessionId(options.id);
@@ -1171,12 +1285,15 @@ export class SessionManager {
             cwd: resolvedTargetCwd,
             parentSession: resolvedSourcePath,
         };
-        writeFileSync(newSessionFile, `${JSON.stringify(newHeader)}\n`, { flag: "wx" });
-        // Copy all non-header entries from source
-        for (const entry of sourceEntries) {
-            if (entry.type !== "session") {
-                appendFileSync(newSessionFile, `${JSON.stringify(entry)}\n`);
-            }
+        const forkEntries = [newHeader, ...sourceEntries.filter((entry) => entry.type !== "session")];
+        const lock = acquireDurableFileMutationLockSync(newSessionFile);
+        try {
+            if (existsSync(newSessionFile))
+                throw new SessionManagerStaleWriteError("Fork session path already exists");
+            atomicRewriteFileSync(newSessionFile, serializeFileEntries(forkEntries));
+        }
+        finally {
+            lock.release();
         }
         return new SessionManager(resolvedTargetCwd, dir, newSessionFile, true);
     }