@compass-ai/nova 1.0.72 → 1.0.74

package/dist/services/session-manager.js

@@ -0,0 +1,1184 @@
+/**
+ * Session management service for conversation state persistence.
+ *
+ * This module provides comprehensive session management functionality for the Compass CLI,
+ * including creating, saving, loading, and persisting session state with conversation history,
+ * operations tracking, and metadata management.
+ */
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { ApprovalMode } from '../types/approval.js';
+import { getGlobalCompassDir, getProjectCompassDir } from '../utils/path.js';
+import { safeReadJson, safeWriteJson, pathExists, ensureDir, readDir, } from '../utils/file-system.js';
+import { formatTimestamp } from '../utils/format.js';
+import { DEFAULT_PERSONALITY_MODE } from '../constants/index.js';
+import { logger } from '../utils/logger.js';
+import { SESSION_FILE_NAME, SAVED_SESSIONS_DIR, DEFAULT_MODEL, MAX_HISTORY_LENGTH, AUTO_SAVE_INTERVAL_MS, } from '../constants/defaults.js';
+import { getEventEmitter } from '../core/event-emitter.js';
+import { createChatArchivalService, } from './chat-archival-service.js';
+/**
+ * SessionManager class provides comprehensive session state management.
+ *
+ * Features:
+ * - Session creation and initialization
+ * - Conversation history management with automatic trimming
+ * - Operation tracking for file modifications and commands
+ * - Token usage and cost tracking
+ * - Session persistence with auto-save capability
+ * - Named session save/load for session restoration
+ * - Compacted summary support for conversation compaction
+ */
+class SessionManager {
+    session = null;
+    projectRoot = process.cwd();
+    autoSaveTimer = null;
+    dirty = false;
+    /** Transient unguarded mode flag - NOT persisted to session.json */
+    unguardedMode = false;
+    /** Pending attachments for the next message - NOT persisted to session.json */
+    pendingAttachments = [];
+    /** Chat archival service instance */
+    archivalService = null;
+    /**
+     * Creates a new session with default state.
+     *
+     * @param projectPath - Optional project root path. Defaults to current working directory.
+     * @returns The newly created Session object
+     *
+     * @example
+     * ```typescript
+     * const sessionManager = getSessionManager();
+     * const session = sessionManager.createSession('/path/to/project');
+     * console.log(session.id); // UUID of the new session
+     * ```
+     */
+    createSession(projectPath) {
+        this.projectRoot = projectPath || process.cwd();
+        this.session = {
+            id: uuidv4(),
+            createdAt: formatTimestamp(),
+            updatedAt: formatTimestamp(),
+            projectPath: this.projectRoot,
+            state: {
+                conversationHistory: [],
+                operations: [],
+                currentModel: DEFAULT_MODEL,
+                approvalMode: ApprovalMode.MANUAL,
+                contextFiles: [],
+                executionMode: 'hybrid', // Default to hybrid mode (LLM decides)
+            },
+            metadata: {
+                totalTokensUsed: 0,
+                totalCost: 0,
+                messageCount: 0,
+                operationCount: 0,
+                lastActivity: formatTimestamp(),
+                tags: [],
+            },
+        };
+        this.dirty = true;
+        logger.debug(`Session created: ${this.session.id}`);
+        return this.session;
+    }
+    /**
+     * Gets the current session.
+     *
+     * @returns The current Session object or null if no session is active
+     */
+    getSession() {
+        return this.session;
+    }
+    /**
+     * Gets the current session state.
+     *
+     * @returns The SessionState object or null if no session is active
+     */
+    getState() {
+        return this.session?.state || null;
+    }
+    /**
+     * Gets the session metadata.
+     *
+     * @returns The SessionMetadata object or null if no session is active
+     */
+    getMetadata() {
+        return this.session?.metadata || null;
+    }
+    /**
+     * Adds a message to the conversation history.
+     * Automatically trims history if it exceeds MAX_HISTORY_LENGTH.
+     *
+     * @param message - The message to add (without id and timestamp)
+     * @returns The complete ConversationMessage with generated id and timestamp
+     *
+     * @example
+     * ```typescript
+     * const message = sessionManager.addMessage({
+     *   role: 'user',
+     *   content: 'Hello, Claude!'
+     * });
+     * console.log(message.id); // Generated UUID
+     * console.log(message.timestamp); // ISO timestamp
+     * ```
+     */
+    addMessage(message) {
+        if (!this.session) {
+            this.createSession();
+        }
+        const fullMessage = {
+            id: uuidv4(),
+            timestamp: formatTimestamp(),
+            ...message,
+        };
+        this.session.state.conversationHistory.push(fullMessage);
+        this.session.metadata.messageCount++;
+        this.session.metadata.lastActivity = formatTimestamp();
+        this.session.updatedAt = formatTimestamp();
+        // Trim history if too long
+        if (this.session.state.conversationHistory.length > MAX_HISTORY_LENGTH) {
+            this.session.state.conversationHistory =
+                this.session.state.conversationHistory.slice(-MAX_HISTORY_LENGTH);
+        }
+        this.dirty = true;
+        logger.debug(`Message added: ${fullMessage.role} (${fullMessage.id})`);
+        return fullMessage;
+    }
+    /**
+     * Gets the conversation history.
+     *
+     * @returns Array of ConversationMessage objects
+     */
+    getConversationHistory() {
+        return this.session?.state.conversationHistory || [];
+    }
+    /**
+     * Clears the conversation history while preserving other session state.
+     * Also clears any compacted summary and operations.
+     */
+    clearHistory() {
+        if (this.session) {
+            const clearedCount = this.session.state.conversationHistory.length;
+            const clearedOpsCount = this.session.state.operations.length;
+            this.session.state.conversationHistory = [];
+            this.session.state.operations = [];
+            this.session.state.compactedSummary = undefined;
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.debug(`Conversation history cleared: ${clearedCount} messages, ${clearedOpsCount} operations removed`);
+        }
+    }
+    /**
+     * Archives the current session's conversation history to .compass/chats/.
+     * Call this before clearing history to preserve the conversation.
+     *
+     * @returns Archive result with path and ID, or error if archival failed
+     */
+    async archiveCurrentSession() {
+        if (!this.session) {
+            return { success: false, error: 'No active session to archive' };
+        }
+        // Skip if no messages to archive
+        if (!this.session.state.conversationHistory || this.session.state.conversationHistory.length === 0) {
+            logger.debug('No messages to archive, skipping');
+            return { success: false, error: 'No messages to archive' };
+        }
+        // Initialize archival service if needed
+        if (!this.archivalService) {
+            this.archivalService = createChatArchivalService(this.projectRoot);
+        }
+        try {
+            const result = await this.archivalService.archiveSession(this.session);
+            if (result.success) {
+                logger.info(`Session archived to: ${result.filename}`);
+            }
+            return result;
+        }
+        catch (error) {
+            logger.error('Failed to archive session', error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+    /**
+     * Archives the current session and clears the history.
+     * Use this on startup to preserve previous conversation before starting fresh.
+     *
+     * @returns The archived conversation data (for -c flag to load into context), or null if archival failed
+     */
+    async archiveAndClearSession() {
+        // First, get the archive data before clearing
+        let archive = null;
+        // Initialize archival service if needed
+        if (!this.archivalService) {
+            this.archivalService = createChatArchivalService(this.projectRoot);
+        }
+        // Archive the session
+        const result = await this.archiveCurrentSession();
+        // If archival succeeded, load the archive data for returning
+        if (result.success && result.path) {
+            archive = await this.archivalService.getLatestArchive();
+        }
+        // Clear the history regardless of archival success
+        this.clearHistory();
+        // Run cleanup of old archives (non-blocking)
+        this.archivalService.cleanupOldArchives().catch((err) => {
+            logger.warn('Failed to cleanup old archives', err);
+        });
+        return { archive, result };
+    }
+    /**
+     * Gets the chat archival service instance.
+     * Creates one if it doesn't exist.
+     *
+     * @returns ChatArchivalService instance
+     */
+    getArchivalService() {
+        if (!this.archivalService) {
+            this.archivalService = createChatArchivalService(this.projectRoot);
+        }
+        return this.archivalService;
+    }
+    /**
+     * Sets a compacted summary and clears the conversation history.
+     * Used by the conversation compactor to reduce token usage.
+     *
+     * @param summary - The compacted summary text
+     */
+    setCompactedSummary(summary) {
+        if (this.session) {
+            this.session.state.compactedSummary = summary;
+            this.session.state.conversationHistory = [];
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.info('Compacted summary set, conversation history cleared');
+        }
+    }
+    /**
+     * Gets the compacted summary if one exists.
+     *
+     * @returns The compacted summary string or undefined
+     */
+    getCompactedSummary() {
+        return this.session?.state.compactedSummary;
+    }
+    /**
+     * Updates the session after agentic loop compaction.
+     * Stores the summary and keeps a record of recent messages for context.
+     *
+     * @param summary - The compacted summary text
+     * @param recentMessagesCount - Number of recent messages that were preserved (for context)
+     */
+    syncAfterCompaction(summary, recentMessagesCount) {
+        if (this.session) {
+            this.session.state.compactedSummary = summary;
+            // Keep recent messages in history for UI display, but mark session as compacted
+            this.session.metadata.isCompacted = true;
+            this.session.metadata.compactionTimestamp = formatTimestamp();
+            this.session.metadata.messagesPreserved = recentMessagesCount;
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.info(`Session synced after compaction: summary stored, ${recentMessagesCount} recent messages preserved`);
+        }
+    }
+    /**
+     * Replaces the entire conversation history.
+     * Used when syncing the agentic loop messages back to the session.
+     *
+     * @param messages - Array of messages to set as the new history
+     */
+    replaceConversationHistory(messages) {
+        if (this.session) {
+            this.session.state.conversationHistory = messages;
+            this.session.metadata.messageCount = messages.length;
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.debug(`Conversation history replaced: ${messages.length} messages`);
+        }
+    }
+    /**
+     * Updates the estimated context token count.
+     * Called during agentic loops to keep the session metadata in sync with
+     * the actual API messages token usage.
+     *
+     * @param tokenCount - The estimated token count of current context
+     */
+    updateEstimatedContextTokens(tokenCount) {
+        if (this.session) {
+            this.session.metadata.estimatedContextTokens = tokenCount;
+            // Don't mark dirty for frequent token updates - this is informational only
+            logger.debug(`Session context tokens updated: ${tokenCount.toLocaleString()}`);
+        }
+    }
+    /**
+     * Gets the estimated context token count.
+     *
+     * @returns The estimated context tokens or 0 if not set
+     */
+    getEstimatedContextTokens() {
+        return this.session?.metadata.estimatedContextTokens ?? 0;
+    }
+    /**
+     * Records an operation (file modification, command execution, etc.).
+     *
+     * @param operation - The operation to record (without id and timestamp)
+     * @returns The complete Operation with generated id and timestamp
+     *
+     * @example
+     * ```typescript
+     * const operation = sessionManager.recordOperation({
+     *   type: 'file_modify',
+     *   description: 'Updated src/index.ts',
+     *   status: 'completed',
+     *   details: {
+     *     filePath: 'src/index.ts',
+     *     oldContent: '...',
+     *     newContent: '...'
+     *   }
+     * });
+     * ```
+     */
+    recordOperation(operation) {
+        if (!this.session) {
+            this.createSession();
+        }
+        const fullOperation = {
+            id: uuidv4(),
+            timestamp: formatTimestamp(),
+            ...operation,
+        };
+        this.session.state.operations.push(fullOperation);
+        this.session.metadata.operationCount++;
+        this.session.metadata.lastActivity = formatTimestamp();
+        this.session.updatedAt = formatTimestamp();
+        this.dirty = true;
+        logger.debug(`Operation recorded: ${fullOperation.type} (${fullOperation.id})`);
+        return fullOperation;
+    }
+    /**
+     * Gets the operations history.
+     *
+     * @returns Array of Operation objects
+     */
+    getOperations() {
+        return this.session?.state.operations || [];
+    }
+    /**
+     * Gets the last operation performed.
+     *
+     * @returns The most recent Operation or undefined if none exist
+     */
+    getLastOperation() {
+        const operations = this.session?.state.operations || [];
+        return operations[operations.length - 1];
+    }
+    /**
+     * Updates an existing operation's status.
+     *
+     * @param operationId - The ID of the operation to update
+     * @param updates - Partial operation data to merge
+     * @returns True if the operation was found and updated
+     */
+    updateOperation(operationId, updates) {
+        if (!this.session) {
+            return false;
+        }
+        const operation = this.session.state.operations.find((op) => op.id === operationId);
+        if (!operation) {
+            return false;
+        }
+        Object.assign(operation, updates);
+        this.session.updatedAt = formatTimestamp();
+        this.dirty = true;
+        logger.debug(`Operation updated: ${operationId}`);
+        return true;
+    }
+    /**
+     * Updates token usage and cost statistics.
+     *
+     * @param tokens - Number of tokens to add
+     * @param cost - Cost to add
+     */
+    updateTokenUsage(tokens, cost) {
+        if (this.session) {
+            this.session.metadata.totalTokensUsed += tokens;
+            this.session.metadata.totalCost += cost;
+            this.session.metadata.lastActivity = formatTimestamp();
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+        }
+    }
+    /**
+     * Sets the current model for the session.
+     *
+     * @param modelId - The model ID to set
+     */
+    setModel(modelId) {
+        if (this.session) {
+            this.session.state.currentModel = modelId;
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.debug(`Model set: ${modelId}`);
+        }
+    }
+    /**
+     * Gets the current model ID.
+     *
+     * @returns The current model ID or the default model
+     */
+    getCurrentModel() {
+        return this.session?.state.currentModel || DEFAULT_MODEL;
+    }
+    /**
+     * Sets the approval mode for the session.
+     *
+     * @param mode - The ApprovalMode to set
+     */
+    setApprovalMode(mode) {
+        if (this.session) {
+            this.session.state.approvalMode = mode;
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.debug(`Approval mode set: ${mode}`);
+        }
+    }
+    /**
+     * Gets the current approval mode.
+     *
+     * @returns The current ApprovalMode
+     */
+    getApprovalMode() {
+        return this.session?.state.approvalMode || ApprovalMode.MANUAL;
+    }
+    /**
+     * Sets the execution mode for the session.
+     *
+     * @param mode - The ExecutionMode to set
+     */
+    setExecutionMode(mode) {
+        if (this.session) {
+            this.session.state.executionMode = mode;
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.debug(`Execution mode set: ${mode}`);
+        }
+    }
+    /**
+     * Gets the current execution mode.
+     *
+     * @returns The current ExecutionMode (defaults to 'hybrid' if not set)
+     */
+    getExecutionMode() {
+        return this.session?.state.executionMode || 'hybrid';
+    }
+    /**
+     * Sets whether to show tool execution blocks in conversation history.
+     *
+     * @param show - Whether to show tool blocks (true) or minimal text-only (false)
+     */
+    setShowToolBlocks(show) {
+        if (this.session) {
+            this.session.state.showToolBlocks = show;
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.debug(`Show tool blocks set: ${show}`);
+        }
+    }
+    /**
+     * Gets whether tool execution blocks should be shown in conversation history.
+     *
+     * @returns Whether to show tool blocks (defaults to true if not set)
+     */
+    getShowToolBlocks() {
+        return this.session?.state.showToolBlocks ?? true;
+    }
+    /**
+     * Adds a file to the context files list.
+     *
+     * @param filePath - The file path to add
+     */
+    addContextFile(filePath) {
+        if (this.session) {
+            if (!this.session.state.contextFiles.includes(filePath)) {
+                this.session.state.contextFiles.push(filePath);
+                this.session.updatedAt = formatTimestamp();
+                this.dirty = true;
+            }
+        }
+    }
+    /**
+     * Removes a file from the context files list.
+     *
+     * @param filePath - The file path to remove
+     */
+    removeContextFile(filePath) {
+        if (this.session) {
+            const index = this.session.state.contextFiles.indexOf(filePath);
+            if (index !== -1) {
+                this.session.state.contextFiles.splice(index, 1);
+                this.session.updatedAt = formatTimestamp();
+                this.dirty = true;
+            }
+        }
+    }
+    /**
+     * Gets the list of context files.
+     *
+     * @returns Array of file paths
+     */
+    getContextFiles() {
+        return this.session?.state.contextFiles || [];
+    }
+    /**
+     * Adds a folder to the excluded folders list.
+     * These folders will be excluded from indexing, code snippets, and file discovery.
+     *
+     * @param folderPattern - The folder pattern to exclude (glob pattern supported)
+     */
+    addExcludedFolder(folderPattern) {
+        if (this.session) {
+            if (!this.session.state.excludedFolders) {
+                this.session.state.excludedFolders = [];
+            }
+            if (!this.session.state.excludedFolders.includes(folderPattern)) {
+                this.session.state.excludedFolders.push(folderPattern);
+                this.session.updatedAt = formatTimestamp();
+                this.dirty = true;
+                logger.debug(`Excluded folder added: ${folderPattern}`);
+            }
+        }
+    }
+    /**
+     * Removes a folder from the excluded folders list.
+     *
+     * @param folderPattern - The folder pattern to remove
+     */
+    removeExcludedFolder(folderPattern) {
+        if (this.session && this.session.state.excludedFolders) {
+            const index = this.session.state.excludedFolders.indexOf(folderPattern);
+            if (index !== -1) {
+                this.session.state.excludedFolders.splice(index, 1);
+                this.session.updatedAt = formatTimestamp();
+                this.dirty = true;
+                logger.debug(`Excluded folder removed: ${folderPattern}`);
+            }
+        }
+    }
+    /**
+     * Sets the excluded folders list, replacing any existing entries.
+     *
+     * @param folderPatterns - Array of folder patterns to exclude
+     */
+    setExcludedFolders(folderPatterns) {
+        if (this.session) {
+            this.session.state.excludedFolders = [...folderPatterns];
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.debug(`Excluded folders set: ${folderPatterns.length} patterns`);
+        }
+    }
+    /**
+     * Gets the list of excluded folders.
+     *
+     * @returns Array of folder patterns
+     */
+    getExcludedFolders() {
+        return this.session?.state.excludedFolders || [];
+    }
+    /**
+     * Clears all excluded folders.
+     */
+    clearExcludedFolders() {
+        if (this.session) {
+            this.session.state.excludedFolders = [];
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.debug('Excluded folders cleared');
+        }
+    }
+    /**
+     * Sets the personality mode for the assistant's communication style.
+     *
+     * @param mode - The PersonalityMode to set
+     */
+    setPersonalityMode(mode) {
+        if (this.session) {
+            this.session.state.personalityMode = mode;
+            this.session.updatedAt = formatTimestamp();
+            this.dirty = true;
+            logger.debug(`Personality mode set: ${mode}`);
+        }
+    }
+    /**
+     * Gets the current personality mode.
+     *
+     * @returns The current PersonalityMode (defaults to 'professional' if not set)
+     */
+    getPersonalityMode() {
+        return this.session?.state.personalityMode || DEFAULT_PERSONALITY_MODE;
+    }
+    /**
+     * Sets a temporary personality mode for the next response only.
+     * This overrides the regular personality mode until cleared.
+     *
+     * @param mode - The temporary PersonalityMode to set
+     */
+    setTemporaryPersonalityMode(mode) {
+        if (this.session) {
+            this.session.state.temporaryPersonalityMode = mode;
+            this.session.updatedAt = formatTimestamp();
+            // Don't mark dirty - temporary mode shouldn't persist to disk
+            logger.debug(`Temporary personality mode set: ${mode}`);
+        }
+    }
+    /**
+     * Clears the temporary personality mode.
+     * Should be called after each response when temporary mode is set.
+     */
+    clearTemporaryPersonalityMode() {
+        if (this.session && this.session.state.temporaryPersonalityMode) {
+            this.session.state.temporaryPersonalityMode = undefined;
+            this.session.updatedAt = formatTimestamp();
+            logger.debug('Temporary personality mode cleared');
+        }
+    }
+    /**
+     * Gets the effective personality mode (temporary if set, otherwise regular).
+     *
+     * @returns The effective PersonalityMode to use for the current response
+     */
+    getEffectivePersonalityMode() {
+        if (this.session?.state.temporaryPersonalityMode) {
+            return this.session.state.temporaryPersonalityMode;
+        }
+        return this.getPersonalityMode();
+    }
+    /**
+     * Checks if a temporary personality mode is currently active.
+     *
+     * @returns True if temporary mode is set
+     */
+    hasTemporaryPersonalityMode() {
+        return this.session?.state.temporaryPersonalityMode !== undefined;
+    }
+    /**
+     * Sets the unguarded mode for the session.
+     * When enabled, removes safety guardrails from the system prompt.
+     * NOTE: This is a transient setting that is NOT persisted to session.json.
+     *
+     * @param enabled - Whether to enable unguarded mode
+     */
+    setUnguardedMode(enabled) {
+        this.unguardedMode = enabled;
+        logger.debug(`Unguarded mode set: ${enabled} (transient - not persisted)`);
+    }
+    /**
+     * Gets whether unguarded mode is currently active.
+     * NOTE: This is a transient setting that is NOT persisted to session.json.
+     *
+     * @returns True if unguarded mode is enabled
+     */
+    getUnguardedMode() {
+        return this.unguardedMode;
+    }
+    /**
+     * Adds a tag to the session.
+     *
+     * @param tag - The tag to add
+     */
+    addTag(tag) {
+        if (this.session) {
+            if (!this.session.metadata.tags.includes(tag)) {
+                this.session.metadata.tags.push(tag);
+                this.session.updatedAt = formatTimestamp();
+                this.dirty = true;
+            }
+        }
+    }
+    /**
+     * Removes a tag from the session.
+     *
+     * @param tag - The tag to remove
+     */
+    removeTag(tag) {
+        if (this.session) {
+            const index = this.session.metadata.tags.indexOf(tag);
+            if (index !== -1) {
+                this.session.metadata.tags.splice(index, 1);
+                this.session.updatedAt = formatTimestamp();
+                this.dirty = true;
+            }
+        }
+    }
+    /**
+     * Saves the current session to the project's .compass directory.
+     */
+    async save() {
+        if (!this.session) {
+            logger.debug('No session to save');
+            return;
+        }
+        if (!this.dirty) {
+            logger.debug('Session not dirty, skipping save');
+            return;
+        }
+        try {
+            const compassDir = getProjectCompassDir(this.projectRoot);
+            await ensureDir(compassDir);
+            const sessionPath = path.join(compassDir, SESSION_FILE_NAME);
+            await safeWriteJson(sessionPath, this.session);
+            this.dirty = false;
+            logger.debug('Session saved');
+            // Emit session saved event
+            const eventEmitter = getEventEmitter();
+            eventEmitter.emit('session-saved', { sessionId: this.session.id });
+        }
+        catch (error) {
+            logger.error('Failed to save session', error);
+            throw error;
+        }
+    }
+    /**
+     * Loads a session from the project's .compass directory.
+     *
+     * @param projectPath - Optional project root path
+     * @returns The loaded Session or null if not found
+     */
+    async load(projectPath) {
+        this.projectRoot = projectPath || process.cwd();
+        const sessionPath = path.join(getProjectCompassDir(this.projectRoot), SESSION_FILE_NAME);
+        if (!(await pathExists(sessionPath))) {
+            logger.debug('No existing session found');
+            return null;
+        }
+        try {
+            const session = await safeReadJson(sessionPath);
+            if (session) {
+                // Migrate/validate session structure to ensure all required fields exist
+                this.session = this.migrateSession(session);
+                this.dirty = false;
+                logger.info(`Session loaded: ${this.session.id}`);
+                // Update projectPath if it doesn't match the current absolute path
+                const absoluteProjectRoot = path.resolve(this.projectRoot);
+                const absoluteSessionPath = path.resolve(this.session.projectPath);
+                if (absoluteSessionPath !== absoluteProjectRoot) {
+                    logger.debug(`Updating session projectPath from ${this.session.projectPath} to ${absoluteProjectRoot}`);
+                    this.session.projectPath = absoluteProjectRoot;
+                    this.session.updatedAt = formatTimestamp();
+                    this.dirty = true;
+                }
+            }
+            return this.session;
+        }
+        catch (error) {
+            logger.error('Failed to load session', error);
+            return null;
+        }
+    }
+    /**
+     * Migrates a session loaded from disk to ensure all required fields exist.
+     * This handles backward compatibility when session schema changes.
+     *
+     * @param session - The raw session data loaded from disk
+     * @returns A valid Session object with all required fields
+     */
+    migrateSession(session) {
+        let needsMigration = false;
+        // Ensure metadata exists with all required fields
+        if (!session.metadata) {
+            session.metadata = {
+                totalTokensUsed: 0,
+                totalCost: 0,
+                messageCount: 0,
+                operationCount: 0,
+                lastActivity: formatTimestamp(),
+                tags: [],
+            };
+            needsMigration = true;
+            logger.debug('Session migrated: added missing metadata field');
+        }
+        else {
+            // Ensure all metadata fields exist
+            const metadata = session.metadata;
+            if (typeof metadata.totalTokensUsed !== 'number') {
+                metadata.totalTokensUsed = 0;
+                needsMigration = true;
+            }
+            if (typeof metadata.totalCost !== 'number') {
+                metadata.totalCost = 0;
+                needsMigration = true;
+            }
+            if (typeof metadata.messageCount !== 'number') {
+                metadata.messageCount = 0;
+                needsMigration = true;
+            }
+            if (typeof metadata.operationCount !== 'number') {
+                metadata.operationCount = 0;
+                needsMigration = true;
+            }
+            if (!metadata.lastActivity) {
+                metadata.lastActivity = formatTimestamp();
+                needsMigration = true;
+            }
+            if (!Array.isArray(metadata.tags)) {
+                metadata.tags = [];
+                needsMigration = true;
+            }
+        }
+        // Ensure state exists with all required fields
+        if (!session.state) {
+            session.state = {
+                conversationHistory: [],
+                operations: [],
+                currentModel: DEFAULT_MODEL,
+                approvalMode: ApprovalMode.MANUAL,
+                contextFiles: [],
+                executionMode: 'hybrid',
+            };
+            needsMigration = true;
+            logger.debug('Session migrated: added missing state field');
+        }
+        else {
+            // Ensure all state fields exist
+            const state = session.state;
+            if (!Array.isArray(state.conversationHistory)) {
+                state.conversationHistory = [];
+                needsMigration = true;
+            }
+            if (!Array.isArray(state.operations)) {
+                state.operations = [];
+                needsMigration = true;
+            }
+            if (!state.currentModel) {
+                state.currentModel = DEFAULT_MODEL;
+                needsMigration = true;
+            }
+            if (!state.approvalMode) {
+                state.approvalMode = ApprovalMode.MANUAL;
+                needsMigration = true;
+            }
+            if (!Array.isArray(state.contextFiles)) {
+                state.contextFiles = [];
+                needsMigration = true;
+            }
+        }
+        // Ensure required top-level fields exist
+        if (!session.id) {
+            session.id = uuidv4();
+            needsMigration = true;
+        }
+        if (!session.createdAt) {
+            session.createdAt = formatTimestamp();
+            needsMigration = true;
+        }
+        if (!session.updatedAt) {
+            session.updatedAt = formatTimestamp();
+            needsMigration = true;
+        }
+        if (!session.projectPath) {
+            session.projectPath = this.projectRoot;
+            needsMigration = true;
+        }
+        if (needsMigration) {
+            this.dirty = true;
+            logger.info('Session structure migrated to current schema');
+        }
+        return session;
+    }
+    /**
+     * Saves the current session to a named file in the saved-sessions directory.
+     *
+     * @param name - The name for the saved session
+     * @param description - Optional description for the saved session
+     * @returns The path to the saved session file
+     *
+     * @example
+     * ```typescript
+     * const path = await sessionManager.saveAs('my-feature-work', 'Working on login feature');
+     * console.log(`Session saved to: ${path}`);
+     * ```
+     */
+    async saveAs(name, description) {
+        if (!this.session) {
+            throw new Error('No active session to save');
+        }
+        const savedSessionsDir = path.join(getGlobalCompassDir(), SAVED_SESSIONS_DIR);
+        await ensureDir(savedSessionsDir);
+        const savedSession = {
+            session: this.session,
+            savedAt: formatTimestamp(),
+            name,
+            description,
+        };
+        // Sanitize the name for use as a filename
+        const sanitizedName = name.replace(/[^a-zA-Z0-9-_]/g, '_');
+        const fileName = `${sanitizedName}.json`;
+        const filePath = path.join(savedSessionsDir, fileName);
+        await safeWriteJson(filePath, savedSession);
+        logger.info(`Session saved as: ${name}`);
+        return filePath;
+    }
+    /**
+     * Lists all saved sessions.
+     *
+     * @returns Array of SavedSession objects sorted by savedAt (most recent first)
+     */
+    async listSavedSessions() {
+        const savedSessionsDir = path.join(getGlobalCompassDir(), SAVED_SESSIONS_DIR);
+        if (!(await pathExists(savedSessionsDir))) {
+            return [];
+        }
+        const files = await readDir(savedSessionsDir);
+        const sessions = [];
+        for (const file of files) {
+            if (file.endsWith('.json')) {
+                const filePath = path.join(savedSessionsDir, file);
+                try {
+                    const saved = await safeReadJson(filePath);
+                    if (saved) {
+                        sessions.push(saved);
+                    }
+                }
+                catch (error) {
+                    logger.debug(`Failed to load saved session: ${file}`, error);
+                }
+            }
+        }
+        // Sort by savedAt, most recent first
+        return sessions.sort((a, b) => new Date(b.savedAt).getTime() - new Date(a.savedAt).getTime());
+    }
+    /**
+     * Loads a saved session by name.
+     *
+     * @param name - The name of the saved session to load
+     * @returns The loaded Session or null if not found
+     */
+    async loadSaved(name) {
+        const savedSessionsDir = path.join(getGlobalCompassDir(), SAVED_SESSIONS_DIR);
+        const sanitizedName = name.replace(/[^a-zA-Z0-9-_]/g, '_');
+        const fileName = `${sanitizedName}.json`;
+        const filePath = path.join(savedSessionsDir, fileName);
+        if (!(await pathExists(filePath))) {
+            logger.debug(`Saved session not found: ${name}`);
+            return null;
+        }
+        try {
+            const saved = await safeReadJson(filePath);
+            if (saved) {
+                this.session = saved.session;
+                this.projectRoot = saved.session.projectPath;
+                this.dirty = false;
+                logger.info(`Loaded saved session: ${name}`);
+                return this.session;
+            }
+            return null;
+        }
+        catch (error) {
+            logger.error(`Failed to load saved session: ${name}`, error);
+            return null;
+        }
+    }
+    /**
+     * Deletes a saved session by name.
+     *
+     * @param name - The name of the saved session to delete
+     * @returns True if the session was deleted, false if not found
+     */
+    async deleteSavedSession(name) {
+        const savedSessionsDir = path.join(getGlobalCompassDir(), SAVED_SESSIONS_DIR);
+        const sanitizedName = name.replace(/[^a-zA-Z0-9-_]/g, '_');
+        const fileName = `${sanitizedName}.json`;
+        const filePath = path.join(savedSessionsDir, fileName);
+        if (!(await pathExists(filePath))) {
+            return false;
+        }
+        try {
+            const { remove } = await import('../utils/file-system.js');
+            await remove(filePath);
+            logger.info(`Deleted saved session: ${name}`);
+            return true;
+        }
+        catch (error) {
+            logger.error(`Failed to delete saved session: ${name}`, error);
+            return false;
+        }
+    }
+    /**
+     * Starts the auto-save timer.
+     *
+     * @param intervalMs - Interval in milliseconds between auto-saves
+     */
+    startAutoSave(intervalMs = AUTO_SAVE_INTERVAL_MS) {
+        this.stopAutoSave();
+        this.autoSaveTimer = setInterval(() => {
+            if (this.dirty) {
+                this.save().catch((err) => {
+                    logger.error('Auto-save failed', err);
+                });
+            }
+        }, intervalMs);
+        logger.debug(`Auto-save started with interval: ${intervalMs}ms`);
+    }
+    /**
+     * Stops the auto-save timer.
+     */
+    stopAutoSave() {
+        if (this.autoSaveTimer) {
+            clearInterval(this.autoSaveTimer);
+            this.autoSaveTimer = null;
+            logger.debug('Auto-save stopped');
+        }
+    }
+    /**
+     * Checks if the session has unsaved changes.
+     *
+     * @returns True if there are unsaved changes
+     */
+    isDirty() {
+        return this.dirty;
+    }
+    /**
+     * Forces a save regardless of dirty state.
+     */
+    async forceSave() {
+        this.dirty = true;
+        await this.save();
+    }
+    /**
+     * Gets the project root path.
+     *
+     * @returns The project root path
+     */
+    getProjectRoot() {
+        return this.projectRoot;
+    }
+    /**
+     * Sets the project root path.
+     *
+     * @param projectRoot - The new project root path
+     */
+    setProjectRoot(projectRoot) {
+        this.projectRoot = projectRoot;
+        if (this.session) {
+            this.session.projectPath = projectRoot;
+            this.dirty = true;
+        }
+    }
+    /**
+     * Exports the current session data for backup or analysis.
+     *
+     * @returns The current session or null
+     */
+    exportSession() {
+        return this.session ? { ...this.session } : null;
+    }
+    /**
+     * Imports a session from exported data.
+     *
+     * @param session - The session data to import
+     */
+    importSession(session) {
+        this.session = { ...session };
+        this.projectRoot = session.projectPath;
+        this.dirty = true;
+        logger.info(`Session imported: ${session.id}`);
+    }
+    /**
+     * Gets the list of pending attachments for the next message.
+     *
+     * @returns Array of pending Attachment objects
+     */
+    getPendingAttachments() {
+        return [...this.pendingAttachments];
+    }
+    /**
+     * Adds an attachment to the pending list.
+     *
+     * @param attachment - The attachment to add
+     */
+    addPendingAttachment(attachment) {
+        this.pendingAttachments.push(attachment);
+        logger.debug(`Pending attachment added: ${attachment.filename} (${attachment.type})`);
+    }
+    /**
+     * Adds multiple attachments to the pending list.
+     *
+     * @param attachments - Array of attachments to add
+     */
+    addPendingAttachments(attachments) {
+        this.pendingAttachments.push(...attachments);
+        logger.debug(`Added ${attachments.length} pending attachments`);
+    }
+    /**
+     * Clears all pending attachments.
+     */
+    clearPendingAttachments() {
+        const count = this.pendingAttachments.length;
+        this.pendingAttachments = [];
+        if (count > 0) {
+            logger.debug(`Cleared ${count} pending attachments`);
+        }
+    }
+    /**
+     * Consumes and returns all pending attachments, clearing the pending list.
+     * Use this when sending a message that includes attachments.
+     *
+     * @returns Array of Attachment objects
+     */
+    consumePendingAttachments() {
+        const attachments = [...this.pendingAttachments];
+        this.pendingAttachments = [];
+        if (attachments.length > 0) {
+            logger.debug(`Consumed ${attachments.length} pending attachments`);
+        }
+        return attachments;
+    }
+    /**
+     * Checks if there are any pending attachments.
+     *
+     * @returns True if there are pending attachments
+     */
+    hasPendingAttachments() {
+        return this.pendingAttachments.length > 0;
+    }
+    /**
+     * Gets the count of pending attachments.
+     *
+     * @returns Number of pending attachments
+     */
+    getPendingAttachmentsCount() {
+        return this.pendingAttachments.length;
+    }
+}
+// Singleton instance
+let sessionManagerInstance = null;
+/**
+ * Gets the singleton SessionManager instance.
+ * Creates the instance on first call.
+ *
+ * @returns The SessionManager instance
+ *
+ * @example
+ * ```typescript
+ * const sessionManager = getSessionManager();
+ * const session = sessionManager.createSession();
+ * ```
+ */
+export function getSessionManager() {
+    if (!sessionManagerInstance) {
+        sessionManagerInstance = new SessionManager();
+    }
+    return sessionManagerInstance;
+}
+/**
+ * Creates a new SessionManager instance with custom configuration.
+ * Use this when you need a separate instance from the singleton.
+ *
+ * @returns A new SessionManager instance
+ */
+export function createSessionManager() {
+    return new SessionManager();
+}
+export { SessionManager };
+//# sourceMappingURL=session-manager.js.map