@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/session/session-manager.js

@@ -0,0 +1,261 @@
+/**
+ * Session lifecycle manager.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { nanoid } from "nanoid";
+import { Transcript } from "./transcript.js";
+import { SessionError } from "../exceptions.js";
+export class SessionManager {
+    sessionsDir;
+    constructor(storageDir) {
+        this.sessionsDir = storageDir ?? join(homedir(), ".code-shell", "sessions");
+        mkdirSync(this.sessionsDir, { recursive: true });
+    }
+    /**
+     * Create a new on-disk session. If `explicitSessionId` is passed, use
+     * it verbatim (ChatSessionManager-driven hosts choose a logical sid like
+     * "tui-main" and expect us to honor it). Otherwise generate one with
+     * nanoid. Either way the on-disk directory is materialized and the
+     * state.json + transcript.jsonl files are written before return.
+     */
+    create(cwd, model, provider, explicitSessionId) {
+        const sessionId = explicitSessionId ?? nanoid(16);
+        const sessionDir = join(this.sessionsDir, sessionId);
+        mkdirSync(sessionDir, { recursive: true });
+        const state = {
+            sessionId,
+            cwd,
+            startedAt: Date.now(),
+            model,
+            provider,
+            tokenUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            turnCount: 0,
+            invokedSkills: [],
+            status: "active",
+        };
+        writeFileSync(join(sessionDir, "state.json"), JSON.stringify(state, null, 2), "utf-8");
+        const transcript = new Transcript(join(sessionDir, "transcript.jsonl"));
+        transcript.append("session_meta", {
+            sessionId,
+            cwd,
+            model,
+            provider,
+            startedAt: state.startedAt,
+        });
+        return { state, transcript };
+    }
+    /**
+     * Whether a session directory exists on disk. Used by ChatSession-driven
+     * cold starts to decide between resume vs create-with-explicit-sid
+     * without catching SessionError.
+     */
+    exists(sessionId) {
+        return existsSync(join(this.sessionsDir, sessionId));
+    }
+    resume(sessionId) {
+        const sessionDir = join(this.sessionsDir, sessionId);
+        if (!existsSync(sessionDir)) {
+            throw new SessionError(`Session not found: ${sessionId}`);
+        }
+        const stateFile = join(sessionDir, "state.json");
+        if (!existsSync(stateFile)) {
+            throw new SessionError(`Session state file not found: ${sessionId}`);
+        }
+        const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+        const transcriptFile = join(sessionDir, "transcript.jsonl");
+        const transcript = Transcript.loadFromFile(transcriptFile);
+        state.status = "active";
+        return { state, transcript };
+    }
+    saveState(state) {
+        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.
+        const target = join(sessionDir, "state.json");
+        const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
+        renameSync(tmp, target);
+    }
+    /**
+     * 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 > forkTurn) {
+                break;
+            }
+            newBundle.transcript.append(event.type, event.data);
+        }
+        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())
+            .map((d) => d.name);
+        const candidates = [];
+        for (const dir of dirs) {
+            const stateFile = join(this.sessionsDir, dir, "state.json");
+            if (!existsSync(stateFile))
+                continue;
+            const transcriptFile = join(this.sessionsDir, dir, "transcript.jsonl");
+            let lastActiveAt;
+            let transcriptExists = false;
+            try {
+                transcriptExists = existsSync(transcriptFile);
+                if (transcriptExists) {
+                    lastActiveAt = statSync(transcriptFile).mtimeMs;
+                }
+                else {
+                    // Fall back to state.json mtime (cheaper than parsing it for
+                    // state.startedAt and good enough for ordering).
+                    lastActiveAt = statSync(stateFile).mtimeMs;
+                }
+            }
+            catch {
+                continue;
+            }
+            candidates.push({ dir, lastActiveAt, transcriptFile, stateFile, transcriptExists });
+        }
+        candidates.sort((a, b) => b.lastActiveAt - a.lastActiveAt);
+        const top = candidates.slice(0, limit);
+        const sessions = [];
+        for (const c of top) {
+            try {
+                const state = JSON.parse(readFileSync(c.stateFile, "utf-8"));
+                const preview = c.transcriptExists ? readLastUserMessage(c.transcriptFile) : undefined;
+                sessions.push({ ...state, preview, lastActiveAt: c.lastActiveAt });
+            }
+            catch {
+                // Skip corrupted sessions
+            }
+        }
+        return sessions;
+    }
+}
+/**
+ * Scan a transcript.jsonl for the LAST user message and return a short
+ * preview, reading the file from the END in 64 KiB chunks.
+ *
+ * Why: SessionManager.list() calls this for every session in
+ * ~/.code-shell/sessions (hundreds to thousands at steady state). The
+ * earlier readFileSync-the-whole-file implementation made `/resume`
+ * scan ~64 MiB across nearly 1 k transcripts every time the list
+ * opened — visible as several seconds of UI freeze. The vast majority
+ * of transcripts have their last user message in the final few KiB, so
+ * tailing one chunk is usually enough and we never read more than we
+ * have to.
+ *
+ * Algorithm: open the file once, seek to the tail, read backwards one
+ * chunk at a time, splitting on newlines. Walk the lines we have so
+ * far from newest to oldest; the moment we find a `type:"message",
+ * role:"user"` event with non-empty text we close the fd and return.
+ * Keep a small "leftover" prefix between chunks so a JSON line straddling
+ * a chunk boundary still parses.
+ *
+ * Returns undefined if the session has no user messages, or on any IO
+ * error (caller treats the preview as optional).
+ */
+const TAIL_CHUNK_SIZE = 64 * 1024;
+function readLastUserMessage(transcriptFile) {
+    if (!existsSync(transcriptFile))
+        return undefined;
+    let fd;
+    let fileSize;
+    try {
+        fd = openSync(transcriptFile, "r");
+        fileSize = statSync(transcriptFile).size;
+    }
+    catch {
+        return undefined;
+    }
+    if (fileSize === 0) {
+        closeSync(fd);
+        return undefined;
+    }
+    try {
+        let position = fileSize;
+        // `leftover` holds bytes from the previous (later) chunk that we
+        // couldn't yet split on a newline — they're the partial start of a
+        // line whose end lives in the older chunk we just read.
+        let leftover = "";
+        const buf = Buffer.alloc(TAIL_CHUNK_SIZE);
+        while (position > 0) {
+            const readLen = Math.min(TAIL_CHUNK_SIZE, position);
+            position -= readLen;
+            const got = readSync(fd, buf, 0, readLen, position);
+            if (got <= 0)
+                break;
+            const text = buf.toString("utf8", 0, got) + leftover;
+            const lines = text.split("\n");
+            // If we haven't reached the beginning of the file, the first
+            // element of `lines` may be a partial line; defer it to the next
+            // (older) chunk. Once position==0 we know the first element is a
+            // real complete line and we should process it too.
+            const start = position === 0 ? 0 : 1;
+            if (position > 0)
+                leftover = lines[0] ?? "";
+            for (let i = lines.length - 1; i >= start; i--) {
+                const preview = parseUserPreview(lines[i]);
+                if (preview !== undefined)
+                    return preview;
+            }
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* already closed */
+        }
+    }
+}
+/**
+ * Parse one transcript line; return the preview string if it's a
+ * non-empty user message, otherwise undefined. Pulled out so the
+ * tail loop above stays focused on IO mechanics.
+ */
+function parseUserPreview(line) {
+    if (!line)
+        return undefined;
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (event.type !== "message")
+        return undefined;
+    if (event.data?.role !== "user")
+        return undefined;
+    const content = event.data.content;
+    const text = typeof content === "string"
+        ? content
+        : Array.isArray(content)
+            ? (content.find((b) => b.type === "text")?.text ?? "")
+            : "";
+    if (!text.trim())
+        return undefined;
+    return text.replace(/\s+/g, " ").trim();
+}

