feat: Phase 2 — profiles, session registry, providers, PDF, inactivity

Add multi-profile management with CDP port allocation (18800-18899),
per-agent session tab tracking, cloud provider abstraction with
Browserbase integration (graceful 402 fallback chain), PDF export tool,
and session inactivity cleanup monitor.

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

Author: Hein van Vuuren

src/config/profiles.ts

@@ -0,0 +1,166 @@
+/**
+ * Boss Ghost MCP — Multi-profile management with CDP port allocation.
+ *
+ * Profiles define browser instances with isolated user data dirs,
+ * CDP ports, and launch configurations. Inspired by OpenClaw's profile system.
+ */
+
+import {getConfig} from './config.js';
+import type {ProfileConfig} from './types.js';
+import {logger} from '../logger.js';
+
+// CDP port range: 18800-18899 (same as OpenClaw)
+const CDP_PORT_RANGE_START = 18800;
+const CDP_PORT_RANGE_END = 18899;
+
+export interface ResolvedProfile {
+  name: string;
+  cdpPort: number;
+  cdpUrl?: string;
+  userDataDir?: string;
+  driver: 'managed' | 'existing-session';
+  headless: boolean;
+  channel: 'stable' | 'canary' | 'beta' | 'dev';
+  executablePath?: string;
+  extraArgs: string[];
+  attachOnly: boolean;
+}
+
+/**
+ * Build a ResolvedProfile from a ProfileConfig and its name.
+ * Fills in defaults for any missing fields.
+ */
+function resolveFromConfig(
+  name: string,
+  config: ProfileConfig,
+  portIndex: number,
+): ResolvedProfile {
+  const cdpPort = config.cdpPort ?? CDP_PORT_RANGE_START + portIndex;
+
+  if (cdpPort < CDP_PORT_RANGE_START || cdpPort > CDP_PORT_RANGE_END) {
+    logger(
+      'Profile "%s" CDP port %d is outside range %d-%d',
+      name,
+      cdpPort,
+      CDP_PORT_RANGE_START,
+      CDP_PORT_RANGE_END,
+    );
+  }
+
+  return {
+    name,
+    cdpPort,
+    cdpUrl: config.cdpUrl,
+    userDataDir: config.userDataDir,
+    driver: config.driver ?? 'managed',
+    headless: config.headless ?? false,
+    channel: config.channel ?? 'stable',
+    executablePath: config.executablePath,
+    extraArgs: config.extraArgs ?? [],
+    attachOnly: config.attachOnly ?? false,
+  };
+}
+
+/**
+ * Create a default profile with sensible defaults.
+ * Used when no profiles are configured at all.
+ */
+function createDefaultProfile(): ResolvedProfile {
+  return {
+    name: 'default',
+    cdpPort: CDP_PORT_RANGE_START,
+    driver: 'managed',
+    headless: false,
+    channel: 'stable',
+    extraArgs: [],
+    attachOnly: false,
+  };
+}
+
+/**
+ * Get the default profile name from config, falling back to "default".
+ */
+function getDefaultProfileName(): string {
+  const config = getConfig();
+  return config.defaultProfile ?? 'default';
+}
+
+/**
+ * Get or create the default profile.
+ * If the default profile is configured, resolves it. Otherwise creates
+ * a minimal managed profile automatically.
+ */
+export function getDefaultProfile(): ResolvedProfile {
+  const config = getConfig();
+  const defaultName = getDefaultProfileName();
+  const profiles = config.profiles;
+
+  if (profiles && profiles[defaultName]) {
+    const keys = Object.keys(profiles);
+    const portIndex = keys.indexOf(defaultName);
+    return resolveFromConfig(defaultName, profiles[defaultName], portIndex);
+  }
+
+  logger('No profile "%s" found in config — using auto-generated default', defaultName);
+  return createDefaultProfile();
+}
+
+/**
+ * Resolve a named profile from config.
+ * Returns null if the profile does not exist.
+ */
+export function resolveProfile(name: string): ResolvedProfile | null {
+  const config = getConfig();
+  const profiles = config.profiles;
+
+  if (!profiles || !profiles[name]) {
+    logger('Profile "%s" not found in config', name);
+    return null;
+  }
+
+  const keys = Object.keys(profiles);
+  const portIndex = keys.indexOf(name);
+  return resolveFromConfig(name, profiles[name], portIndex);
+}
+
+/**
+ * List all configured profiles with their resolved settings.
+ * If no profiles are configured, returns a single auto-generated default.
+ */
+export function listProfiles(): ResolvedProfile[] {
+  const config = getConfig();
+  const profiles = config.profiles;
+
+  if (!profiles || Object.keys(profiles).length === 0) {
+    return [createDefaultProfile()];
+  }
+
+  const keys = Object.keys(profiles);
+  return keys.map((name, idx) => resolveFromConfig(name, profiles[name], idx));
+}
+
+/**
+ * Allocate the next available CDP port in the 18800-18899 range.
+ * Skips any ports already in the usedPorts set.
+ * Throws if no ports are available.
+ */
+export function allocateCdpPort(usedPorts: Set<number>): number {
+  for (let port = CDP_PORT_RANGE_START; port <= CDP_PORT_RANGE_END; port++) {
+    if (!usedPorts.has(port)) {
+      return port;
+    }
+  }
+  throw new Error(
+    `No available CDP ports in range ${CDP_PORT_RANGE_START}-${CDP_PORT_RANGE_END}. ` +
+      `All ${CDP_PORT_RANGE_END - CDP_PORT_RANGE_START + 1} ports are in use.`,
+  );
+}
+
+/**
+ * Ensure the default profile exists.
+ * Returns the resolved default profile, auto-creating one if no profiles
+ * are configured.
+ */
+export function ensureDefaultProfile(): ResolvedProfile {
+  return getDefaultProfile();
+}

