@mariozechner/pi-coding-agent 0.30.2 → 0.31.0

package/dist/core/session-manager.js

@@ -1,27 +1,63 @@
-import { randomBytes } from "crypto";
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "fs";
+import { randomUUID } from "crypto";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, statSync, writeFileSync, } from "fs";
 import { join, resolve } from "path";
 import { getAgentDir as getDefaultAgentDir } from "../config.js";
-function uuidv4() {
-    const bytes = randomBytes(16);
-    bytes[6] = (bytes[6] & 0x0f) | 0x40;
-    bytes[8] = (bytes[8] & 0x3f) | 0x80;
-    const hex = bytes.toString("hex");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+import { createBranchSummaryMessage, createCompactionSummaryMessage, createHookMessage, } from "./messages.js";
+export const CURRENT_SESSION_VERSION = 2;
+/** Generate a unique short ID (8 hex chars, collision-checked) */
+function generateId(byId) {
+    for (let i = 0; i < 100; i++) {
+        const id = randomUUID().slice(0, 8);
+        if (!byId.has(id))
+            return id;
+    }
+    // Fallback to full UUID if somehow we have collisions
+    return randomUUID();
 }
-export const SUMMARY_PREFIX = `The conversation history before this point was compacted into the following summary:
-
-<summary>
-`;
-export const SUMMARY_SUFFIX = `
-</summary>`;
-/** Exported for compaction.test.ts */
-export function createSummaryMessage(summary) {
-    return {
-        role: "user",
-        content: SUMMARY_PREFIX + summary + SUMMARY_SUFFIX,
-        timestamp: Date.now(),
-    };
+/** Migrate v1 → v2: add id/parentId tree structure. Mutates in place. */
+function migrateV1ToV2(entries) {
+    const ids = new Set();
+    let prevId = null;
+    for (const entry of entries) {
+        if (entry.type === "session") {
+            entry.version = 2;
+            continue;
+        }
+        entry.id = generateId(ids);
+        entry.parentId = prevId;
+        prevId = entry.id;
+        // Convert firstKeptEntryIndex to firstKeptEntryId for compaction
+        if (entry.type === "compaction") {
+            const comp = entry;
+            if (typeof comp.firstKeptEntryIndex === "number") {
+                const targetEntry = entries[comp.firstKeptEntryIndex];
+                if (targetEntry && targetEntry.type !== "session") {
+                    comp.firstKeptEntryId = targetEntry.id;
+                }
+                delete comp.firstKeptEntryIndex;
+            }
+        }
+    }
+}
+// Add future migrations here:
+// function migrateV2ToV3(entries: FileEntry[]): void { ... }
+/**
+ * Run all necessary migrations to bring entries to current version.
+ * Mutates entries in place. Returns true if any migration was applied.
+ */
+function migrateToCurrentVersion(entries) {
+    const header = entries.find((e) => e.type === "session");
+    const version = header?.version ?? 1;
+    if (version >= CURRENT_SESSION_VERSION)
+        return false;
+    if (version < 2)
+        migrateV1ToV2(entries);
+    // if (version < 3) migrateV2ToV3(entries);
+    return true;
+}
+/** Exported for testing */
+export function migrateSessionEntries(entries) {
+    migrateToCurrentVersion(entries);
 }
 /** Exported for compaction.test.ts */
 export function parseSessionEntries(content) {
@@ -49,17 +85,46 @@ export function getLatestCompactionEntry(entries) {
     return null;
 }
 /**
- * Build the session context from entries. This is what gets sent to the LLM.
- *
- * If there's a compaction entry, returns the summary message plus messages
- * from `firstKeptEntryIndex` onwards. Otherwise returns all messages.
- *
- * Also extracts the current thinking level and model from the entries.
+ * Build the session context from entries using tree traversal.
+ * If leafId is provided, walks from that entry to root.
+ * Handles compaction and branch summaries along the path.
  */
-export function buildSessionContext(entries) {
+export function buildSessionContext(entries, leafId, byId) {
+    // Build uuid index if not available
+    if (!byId) {
+        byId = new Map();
+        for (const entry of entries) {
+            byId.set(entry.id, entry);
+        }
+    }
+    // Find leaf
+    let leaf;
+    if (leafId === null) {
+        // Explicitly null - return no messages (navigated to before first entry)
+        return { messages: [], thinkingLevel: "off", model: null };
+    }
+    if (leafId) {
+        leaf = byId.get(leafId);
+    }
+    if (!leaf) {
+        // Fallback to last entry (when leafId is undefined)
+        leaf = entries[entries.length - 1];
+    }
+    if (!leaf) {
+        return { messages: [], thinkingLevel: "off", model: null };
+    }
+    // Walk from leaf to root, collecting path
+    const path = [];
+    let current = leaf;
+    while (current) {
+        path.unshift(current);
+        current = current.parentId ? byId.get(current.parentId) : undefined;
+    }
+    // Extract settings and find compaction
     let thinkingLevel = "off";
     let model = null;
-    for (const entry of entries) {
+    let compaction = null;
+    for (const entry of path) {
         if (entry.type === "thinking_level_change") {
             thinkingLevel = entry.thinkingLevel;
         }
@@ -69,34 +134,55 @@ export function buildSessionContext(entries) {
         else if (entry.type === "message" && entry.message.role === "assistant") {
             model = { provider: entry.message.provider, modelId: entry.message.model };
         }
-    }
-    let latestCompactionIndex = -1;
-    for (let i = entries.length - 1; i >= 0; i--) {
-        if (entries[i].type === "compaction") {
-            latestCompactionIndex = i;
-            break;
+        else if (entry.type === "compaction") {
+            compaction = entry;
         }
     }
-    if (latestCompactionIndex === -1) {
-        const messages = [];
-        for (const entry of entries) {
-            if (entry.type === "message") {
-                messages.push(entry.message);
+    // Build messages and collect corresponding entries
+    // When there's a compaction, we need to:
+    // 1. Emit summary first (entry = compaction)
+    // 2. Emit kept messages (from firstKeptEntryId up to compaction)
+    // 3. Emit messages after compaction
+    const messages = [];
+    const appendMessage = (entry) => {
+        if (entry.type === "message") {
+            messages.push(entry.message);
+        }
+        else if (entry.type === "custom_message") {
+            messages.push(createHookMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp));
+        }
+        else if (entry.type === "branch_summary" && entry.summary) {
+            messages.push(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
+        }
+    };
+    if (compaction) {
+        // Emit summary first
+        messages.push(createCompactionSummaryMessage(compaction.summary, compaction.tokensBefore, compaction.timestamp));
+        // Find compaction index in path
+        const compactionIdx = path.findIndex((e) => e.type === "compaction" && e.id === compaction.id);
+        // Emit kept messages (before compaction, starting from firstKeptEntryId)
+        let foundFirstKept = false;
+        for (let i = 0; i < compactionIdx; i++) {
+            const entry = path[i];
+            if (entry.id === compaction.firstKeptEntryId) {
+                foundFirstKept = true;
             }
+            if (foundFirstKept) {
+                appendMessage(entry);
+            }
+        }
+        // Emit messages after compaction
+        for (let i = compactionIdx + 1; i < path.length; i++) {
+            const entry = path[i];
+            appendMessage(entry);
         }
-        return { messages, thinkingLevel, model };
     }
-    const compactionEvent = entries[latestCompactionIndex];
-    const keptMessages = [];
-    for (let i = compactionEvent.firstKeptEntryIndex; i < entries.length; i++) {
-        const entry = entries[i];
-        if (entry.type === "message") {
-            keptMessages.push(entry.message);
+    else {
+        // No compaction - emit all messages, handle branch summaries and custom messages
+        for (const entry of path) {
+            appendMessage(entry);
         }
     }
-    const messages = [];
-    messages.push(createSummaryMessage(compactionEvent.summary));
-    messages.push(...keptMessages);
     return { messages, thinkingLevel, model };
 }
 /**
@@ -111,7 +197,8 @@ function getDefaultSessionDir(cwd) {
     }
     return sessionDir;
 }
-function loadEntriesFromFile(filePath) {
+/** Exported for testing */
+export function loadEntriesFromFile(filePath) {
     if (!existsSync(filePath))
         return [];
     const content = readFileSync(filePath, "utf8");
@@ -128,16 +215,39 @@ function loadEntriesFromFile(filePath) {
             // Skip malformed lines
         }
     }
+    // Validate session header
+    if (entries.length === 0)
+        return entries;
+    const header = entries[0];
+    if (header.type !== "session" || typeof header.id !== "string") {
+        return [];
+    }
     return entries;
 }
-function findMostRecentSession(sessionDir) {
+function isValidSessionFile(filePath) {
+    try {
+        const fd = openSync(filePath, "r");
+        const buffer = Buffer.alloc(512);
+        const bytesRead = readSync(fd, buffer, 0, 512, 0);
+        closeSync(fd);
+        const firstLine = buffer.toString("utf8", 0, bytesRead).split("\n")[0];
+        if (!firstLine)
+            return false;
+        const header = JSON.parse(firstLine);
+        return header.type === "session" && typeof header.id === "string";
+    }
+    catch {
+        return false;
+    }
+}
+/** Exported for testing */
+export function findMostRecentSession(sessionDir) {
     try {
         const files = readdirSync(sessionDir)
             .filter((f) => f.endsWith(".jsonl"))
-            .map((f) => ({
-            path: join(sessionDir, f),
-            mtime: statSync(join(sessionDir, f)).mtime,
-        }))
+            .map((f) => join(sessionDir, f))
+            .filter(isValidSessionFile)
+            .map((path) => ({ path, mtime: statSync(path).mtime }))
             .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
         return files[0]?.path || null;
     }
@@ -145,53 +255,106 @@ function findMostRecentSession(sessionDir) {
         return null;
     }
 }
+/**
+ * Manages conversation sessions as append-only trees stored in JSONL files.
+ *
+ * Each session entry has an id and parentId forming a tree structure. The "leaf"
+ * pointer tracks the current position. Appending creates a child of the current leaf.
+ * Branching moves the leaf to an earlier entry, allowing new branches without
+ * modifying history.
+ *
+ * Use buildSessionContext() to get the resolved message list for the LLM, which
+ * handles compaction summaries and follows the path from root to current leaf.
+ */
 export class SessionManager {
     sessionId = "";
-    sessionFile = "";
+    sessionFile;
     sessionDir;
     cwd;
     persist;
     flushed = false;
-    inMemoryEntries = [];
+    fileEntries = [];
+    byId = new Map();
+    labelsById = new Map();
+    leafId = null;
     constructor(cwd, sessionDir, sessionFile, persist) {
         this.cwd = cwd;
         this.sessionDir = sessionDir;
+        this.persist = persist;
         if (persist && sessionDir && !existsSync(sessionDir)) {
             mkdirSync(sessionDir, { recursive: true });
         }
-        this.persist = persist;
         if (sessionFile) {
             this.setSessionFile(sessionFile);
         }
         else {
-            this.sessionId = uuidv4();
-            const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-            const sessionFile = join(this.getSessionDir(), `${timestamp}_${this.sessionId}.jsonl`);
-            this.setSessionFile(sessionFile);
+            this.newSession();
         }
     }
     /** Switch to a different session file (used for resume and branching) */
     setSessionFile(sessionFile) {
         this.sessionFile = resolve(sessionFile);
         if (existsSync(this.sessionFile)) {
-            this.inMemoryEntries = loadEntriesFromFile(this.sessionFile);
-            const header = this.inMemoryEntries.find((e) => e.type === "session");
-            this.sessionId = header ? header.id : uuidv4();
+            this.fileEntries = loadEntriesFromFile(this.sessionFile);
+            const header = this.fileEntries.find((e) => e.type === "session");
+            this.sessionId = header?.id ?? randomUUID();
+            if (migrateToCurrentVersion(this.fileEntries)) {
+                this._rewriteFile();
+            }
+            this._buildIndex();
             this.flushed = true;
         }
         else {
-            this.sessionId = uuidv4();
-            this.inMemoryEntries = [];
-            this.flushed = false;
-            const entry = {
-                type: "session",
-                id: this.sessionId,
-                timestamp: new Date().toISOString(),
-                cwd: this.cwd,
-            };
-            this.inMemoryEntries.push(entry);
+            this.newSession();
         }
     }
+    newSession(options) {
+        this.sessionId = randomUUID();
+        const timestamp = new Date().toISOString();
+        const header = {
+            type: "session",
+            version: CURRENT_SESSION_VERSION,
+            id: this.sessionId,
+            timestamp,
+            cwd: this.cwd,
+            parentSession: options?.parentSession,
+        };
+        this.fileEntries = [header];
+        this.byId.clear();
+        this.leafId = null;
+        this.flushed = false;
+        // Only generate filename if persisting and not already set (e.g., via --session flag)
+        if (this.persist && !this.sessionFile) {
+            const fileTimestamp = timestamp.replace(/[:.]/g, "-");
+            this.sessionFile = join(this.getSessionDir(), `${fileTimestamp}_${this.sessionId}.jsonl`);
+        }
+        return this.sessionFile;
+    }
+    _buildIndex() {
+        this.byId.clear();
+        this.labelsById.clear();
+        this.leafId = null;
+        for (const entry of this.fileEntries) {
+            if (entry.type === "session")
+                continue;
+            this.byId.set(entry.id, entry);
+            this.leafId = entry.id;
+            if (entry.type === "label") {
+                if (entry.label) {
+                    this.labelsById.set(entry.targetId, entry.label);
+                }
+                else {
+                    this.labelsById.delete(entry.targetId);
+                }
+            }
+        }
+    }
+    _rewriteFile() {
+        if (!this.persist || !this.sessionFile)
+            return;
+        const content = `${this.fileEntries.map((e) => JSON.stringify(e)).join("\n")}\n`;
+        writeFileSync(this.sessionFile, content);
+    }
     isPersisted() {
         return this.persist;
     }
@@ -207,28 +370,14 @@ export class SessionManager {
     getSessionFile() {
         return this.sessionFile;
     }
-    reset() {
-        this.sessionId = uuidv4();
-        this.flushed = false;
-        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-        this.sessionFile = join(this.getSessionDir(), `${timestamp}_${this.sessionId}.jsonl`);
-        this.inMemoryEntries = [
-            {
-                type: "session",
-                id: this.sessionId,
-                timestamp: new Date().toISOString(),
-                cwd: this.cwd,
-            },
-        ];
-    }
     _persist(entry) {
-        if (!this.persist)
+        if (!this.persist || !this.sessionFile)
             return;
-        const hasAssistant = this.inMemoryEntries.some((e) => e.type === "message" && e.message.role === "assistant");
+        const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message.role === "assistant");
         if (!hasAssistant)
             return;
         if (!this.flushed) {
-            for (const e of this.inMemoryEntries) {
+            for (const e of this.fileEntries) {
                 appendFileSync(this.sessionFile, `${JSON.stringify(e)}\n`);
             }
             this.flushed = true;
@@ -237,81 +386,364 @@ export class SessionManager {
             appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
         }
     }
-    saveMessage(message) {
+    _appendEntry(entry) {
+        this.fileEntries.push(entry);
+        this.byId.set(entry.id, entry);
+        this.leafId = entry.id;
+        this._persist(entry);
+    }
+    /** Append a message as child of current leaf, then advance leaf. Returns entry id.
+     * Does not allow writing CompactionSummaryMessage and BranchSummaryMessage directly.
+     * Reason: we want these to be top-level entries in the session, not message session entries,
+     * so it is easier to find them.
+     * These need to be appended via appendCompaction() and appendBranchSummary() methods.
+     */
+    appendMessage(message) {
         const entry = {
             type: "message",
+            id: generateId(this.byId),
+            parentId: this.leafId,
             timestamp: new Date().toISOString(),
             message,
         };
-        this.inMemoryEntries.push(entry);
-        this._persist(entry);
+        this._appendEntry(entry);
+        return entry.id;
     }
-    saveThinkingLevelChange(thinkingLevel) {
+    /** Append a thinking level change as child of current leaf, then advance leaf. Returns entry id. */
+    appendThinkingLevelChange(thinkingLevel) {
         const entry = {
             type: "thinking_level_change",
+            id: generateId(this.byId),
+            parentId: this.leafId,
             timestamp: new Date().toISOString(),
             thinkingLevel,
         };
-        this.inMemoryEntries.push(entry);
-        this._persist(entry);
+        this._appendEntry(entry);
+        return entry.id;
     }
-    saveModelChange(provider, modelId) {
+    /** Append a model change as child of current leaf, then advance leaf. Returns entry id. */
+    appendModelChange(provider, modelId) {
         const entry = {
             type: "model_change",
+            id: generateId(this.byId),
+            parentId: this.leafId,
             timestamp: new Date().toISOString(),
             provider,
             modelId,
         };
-        this.inMemoryEntries.push(entry);
-        this._persist(entry);
+        this._appendEntry(entry);
+        return entry.id;
     }
-    saveCompaction(entry) {
-        this.inMemoryEntries.push(entry);
-        this._persist(entry);
+    /** Append a compaction summary as child of current leaf, then advance leaf. Returns entry id. */
+    appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook) {
+        const entry = {
+            type: "compaction",
+            id: generateId(this.byId),
+            parentId: this.leafId,
+            timestamp: new Date().toISOString(),
+            summary,
+            firstKeptEntryId,
+            tokensBefore,
+            details,
+            fromHook,
+        };
+        this._appendEntry(entry);
+        return entry.id;
+    }
+    /** Append a custom entry (for hooks) as child of current leaf, then advance leaf. Returns entry id. */
+    appendCustomEntry(customType, data) {
+        const entry = {
+            type: "custom",
+            customType,
+            data,
+            id: generateId(this.byId),
+            parentId: this.leafId,
+            timestamp: new Date().toISOString(),
+        };
+        this._appendEntry(entry);
+        return entry.id;
+    }
+    /**
+     * Append a custom message entry (for hooks) that participates in LLM context.
+     * @param customType Hook identifier for filtering on reload
+     * @param content Message content (string or TextContent/ImageContent array)
+     * @param display Whether to show in TUI (true = styled display, false = hidden)
+     * @param details Optional hook-specific metadata (not sent to LLM)
+     * @returns Entry id
+     */
+    appendCustomMessageEntry(customType, content, display, details) {
+        const entry = {
+            type: "custom_message",
+            customType,
+            content,
+            display,
+            details,
+            id: generateId(this.byId),
+            parentId: this.leafId,
+            timestamp: new Date().toISOString(),
+        };
+        this._appendEntry(entry);
+        return entry.id;
+    }
+    // =========================================================================
+    // Tree Traversal
+    // =========================================================================
+    getLeafId() {
+        return this.leafId;
+    }
+    getLeafEntry() {
+        return this.leafId ? this.byId.get(this.leafId) : undefined;
+    }
+    getEntry(id) {
+        return this.byId.get(id);
+    }
+    /**
+     * Get all direct children of an entry.
+     */
+    getChildren(parentId) {
+        const children = [];
+        for (const entry of this.byId.values()) {
+            if (entry.parentId === parentId) {
+                children.push(entry);
+            }
+        }
+        return children;
+    }
+    /**
+     * Get the label for an entry, if any.
+     */
+    getLabel(id) {
+        return this.labelsById.get(id);
+    }
+    /**
+     * Set or clear a label on an entry.
+     * Labels are user-defined markers for bookmarking/navigation.
+     * Pass undefined or empty string to clear the label.
+     */
+    appendLabelChange(targetId, label) {
+        if (!this.byId.has(targetId)) {
+            throw new Error(`Entry ${targetId} not found`);
+        }
+        const entry = {
+            type: "label",
+            id: generateId(this.byId),
+            parentId: this.leafId,
+            timestamp: new Date().toISOString(),
+            targetId,
+            label,
+        };
+        this._appendEntry(entry);
+        if (label) {
+            this.labelsById.set(targetId, label);
+        }
+        else {
+            this.labelsById.delete(targetId);
+        }
+        return entry.id;
+    }
+    /**
+     * Walk from entry to root, returning all entries in path order.
+     * Includes all entry types (messages, compaction, model changes, etc.).
+     * Use buildSessionContext() to get the resolved messages for the LLM.
+     */
+    getBranch(fromId) {
+        const path = [];
+        const startId = fromId ?? this.leafId;
+        let current = startId ? this.byId.get(startId) : undefined;
+        while (current) {
+            path.unshift(current);
+            current = current.parentId ? this.byId.get(current.parentId) : undefined;
+        }
+        return path;
     }
     /**
      * Build the session context (what gets sent to the LLM).
-     * If compacted, returns summary + kept messages. Otherwise all messages.
-     * Includes thinking level and model.
+     * Uses tree traversal from current leaf.
      */
     buildSessionContext() {
-        return buildSessionContext(this.getEntries());
+        return buildSessionContext(this.getEntries(), this.leafId, this.byId);
+    }
+    /**
+     * Get session header.
+     */
+    getHeader() {
+        const h = this.fileEntries.find((e) => e.type === "session");
+        return h ? h : null;
     }
     /**
-     * Get all session entries. Returns a defensive copy.
-     * Use buildSessionContext() if you need the messages for the LLM.
+     * Get all session entries (excludes header). Returns a shallow copy.
+     * The session is append-only: use appendXXX() to add entries, branch() to
+     * change the leaf pointer. Entries cannot be modified or deleted.
      */
     getEntries() {
-        return [...this.inMemoryEntries];
-    }
-    createBranchedSessionFromEntries(entries, branchBeforeIndex) {
-        const newSessionId = uuidv4();
-        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const newSessionFile = join(this.getSessionDir(), `${timestamp}_${newSessionId}.jsonl`);
-        const newEntries = [];
-        for (let i = 0; i < branchBeforeIndex; i++) {
-            const entry = entries[i];
-            if (entry.type === "session") {
-                newEntries.push({
-                    ...entry,
-                    id: newSessionId,
-                    timestamp: new Date().toISOString(),
-                    branchedFrom: this.persist ? this.sessionFile : undefined,
-                });
+        return this.fileEntries.filter((e) => e.type !== "session");
+    }
+    /**
+     * Get the session as a tree structure. Returns a shallow defensive copy of all entries.
+     * A well-formed session has exactly one root (first entry with parentId === null).
+     * Orphaned entries (broken parent chain) are also returned as roots.
+     */
+    getTree() {
+        const entries = this.getEntries();
+        const nodeMap = new Map();
+        const roots = [];
+        // Create nodes with resolved labels
+        for (const entry of entries) {
+            const label = this.labelsById.get(entry.id);
+            nodeMap.set(entry.id, { entry, children: [], label });
+        }
+        // Build tree
+        for (const entry of entries) {
+            const node = nodeMap.get(entry.id);
+            if (entry.parentId === null || entry.parentId === entry.id) {
+                roots.push(node);
             }
             else {
-                newEntries.push(entry);
+                const parent = nodeMap.get(entry.parentId);
+                if (parent) {
+                    parent.children.push(node);
+                }
+                else {
+                    // Orphan - treat as root
+                    roots.push(node);
+                }
+            }
+        }
+        // Sort children by timestamp (oldest first, newest at bottom)
+        // Use iterative approach to avoid stack overflow on deep trees
+        const stack = [...roots];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            node.children.sort((a, b) => new Date(a.entry.timestamp).getTime() - new Date(b.entry.timestamp).getTime());
+            stack.push(...node.children);
+        }
+        return roots;
+    }
+    // =========================================================================
+    // Branching
+    // =========================================================================
+    /**
+     * Start a new branch from an earlier entry.
+     * Moves the leaf pointer to the specified entry. The next appendXXX() call
+     * will create a child of that entry, forming a new branch. Existing entries
+     * are not modified or deleted.
+     */
+    branch(branchFromId) {
+        if (!this.byId.has(branchFromId)) {
+            throw new Error(`Entry ${branchFromId} not found`);
+        }
+        this.leafId = branchFromId;
+    }
+    /**
+     * Reset the leaf pointer to null (before any entries).
+     * The next appendXXX() call will create a new root entry (parentId = null).
+     * Use this when navigating to re-edit the first user message.
+     */
+    resetLeaf() {
+        this.leafId = null;
+    }
+    /**
+     * Start a new branch with a summary of the abandoned path.
+     * Same as branch(), but also appends a branch_summary entry that captures
+     * context from the abandoned conversation path.
+     */
+    branchWithSummary(branchFromId, summary, details, fromHook) {
+        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),
+            parentId: branchFromId,
+            timestamp: new Date().toISOString(),
+            fromId: branchFromId ?? "root",
+            summary,
+            details,
+            fromHook,
+        };
+        this._appendEntry(entry);
+        return entry.id;
+    }
+    /**
+     * Create a new session file containing only the path from root to the specified leaf.
+     * Useful for extracting a single conversation path from a branched session.
+     * Returns the new session file path, or undefined if not persisting.
+     */
+    createBranchedSession(leafId) {
+        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 = randomUUID();
+        const timestamp = new Date().toISOString();
+        const fileTimestamp = timestamp.replace(/[:.]/g, "-");
+        const newSessionFile = join(this.getSessionDir(), `${fileTimestamp}_${newSessionId}.jsonl`);
+        const header = {
+            type: "session",
+            version: CURRENT_SESSION_VERSION,
+            id: newSessionId,
+            timestamp,
+            cwd: this.cwd,
+            parentSession: this.persist ? this.sessionFile : undefined,
+        };
+        // Collect labels for entries in the path
+        const pathEntryIds = new Set(pathWithoutLabels.map((e) => e.id));
+        const labelsToWrite = [];
+        for (const [targetId, label] of this.labelsById) {
+            if (pathEntryIds.has(targetId)) {
+                labelsToWrite.push({ targetId, label });
             }
         }
         if (this.persist) {
-            for (const entry of newEntries) {
+            appendFileSync(newSessionFile, `${JSON.stringify(header)}\n`);
+            for (const entry of pathWithoutLabels) {
                 appendFileSync(newSessionFile, `${JSON.stringify(entry)}\n`);
             }
+            // Write fresh label entries at the end
+            const lastEntryId = pathWithoutLabels[pathWithoutLabels.length - 1]?.id || null;
+            let parentId = lastEntryId;
+            const labelEntries = [];
+            for (const { targetId, label } of labelsToWrite) {
+                const labelEntry = {
+                    type: "label",
+                    id: generateId(new Set(pathEntryIds)),
+                    parentId,
+                    timestamp: new Date().toISOString(),
+                    targetId,
+                    label,
+                };
+                appendFileSync(newSessionFile, `${JSON.stringify(labelEntry)}\n`);
+                pathEntryIds.add(labelEntry.id);
+                labelEntries.push(labelEntry);
+                parentId = labelEntry.id;
+            }
+            this.fileEntries = [header, ...pathWithoutLabels, ...labelEntries];
+            this.sessionId = newSessionId;
+            this._buildIndex();
             return newSessionFile;
         }
-        this.inMemoryEntries = newEntries;
+        // In-memory mode: replace current session with the path + labels
+        const labelEntries = [];
+        let parentId = pathWithoutLabels[pathWithoutLabels.length - 1]?.id || null;
+        for (const { targetId, label } of labelsToWrite) {
+            const labelEntry = {
+                type: "label",
+                id: generateId(new Set([...pathEntryIds, ...labelEntries.map((e) => e.id)])),
+                parentId,
+                timestamp: new Date().toISOString(),
+                targetId,
+                label,
+            };
+            labelEntries.push(labelEntry);
+            parentId = labelEntry.id;
+        }
+        this.fileEntries = [header, ...pathWithoutLabels, ...labelEntries];
         this.sessionId = newSessionId;
-        return null;
+        this._buildIndex();
+        return undefined;
     }
     /**
      * Create a new session.
@@ -320,7 +752,7 @@ export class SessionManager {
      */
     static create(cwd, sessionDir) {
         const dir = sessionDir ?? getDefaultSessionDir(cwd);
-        return new SessionManager(cwd, dir, null, true);
+        return new SessionManager(cwd, dir, undefined, true);
     }
     /**
      * Open a specific session file.
@@ -347,11 +779,11 @@ export class SessionManager {
         if (mostRecent) {
             return new SessionManager(cwd, dir, mostRecent, true);
         }
-        return new SessionManager(cwd, dir, null, true);
+        return new SessionManager(cwd, dir, undefined, true);
     }
     /** Create an in-memory session (no file persistence) */
     static inMemory(cwd = process.cwd()) {
-        return new SessionManager(cwd, "", null, false);
+        return new SessionManager(cwd, "", undefined, false);
     }
     /**
      * List all sessions.