package/dist/session/transcript.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Transcript — JSONL event log (NOT chat history).
+ * toMessages() derives Message[] from events for sending to LLM.
+ */
+import type { TranscriptEvent, TranscriptEventType, Message, ContentBlock } from "../types.js";
+export declare class Transcript {
+    private events;
+    private filePath;
+    private currentTurn;
+    getFilePath(): string;
+    constructor(filePath: string);
+    append(type: TranscriptEventType, data: Record<string, unknown>): TranscriptEvent;
+    appendMessage(role: string, content: string | ContentBlock[]): TranscriptEvent;
+    appendToolUse(toolName: string, toolCallId: string, args: Record<string, unknown>): TranscriptEvent;
+    appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string): TranscriptEvent;
+    appendTurnBoundary(): TranscriptEvent;
+    appendSummary(summary: string, compactedRange: {
+        fromTurn: number;
+        toTurn: number;
+        eventCount: number;
+    }): TranscriptEvent;
+    appendError(error: string, details?: Record<string, unknown>): TranscriptEvent;
+    /**
+     * Derive Message[] from transcript events for sending to the LLM.
+     * This is the critical boundary: the LLM never sees the event log directly.
+     */
+    toMessages(): Message[];
+    getEvents(type?: TranscriptEventType): TranscriptEvent[];
+    get turnNumber(): number;
+    get eventCount(): number;
+    private flush;
+    /**
+     * 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 loadFromFile(filePath: string): Transcript;
+}

package/dist/session/transcript.js

@@ -0,0 +1,186 @@
+/**
+ * Transcript — JSONL event log (NOT chat history).
+ * toMessages() derives Message[] from events for sending to LLM.
+ */
+import { appendFileSync, readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { nanoid } from "nanoid";
+export class Transcript {
+    events = [];
+    filePath;
+    currentTurn = 0;
+    getFilePath() { return this.filePath; }
+    constructor(filePath) {
+        this.filePath = filePath;
+        mkdirSync(dirname(filePath), { recursive: true });
+        if (!existsSync(filePath)) {
+            writeFileSync(filePath, "", "utf-8");
+        }
+    }
+    append(type, data) {
+        const event = {
+            id: nanoid(12),
+            type,
+            timestamp: Date.now(),
+            turnNumber: this.currentTurn,
+            data,
+        };
+        this.events.push(event);
+        this.flush(event);
+        return event;
+    }
+    appendMessage(role, content) {
+        return this.append("message", { role, content });
+    }
+    appendToolUse(toolName, toolCallId, args) {
+        return this.append("tool_use", { toolName, toolCallId, args });
+    }
+    appendToolResult(toolCallId, toolName, result, error) {
+        return this.append("tool_result", { toolCallId, toolName, result, error });
+    }
+    appendTurnBoundary() {
+        this.currentTurn++;
+        return this.append("turn_boundary", { turnNumber: this.currentTurn });
+    }
+    appendSummary(summary, compactedRange) {
+        return this.append("summary", {
+            summary,
+            trigger: "auto",
+            compactedRange,
+            preservedSegment: {
+                headEventId: this.events[0]?.id,
+                tailEventId: this.events[this.events.length - 1]?.id,
+            },
+        });
+    }
+    appendError(error, details) {
+        return this.append("error", { error, ...details });
+    }
+    /**
+     * Derive Message[] from transcript events for sending to the LLM.
+     * This is the critical boundary: the LLM never sees the event log directly.
+     */
+    toMessages() {
+        const messages = [];
+        for (const event of this.events) {
+            switch (event.type) {
+                case "message": {
+                    const { role, content } = event.data;
+                    messages.push({ role: role, content });
+                    break;
+                }
+                case "tool_use": {
+                    // Tool use is part of assistant message content blocks
+                    // Already included via the assistant message event
+                    break;
+                }
+                case "tool_result": {
+                    const { toolCallId, result, error } = event.data;
+                    // Find if there's already a user message with tool_results to append to
+                    const lastMsg = messages[messages.length - 1];
+                    const block = {
+                        type: "tool_result",
+                        tool_use_id: toolCallId,
+                        content: error ? `Error: ${error}` : result ?? "(no output)",
+                    };
+                    if (lastMsg?.role === "user" && Array.isArray(lastMsg.content)) {
+                        lastMsg.content.push(block);
+                    }
+                    else {
+                        messages.push({ role: "user", content: [block] });
+                    }
+                    break;
+                }
+                case "summary": {
+                    // Content replacement: inject summary as system-reminder
+                    const { summary } = event.data;
+                    messages.push({
+                        role: "user",
+                        content: `<system-reminder>Previous conversation was summarized:\n${summary}</system-reminder>`,
+                    });
+                    break;
+                }
+                // turn_boundary, session_meta, file_history, plan_operation, error
+                // are not included in LLM messages
+            }
+        }
+        return messages;
+    }
+    getEvents(type) {
+        if (!type)
+            return [...this.events];
+        return this.events.filter((e) => e.type === type);
+    }
+    get turnNumber() {
+        return this.currentTurn;
+    }
+    get eventCount() {
+        return this.events.length;
+    }
+    flush(event) {
+        try {
+            appendFileSync(this.filePath, JSON.stringify(event) + "\n", "utf-8");
+        }
+        catch {
+            // Silently fail on flush errors — events are still in memory
+        }
+    }
+    /**
+     * 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() {
+        const toolUseIds = new Set();
+        const toolResultIds = new Set();
+        for (const event of this.events) {
+            if (event.type === "tool_use") {
+                toolUseIds.add(event.data.toolCallId);
+            }
+            else if (event.type === "tool_result") {
+                toolResultIds.add(event.data.toolCallId);
+            }
+        }
+        // Find tool_use events without matching tool_result
+        for (const id of toolUseIds) {
+            if (!toolResultIds.has(id)) {
+                // Synthesize an error result
+                this.append("tool_result", {
+                    toolCallId: id,
+                    toolName: "unknown",
+                    error: "[Tool result missing due to interrupted session]",
+                });
+            }
+        }
+        // Remove orphaned tool_results (result without matching use)
+        this.events = this.events.filter((event) => {
+            if (event.type === "tool_result") {
+                const id = event.data.toolCallId;
+                return toolUseIds.has(id);
+            }
+            return true;
+        });
+    }
+    static loadFromFile(filePath) {
+        const transcript = new Transcript(filePath);
+        if (!existsSync(filePath))
+            return transcript;
+        const content = readFileSync(filePath, "utf-8");
+        const lines = content.split("\n").filter((l) => l.trim());
+        for (const line of lines) {
+            try {
+                const event = JSON.parse(line);
+                transcript.events.push(event);
+                if (event.type === "turn_boundary") {
+                    transcript.currentTurn = event.data.turnNumber ?? transcript.currentTurn + 1;
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        // Repair pairing on load
+        transcript.repairToolResultPairs();
+        return transcript;
+    }
+}

package/dist/settings/manager.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Settings manager — multi-source loading and merge.
+ *
+ * Priority: CLI flags > local > project > user > managed
+ */
+import { type ValidatedSettings } from "./schema.js";
+export type SettingsSourceName = "managed" | "user" | "project" | "local" | "flag";
+export declare class SettingsManager {
+    private readonly cwd;
+    private sources;
+    private merged;
+    constructor(cwd?: string);
+    /**
+     * Load settings from all sources.
+     */
+    load(flagOverrides?: Record<string, unknown>): ValidatedSettings;
+    /**
+     * Get current effective settings.
+     */
+    get(): ValidatedSettings;
+    /**
+     * Invalidate cached merge.
+     */
+    invalidate(): void;
+    /**
+     * Persist a single setting (dotted key path) to the user-level config file
+     * at ~/.code-shell/settings.json. Other sources (project / local /
+     * managed) are intentionally untouched: writing back to project/local
+     * would surprise version control, and managed is read-only.
+     *
+     * The merged cache is invalidated so the next get() picks up the change.
+     */
+    saveUserSetting(key: string, value: unknown): void;
+    private loadJsonFile;
+    private deepMerge;
+}