src/config/session-registry.ts

@@ -0,0 +1,122 @@
+/**
+ * Boss Ghost MCP — Per-agent session tab tracking.
+ *
+ * Tracks which browser tabs belong to which agent session,
+ * enabling clean teardown when an agent disconnects.
+ * Inspired by OpenClaw's session-tab-registry.ts.
+ */
+
+import {logger} from '../logger.js';
+
+export interface TrackedTab {
+  profileName: string;
+  pageIdx: number;
+  url: string;
+  createdAt: number;
+}
+
+// Session registry — tracks which tabs belong to which agent session.
+// Outer key: sessionKey (agent identifier), inner key: pageIdx.
+const sessions = new Map<string, Map<number, TrackedTab>>();
+
+/**
+ * Register a tab for a session.
+ * If the session doesn't exist yet, it is created automatically.
+ */
+export function trackTab(
+  sessionKey: string,
+  pageIdx: number,
+  profileName: string,
+  url: string,
+): void {
+  let tabs = sessions.get(sessionKey);
+  if (!tabs) {
+    tabs = new Map<number, TrackedTab>();
+    sessions.set(sessionKey, tabs);
+    logger('Created session tracking for "%s"', sessionKey);
+  }
+
+  const tab: TrackedTab = {
+    profileName,
+    pageIdx,
+    url,
+    createdAt: Date.now(),
+  };
+
+  tabs.set(pageIdx, tab);
+  logger(
+    'Tracked tab %d for session "%s" (profile: %s, url: %s)',
+    pageIdx,
+    sessionKey,
+    profileName,
+    url,
+  );
+}
+
+/**
+ * Untrack a tab from a session.
+ * No-op if the session or tab doesn't exist.
+ */
+export function untrackTab(sessionKey: string, pageIdx: number): void {
+  const tabs = sessions.get(sessionKey);
+  if (!tabs) {
+    return;
+  }
+
+  const deleted = tabs.delete(pageIdx);
+  if (deleted) {
+    logger('Untracked tab %d from session "%s"', pageIdx, sessionKey);
+  }
+
+  // Clean up empty sessions automatically
+  if (tabs.size === 0) {
+    sessions.delete(sessionKey);
+    logger('Session "%s" has no more tabs — removed', sessionKey);
+  }
+}
+
+/**
+ * Get all tracked tabs for a session.
+ * Returns an empty array if the session doesn't exist.
+ */
+export function getSessionTabs(sessionKey: string): TrackedTab[] {
+  const tabs = sessions.get(sessionKey);
+  if (!tabs) {
+    return [];
+  }
+  return Array.from(tabs.values());
+}
+
+/**
+ * Get all page indices that should be closed for a session teardown.
+ * Returns indices in descending order so closing them won't shift
+ * the indices of remaining tabs.
+ */
+export function getTabsToClose(sessionKey: string): number[] {
+  const tabs = sessions.get(sessionKey);
+  if (!tabs) {
+    return [];
+  }
+  return Array.from(tabs.keys()).sort((a, b) => b - a);
+}
+
+/**
+ * Clean up all tracking data for a session.
+ */
+export function clearSession(sessionKey: string): void {
+  const tabs = sessions.get(sessionKey);
+  const count = tabs?.size ?? 0;
+  sessions.delete(sessionKey);
+  logger('Cleared session "%s" (%d tabs)', sessionKey, count);
+}
+
+/**
+ * List all active sessions with their tab counts.
+ */
+export function listSessions(): {sessionKey: string; tabCount: number}[] {
+  const result: {sessionKey: string; tabCount: number}[] = [];
+  for (const [sessionKey, tabs] of sessions) {
+    result.push({sessionKey, tabCount: tabs.size});
+  }
+  return result;
+}

src/providers/base.ts

@@ -0,0 +1,42 @@
+/**
+ * Boss Ghost MCP — Cloud browser provider abstraction.
+ *
+ * Defines the interface contract that all cloud browser providers must implement.
+ * Inspired by Hermes's browser_providers/base.py pattern.
+ */
+
+/** Represents an active cloud browser session. */
+export interface ProviderSession {
+  /** Provider's unique session identifier. */
+  sessionId: string;
+  /** Human-readable session name for logging. */
+  sessionName: string;
+  /** WebSocket URL for Chrome DevTools Protocol connection. */
+  cdpUrl: string;
+  /** Runtime feature flags indicating which capabilities are active. */
+  features: Record<string, boolean>;
+}
+
+/** Contract for cloud browser providers (Browserbase, Browser-Use, etc.). */
+export interface CloudBrowserProvider {
+  /** Provider identifier (e.g. 'browserbase', 'browser-use'). */
+  readonly providerName: string;
+
+  /**
+   * Check if this provider is configured with valid credentials.
+   * Must be cheap — no network calls.
+   */
+  isConfigured(): boolean;
+
+  /** Create a new cloud browser session. */
+  createSession(taskId?: string): Promise<ProviderSession>;
+
+  /** Close a session gracefully. Returns true if the session was stopped. */
+  closeSession(sessionId: string): Promise<boolean>;
+
+  /**
+   * Best-effort cleanup for use in exit handlers.
+   * Must never throw — all errors are swallowed.
+   */
+  emergencyCleanup(sessionId: string): Promise<void>;
+}