feat(agent): Decouple Browser Session Tracking from backgroundTools

packages/agent/src/core/backgroundTools.cleanup.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 
 // Import mocked modules
-import { BrowserManager } from '../tools/browser/BrowserManager.js';
 import { agentStates } from '../tools/interaction/agentStart.js';
 import { processStates } from '../tools/system/shellStart.js';
 
@@ -35,14 +34,6 @@
 };
 
 // Mock dependencies
-vi.mock('../tools/browser/BrowserManager.js', () => {
-  return {
-    BrowserManager: class MockBrowserManager {
-      closeSession = vi.fn().mockResolvedValue(undefined);
-    },
-  };
-});
-
 vi.mock('../tools/system/shellStart.js', () => {
   return {
     processStates: new Map<string, MockProcessState>(),
@@ -58,20 +49,13 @@
 describe('BackgroundTools cleanup', () => {
   let backgroundTools: BackgroundTools;
 
-  // Setup mocks for globalThis and process states
+  // Setup mocks for process states
   beforeEach(() => {
     backgroundTools = new BackgroundTools('test-agent');
 
     // Reset mocks
     vi.resetAllMocks();
 
-    // Setup global browser manager
-    (
-      globalThis as unknown as { __BROWSER_MANAGER__: BrowserManager }
-    ).__BROWSER_MANAGER__ = {
-      closeSession: vi.fn().mockResolvedValue(undefined),
-    } as unknown as BrowserManager;
-
     // Setup mock process states
     const mockProcess = {
       kill: vi.fn(),
@@ -88,7 +72,7 @@
     };
 
     processStates.clear();
     processStates.set('shell-1', mockProcessState as any);
 
     // Setup mock agent states
     const mockAgentState: MockAgentState = {
@@ -107,40 +91,17 @@
     };
 
     agentStates.clear();
     agentStates.set('agent-1', mockAgentState as any);
   });
 
   afterEach(() => {
     vi.resetAllMocks();
 
-    // Clear global browser manager
-    (
-      globalThis as unknown as { __BROWSER_MANAGER__?: BrowserManager }
-    ).__BROWSER_MANAGER__ = undefined;
-
     // Clear mock states
     processStates.clear();
     agentStates.clear();
   });
 
-  it('should clean up browser sessions', async () => {
-    // Register a browser tool
-    const browserId = backgroundTools.registerBrowser('https://example.com');
-
-    // Run cleanup
-    await backgroundTools.cleanup();
-
-    // Check that closeSession was called
-    expect(
-      (globalThis as unknown as { __BROWSER_MANAGER__: BrowserManager })
-        .__BROWSER_MANAGER__.closeSession,
-    ).toHaveBeenCalledWith(browserId);
-
-    // Check that tool status was updated
-    const tool = backgroundTools.getToolById(browserId);
-    expect(tool?.status).toBe(BackgroundToolStatus.COMPLETED);
-  });
-
   it('should clean up shell processes', async () => {
     // Register a shell tool
     const shellId = backgroundTools.registerShell('echo "test"');
@@ -149,7 +110,7 @@
     const mockProcessState = processStates.get('shell-1');
 
     // Set the shell ID to match
     processStates.set(shellId, processStates.get('shell-1') as any);
 
     // Run cleanup
     await backgroundTools.cleanup();
@@ -170,7 +131,7 @@
     const mockAgentState = agentStates.get('agent-1');
 
     // Set the agent ID to match
     agentStates.set(agentId, agentStates.get('agent-1') as any);
 
     // Run cleanup
     await backgroundTools.cleanup();
@@ -186,38 +147,4 @@
     const tool = backgroundTools.getToolById(agentId);
     expect(tool?.status).toBe(BackgroundToolStatus.TERMINATED);
   });
-
-  it('should handle errors during cleanup', async () => {
-    // Register a browser tool
-    const browserId = backgroundTools.registerBrowser('https://example.com');
-
-    // Make closeSession throw an error
-    (
-      (globalThis as unknown as { __BROWSER_MANAGER__: BrowserManager })
-        .__BROWSER_MANAGER__.closeSession as ReturnType<typeof vi.fn>
-    ).mockRejectedValue(new Error('Test error'));
-
-    // Run cleanup
-    await backgroundTools.cleanup();
-
-    // Check that tool status was updated to ERROR
-    const tool = backgroundTools.getToolById(browserId);
-    expect(tool?.status).toBe(BackgroundToolStatus.ERROR);
-    expect(tool?.metadata.error).toBe('Test error');
-  });
-
-  it('should only clean up running tools', async () => {
-    // Register a browser tool and mark it as completed
-    const browserId = backgroundTools.registerBrowser('https://example.com');
-    backgroundTools.updateToolStatus(browserId, BackgroundToolStatus.COMPLETED);
-
-    // Run cleanup
-    await backgroundTools.cleanup();
-
-    // Check that closeSession was not called
-    expect(
-      (globalThis as unknown as { __BROWSER_MANAGER__: BrowserManager })
-        .__BROWSER_MANAGER__.closeSession,
-    ).not.toHaveBeenCalled();
-  });
 });

packages/agent/src/core/backgroundTools.test.ts

@@ -35,21 +35,7 @@
     }
   });
 
