Refactor: Merge SessionManager into SessionTracker

[bhouston]

Refactoring Plan: Merge SessionManager into SessionTracker

Current Structure Analysis

We currently have two classes handling browser session management with overlapping responsibilities:

SessionTracker

• Located in: packages/agent/src/tools/session/SessionTracker.ts
• Primary responsibility: Tracking browser session metadata and status
• Maintains a registry of browser sessions with their status (running, completed, error, terminated)
• Does not directly handle browser instances but calls SessionManager for cleanup
• Used by the browser tools (sessionStart, sessionMessage, listSessions)

SessionManager

• Located in: packages/agent/src/tools/session/lib/SessionManager.ts
• Primary responsibility: Creating and managing browser sessions
• Handles the actual browser instances and pages
• Manages browser cleanup and shutdown
• Is stored globally via __BROWSER_MANAGER__
• Used by SessionTracker for cleanup operations

Problem Statement

Having two separate classes for session management creates unnecessary complexity:

1. Duplicated session tracking (both classes maintain their own maps of sessions)
2. Shared responsibilities across different files
3. Indirect communication between components
4. Global state management via __BROWSER_MANAGER__ and browserSessions

Refactoring Goals

1. Merge SessionManager functionality into SessionTracker
2. Eliminate global state in favor of a singleton pattern
3. Simplify the API for browser session management
4. Maintain backward compatibility with existing tools
5. Improve error handling and cleanup processes

Implementation Plan

Step 1: Enhance SessionTracker with SessionManager Capabilities

1. Update SessionInfo interface to include browser and page objects:

   export interface SessionInfo {
     id: string;
     status: SessionStatus;
     startTime: Date;
     endTime?: Date;
     browser?: Browser;
     page?: Page;
     metadata: {
       url?: string;
       contentLength?: number;
       closedExplicitly?: boolean;
       error?: string;
       actionType?: string;
     };
   }

2. Add browser creation and management methods to SessionTracker:

   • createSession(config?: BrowserConfig): Promise<SessionInfo>
   • closeSession(sessionId: string): Promise<void>
   • closeAllSessions(): Promise<void>

3. Implement browser setup and cleanup handlers in SessionTracker

Step 2: Implement Singleton Pattern for SessionTracker

1. Convert SessionTracker to use a singleton pattern similar to BrowserAutomation
2. Provide a static getInstance() method
3. Maintain backward compatibility with constructor-based instantiation

Step 3: Update Tool Implementation

1. Update sessionStart.ts to use SessionTracker directly instead of browserSessions
2. Update sessionMessage.ts to use SessionTracker for all browser operations
3. Update listSessions.ts to use the enhanced SessionTracker capabilities

Step 4: Cleanup and Deprecation

1. Mark SessionManager as deprecated
2. Remove global __BROWSER_MANAGER__ reference
3. Remove or deprecate the global browserSessions map
4. Update documentation to reflect the new architecture

Migration Strategy

1. Implement the enhanced SessionTracker without removing existing code
2. Update tools to use the new API while maintaining compatibility with old code
3. Add deprecation warnings for old methods and classes
4. After confirming functionality, remove deprecated code in a future release

Testing Strategy

1. Unit tests for the enhanced SessionTracker
2. Integration tests for browser session creation and management
3. End-to-end tests for the browser tools
4. Stress tests for cleanup and error handling

Timeline

• Implementation: 1-2 days
• Testing: 1 day
• Code review: 1 day
• Documentation: 0.5 day

Related Components

• BrowserAutomation.ts - Will need to be updated to use the enhanced SessionTracker
• PageController.ts - May need adjustments based on the new structure

[bhouston]

done