feat: Phase 3 — profile-aware browser, Browser Use provider, profile tools

Wire profile system into browser.ts with ensureBrowserForProfile() supporting
multi-browser instances (managed launch + existing-session attach). Add Browser
Use cloud provider. Add list_profiles MCP tool showing profiles, sessions, and
provider status.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Hein van Vuuren

src/browser.ts

@@ -17,6 +17,7 @@ import type {
 } from './third_party/index.js';
 import {puppeteer} from './third_party/index.js';
 import {applyGhostMode, type GhostModeConfig} from './ghost-mode.js';
+import type {ResolvedProfile} from './config/profiles.js';
 
 let browser: Browser | undefined;
 
@@ -251,3 +252,113 @@ export async function ensureBrowserLaunched(
 }
 
 export type Channel = 'stable' | 'canary' | 'beta' | 'dev';
+
+// --- Profile-based browser management ---
+
+const profileBrowsers = new Map<string, Browser>();
+
+/**
+ * Launch or connect a browser for a ResolvedProfile.
+ *
+ * - 'managed' profiles launch a new Chrome via `launch()`.
+ * - 'existing-session' profiles connect to a running Chrome via `ensureBrowserConnected()`.
+ *
+ * Returns the Browser instance and caches it by profile name.
+ * If a connected browser already exists for the profile, returns it immediately.
+ */
+export async function ensureBrowserForProfile(
+  profile: ResolvedProfile,
+  ghostMode?: Partial<GhostModeConfig>,
+): Promise<Browser> {
+  const existing = profileBrowsers.get(profile.name);
+  if (existing?.connected) {
+    return existing;
+  }
+
+  let instance: Browser;
+
+  if (profile.driver === 'managed') {
+    const userDataDir =
+      profile.userDataDir ??
+      path.join(
+        os.homedir(),
+        '.boss-ghost',
+        'profiles',
+        profile.name,
+        'chrome-data',
+      );
+
+    const args: string[] = [...profile.extraArgs];
+    if (profile.cdpPort) {
+      args.push(`--remote-debugging-port=${profile.cdpPort}`);
+    }
+
+    instance = await launch({
+      headless: profile.headless,
+      channel: profile.channel,
+      executablePath: profile.executablePath,
+      userDataDir,
+      args,
+      isolated: false,
+      devtools: false,
+      ghostMode,
+    });
+  } else {
+    // existing-session: connect to a running browser
+    if (profile.cdpUrl) {
+      instance = await ensureBrowserConnected({
+        wsEndpoint: profile.cdpUrl,
+        devtools: false,
+      });
+    } else {
+      instance = await ensureBrowserConnected({
+        browserURL: `http://127.0.0.1:${profile.cdpPort}`,
+        devtools: false,
+      });
+    }
+
+    // Apply ghost mode to connected browsers manually since launch() won't do it
+    if (ghostMode) {
+      await applyGhostMode(instance, ghostMode);
+      logger('Ghost Mode applied to connected profile "%s"', profile.name);
+    }
+  }
+
+  profileBrowsers.set(profile.name, instance);
+  logger('Browser ready for profile "%s" (driver=%s)', profile.name, profile.driver);
+  return instance;
+}
+
+/**
+ * Retrieve a cached browser instance by profile name.
+ * Returns undefined if no browser exists or it has disconnected.
+ */
+export function getBrowserForProfile(name: string): Browser | undefined {
+  const instance = profileBrowsers.get(name);
+  if (instance && !instance.connected) {
+    profileBrowsers.delete(name);
+    return undefined;
+  }
+  return instance;
+}
+
+/**
+ * Close/disconnect a profile's browser and remove it from the cache.
+ */
+export async function closeBrowserForProfile(name: string): Promise<void> {
+  const instance = profileBrowsers.get(name);
+  if (!instance) {
+    return;
+  }
+
+  profileBrowsers.delete(name);
+
+  if (instance.connected) {
+    try {
+      await instance.close();
+      logger('Closed browser for profile "%s"', name);
+    } catch (err) {
+      logger('Error closing browser for profile "%s": %s', name, err);
+    }
+  }
+}

src/providers/browser-use.ts

@@ -0,0 +1,91 @@
+/**
+ * Boss Ghost MCP — Browser Use cloud browser provider.
+ *
+ * Creates and manages browser sessions via the Browser Use API.
+ * Ported from Hermes's browser_providers/browser_use.py.
+ */
+
+import type {CloudBrowserProvider, ProviderSession} from './base.js';
+import {logger} from '../logger.js';
+
+const BROWSER_USE_API = 'https://api.browser-use.com/api/v2';
+
+interface BrowserUseConfig {
+  apiKey?: string;
+}
+
+export class BrowserUseProvider implements CloudBrowserProvider {
+  readonly providerName = 'browser-use';
+  private apiKey: string;
+
+  constructor(config?: BrowserUseConfig) {
+    this.apiKey = config?.apiKey ?? process.env['BROWSER_USE_API_KEY'] ?? '';
+  }
+
+  isConfigured(): boolean {
+    return this.apiKey.length > 0;
+  }
+
+  async createSession(taskId?: string): Promise<ProviderSession> {
+    if (!this.isConfigured()) {
+      throw new Error(
+        'Browser Use not configured — set BROWSER_USE_API_KEY, ' +
+          'or configure it in ~/.boss-ghost/config.json under providers.browser-use',
+      );
+    }
+
+    const response = await fetch(`${BROWSER_USE_API}/browsers`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify({}),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      throw new Error(`Browser Use API error ${response.status}: ${text}`);
+    }
+
+    const data = (await response.json()) as {id: string; cdpUrl: string};
+    const sessionName = taskId ? `boss-ghost-${taskId}` : `boss-ghost-${Date.now()}`;
+
+    logger('Browser Use session created: %s (id=%s)', sessionName, data.id);
+
+    return {
+      sessionId: data.id,
+      sessionName,
+      cdpUrl: data.cdpUrl,
+      features: {browserUse: true},
+    };
+  }
+
+  async closeSession(sessionId: string): Promise<boolean> {
+    const response = await fetch(`${BROWSER_USE_API}/browsers/${sessionId}`, {
+      method: 'PATCH',
+      headers: this.headers(),
+      body: JSON.stringify({action: 'stop'}),
+    });
+
+    if (!response.ok) {
+      logger('Browser Use closeSession failed: %s %s', response.status, response.statusText);
+      return false;
+    }
+
+    logger('Browser Use session %s stopped', sessionId);
+    return true;
+  }
+
+  async emergencyCleanup(sessionId: string): Promise<void> {
+    try {
+      await this.closeSession(sessionId);
+    } catch {
+      // Best-effort — swallow all errors in exit handlers
+    }
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      'X-Browser-Use-API-Key': this.apiKey,
+    };
+  }
+}