-  it('should register a browser process', () => {
-    const id = backgroundTools.registerBrowser('https://example.com');
-
-    expect(id).toBe('test-id-1');
-
-    const tool = backgroundTools.getToolById(id);
-    expect(tool).toBeDefined();
-    if (tool) {
-      expect(tool.type).toBe(BackgroundToolType.BROWSER);
-      expect(tool.status).toBe(BackgroundToolStatus.RUNNING);
-      if (tool.type === BackgroundToolType.BROWSER) {
-        expect(tool.metadata.url).toBe('https://example.com');
-      }
-    }
-  });
+  // Browser registration test removed since browser tracking is now decoupled
 
   it('should update tool status', () => {
     const id = backgroundTools.registerShell('sleep 10');
@@ -86,7 +72,7 @@
 
   it('should clean up old completed tools', () => {
     // Create tools with specific dates
     const registry = backgroundTools as any;
 
     // Add a completed tool from 25 hours ago
     const oldTool = {

packages/agent/src/core/backgroundTools.ts

@@ -1,14 +1,12 @@
 import { v4 as uuidv4 } from 'uuid';
 
 // These imports will be used by the cleanup method
-import { BrowserManager } from '../tools/browser/BrowserManager.js';
 import { agentStates } from '../tools/interaction/agentStart.js';
 import { processStates } from '../tools/system/shellStart.js';
 
 // Types of background processes we can track
 export enum BackgroundToolType {
   SHELL = 'shell',
-  BROWSER = 'browser',
   AGENT = 'agent',
 }
 
@@ -27,7 +25,7 @@
   status: BackgroundToolStatus;
   startTime: Date;
   endTime?: Date;
   metadata: Record<string, any>; // Additional tool-specific information
 }
 
 // Shell process specific data
@@ -41,15 +39,6 @@
   };
 }
 
-// Browser process specific data
-export interface BrowserBackgroundTool extends BackgroundTool {
-  type: BackgroundToolType.BROWSER;
-  metadata: {
-    url?: string;
-    error?: string;
-  };
-}
-
 // Agent process specific data (for future use)
 export interface AgentBackgroundTool extends BackgroundTool {
   type: BackgroundToolType.AGENT;
@@ -60,10 +49,7 @@
 }
 
 // Utility type for all background tool types
-export type AnyBackgroundTool =
-  | ShellBackgroundTool
-  | BrowserBackgroundTool
-  | AgentBackgroundTool;
+export type AnyBackgroundTool = ShellBackgroundTool | AgentBackgroundTool;
 
 /**
  * Registry to keep track of all background processes
@@ -90,22 +76,6 @@
     return id;
   }
 
-  // Register a new browser process
-  public registerBrowser(url?: string): string {
-    const id = uuidv4();
-    const tool: BrowserBackgroundTool = {
-      id,
-      type: BackgroundToolType.BROWSER,
-      status: BackgroundToolStatus.RUNNING,
-      startTime: new Date(),
-      metadata: {
-        url,
-      },
-    };
-    this.tools.set(id, tool);
-    return id;
-  }
-
   // Register a new agent process (for future use)
   public registerAgent(goal?: string): string {
     const id = uuidv4();
@@ -126,7 +96,7 @@
   public updateToolStatus(
     id: string,
     status: BackgroundToolStatus,
     metadata?: Record<string, any>,
   ): boolean {
     const tool = this.tools.get(id);
     if (!tool) {
@@ -171,12 +141,6 @@
     const tools = this.getTools();
 
     // Group tools by type for better cleanup organization
-    const browserTools = tools.filter(
-      (tool): tool is BrowserBackgroundTool =>
-        tool.type === BackgroundToolType.BROWSER &&
-        tool.status === BackgroundToolStatus.RUNNING,
-    );
-
     const shellTools = tools.filter(
       (tool): tool is ShellBackgroundTool =>
         tool.type === BackgroundToolType.SHELL &&
@@ -190,9 +154,6 @@
     );
 
     // Create cleanup promises for each resource type
-    const browserCleanupPromises = browserTools.map((tool) =>
-      this.cleanupBrowserSession(tool),
-    );
     const shellCleanupPromises = shellTools.map((tool) =>
       this.cleanupShellProcess(tool),
     );
@@ -201,33 +162,7 @@
     );
 
     // Wait for all cleanup operations to complete in parallel
-    await Promise.all([
-      ...browserCleanupPromises,
-      ...shellCleanupPromises,
-      ...agentCleanupPromises,
-    ]);
-  }
-
-  /**
-   * Cleans up a browser session
-   * @param tool The browser tool to clean up
-   */
-  private async cleanupBrowserSession(
-    tool: BrowserBackgroundTool,
-  ): Promise<void> {
-    try {
-      const browserManager = (
-        globalThis as unknown as { __BROWSER_MANAGER__?: BrowserManager }
-      ).__BROWSER_MANAGER__;
-      if (browserManager) {
-        await browserManager.closeSession(tool.id);
-      }
-      this.updateToolStatus(tool.id, BackgroundToolStatus.COMPLETED);
-    } catch (error) {
-      this.updateToolStatus(tool.id, BackgroundToolStatus.ERROR, {
-        error: error instanceof Error ? error.message : String(error),
-      });
-    }
+    await Promise.all([...shellCleanupPromises, ...agentCleanupPromises]);
   }
 
   /**

packages/agent/src/core/types.ts

@@ -23,6 +23,7 @@ export type ToolContext = {
   tokenCache?: boolean;
   userPrompt?: boolean;
   agentId?: string; // Unique identifier for the agent, used for background tool tracking
+  agentName?: string; // Name of the agent, used for browser tracker
   provider: ModelProvider;
   model?: string;
   baseUrl?: string;

packages/agent/src/index.ts

@@ -18,6 +18,8 @@ export * from './tools/browser/browseMessage.js';
 export * from './tools/browser/browseStart.js';
 export * from './tools/browser/PageController.js';
 export * from './tools/browser/BrowserAutomation.js';
+export * from './tools/browser/listBrowsers.js';
+export * from './tools/browser/browserTracker.js';
 
 // Tools - Interaction
 export * from './tools/interaction/subAgent.js';

packages/agent/src/tools/browser/browseMessage.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 
-import { BackgroundToolStatus } from '../../core/backgroundTools.js';
 import { Tool } from '../../core/types.js';
 import { errorToString } from '../../utils/errorToString.js';
 import { sleep } from '../../utils/sleep.js';
 
+import { BrowserSessionStatus, getBrowserTracker } from './browserTracker.js';
 import { filterPageContent } from './filterPageContent.js';
 import { browserSessions, SelectorType } from './types.js';
 
@@ -72,7 +72,7 @@ export const browseMessageTool: Tool<Parameters, ReturnType> = {
 
   execute: async (
     { instanceId, actionType, url, selector, selectorType, text },
-    { logger, pageFilter, backgroundTools },
+    { logger, pageFilter, agentName = 'default' },
   ): Promise<ReturnType> => {
     // Validate action format
 
@@ -87,6 +87,9 @@ export const browseMessageTool: Tool<Parameters, ReturnType> = {
     logger.verbose(`Executing browser action: ${actionType}`);
     logger.verbose(`Webpage processing mode: ${pageFilter}`);
 
+    // Get the browser tracker instance
+    const browserTracker = getBrowserTracker(agentName);
+
     try {
       const session = browserSessions.get(instanceId);
       if (!session) {
@@ -186,10 +189,10 @@ export const browseMessageTool: Tool<Parameters, ReturnType> = {
           await session.browser.close();
           browserSessions.delete(instanceId);
 
-          // Update background tool registry when browser is explicitly closed
-          backgroundTools.updateToolStatus(
+          // Update browser tracker when browser is explicitly closed
+          browserTracker.updateSessionStatus(
             instanceId,
-            BackgroundToolStatus.COMPLETED,
+            BrowserSessionStatus.COMPLETED,
             {
               closedExplicitly: true,
             },
@@ -206,11 +209,15 @@ export const browseMessageTool: Tool<Parameters, ReturnType> = {
     } catch (error) {
       logger.error('Browser action failed:', { error });
 
-      // Update background tool registry with error status if action fails
-      backgroundTools.updateToolStatus(instanceId, BackgroundToolStatus.ERROR, {
-        error: errorToString(error),
-        actionType,
-      });
+      // Update browser tracker with error status if action fails
+      browserTracker.updateSessionStatus(
+        instanceId,
+        BrowserSessionStatus.ERROR,
+        {
+          error: errorToString(error),
+          actionType,
+        },
+      );
 
       return {
         status: 'error',