05-session-management

05-Session-Management

Session Management Architecture

Session management is handled by session-manager.ts and state tracking by state-tracker.ts.

Core Responsibilities

• SessionManager: Client lifecycle, status tracking, metrics collection
• StateTracker: File system monitoring, performance metrics, project detection

CRITICAL SESSION RULES - MUST FOLLOW

✅ ALWAYS DO:

1. Use SessionManager for all client operations: Never directly manipulate client objects
2. Emit events for state changes: All client status changes must emit events
3. Update activity timestamps: Every client interaction must update lastActivity
4. Validate client existence: Always check if client exists before operations
5. Implement cleanup: Regular cleanup of inactive clients and resources

❌ NEVER DO:

1. Direct client manipulation: Never modify client objects outside SessionManager
2. Skip event emission: Never change client state without emitting events
3. Ignore session isolation: Client data must be isolated by clientId
4. Forget resource cleanup: Always clean up watchers and intervals on client disconnect
5. Bypass session validation: Never assume a session exists without checking

Client Registration Patterns

✅ PROPER Client Registration:

// Complete client registration with all required fields
export class SessionManager extends EventEmitter {
  public registerClient(client: AgentClient): void {
    // Validate required fields
    if (!client.id || !client.type || !client.name) {
      throw new Error('Invalid client: missing required fields');
    }

    // Set connection info
    client.connectionInfo = {
      ...client.connectionInfo,
      connectedAt: new Date(),
      lastActivity: new Date(),
    };

    // Initialize metrics if not provided
    client.metrics = {
      requestCount: 0,
      errorCount: 0,
      uptime: 0,
      ...client.metrics,
    };

    this.clients.set(client.id, client);
    this.emit('clientConnected', client);
    this.logger.info(`Client registered: ${client.id} (${client.type})`);

    // Start tracking for this client
    this.stateTracker?.startTracking(client.id);
  }
}