src/providers/registry.ts

@@ -8,6 +8,7 @@
 
 import type {CloudBrowserProvider} from './base.js';
 import {BrowserbaseProvider} from './browserbase.js';
+import {BrowserUseProvider} from './browser-use.js';
 import {logger} from '../logger.js';
 import {getConfig} from '../config/config.js';
 
@@ -16,6 +17,7 @@ type ProviderConstructor = new (config?: Record<string, unknown>) => CloudBrowse
 /** Registry of known provider constructors, keyed by name. */
 const PROVIDER_REGISTRY = new Map<string, ProviderConstructor>([
   ['browserbase', BrowserbaseProvider as unknown as ProviderConstructor],
+  ['browser-use', BrowserUseProvider as unknown as ProviderConstructor],
 ]);
 
 /** Cached provider instance (resolved once per process). */
@@ -81,6 +83,14 @@ export function getCloudProvider(): CloudBrowserProvider | null {
     return browserbase;
   }
 
+  // Auto-detect: try Browser Use env vars
+  const browserUse = new BrowserUseProvider();
+  if (browserUse.isConfigured()) {
+    logger('Cloud provider: browser-use (auto-detected from env vars)');
+    cachedProvider = browserUse;
+    return browserUse;
+  }
+
   logger('Cloud provider: local mode (no provider configured)');
   cachedProvider = null;
   return null;

src/tools/profiles.ts

@@ -0,0 +1,53 @@
+/**
+ * Profile management MCP tools.
+ */
+
+import {defineTool} from './ToolDefinition.js';
+import {ToolCategory} from './categories.js';
+import {listProfiles} from '../config/profiles.js';
+import {listSessions} from '../config/session-registry.js';
+import {listSessionActivity} from '../utils/inactivity.js';
+import {listProviders} from '../providers/registry.js';
+
+export const listProfilesTool = defineTool({
+  name: 'list_profiles',
+  description:
+    'List all configured browser profiles with their settings, active sessions, and cloud providers.',
+  annotations: {
+    category: ToolCategory.NAVIGATION,
+    readOnlyHint: true,
+  },
+  schema: {},
+  handler: async (_request, response) => {
+    const profiles = listProfiles();
+    const sessions = listSessions();
+    const activity = listSessionActivity();
+    const providers = listProviders();
+
+    response.appendResponseLine('## Browser Profiles');
+    for (const p of profiles) {
+      response.appendResponseLine(
+        `- **${p.name}** [${p.driver}] port:${p.cdpPort} headless:${p.headless} channel:${p.channel}${p.cdpUrl ? ` cdp:${p.cdpUrl}` : ''}${p.attachOnly ? ' (attach-only)' : ''}`,
+      );
+    }
+
+    if (sessions.length > 0) {
+      response.appendResponseLine('\n## Active Sessions');
+      for (const s of sessions) {
+        const idle = activity.find(a => a.sessionKey === s.sessionKey);
+        response.appendResponseLine(
+          `- ${s.sessionKey}: ${s.tabCount} tab(s)${idle ? ` (idle ${Math.round(idle.idleMs / 1000)}s)` : ''}`,
+        );
+      }
+    }
+
+    if (providers.length > 0) {
+      response.appendResponseLine('\n## Cloud Providers');
+      for (const p of providers) {
+        response.appendResponseLine(
+          `- ${p.name}: ${p.configured ? '✓ configured' : '✗ not configured'}`,
+        );
+      }
+    }
+  },
+});

src/tools/tools.ts

@@ -10,6 +10,7 @@ import * as inputTools from './input.js';
 import * as networkTools from './network.js';
 import * as pagesTools from './pages.js';
 import * as pdfTools from './pdf.js';
+import * as profileTools from './profiles.js';
 import * as performanceTools from './performance.js';
 import * as screenshotTools from './screenshot.js';
 import * as scriptTools from './script.js';
@@ -25,6 +26,7 @@ const tools = [
   ...Object.values(pagesTools),
   ...Object.values(pdfTools),
   ...Object.values(performanceTools),
+  ...Object.values(profileTools),
   ...Object.values(screenshotTools),
   ...Object.values(scriptTools),
   ...Object.values(snapshotTools),