@cjhyy/code-shell-core 0.7.0 → 0.7.1

package/dist/session/session-manager.d.ts

@@ -1,12 +1,22 @@
 /**
  * Session lifecycle manager.
  */
-import type { SessionState, SessionWorkspace } from "../types.js";
+import type { SessionForkLineage, SessionState, SessionWorkspace, TranscriptEvent } from "../types.js";
 import { Transcript } from "./transcript.js";
 export interface SessionBundle {
     state: SessionState;
     transcript: Transcript;
 }
+export interface ForkSessionOptions {
+    targetSessionId?: string;
+    /** Inclusive source event cursor; omitted means the frozen transcript tail. */
+    throughEventId?: string;
+}
+export interface ForkSessionResult {
+    bundle: SessionBundle;
+    lineage: SessionForkLineage;
+    copiedEventCount: number;
+}
 export type SessionWorkspaceResumeResolution = {
     ok: true;
     cwd: string;
@@ -44,7 +54,13 @@ export declare function assertSafeSessionId(sessionId: unknown): asserts session
 export declare function codeShellHome(): string;
 export declare class SessionManager {
     private readonly sessionsDir;
+    private readonly registeredCloseEpochs;
     constructor(storageDir?: string);
+    private cleanupStaleForkStaging;
+    /** Bind one Engine/session pair to the current close epoch without advancing it. */
+    registerSessionGeneration(sessionId: string): number;
+    /** Advance the close epoch once before close waits for the old run to settle. */
+    incrementSessionGeneration(sessionId: string): number;
     /**
      * Create a new on-disk session. If `explicitSessionId` is passed, use
      * it verbatim (ChatSessionManager-driven hosts choose a logical sid like
@@ -121,15 +137,28 @@ export declare class SessionManager {
      */
     clearActiveGoal(sessionId: string): boolean;
     resume(sessionId: string): SessionBundle;
-    saveState(state: SessionState): void;
     /**
-     * Fork a session from a specific point.
-     * Creates a new session that shares events up to the given turn,
-     * then diverges independently.
+     * Merge a field-level state update into the latest persisted snapshot.
+     *
+     * Unlike saveState(), callers do not supply a potentially stale whole-state
+     * object. The read, shallow merge, and atomic write are synchronous, so no
+     * other callback on this process's event loop can interleave between them.
+     * This is deliberately not a session-level lock. Engine.run rejects re-entry
+     * on one Engine (G6), and the generation check in saveState rejects an older
+     * registered Engine in this process. Workers and separate processes remain
+     * an unresolved finding requiring locking/CAS.
      */
-    fork(sourceSessionId: string, forkAtTurn?: number): SessionBundle;
+    updateSessionState(sessionId: string, partial: Readonly<Partial<Omit<SessionState, "sessionId">>>): void;
+    saveState(state: SessionState, generation?: number): boolean;
+    private generationKey;
+    /** Create an independent, top-level session from a frozen event cursor. */
+    fork(sourceSessionId: string, options?: ForkSessionOptions): ForkSessionResult;
+    private readForkSnapshot;
+    private publishSessionAtomically;
     list(limit?: number): SessionListEntry[];
 }
+export declare function buildForkState(source: SessionState, targetSessionId: string, lineage: SessionForkLineage, startedAt?: number): SessionState;
+export declare function buildForkTranscript(sourceEvents: readonly TranscriptEvent[], state: SessionState): TranscriptEvent[];
 export type SessionListEntry = SessionState & {
     preview?: string;
     /** Last activity time — transcript mtime, falling back to startedAt. */

package/dist/session/session-manager.js

@@ -1,7 +1,7 @@
 /**
  * Session lifecycle manager.
  */
-import { closeSync, existsSync, mkdirSync, lstatSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, mkdirSync, lstatSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { nanoid } from "nanoid";
@@ -10,6 +10,31 @@ import { SessionError } from "../exceptions.js";
 import { normalizeCumulativeUsageCounters } from "../engine/session-usage.js";
 import { isSameGoalInstance } from "../engine/goal.js";
 import { branchExists, isGitWorktreeRoot } from "../git/worktree.js";
+// Shared close epochs for SessionManager instances in this process. Concurrent
+// Engines bind the same epoch; only close advances it. This intentionally does
+// not claim cross-process/Worker protection.
+const currentSessionCloseEpochs = new Map();
+const FORK_COPY_EVENT_TYPES = new Set([
+    "message",
+    "tool_use",
+    "tool_result",
+    "summary",
+    "content_replace",
+    "subagent",
+    "external_file_changes",
+    "goal_progress",
+    "turn_boundary",
+    "turn_stopped",
+    "error",
+]);
+const FORK_SKIP_EVENT_TYPES = new Set([
+    "session_meta",
+    "file_history",
+    "plan_operation",
+]);
+const FORK_STAGING_NAME = /^\.pending-fork-[A-Za-z0-9_.-]+-[A-Za-z0-9_-]{8}$/;
+const FORK_STAGING_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const FORK_STAGING_CLEANUP_LIMIT = 32;
 /**
  * Validate a session ID before it is joined into a filesystem path.
  *
@@ -97,9 +122,54 @@ async function validateResumeWorktreeRoot(root) {
 }
 export class SessionManager {
     sessionsDir;
+    registeredCloseEpochs = new Map();
     constructor(storageDir) {
         this.sessionsDir = storageDir ?? join(codeShellHome(), "sessions");
         mkdirSync(this.sessionsDir, { recursive: true });
+        this.cleanupStaleForkStaging();
+    }
+    cleanupStaleForkStaging() {
+        let removed = 0;
+        let entries;
+        try {
+            entries = readdirSync(this.sessionsDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (removed >= FORK_STAGING_CLEANUP_LIMIT)
+                return;
+            if (!entry.isDirectory() || !FORK_STAGING_NAME.test(entry.name))
+                continue;
+            const path = join(this.sessionsDir, entry.name);
+            try {
+                if (Date.now() - statSync(path).mtimeMs <= FORK_STAGING_MAX_AGE_MS)
+                    continue;
+                rmSync(path, { recursive: true, force: true });
+                removed++;
+            }
+            catch {
+                // Startup cleanup is best effort; a live/unreadable staging directory
+                // must never prevent the SessionManager from serving normal sessions.
+            }
+        }
+    }
+    /** Bind one Engine/session pair to the current close epoch without advancing it. */
+    registerSessionGeneration(sessionId) {
+        assertSafeSessionId(sessionId);
+        const key = this.generationKey(sessionId);
+        const generation = currentSessionCloseEpochs.get(key) ?? 0;
+        this.registeredCloseEpochs.set(sessionId, generation);
+        return generation;
+    }
+    /** Advance the close epoch once before close waits for the old run to settle. */
+    incrementSessionGeneration(sessionId) {
+        assertSafeSessionId(sessionId);
+        const key = this.generationKey(sessionId);
+        const next = (currentSessionCloseEpochs.get(key) ?? 0) + 1;
+        currentSessionCloseEpochs.set(key, next);
+        return next;
     }
     /**
      * Create a new on-disk session. If `explicitSessionId` is passed, use
@@ -440,14 +510,52 @@ export class SessionManager {
         Object.assign(state, normalizeCumulativeUsageCounters(state, state.tokenUsage));
         return { state, transcript };
     }
-    saveState(state) {
+    /**
+     * Merge a field-level state update into the latest persisted snapshot.
+     *
+     * Unlike saveState(), callers do not supply a potentially stale whole-state
+     * object. The read, shallow merge, and atomic write are synchronous, so no
+     * other callback on this process's event loop can interleave between them.
+     * This is deliberately not a session-level lock. Engine.run rejects re-entry
+     * on one Engine (G6), and the generation check in saveState rejects an older
+     * registered Engine in this process. Workers and separate processes remain
+     * an unresolved finding requiring locking/CAS.
+     */
+    updateSessionState(sessionId, partial) {
+        assertSafeSessionId(sessionId);
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile)) {
+            throw new SessionError(`Session state file not found: ${sessionId}`);
+        }
+        let state;
+        try {
+            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+        }
+        catch (err) {
+            throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        Object.assign(state, partial);
+        state.sessionId = sessionId;
+        this.saveState(state);
+    }
+    saveState(state, generation) {
         // state.sessionId could come from a deserialized state.json that was
         // tampered with on disk. Validate before joining.
         assertSafeSessionId(state.sessionId);
+        const writerGeneration = generation ?? this.registeredCloseEpochs.get(state.sessionId);
+        if (writerGeneration !== undefined &&
+            (currentSessionCloseEpochs.get(this.generationKey(state.sessionId)) ?? 0) !== writerGeneration) {
+            // A closing/old Engine may finish asynchronously after its generation was
+            // invalidated. Reject explicitly without throwing into an unobserved
+            // engine finally path, and most importantly without touching the disk.
+            return false;
+        }
         const sessionDir = join(this.sessionsDir, state.sessionId);
         mkdirSync(sessionDir, { recursive: true });
-        // Atomic write: stage to .tmp, then rename. Protects against two processes
-        // clobbering each other's state.json mid-write.
+        // Atomic file replacement: stage to .tmp, then rename, preventing a torn
+        // state.json. Registered Engines share one epoch until close advances it,
+        // so concurrent opens are not fenced from each other. Workers, separate
+        // processes, and their stale-writer ordering still require locking/CAS.
         const target = join(sessionDir, "state.json");
         // Preserve the newest goal tombstone across whole-state writers. If an old
         // detached bundle still carries the tombstoned goal, drop it before write;
@@ -463,6 +571,13 @@ export class SessionManager {
                 // behavior and overwrite malformed state with the caller's snapshot.
             }
         }
+        // A title is generated after the first run and may be merged while the
+        // next run still owns a state object loaded before that title existed.
+        // Preserve the newly persisted title when such a stale whole-state writer
+        // saves later; assigning title = undefined explicitly still clears it.
+        if (persisted?.title !== undefined && !("title" in state)) {
+            state.title = persisted.title;
+        }
         const terminal = newestGoalTerminal(state.goalTerminal, persisted?.goalTerminal);
         if (terminal)
             state.goalTerminal = terminal;
@@ -473,36 +588,110 @@ export class SessionManager {
         const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
         writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
         renameSync(tmp, target);
+        return true;
     }
-    /**
-     * Fork a session from a specific point.
-     * Creates a new session that shares events up to the given turn,
-     * then diverges independently.
-     */
-    fork(sourceSessionId, forkAtTurn) {
-        const source = this.resume(sourceSessionId);
-        const events = source.transcript.getEvents();
-        // Determine fork point
-        const forkTurn = forkAtTurn ?? source.state.turnCount;
-        // Create new session
-        const newBundle = this.create(source.state.cwd, source.state.model, source.state.provider);
-        newBundle.state.parentSessionId = sourceSessionId;
-        // Copy events up to the fork point
-        for (const event of events) {
-            if (event.type === "turn_boundary" &&
-                (event.data.turnNumber ?? -1) > forkTurn) {
-                break;
+    generationKey(sessionId) {
+        return `${this.sessionsDir}\0${sessionId}`;
+    }
+    /** Create an independent, top-level session from a frozen event cursor. */
+    fork(sourceSessionId, options = {}) {
+        assertSafeSessionId(sourceSessionId);
+        if (options.targetSessionId !== undefined)
+            assertSafeSessionId(options.targetSessionId);
+        const snapshot = this.readForkSnapshot(sourceSessionId, options.throughEventId);
+        const targetSessionId = options.targetSessionId ?? nanoid(16);
+        const createdAt = Date.now();
+        const lineage = {
+            sessionId: sourceSessionId,
+            mode: "full",
+            fromEventId: snapshot.copiedEvents[0]?.id,
+            throughEventId: snapshot.copiedEvents[snapshot.copiedEvents.length - 1]?.id,
+            sourceEventCount: snapshot.copiedEvents.length,
+            createdAt,
+        };
+        const state = buildForkState(snapshot.sourceState, targetSessionId, lineage, createdAt);
+        const events = buildForkTranscript(snapshot.copiedEvents, state);
+        const bundle = this.publishSessionAtomically(targetSessionId, state, events);
+        return { bundle, lineage, copiedEventCount: snapshot.copiedEvents.length };
+    }
+    readForkSnapshot(sourceSessionId, throughEventId) {
+        const sessionDir = join(this.sessionsDir, sourceSessionId);
+        const stateFile = join(sessionDir, "state.json");
+        const transcriptFile = join(sessionDir, "transcript.jsonl");
+        if (!existsSync(stateFile))
+            throw new SessionError(`Session not found: ${sourceSessionId}`);
+        let sourceState;
+        try {
+            sourceState = JSON.parse(readFileSync(stateFile, "utf-8"));
+        }
+        catch (err) {
+            throw new SessionError(`Session state is corrupt for ${sourceSessionId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const parsed = Transcript.readEvents(transcriptFile);
+        if (parsed.malformedLineCount > 0) {
+            throw new SessionError(`Session transcript is malformed for ${sourceSessionId}: ${parsed.malformedLineCount} invalid line(s)`);
+        }
+        const sourceEvents = structuredClone(parsed.events);
+        let frozen = sourceEvents;
+        if (throughEventId !== undefined) {
+            const matches = sourceEvents
+                .map((event, index) => (event.id === throughEventId ? index : -1))
+                .filter((index) => index >= 0);
+            if (matches.length !== 1) {
+                throw new SessionError(`Fork cursor must identify exactly one source event`);
+            }
+            const cursor = sourceEvents[matches[0]];
+            if (cursor.type === "session_meta") {
+                throw new SessionError(`Fork cursor cannot point at session metadata`);
+            }
+            frozen = sourceEvents.slice(0, matches[0] + 1);
+        }
+        const copiedEvents = [];
+        for (const event of frozen) {
+            if (FORK_SKIP_EVENT_TYPES.has(event.type))
+                continue;
+            if (!FORK_COPY_EVENT_TYPES.has(event.type)) {
+                throw new SessionError(`Unsupported transcript event in fork: ${String(event.type)}`);
+            }
+            copiedEvents.push(structuredClone(event));
+        }
+        validateForkToolPairs(copiedEvents);
+        return { sourceState: structuredClone(sourceState), copiedEvents };
+    }
+    publishSessionAtomically(targetSessionId, state, events) {
+        const targetDir = join(this.sessionsDir, targetSessionId);
+        if (existsSync(targetDir))
+            throw new SessionError(`Session already exists: ${targetSessionId}`);
+        const stagingDir = join(this.sessionsDir, `.pending-fork-${targetSessionId}-${nanoid(8)}`);
+        let published = false;
+        try {
+            mkdirSync(stagingDir);
+            writeFileSync(join(stagingDir, "state.json"), JSON.stringify(state, null, 2), {
+                encoding: "utf-8",
+                mode: 0o600,
+            });
+            const jsonl = events.map((event) => JSON.stringify(event)).join("\n") + "\n";
+            writeFileSync(join(stagingDir, "transcript.jsonl"), jsonl, {
+                encoding: "utf-8",
+                mode: 0o600,
+            });
+            if (existsSync(targetDir)) {
+                throw new SessionError(`Session already exists: ${targetSessionId}`);
             }
-            newBundle.transcript.append(event.type, event.data);
+            renameSync(stagingDir, targetDir);
+            published = true;
+            return this.resume(targetSessionId);
+        }
+        finally {
+            if (!published)
+                rmSync(stagingDir, { recursive: true, force: true });
         }
-        this.saveState(newBundle.state);
-        return newBundle;
     }
     list(limit = 20) {
         if (!existsSync(this.sessionsDir))
             return [];
         const dirs = readdirSync(this.sessionsDir, { withFileTypes: true })
-            .filter((d) => d.isDirectory())
+            .filter((d) => d.isDirectory() && !d.name.startsWith(".pending-"))
             .map((d) => d.name);
         const candidates = [];
         for (const dir of dirs) {
@@ -544,6 +733,153 @@ export class SessionManager {
         return sessions;
     }
 }
+export function buildForkState(source, targetSessionId, lineage, startedAt = Date.now()) {
+    const workspace = isSessionWorkspace(source.workspace)
+        ? structuredClone(source.workspace)
+        : { root: source.cwd, kind: "main" };
+    return {
+        sessionId: targetSessionId,
+        cwd: source.cwd,
+        workspace,
+        startedAt,
+        model: source.model,
+        provider: source.provider,
+        tokenUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+        cumulativePromptTokens: 0,
+        cumulativeCacheReadTokens: 0,
+        cumulativeCacheCreationTokens: 0,
+        turnCount: 0,
+        turnSeq: 0,
+        invokedSkills: [],
+        parentSessionId: null,
+        forkedFrom: structuredClone(lineage),
+        ...(source.origin ? { origin: source.origin } : {}),
+        status: "active",
+    };
+}
+export function buildForkTranscript(sourceEvents, state) {
+    const meta = {
+        id: nanoid(12),
+        type: "session_meta",
+        timestamp: state.startedAt,
+        turnNumber: 0,
+        data: {
+            sessionId: state.sessionId,
+            cwd: state.cwd,
+            workspace: structuredClone(state.workspace),
+            model: state.model,
+            provider: state.provider,
+            startedAt: state.startedAt,
+            forkedFrom: structuredClone(state.forkedFrom),
+        },
+    };
+    return [
+        meta,
+        ...sourceEvents.map((source) => ({
+            ...structuredClone(source),
+            id: nanoid(12),
+        })),
+    ];
+}
+function validateForkToolPairs(events) {
+    const projectedUses = [];
+    const projectedResults = [];
+    const seenProjectedUses = new Set();
+    const seenProjectedResults = new Set();
+    const projectedPending = [];
+    for (const message of Transcript.eventsToMessages(events)) {
+        const blocks = Array.isArray(message.content) ? message.content : [];
+        const uses = blocks.filter((block) => block.type === "tool_use");
+        const results = blocks.filter((block) => block.type === "tool_result");
+        if (projectedPending.length > 0) {
+            if (message.role !== "user" || results.length !== blocks.length || results.length === 0) {
+                throw new SessionError(`Fork provider history inserts a message before pending tool results`);
+            }
+        }
+        else if (results.length > 0) {
+            throw new SessionError(`Fork provider history contains an orphaned tool result`);
+        }
+        if (uses.length > 0) {
+            if (message.role !== "assistant" || results.length > 0) {
+                throw new SessionError(`Fork provider history contains tool use blocks in an invalid role`);
+            }
+            for (const block of uses) {
+                const id = block.id;
+                if (typeof id !== "string" || !id) {
+                    throw new SessionError(`Fork provider history contains a tool use without id`);
+                }
+                if (seenProjectedUses.has(id)) {
+                    throw new SessionError(`Fork provider history contains duplicate tool use ${id}`);
+                }
+                seenProjectedUses.add(id);
+                projectedUses.push(id);
+                projectedPending.push(id);
+            }
+        }
+        for (const block of results) {
+            const id = block.tool_use_id;
+            if (typeof id !== "string" || !id) {
+                throw new SessionError(`Fork provider history contains a tool result without id`);
+            }
+            if (seenProjectedResults.has(id)) {
+                throw new SessionError(`Fork provider history contains duplicate tool result ${id}`);
+            }
+            const expected = projectedPending.shift();
+            if (!expected) {
+                throw new SessionError(`Fork provider history contains an orphaned tool result (${id})`);
+            }
+            if (expected !== id) {
+                throw new SessionError(`Fork provider history tool result order mismatch: expected ${expected}, received ${id}`);
+            }
+            seenProjectedResults.add(id);
+            projectedResults.push(id);
+        }
+    }
+    if (projectedPending.length > 0) {
+        throw new SessionError(`Fork cursor splits an unfinished tool round in provider history (${projectedPending[0]})`);
+    }
+    const metadataUses = [];
+    const metadataResults = [];
+    const seenMetadataUses = new Set();
+    const seenMetadataResults = new Set();
+    const metadataPending = [];
+    for (const event of events) {
+        if (event.type !== "tool_use" && event.type !== "tool_result")
+            continue;
+        const id = event.data.toolCallId;
+        if (typeof id !== "string" || !id) {
+            throw new SessionError(`Fork snapshot contains a tool event without toolCallId`);
+        }
+        if (event.type === "tool_use") {
+            if (seenMetadataUses.has(id)) {
+                throw new SessionError(`Fork snapshot contains duplicate tool use metadata ${id}`);
+            }
+            seenMetadataUses.add(id);
+            metadataUses.push(id);
+            metadataPending.push(id);
+            continue;
+        }
+        if (seenMetadataResults.has(id)) {
+            throw new SessionError(`Fork snapshot contains duplicate tool result metadata ${id}`);
+        }
+        const expected = metadataPending.shift();
+        if (!expected) {
+            throw new SessionError(`Fork snapshot contains tool result metadata before use (${id})`);
+        }
+        if (expected !== id) {
+            throw new SessionError(`Fork snapshot tool metadata order mismatch: expected ${expected}, received ${id}`);
+        }
+        seenMetadataResults.add(id);
+        metadataResults.push(id);
+    }
+    if (metadataPending.length > 0) {
+        throw new SessionError(`Fork cursor splits unfinished tool metadata (${metadataPending[0]})`);
+    }
+    const sameIds = (left, right) => left.length === right.length && left.every((id, index) => id === right[index]);
+    if (!sameIds(projectedUses, metadataUses) || !sameIds(projectedResults, metadataResults)) {
+        throw new SessionError(`Fork tool metadata does not match provider history`);
+    }
+}
 function newestGoalTerminal(incoming, persisted) {
     if (!incoming)
         return persisted;

package/dist/session/transcript.d.ts

@@ -3,12 +3,29 @@
  * toMessages() derives Message[] from events for sending to LLM.
  */
 import type { TranscriptEvent, TranscriptEventType, Message, ContentBlock } from "../types.js";
+type TranscriptWriter = (filePath: string, data: string, encoding: "utf-8") => void;
+type ParsedEvents = {
+    events: TranscriptEvent[];
+    malformedLineCount: number;
+};
+export interface TranscriptFlushFailure {
+    errno: string | number;
+    code?: string;
+    message: string;
+    timestamp: number;
+    attempts: 2;
+    recoverable: false;
+    filePath: string;
+}
 export declare class Transcript {
     private events;
     private filePath;
     private currentTurn;
+    private readonly writer;
+    private dirty;
+    private lastFlushFailure;
     getFilePath(): string;
-    constructor(filePath: string);
+    constructor(filePath: string, writer?: TranscriptWriter);
     append(type: TranscriptEventType, data: Record<string, unknown>): TranscriptEvent;
     /**
      * Append a chat message to the transcript.
@@ -55,13 +72,25 @@ export declare class Transcript {
     getEvents(type?: TranscriptEventType): TranscriptEvent[];
     get turnNumber(): number;
     get eventCount(): number;
+    /** True once any event failed both persistence attempts. Sticky by design. */
+    flushFailed(): boolean;
+    /** Structured details for the most recent unrecoverable flush failure. */
+    getFlushFailure(): TranscriptFlushFailure | undefined;
     private findMessageByClientId;
     private flush;
+    private errorErrno;
+    private errorMessage;
     /**
      * Repair tool_result pairing issues:
      * - Orphaned tool_results (no matching tool_use) get removed
      * - Missing tool_results (tool_use with no result) get synthetic error results
      */
     repairToolResultPairs(): void;
+    static readEvents(filePath: string): ParsedEvents;
+    static eventsToMessages(events: readonly TranscriptEvent[]): Array<{
+        role: string;
+        content: string | ContentBlock[];
+    }>;
     static loadFromFile(filePath: string): Transcript;
 }
+export {};