@everydaydevopsio/pilot 0.6.2 → 0.7.0

package/src/browser/browser-manager.ts

@@ -1,6 +1,8 @@
 import type { Client } from 'chrome-remote-interface';
 import type { ChildProcess } from 'child_process';
 import { mkdirSync } from 'fs';
+import { hostname } from 'os';
+import { basename, join } from 'path';
 import { getLogger } from '../util/logger.js';
 import type { Config } from '../util/config.js';
 import type { ViewportConfig } from '../viewport.js';
@@ -9,6 +11,7 @@ import type {
   BrowserEventCallback,
   BrowserState,
   LaunchOptions,
+  SessionInfo,
   TabInfo
 } from './types.js';
 import {
@@ -18,7 +21,9 @@ import {
   launchChrome,
   resolveUserDataDir,
   waitForChromeReady,
-  cleanupLockFiles
+  cleanupLockFiles,
+  profileLockOwner,
+  DEFAULT_STARTUP_TIMEOUT_MS
 } from './chrome-launcher.js';
 import { assertLinuxBrowserPrerequisites } from './preflight.js';
 import {
@@ -92,6 +97,30 @@ export class BrowserManager {
     return this.external;
   }
 
+  getSessionInfo(): SessionInfo {
+    if (this.external) {
+      return {
+        mode: 'external',
+        connected: this.client !== null,
+        host: this.externalHost ?? undefined,
+        cdpPort: this.externalPort ?? undefined
+      };
+    }
+    if (this.chromeProcess) {
+      return {
+        mode: 'launched',
+        connected: this.client !== null,
+        pid: this.chromeProcess.pid,
+        cdpPort: this.launchedCdpPort ?? undefined,
+        userDataDir: this.launchedUserDataDir ?? undefined,
+        profile: this.launchedUserDataDir
+          ? basename(this.launchedUserDataDir)
+          : undefined
+      };
+    }
+    return { mode: 'none', connected: false };
+  }
+
   getViewportConfig(): ViewportConfig | null {
     return this.viewportConfig;
   }
@@ -159,9 +188,7 @@ export class BrowserManager {
     const userDataDir = resolveUserDataDir(profileName);
 
     if (isProfileLocked(userDataDir)) {
-      throw new Error(
-        `Profile "${profileName}" is already in use by another browser instance.`
-      );
+      throw new Error(describeProfileConflict(profileName, userDataDir));
     }
 
     const viewportPreset = opts.viewport ?? this.config.viewport;
@@ -198,18 +225,30 @@ export class BrowserManager {
     this.launchedUserDataDir = userDataDir;
 
     const stderrChunks: string[] = [];
-    this.chromeProcess.stderr?.on('data', (data: Buffer) => {
+    const proc = this.chromeProcess;
+    let spawnError: Error | null = null;
+    let exitStatus: string | null = null;
+
+    proc.stderr?.on('data', (data: Buffer) => {
       stderrChunks.push(data.toString());
     });
 
-    this.chromeProcess.on('exit', (code, signal) => {
+    proc.on('error', (err) => {
+      spawnError = err;
+      getLogger().warn({ err, chromePath }, 'Chrome process failed to start');
+      // A failed spawn does not necessarily emit 'exit'.
+      if (this.chromeProcess === proc && proc.pid === undefined) {
+        this.chromeProcess = null;
+        this.launchedCdpPort = null;
+        this.launchedUserDataDir = null;
+      }
+    });
+
+    proc.on('exit', (code, signal) => {
       const logger = getLogger();
       const stderr = stderrChunks.join('').trim();
-      const stderrFiltered = stderr
-        .split('\n')
-        .filter((l) => !l.includes('dbus/bus.cc'))
-        .join('\n')
-        .trim();
+      const stderrFiltered = filterChromeStderr(stderr);
+      exitStatus = signal ? `signal ${signal}` : `exit code ${code}`;
       logger.warn(
         {
           code,
@@ -219,17 +258,78 @@ export class BrowserManager {
         },
         'Chrome process exited'
       );
-      this.chromeProcess = null;
-      this.launchedCdpPort = null;
-      this.cleanupUserDataDir();
+      if (this.chromeProcess === proc) {
+        this.chromeProcess = null;
+        this.launchedCdpPort = null;
+        this.cleanupUserDataDir(proc.pid);
+      }
     });
 
-    await waitForChromeReady(port, opts.startupTimeoutMs);
+    const startupTimeoutMs =
+      opts.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+    const earlyFailure = (): Error | null => {
+      if (spawnError) {
+        return new Error(
+          `Chrome failed to start (${chromePath}): ${spawnError.message}`,
+          { cause: spawnError }
+        );
+      }
+      if (exitStatus) {
+        const stderr = filterChromeStderr(stderrChunks.join('').trim());
+        return new Error(
+          `Chrome exited (${exitStatus}) before DevTools became ready on port ${port}.` +
+            (stderr ? ` Chrome stderr: ${stderr.slice(-1000)}` : '')
+        );
+      }
+      return null;
+    };
+
+    try {
+      await waitForChromeReady(port, startupTimeoutMs, earlyFailure);
+    } catch (err) {
+      const timedOut = earlyFailure() === null;
+      const cleanup = await this.abortLaunch(proc, userDataDir);
+      throw new Error(
+        describeLaunchFailure({
+          reason: (err as Error).message,
+          timedOut,
+          startupTimeoutMs,
+          chromePath,
+          profileName,
+          userDataDir,
+          headless,
+          port,
+          cleanup
+        }),
+        { cause: err }
+      );
+    }
     await this.connect();
 
     return { headless, viewport: viewportPreset };
   }
 
+  /**
+   * Stop a Chrome process whose launch failed so it does not keep holding
+   * the profile lock while this manager forgets about it.
+   */
+  private async abortLaunch(
+    proc: ChildProcess,
+    userDataDir: string
+  ): Promise<LaunchCleanup> {
+    if (this.chromeProcess === proc) {
+      this.chromeProcess = null;
+      this.launchedCdpPort = null;
+    }
+    this.launchedUserDataDir = null;
+    const pid = proc.pid;
+    const stopped = await stopChromeProcess(proc);
+    if (stopped && pid !== undefined) {
+      cleanupLockFiles(userDataDir, pid);
+    }
+    return { pid, stopped };
+  }
+
   async connect(): Promise<void> {
     if (this.destroyed) return;
     const logger = getLogger();
@@ -404,9 +504,9 @@ export class BrowserManager {
     this.retryTimer.unref();
   }
 
-  private cleanupUserDataDir(): void {
-    if (this.launchedUserDataDir) {
-      cleanupLockFiles(this.launchedUserDataDir);
+  private cleanupUserDataDir(ownerPid: number | undefined): void {
+    if (this.launchedUserDataDir && ownerPid !== undefined) {
+      cleanupLockFiles(this.launchedUserDataDir, ownerPid);
     }
     this.launchedUserDataDir = null;
   }
@@ -436,30 +536,137 @@ export class BrowserManager {
       const proc = this.chromeProcess;
       this.chromeProcess = null;
       this.launchedCdpPort = null;
-      try {
-        proc.kill();
-      } catch {
-        // process may have already exited
+      if (await stopChromeProcess(proc)) {
+        this.cleanupUserDataDir(proc.pid);
+      } else {
+        getLogger().warn(
+          { pid: proc.pid },
+          'Chrome did not exit after SIGKILL; leaving its profile lock in place'
+        );
+        this.launchedUserDataDir = null;
       }
-      await new Promise<void>((resolve) => {
-        if (proc.exitCode !== null) {
-          resolve();
-          return;
-        }
-        const timer = setTimeout(() => {
-          try {
-            proc.kill('SIGKILL');
-          } catch {
-            // process may have already exited
-          }
-          resolve();
-        }, 5000);
-        proc.once('exit', () => {
-          clearTimeout(timer);
-          resolve();
-        });
-      });
-      this.cleanupUserDataDir();
     }
   }
 }
+
+function filterChromeStderr(stderr: string): string {
+  return stderr
+    .split('\n')
+    .filter((l) => !l.includes('dbus/bus.cc'))
+    .join('\n')
+    .trim();
+}
+
+interface LaunchCleanup {
+  pid: number | undefined;
+  stopped: boolean;
+}
+
+/** Terminate a Chrome process, escalating to SIGKILL. Resolves true once it has exited. */
+async function stopChromeProcess(proc: ChildProcess): Promise<boolean> {
+  const hasExited = () => proc.exitCode !== null || proc.signalCode !== null;
+  if (proc.pid === undefined || hasExited()) return true;
+
+  const waitForExit = (ms: number) =>
+    new Promise<boolean>((resolve) => {
+      if (hasExited()) {
+        resolve(true);
+        return;
+      }
+      const timer = setTimeout(() => {
+        proc.off('exit', onExit);
+        resolve(hasExited());
+      }, ms);
+      const onExit = () => {
+        clearTimeout(timer);
+        resolve(true);
+      };
+      proc.once('exit', onExit);
+    });
+
+  try {
+    proc.kill();
+  } catch {
+    // process may have already exited
+  }
+  if (await waitForExit(5000)) return true;
+  try {
+    proc.kill('SIGKILL');
+  } catch {
+    // process may have already exited
+  }
+  return waitForExit(2000);
+}
+
+function describeProfileConflict(
+  profileName: string,
+  userDataDir: string
+): string {
+  const lockPath = join(userDataDir, 'SingletonLock');
+  const owner = profileLockOwner(userDataDir);
+  const message = [
+    `Profile "${profileName}" is already in use by another browser instance.`
+  ];
+  if (owner && owner.lockHost === hostname()) {
+    message.push(
+      `Chrome pid ${owner.pid} on this host holds ${lockPath}. This Pilot session is not tracking that browser, so browser_stop will not stop it.`,
+      `Close that Chrome window or stop pid ${owner.pid}, or call browser_start with a different profileName.`
+    );
+  } else if (owner) {
+    message.push(
+      `The lock ${lockPath} was created by pid ${owner.pid} on host "${owner.lockHost}", not this host ("${hostname()}"), so Pilot cannot tell whether that browser is still running.`,
+      `Call browser_start with a different profileName. If no browser on "${owner.lockHost}" uses this profile any more, delete the lock file and retry.`
+    );
+  } else {
+    message.push(
+      `Pilot could not identify the owner of the lock in ${userDataDir}.`,
+      `Call browser_start with a different profileName. If no Chrome is using that directory, delete its SingletonLock and lockfile and retry.`
+    );
+  }
+  return message.join(' ');
+}
+
+function describeLaunchFailure(details: {
+  reason: string;
+  timedOut: boolean;
+  startupTimeoutMs: number;
+  chromePath: string;
+  profileName: string;
+  userDataDir: string;
+  headless: boolean;
+  port: number;
+  cleanup: LaunchCleanup;
+}): string {
+  const { cleanup } = details;
+  const display =
+    process.env.DISPLAY || process.env.WAYLAND_DISPLAY || '(not set)';
+  const launch = [
+    `chrome=${details.chromePath}`,
+    `profile="${details.profileName}" (${details.userDataDir})`,
+    `mode=${details.headless ? 'headless' : 'visible'}`,
+    `devtools port=${details.port}`,
+    ...(process.platform === 'linux' && !details.headless
+      ? [`display=${display}`]
+      : [])
+  ].join(', ');
+
+  let cleanupText: string;
+  if (cleanup.pid === undefined) {
+    cleanupText = 'No Chrome process was left running.';
+  } else if (cleanup.stopped) {
+    cleanupText = `Pilot stopped the Chrome process it launched (pid ${cleanup.pid}); profile "${details.profileName}" is free to reuse.`;
+  } else {
+    cleanupText = `Chrome (pid ${cleanup.pid}) did not stop and may still hold profile "${details.profileName}". Stop it (kill -9 ${cleanup.pid}) or call browser_start with a different profileName.`;
+  }
+
+  const nextSteps = details.timedOut
+    ? `Chrome can be slow on a first run or with software rendering; retry with a larger startupTimeoutMs (this attempt used ${details.startupTimeoutMs}ms). Run \`pilot check\` to diagnose the environment.`
+    : `Run \`pilot check\` to diagnose the environment${details.headless ? '' : ', or retry with headless: true if no graphical display is available'}.`;
+
+  return [
+    details.reason,
+    `Launch: ${launch}.`,
+    `Cleanup: ${cleanupText}`,
+    `Next: ${nextSteps}`
+  ].join('\n');
+}

package/src/browser/chrome-launcher.ts

@@ -188,12 +188,21 @@ export function formatPortBindError(error: NodeJS.ErrnoException): Error {
   return error;
 }
 
+// Cold starts on Linux servers (first-run profile setup, software rendering
+// under Xvfb/VNC) can take well over 30s. A healthy start returns as soon as
+// DevTools answers, and a Chrome that exits is detected immediately, so the
+// longer ceiling only matters when Chrome is genuinely slow.
+export const DEFAULT_STARTUP_TIMEOUT_MS = 90000;
+
 export async function waitForChromeReady(
   port: number,
-  timeoutMs = 30000
+  timeoutMs = DEFAULT_STARTUP_TIMEOUT_MS,
+  earlyFailure?: () => Error | null
 ): Promise<void> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
+    const failure = earlyFailure?.();
+    if (failure) throw failure;
     try {
       await CDP.List({ host: '127.0.0.1', port });
       return;
@@ -201,6 +210,8 @@ export async function waitForChromeReady(
       await new Promise((r) => setTimeout(r, 200));
     }
   }
+  const failure = earlyFailure?.();
+  if (failure) throw failure;
   throw new Error(
     `Chrome did not become ready on port ${port} within ${timeoutMs}ms`
   );
@@ -271,12 +282,37 @@ export function launchChrome(opts: {
   });
 }
 
-export function cleanupLockFiles(userDataDir: string): void {
+export function profileLockOwner(
+  userDataDir: string
+): { pid: number; lockHost: string } | null {
+  return extractLockPid(join(userDataDir, 'SingletonLock'));
+}
+
+/**
+ * Remove the profile lock files left by a Chrome process Pilot launched.
+ * A SingletonLock that names a different process is left alone: if Chrome
+ * handed off to another instance already using the profile, that lock
+ * belongs to the live browser. Returns false when a lock was left in place.
+ */
+export function cleanupLockFiles(
+  userDataDir: string,
+  ownerPid: number
+): boolean {
+  const owner = profileLockOwner(userDataDir);
+  if (
+    fileOrSymlinkExists(join(userDataDir, 'SingletonLock')) &&
+    (!owner || owner.pid !== ownerPid || owner.lockHost !== hostname())
+  ) {
+    return false;
+  }
+  let removed = true;
   for (const lockName of ['SingletonLock', 'lockfile']) {
     try {
       unlinkSync(join(userDataDir, lockName));
-    } catch {
-      // lock file may not exist — that's fine
+    } catch (err) {
+      // A lock file that does not exist is already gone.
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') removed = false;
     }
   }
+  return removed;
 }

package/src/browser/driver/capabilities.ts

@@ -0,0 +1,88 @@
+import type { ToolName } from '../../mcp/tools/names.js';
+import type { BrowserKind, Capability } from './types.js';
+
+/**
+ * Capabilities each MCP tool needs from the active driver. Tools mapped to an
+ * empty list either manage the session itself (start/stop/status) or only read
+ * buffers that every driver fills.
+ */
+export const TOOL_CAPABILITIES: Readonly<
+  Record<ToolName, readonly Capability[]>
+> = {
+  browser_start: [],
+  browser_stop: [],
+  browser_status: [],
+  browser_stop_all: [],
+  browser_connect: ['connectExisting'],
+  browser_screenshot: ['screenshot'],
+  browser_navigate: ['navigation'],
+  browser_click: ['input'],
+  browser_type: ['input'],
+  browser_evaluate: ['evaluate'],
+  browser_wait: ['evaluate'],
+  browser_page_info: ['evaluate'],
+  browser_list_tabs: ['tabs'],
+  browser_new_tab: ['tabs'],
+  browser_close_tab: ['tabs'],
+  browser_switch_tab: ['tabs'],
+  browser_tabs: ['tabs'],
+  browser_viewport_resize: ['viewport'],
+  browser_get_console_logs: ['console'],
+  browser_get_errors: ['console'],
+  browser_clear_errors: ['console'],
+  browser_console: ['console'],
+  browser_errors: ['console'],
+  browser_snapshot: ['accessibilitySnapshot'],
+  browser_find: ['accessibilitySnapshot'],
+  browser_fill: ['input'],
+  browser_hover: ['input'],
+  browser_press_key: ['input'],
+  browser_select: ['input'],
+  browser_check: ['input'],
+  browser_scroll: ['input'],
+  browser_network: ['network'],
+  browser_styles: ['styles'],
+  browser_dialog: ['dialogs'],
+  browser_upload: ['uploads'],
+  browser_downloads: ['downloads'],
+  browser_performance: ['performanceTrace']
+};
+
+export class CapabilityError extends Error {
+  constructor(
+    readonly tool: ToolName,
+    readonly browser: BrowserKind,
+    readonly missing: readonly Capability[]
+  ) {
+    super(
+      `${tool} is not supported by ${browser} (missing capabilities: ${missing.join(', ')}).`
+    );
+    this.name = 'CapabilityError';
+  }
+}
+
+export function missingCapabilities(
+  tool: ToolName,
+  capabilities: ReadonlySet<Capability>
+): Capability[] {
+  return TOOL_CAPABILITIES[tool].filter((c) => !capabilities.has(c));
+}
+
+export function assertToolSupported(
+  tool: ToolName,
+  driver: { kind: BrowserKind; capabilities: ReadonlySet<Capability> }
+): void {
+  const missing = missingCapabilities(tool, driver.capabilities);
+  if (missing.length > 0) {
+    throw new CapabilityError(tool, driver.kind, missing);
+  }
+}
+
+/** Tools the given capability set cannot run, for status and docs output. */
+export function unsupportedTools(
+  capabilities: ReadonlySet<Capability>
+): ToolName[] {
+  return (Object.keys(TOOL_CAPABILITIES) as ToolName[]).filter(
+    (tool) => missingCapabilities(tool, capabilities).length > 0
+  );
+}