@loxia-labs/loxia-autopilot-one 1.0.1

package/src/core/stateManager.js

@@ -0,0 +1,877 @@
+/**
+ * StateManager - Handles state persistence, recovery, and project state management
+ * 
+ * Purpose:
+ * - Project state persistence and recovery
+ * - Agent state management across sessions
+ * - Multi-model conversation state handling
+ * - Context reference state management
+ * - Session recovery and resume functionality
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+
+class StateManager {
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger;
+    
+    this.stateDirectory = config.system?.stateDirectory || '.loxia-state';
+    this.stateVersion = '1.0.0';
+    
+    // State file paths
+    this.stateFiles = {
+      projectState: 'project-state.json',
+      agentIndex: 'agent-index.json',
+      conversationIndex: 'conversation-index.json',
+      lastSession: 'last-session.json',
+      contextReferences: 'context-references.json',
+      asyncOperations: 'operations/async-operations.json',
+      pausedAgents: 'operations/paused-agents.json',
+      toolHistory: 'operations/tool-history.json',
+      modelRouterCache: 'models/model-router-cache.json',
+      errorRecoveryLog: 'models/error-recovery-log.json'
+    };
+  }
+
+  /**
+   * Initialize state directory structure
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<void>}
+   */
+  async initializeStateDirectory(projectDir) {
+    const stateDir = path.join(projectDir, this.stateDirectory);
+    
+    try {
+      // Create main state directory
+      await fs.mkdir(stateDir, { recursive: true });
+      
+      // Create subdirectories
+      await fs.mkdir(path.join(stateDir, 'agents'), { recursive: true });
+      await fs.mkdir(path.join(stateDir, 'operations'), { recursive: true });
+      await fs.mkdir(path.join(stateDir, 'models'), { recursive: true });
+      
+      this.logger.info(`State directory initialized: ${stateDir}`);
+      
+    } catch (error) {
+      this.logger.error(`Failed to initialize state directory: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Resume project from saved state
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Resumed project state
+   */
+  async resumeProject(projectDir) {
+    try {
+      await this.initializeStateDirectory(projectDir);
+      
+      // Load project state
+      const projectState = await this.loadProjectState(projectDir);
+      const agentIndex = await this.loadAgentIndex(projectDir);
+      
+      // Restore agents with multi-model conversations
+      const restoredAgents = [];
+      for (const [agentId, agentInfo] of Object.entries(agentIndex)) {
+        try {
+          const agent = await this.restoreAgent(agentId, agentInfo, projectDir);
+          restoredAgents.push(agent);
+        } catch (error) {
+          this.logger.warn(`Failed to restore agent: ${agentId}`, error.message);
+        }
+      }
+      
+      // Restore async operations
+      const asyncOperations = await this.restoreAsyncOperations(projectDir);
+      
+      // Restore paused agents
+      const pausedAgents = await this.restorePausedAgents(projectDir);
+      
+      // Restore context references
+      const contextReferences = await this.restoreContextReferences(projectDir);
+      
+      const resumedState = {
+        projectState,
+        agents: restoredAgents,
+        asyncOperations,
+        pausedAgents,
+        contextReferences,
+        resumedSuccessfully: true,
+        resumedAt: new Date().toISOString()
+      };
+      
+      // Update last session
+      await this.saveLastSession(projectDir, {
+        resumedAt: new Date().toISOString(),
+        agentCount: restoredAgents.length,
+        operationCount: asyncOperations.length
+      });
+      
+      this.logger.info(`Project resumed successfully`, {
+        projectDir,
+        agentCount: restoredAgents.length,
+        operationCount: asyncOperations.length
+      });
+      
+      return resumedState;
+      
+    } catch (error) {
+      this.logger.error(`Project resume failed: ${error.message}`, {
+        projectDir,
+        error: error.stack
+      });
+      
+      return {
+        projectState: null,
+        agents: [],
+        asyncOperations: [],
+        pausedAgents: [],
+        contextReferences: [],
+        resumedSuccessfully: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Persist agent state to storage
+   * @param {Object} agent - Agent object to persist
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<void>}
+   */
+  async persistAgentState(agent, projectDir = process.cwd()) {
+    const stateDir = path.join(projectDir, this.stateDirectory);
+    const agentStateFile = path.join(stateDir, 'agents', `agent-${agent.id}-state.json`);
+    const agentConversationsFile = path.join(stateDir, 'agents', `agent-${agent.id}-conversations.json`);
+    
+    try {
+      // Separate conversations from main agent state
+      const { conversations, ...agentState } = agent;
+      
+      // Save agent state
+      await this.saveJSON(agentStateFile, {
+        version: this.stateVersion,
+        agentId: agent.id,
+        state: agentState,
+        lastPersisted: new Date().toISOString()
+      });
+      
+      // Save conversations separately
+      await this.saveJSON(agentConversationsFile, {
+        version: this.stateVersion,
+        agentId: agent.id,
+        conversations,
+        lastPersisted: new Date().toISOString()
+      });
+      
+      // Update agent index
+      await this.updateAgentIndex(agent, projectDir);
+      
+      this.logger.debug(`Agent state persisted: ${agent.id}`);
+      
+    } catch (error) {
+      this.logger.error(`Failed to persist agent state: ${error.message}`, {
+        agentId: agent.id,
+        error: error.stack
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Get project state
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Project state object
+   */
+  async getProjectState(projectDir) {
+    return await this.loadProjectState(projectDir);
+  }
+
+  /**
+   * Load project state from storage
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Project state object
+   */
+  async loadProjectState(projectDir) {
+    const stateFile = path.join(projectDir, this.stateDirectory, this.stateFiles.projectState);
+    
+    try {
+      const data = await this.loadJSON(stateFile);
+      return data;
+    } catch (error) {
+      // Return default project state if file doesn't exist
+      const defaultState = {
+        version: this.stateVersion,
+        projectDir,
+        createdAt: new Date().toISOString(),
+        lastModified: new Date().toISOString(),
+        activeAgents: [],
+        lastActiveSession: null,
+        configuration: {
+          defaultModel: this.config.system?.defaultModel || 'anthropic-sonnet',
+          allowedTools: ['terminal', 'filesystem', 'browser'],
+          budgetLimit: 100.00
+        }
+      };
+      
+      await this.saveProjectState(projectDir, defaultState);
+      return defaultState;
+    }
+  }
+
+  /**
+   * Save project state to storage
+   * @param {string} projectDir - Project directory path
+   * @param {Object} projectState - Project state object
+   * @returns {Promise<void>}
+   */
+  async saveProjectState(projectDir, projectState) {
+    const stateFile = path.join(projectDir, this.stateDirectory, this.stateFiles.projectState);
+    
+    const stateData = {
+      ...projectState,
+      lastModified: new Date().toISOString()
+    };
+    
+    await this.saveJSON(stateFile, stateData);
+  }
+
+  /**
+   * Load agent index
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Agent index object
+   */
+  async loadAgentIndex(projectDir) {
+    const indexFile = path.join(projectDir, this.stateDirectory, this.stateFiles.agentIndex);
+    
+    try {
+      return await this.loadJSON(indexFile);
+    } catch (error) {
+      return {}; // Return empty index if file doesn't exist
+    }
+  }
+
+  /**
+   * Update agent index
+   * @param {Object} agent - Agent object
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<void>}
+   */
+  async updateAgentIndex(agent, projectDir) {
+    const indexFile = path.join(projectDir, this.stateDirectory, this.stateFiles.agentIndex);
+    
+    let agentIndex;
+    try {
+      agentIndex = await this.loadJSON(indexFile);
+    } catch {
+      agentIndex = {};
+    }
+    
+    agentIndex[agent.id] = {
+      name: agent.name,
+      type: agent.type,
+      stateFile: `agents/agent-${agent.id}-state.json`,
+      conversationsFile: `agents/agent-${agent.id}-conversations.json`,
+      lastActivity: agent.lastActivity,
+      model: agent.currentModel,
+      status: agent.status
+    };
+    
+    await this.saveJSON(indexFile, agentIndex);
+  }
+
+  /**
+   * Restore agent from saved state
+   * @param {string} agentId - Agent identifier
+   * @param {Object} agentInfo - Agent info from index
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Restored agent object
+   */
+  async restoreAgent(agentId, agentInfo, projectDir) {
+    const stateDir = path.join(projectDir, this.stateDirectory);
+    const stateFile = path.join(stateDir, agentInfo.stateFile);
+    const conversationsFile = path.join(stateDir, agentInfo.conversationsFile);
+    
+    try {
+      // Load agent state
+      const stateData = await this.loadJSON(stateFile);
+      const conversationsData = await this.loadJSON(conversationsFile);
+      
+      // Validate model conversations integrity
+      await this.validateModelConversations(conversationsData.conversations);
+      
+      // Check if agent is paused
+      const pauseStatus = await this.checkAgentPauseStatus(agentId, projectDir);
+      
+      const restoredAgent = {
+        ...stateData.state,
+        conversations: conversationsData.conversations,
+        isPaused: pauseStatus.isPaused,
+        pausedUntil: pauseStatus.pausedUntil,
+        isRestored: true,
+        restoredAt: new Date().toISOString()
+      };
+      
+      this.logger.info(`Agent restored: ${agentId}`, {
+        name: restoredAgent.name,
+        status: restoredAgent.status,
+        messageCount: restoredAgent.conversations?.full?.messages?.length || 0
+      });
+      
+      return restoredAgent;
+      
+    } catch (error) {
+      this.logger.error(`Agent restoration failed: ${agentId}`, error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Restore async operations
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Array>} Array of active async operations
+   */
+  async restoreAsyncOperations(projectDir) {
+    const operationsFile = path.join(projectDir, this.stateDirectory, this.stateFiles.asyncOperations);
+    
+    try {
+      const data = await this.loadJSON(operationsFile);
+      return data.operations || [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Restore paused agents
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Paused agents data
+   */
+  async restorePausedAgents(projectDir) {
+    const pausedFile = path.join(projectDir, this.stateDirectory, this.stateFiles.pausedAgents);
+    
+    try {
+      const data = await this.loadJSON(pausedFile);
+      const now = Date.now();
+      
+      // Check which agents should be resumed
+      const toResume = [];
+      for (const [agentId, pauseInfo] of Object.entries(data.pausedAgents || {})) {
+        const pausedUntil = new Date(pauseInfo.pausedUntil).getTime();
+        
+        if (now >= pausedUntil) {
+          toResume.push(agentId);
+        }
+      }
+      
+      // Move expired pauses to history
+      for (const agentId of toResume) {
+        const pauseInfo = data.pausedAgents[agentId];
+        delete data.pausedAgents[agentId];
+        
+        data.pauseHistory = data.pauseHistory || [];
+        data.pauseHistory.push({
+          agentId,
+          pausedAt: pauseInfo.pausedAt,
+          resumedAt: new Date().toISOString(),
+          reason: pauseInfo.reason,
+          actualDuration: Math.round((now - new Date(pauseInfo.pausedAt).getTime()) / 1000)
+        });
+      }
+      
+      // Save updated data
+      await this.saveJSON(pausedFile, data);
+      
+      return data;
+      
+    } catch {
+      return {
+        pausedAgents: {},
+        pauseHistory: []
+      };
+    }
+  }
+
+  /**
+   * Restore context references
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Context references data
+   */
+  async restoreContextReferences(projectDir) {
+    const contextFile = path.join(projectDir, this.stateDirectory, this.stateFiles.contextReferences);
+    
+    try {
+      const data = await this.loadJSON(contextFile);
+      
+      // Validate context references (implementation would validate file existence, etc.)
+      const validatedReferences = [];
+      for (const reference of data.references || []) {
+        // Add validation logic here
+        reference.isValid = true; // Placeholder
+        reference.lastValidated = new Date().toISOString();
+        validatedReferences.push(reference);
+      }
+      
+      data.references = validatedReferences;
+      await this.saveJSON(contextFile, data);
+      
+      return data;
+      
+    } catch {
+      return {
+        references: [],
+        lastCleanup: new Date().toISOString()
+      };
+    }
+  }
+
+  /**
+   * Save last session data
+   * @param {string} projectDir - Project directory path
+   * @param {Object} sessionData - Session data to save
+   * @returns {Promise<void>}
+   */
+  async saveLastSession(projectDir, sessionData) {
+    const sessionFile = path.join(projectDir, this.stateDirectory, this.stateFiles.lastSession);
+    
+    const data = {
+      ...sessionData,
+      savedAt: new Date().toISOString(),
+      projectDir
+    };
+    
+    await this.saveJSON(sessionFile, data);
+  }
+
+  /**
+   * Load last session data
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Last session data
+   */
+  async loadLastSession(projectDir) {
+    const sessionFile = path.join(projectDir, this.stateDirectory, this.stateFiles.lastSession);
+    
+    try {
+      return await this.loadJSON(sessionFile);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Save paused agent data
+   * @param {string} projectDir - Project directory path
+   * @param {string} agentId - Agent identifier
+   * @param {Object} pauseData - Pause information
+   * @returns {Promise<void>}
+   */
+  async savePausedAgent(projectDir, agentId, pauseData) {
+    const pausedFile = path.join(projectDir, this.stateDirectory, this.stateFiles.pausedAgents);
+    
+    let data;
+    try {
+      data = await this.loadJSON(pausedFile);
+    } catch {
+      data = { pausedAgents: {}, pauseHistory: [] };
+    }
+    
+    data.pausedAgents[agentId] = pauseData;
+    await this.saveJSON(pausedFile, data);
+  }
+
+  /**
+   * Remove paused agent data
+   * @param {string} projectDir - Project directory path
+   * @param {string} agentId - Agent identifier
+   * @returns {Promise<void>}
+   */
+  async removePausedAgent(projectDir, agentId) {
+    const pausedFile = path.join(projectDir, this.stateDirectory, this.stateFiles.pausedAgents);
+    
+    try {
+      const data = await this.loadJSON(pausedFile);
+      delete data.pausedAgents[agentId];
+      await this.saveJSON(pausedFile, data);
+    } catch {
+      // File doesn't exist, nothing to remove
+    }
+  }
+
+  /**
+   * Check agent pause status
+   * @param {string} agentId - Agent identifier
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Pause status
+   */
+  async checkAgentPauseStatus(agentId, projectDir) {
+    const pausedFile = path.join(projectDir, this.stateDirectory, this.stateFiles.pausedAgents);
+    
+    try {
+      const data = await this.loadJSON(pausedFile);
+      const pauseInfo = data.pausedAgents[agentId];
+      
+      if (!pauseInfo) {
+        return { isPaused: false, pausedUntil: null };
+      }
+      
+      const now = Date.now();
+      const pausedUntil = new Date(pauseInfo.pausedUntil).getTime();
+      
+      return {
+        isPaused: now < pausedUntil,
+        pausedUntil: pauseInfo.pausedUntil,
+        reason: pauseInfo.reason
+      };
+      
+    } catch {
+      return { isPaused: false, pausedUntil: null };
+    }
+  }
+
+  /**
+   * Validate model conversations integrity
+   * @param {Object} conversations - Conversations object
+   * @returns {Promise<void>}
+   */
+  async validateModelConversations(conversations) {
+    if (!conversations || !conversations.full) {
+      throw new Error('Invalid conversations structure - missing full conversation');
+    }
+    
+    const fullMessages = conversations.full.messages || [];
+    const fullLastUpdated = new Date(conversations.full.lastUpdated);
+    
+    // Validate each model conversation against full conversation
+    for (const [modelName, modelConv] of Object.entries(conversations)) {
+      if (modelName === 'full') continue;
+      
+      if (!modelConv.messages) {
+        this.logger.warn(`Model conversation ${modelName} missing messages array`);
+        continue;
+      }
+      
+      const modelLastUpdated = new Date(modelConv.lastUpdated);
+      
+      if (fullLastUpdated > modelLastUpdated) {
+        this.logger.warn(`Model conversation ${modelName} is outdated, will sync on next use`);
+        modelConv.needsSync = true;
+      }
+    }
+  }
+
+  /**
+   * Save JSON data to file
+   * @private
+   */
+  async saveJSON(filePath, data) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    
+    const jsonData = JSON.stringify(data, null, 2);
+    await fs.writeFile(filePath, jsonData, 'utf8');
+  }
+
+  /**
+   * Load JSON data from file
+   * @private
+   */
+  async loadJSON(filePath) {
+    const data = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(data);
+  }
+
+  /**
+   * Delete agent state from storage
+   * @param {string} agentId - Agent identifier
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<void>}
+   */
+  async deleteAgentState(agentId, projectDir = process.cwd()) {
+    const stateDir = path.join(projectDir, this.stateDirectory);
+    const agentStateFile = path.join(stateDir, 'agents', `agent-${agentId}-state.json`);
+    const agentConversationsFile = path.join(stateDir, 'agents', `agent-${agentId}-conversations.json`);
+
+    try {
+      // Delete agent state file
+      try {
+        await fs.unlink(agentStateFile);
+        this.logger.debug(`Deleted agent state file: ${agentId}`);
+      } catch (error) {
+        if (error.code !== 'ENOENT') {
+          this.logger.warn(`Failed to delete agent state file: ${error.message}`, { agentId });
+        }
+      }
+
+      // Delete agent conversations file
+      try {
+        await fs.unlink(agentConversationsFile);
+        this.logger.debug(`Deleted agent conversations file: ${agentId}`);
+      } catch (error) {
+        if (error.code !== 'ENOENT') {
+          this.logger.warn(`Failed to delete agent conversations file: ${error.message}`, { agentId });
+        }
+      }
+
+      // Remove from agent index
+      await this.removeFromAgentIndex(agentId, projectDir);
+
+      this.logger.info(`Agent state deleted: ${agentId}`);
+
+    } catch (error) {
+      this.logger.error(`Failed to delete agent state: ${error.message}`, {
+        agentId,
+        error: error.stack
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Remove agent from agent index
+   * @param {string} agentId - Agent identifier
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<void>}
+   */
+  async removeFromAgentIndex(agentId, projectDir) {
+    const indexFile = path.join(projectDir, this.stateDirectory, this.stateFiles.agentIndex);
+
+    try {
+      const agentIndex = await this.loadJSON(indexFile);
+      delete agentIndex[agentId];
+      await this.saveJSON(indexFile, agentIndex);
+      this.logger.debug(`Removed agent from index: ${agentId}`);
+    } catch (error) {
+      // If index doesn't exist or can't be updated, log but don't throw
+      this.logger.warn(`Failed to remove agent from index: ${error.message}`, { agentId });
+    }
+  }
+
+  /**
+   * Check if state directory exists
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<boolean>} True if state directory exists
+   */
+  async stateDirectoryExists(projectDir) {
+    const stateDir = path.join(projectDir, this.stateDirectory);
+
+    try {
+      const stats = await fs.stat(stateDir);
+      return stats.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Clean up old state files
+   * @param {string} projectDir - Project directory path
+   * @param {number} maxAge - Maximum age in days
+   * @returns {Promise<void>}
+   */
+  async cleanupOldState(projectDir, maxAge = 30) {
+    const stateDir = path.join(projectDir, this.stateDirectory);
+    const cutoffDate = Date.now() - (maxAge * 24 * 60 * 60 * 1000);
+
+    try {
+      const agentsDir = path.join(stateDir, 'agents');
+      const files = await fs.readdir(agentsDir);
+
+      for (const file of files) {
+        const filePath = path.join(agentsDir, file);
+        const stats = await fs.stat(filePath);
+
+        if (stats.mtime.getTime() < cutoffDate) {
+          await fs.unlink(filePath);
+          this.logger.info(`Cleaned up old state file: ${file}`);
+        }
+      }
+
+    } catch (error) {
+      this.logger.warn(`State cleanup failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get all available agents (active + archived) from filesystem
+   * @param {string} projectDir - Project directory path
+   * @param {Object} agentPool - Agent pool instance to check active agents
+   * @returns {Promise<Array>} List of all agents with metadata
+   */
+  async getAllAvailableAgents(projectDir, agentPool) {
+    try {
+      const agentIndex = await this.loadAgentIndex(projectDir);
+      const activeAgentIds = agentPool ? (await agentPool.getAllAgents()).map(a => a.id) : [];
+
+      const agents = [];
+      for (const [agentId, info] of Object.entries(agentIndex)) {
+        // Skip invalid or undefined entries
+        if (!info || !info.name) {
+          continue;
+        }
+
+        agents.push({
+          agentId,
+          name: info.name,
+          type: info.type,
+          model: info.model,
+          lastActivity: info.lastActivity,
+          status: info.status,
+          stateFile: info.stateFile,
+          conversationsFile: info.conversationsFile,
+          isLoaded: activeAgentIds.includes(agentId),
+          canImport: !activeAgentIds.includes(agentId)
+        });
+      }
+
+      // Sort by last activity (most recent first)
+      agents.sort((a, b) => {
+        const dateA = a.lastActivity ? new Date(a.lastActivity) : new Date(0);
+        const dateB = b.lastActivity ? new Date(b.lastActivity) : new Date(0);
+        return dateB - dateA;
+      });
+
+      this.logger.info(`Found ${agents.length} available agents (${agents.filter(a => a.isLoaded).length} active, ${agents.filter(a => !a.isLoaded).length} archived)`);
+
+      return agents;
+    } catch (error) {
+      this.logger.error(`Failed to get available agents: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Get agent metadata without full restoration (lightweight preview)
+   * @param {string} agentId - Agent ID
+   * @param {string} projectDir - Project directory path
+   * @returns {Promise<Object>} Agent metadata for preview
+   */
+  async getAgentMetadata(agentId, projectDir) {
+    try {
+      // Load agent index
+      const agentIndex = await this.loadAgentIndex(projectDir);
+      const agentInfo = agentIndex[agentId];
+
+      if (!agentInfo) {
+        throw new Error(`Agent ${agentId} not found in index`);
+      }
+
+      // Load just the state file (lightweight)
+      const stateDir = path.join(projectDir, this.stateDirectory);
+      const stateFile = path.join(stateDir, agentInfo.stateFile);
+      const conversationsFile = path.join(stateDir, agentInfo.conversationsFile);
+
+      // Check if files exist
+      const stateExists = await fs.access(stateFile).then(() => true).catch(() => false);
+      const conversationsExist = await fs.access(conversationsFile).then(() => true).catch(() => false);
+
+      if (!stateExists) {
+        throw new Error(`State file not found for agent ${agentId}`);
+      }
+
+      // Load state
+      const stateData = await this.loadJSON(stateFile);
+      const state = stateData.state || {};
+
+      // Load conversation count without loading full messages (for performance)
+      let messageCount = 0;
+      let lastMessage = null;
+      if (conversationsExist) {
+        try {
+          const conversations = await this.loadJSON(conversationsFile);
+          messageCount = Array.isArray(conversations) ? conversations.length : 0;
+
+          // Get last message for preview
+          if (messageCount > 0) {
+            const lastMsg = conversations[conversations.length - 1];
+            lastMessage = lastMsg?.content?.substring(0, 100) || null;
+          }
+        } catch (error) {
+          this.logger.warn(`Failed to load conversations for ${agentId}: ${error.message}`);
+        }
+      }
+
+      const metadata = {
+        agentId,
+        name: agentInfo.name || state.name,
+        model: agentInfo.model || state.preferredModel || state.currentModel,
+        lastActivity: agentInfo.lastActivity,
+        status: agentInfo.status,
+        capabilities: state.capabilities || [],
+        messageCount,
+        lastMessage,
+        taskCount: state.taskList?.tasks?.length || 0,
+        createdAt: state.createdAt,
+        workingDirectory: state.directoryAccess?.workingDirectory,
+        mode: state.mode,
+        systemPrompt: state.originalSystemPrompt
+      };
+
+      this.logger.info(`Loaded metadata for agent ${agentId}: ${metadata.messageCount} messages, ${metadata.taskCount} tasks`);
+
+      return metadata;
+    } catch (error) {
+      this.logger.error(`Failed to get agent metadata for ${agentId}: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Import archived agent from filesystem and add to agent pool
+   * @param {string} agentId - Agent ID to import
+   * @param {string} projectDir - Project directory path
+   * @param {Object} agentPool - Agent pool instance
+   * @returns {Promise<Object>} Imported agent object
+   */
+  async importArchivedAgent(agentId, projectDir, agentPool) {
+    try {
+      // Validate agent ID format for security
+      const AGENT_ID_REGEX = /^agent-[a-z0-9-]+-\d+$/;
+      if (!AGENT_ID_REGEX.test(agentId)) {
+        throw new Error('Invalid agent ID format');
+      }
+
+      // Check if already loaded in agent pool
+      if (agentPool && await agentPool.getAgent(agentId)) {
+        throw new Error(`Agent ${agentId} is already loaded. Use switchAgent() instead.`);
+      }
+
+      // Load from agent index
+      const agentIndex = await this.loadAgentIndex(projectDir);
+      const agentInfo = agentIndex[agentId];
+
+      if (!agentInfo) {
+        throw new Error(`Agent ${agentId} not found in index`);
+      }
+
+      this.logger.info(`Importing archived agent: ${agentId} (${agentInfo.name})`);
+
+      // Restore agent using existing restore logic
+      const agent = await this.restoreAgent(agentId, agentInfo, projectDir);
+
+      // Update agent's last activity
+      agent.lastActivity = new Date().toISOString();
+
+      // Add to agent pool if provided
+      if (agentPool) {
+        agentPool.agents.set(agent.id, agent);
+        agentPool._updateAgentDirectory(agent);
+        this.logger.info(`Agent ${agentId} added to agent pool`);
+      }
+
+      // Update agent index with new last activity
+      await this.updateAgentIndex(agent, projectDir);
+
+      this.logger.info(`Successfully imported agent ${agentId}: ${agent.name}`);
+
+      return agent;
+    } catch (error) {
+      this.logger.error(`Failed to import agent ${agentId}: ${error.message}`);
+      throw error;
+    }
+  }
+}
+
+export default StateManager;