@everydaydevopsio/pilot 0.5.2 → 0.6.1

package/dist/util/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/util/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/util/config.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everydaydevopsio/pilot",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "DevTools-grade browser control for AI agents via MCP + CDP",
   "type": "module",
   "main": "dist/mcp/index.js",
@@ -8,7 +8,8 @@
     "pilot": "dist/mcp/index.js"
   },
   "scripts": {
-    "build": "rimraf ./dist && tsc",
+    "build:skill": "node scripts/build-skill.mjs",
+    "build": "pnpm run build:skill && rimraf ./dist && tsc",
     "start": "node dist/mcp/index.js",
     "dev": "tsx src/mcp/index.ts",
     "lint": "eslint .",
@@ -17,8 +18,8 @@
     "prettier:fix": "prettier . --write",
     "test": "jest",
     "test:coverage": "jest --coverage",
-    "test:e2e:mcp": "PILOT_HEADLESS=false jest --config jest.e2e-mcp.config.js --verbose",
-    "test:e2e:mcp:ci": "jest --config jest.e2e-mcp.config.js --verbose",
+    "test:e2e:mcp": "jest --config jest.e2e-mcp.config.js --verbose",
+    "test:e2e:mcp:ci": "PILOT_HEADLESS=true jest --config jest.e2e-mcp.config.js --verbose",
     "test:e2e:mcp:docker": "docker compose -f docker-compose.e2e.yml up --build --abort-on-container-exit --exit-code-from e2e",
     "pretest:smoke": "pnpm run build",
     "test:smoke": "tsx smoke/mcp-smoke.ts",

package/skills/pilot/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pilot
+description: Control and debug web pages with the Pilot MCP browser tools. Use when the user asks to open, inspect, test, or troubleshoot a site in Chrome with Pilot.
+---
+
+# Pilot browser workflow
+
+Use the `pilot` MCP tools to operate Chrome through the Chrome DevTools Protocol.
+
+## Start and inspect
+
+1. Call `browser_start` before any other Pilot browser tool. Use visible mode unless the user requests headless operation or the environment has no graphical display.
+2. Navigate with `browser_navigate`, then confirm the result with `browser_page_info` or `browser_snapshot`.
+3. Use refs returned by `browser_snapshot` or `browser_find` for interaction. Take a fresh snapshot after navigation or substantial DOM changes because refs can become stale.
+4. For debugging, clear errors before reproducing the problem, then inspect `browser_errors`, `browser_console`, and `browser_network`. Use performance tracing only when the user asks about load or runtime performance.
+5. Call `browser_stop` when the browser is no longer needed.
+
+Do not enter credentials, submit consequential forms, upload files, or make other externally visible changes unless the user authorized that action.
+
+## Troubleshooting
+
+### Visible Chrome on Linux
+
+Run `pilot check` when `browser_start` fails. Visible Chrome requires `DISPLAY` or `WAYLAND_DISPLAY` in the Pilot MCP server process. Headless operation does not.
+
+If desktop applications open but Pilot reports that the display is missing, inspect the graphical session with `printenv DISPLAY`. Forward the returned value through the MCP server configuration and restart the agent so Pilot is relaunched. For Codex:
+
+```toml
+[mcp_servers.pilot]
+command = "npx"
+args = ["-y", "@everydaydevopsio/pilot"]
+env = { DISPLAY = ":1" }
+```
+
+Replace `:1` with the actual value. If the X server requires a cookie, forward `XAUTHORITY` in the same map. For SSH, use trusted X11 forwarding (`ssh -Y`) when policy permits, or use a remote desktop session and its display value. Use `PILOT_HEADLESS=true` on systems without a desktop. In CI, use headless mode or run Pilot under Xvfb.
+
+### Other Linux preflight failures
+
+- If the profile directory is not writable, set `XDG_DATA_HOME` to a writable directory.
+- If loopback binding fails with `EPERM`, the host or container must allow binding on `127.0.0.1`; disabling Chrome's renderer sandbox does not fix it.
+- If Chrome is not detected, set `PILOT_CHROME_PATH` to its executable.
+- Avoid `PILOT_CHROME_NO_SANDBOX=true` unless the runtime genuinely cannot support Chrome's sandbox and the user accepts the security tradeoff.
+
+### Connection and page failures
+
+- Confirm the active page with `browser_page_info` and list tabs if Pilot controls the wrong tab.
+- Inspect failed document, script, XHR, and fetch requests with `browser_network`.
+- If element refs stop resolving after a page update, take another snapshot and retry with the new refs.

package/src/browser/browser-manager.ts

@@ -0,0 +1,465 @@
+import type { Client } from 'chrome-remote-interface';
+import type { ChildProcess } from 'child_process';
+import { mkdirSync } from 'fs';
+import { getLogger } from '../util/logger.js';
+import type { Config } from '../util/config.js';
+import type { ViewportConfig } from '../viewport.js';
+import { resolveViewport } from '../viewport.js';
+import type {
+  BrowserEventCallback,
+  BrowserState,
+  LaunchOptions,
+  TabInfo
+} from './types.js';
+import {
+  findChromeExecutable,
+  findFreePort,
+  isProfileLocked,
+  launchChrome,
+  resolveUserDataDir,
+  waitForChromeReady,
+  cleanupLockFiles
+} from './chrome-launcher.js';
+import { assertLinuxBrowserPrerequisites } from './preflight.js';
+import {
+  connectToChrome,
+  enableDomains,
+  getConnectionInfo,
+  type ConnectionInfo
+} from './connection.js';
+import { attachEventListeners } from './events.js';
+import {
+  listTabs as listTabsImpl,
+  createTab as createTabImpl,
+  closeTab as closeTabImpl,
+  switchTab as switchTabImpl
+} from './tabs.js';
+
+export class BrowserManager {
+  private client: Client | null = null;
+  private targetId: string | null = null;
+  private currentUrl: string | null = null;
+  private retryTimer: ReturnType<typeof setTimeout> | null = null;
+  private retryMs: number;
+  private destroyed = false;
+  private intentionalClose = false;
+  private eventCallback: BrowserEventCallback | null = null;
+  private pendingNetworkRequests = new Set<string>();
+  private networkIdleTimer: ReturnType<typeof setTimeout> | null = null;
+  private networkIdleResolvers: Array<() => void> = [];
+  private chromeProcess: ChildProcess | null = null;
+  private launchedCdpPort: number | null = null;
+  private viewportConfig: ViewportConfig | null = null;
+  private launchedUserDataDir: string | null = null;
+  private external = false;
+  private externalHost: string | null = null;
+  private externalPort: number | null = null;
+
+  constructor(private readonly config: Config) {
+    this.retryMs = config.cdpRetryMs;
+  }
+
+  setEventCallback(cb: BrowserEventCallback): void {
+    this.eventCallback = cb;
+  }
+
+  private emit(event: string, data: unknown): void {
+    this.eventCallback?.(event, data);
+  }
+
+  getState(): BrowserState {
+    return {
+      client: this.client,
+      targetId: this.targetId,
+      url: this.currentUrl,
+      connected: this.client !== null
+    };
+  }
+
+  getClient(): Client | null {
+    return this.client;
+  }
+
+  isConnected(): boolean {
+    return this.client !== null;
+  }
+
+  isLaunched(): boolean {
+    return this.chromeProcess !== null;
+  }
+
+  isExternalChrome(): boolean {
+    return this.external;
+  }
+
+  getViewportConfig(): ViewportConfig | null {
+    return this.viewportConfig;
+  }
+
+  setViewportConfig(config: ViewportConfig): void {
+    this.viewportConfig = config;
+  }
+
+  static findChromeExecutable(override?: string): string {
+    return findChromeExecutable(override);
+  }
+
+  static async findFreePort(): Promise<number> {
+    return findFreePort();
+  }
+
+  private getConnectionInfo(): ConnectionInfo {
+    return getConnectionInfo(this.config, this.launchedCdpPort);
+  }
+
+  private makeEventListenerOpts() {
+    return {
+      emit: (event: string, data: unknown) => this.emit(event, data),
+      onDisconnect: () => {
+        if (this.intentionalClose) {
+          this.intentionalClose = false;
+          return;
+        }
+        const logger = getLogger();
+        logger.warn('Chrome disconnected');
+        this.client = null;
+        this.targetId = null;
+        this.emit('browser_disconnected', {
+          reason: 'chrome_disconnected'
+        });
+        this.scheduleReconnect();
+      },
+      pendingNetworkRequests: this.pendingNetworkRequests,
+      checkNetworkIdle: () => this.checkNetworkIdle(),
+      onFrameNavigated: (url: string) => {
+        this.currentUrl = url;
+        this.emit('page_navigated', {
+          url,
+          timestamp: Date.now()
+        });
+      }
+    };
+  }
+
+  async launch(
+    opts: LaunchOptions = {}
+  ): Promise<{ headless: boolean; viewport: string }> {
+    if (this.chromeProcess) {
+      throw new Error('Chrome is already launched');
+    }
+    if (this.destroyed) {
+      throw new Error(
+        'BrowserManager has been destroyed; create a new instance'
+      );
+    }
+
+    const chromePath = findChromeExecutable(opts.chromePath);
+
+    const profileName = opts.profileName ?? this.config.profileName;
+    const userDataDir = resolveUserDataDir(profileName);
+
+    if (isProfileLocked(userDataDir)) {
+      throw new Error(
+        `Profile "${profileName}" is already in use by another browser instance.`
+      );
+    }
+
+    const viewportPreset = opts.viewport ?? this.config.viewport;
+    this.viewportConfig = resolveViewport({
+      preset: viewportPreset,
+      width: opts.viewportWidth,
+      height: opts.viewportHeight,
+      deviceScaleFactor: opts.deviceScaleFactor,
+      responsive: opts.responsive ?? this.config.responsive
+    });
+
+    const headless = opts.headless ?? this.config.headless;
+
+    await assertLinuxBrowserPrerequisites({
+      headless,
+      chromePath,
+      profileName,
+      checkNetwork: false
+    });
+
+    mkdirSync(userDataDir, { recursive: true });
+    const port = await findFreePort();
+
+    this.chromeProcess = launchChrome({
+      chromePath,
+      port,
+      userDataDir,
+      headless,
+      windowWidth: this.viewportConfig.width,
+      windowHeight: this.viewportConfig.height
+    });
+
+    this.launchedCdpPort = port;
+    this.launchedUserDataDir = userDataDir;
+
+    const stderrChunks: string[] = [];
+    this.chromeProcess.stderr?.on('data', (data: Buffer) => {
+      stderrChunks.push(data.toString());
+    });
+
+    this.chromeProcess.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();
+      logger.warn(
+        {
+          code,
+          signal,
+          ...(stderrFiltered && { stderr: stderrFiltered.slice(0, 1000) }),
+          ...(stderr && !stderrFiltered && { stderrRaw: stderr.slice(0, 500) })
+        },
+        'Chrome process exited'
+      );
+      this.chromeProcess = null;
+      this.launchedCdpPort = null;
+      this.cleanupUserDataDir();
+    });
+
+    await waitForChromeReady(port, opts.startupTimeoutMs);
+    await this.connect();
+
+    return { headless, viewport: viewportPreset };
+  }
+
+  async connect(): Promise<void> {
+    if (this.destroyed) return;
+    const logger = getLogger();
+
+    try {
+      const connInfo = this.getConnectionInfo();
+      const { client, targetId, url } = await connectToChrome(connInfo);
+
+      this.client = client;
+      this.targetId = targetId;
+      this.currentUrl = url;
+      this.retryMs = this.config.cdpRetryMs;
+
+      await enableDomains(client, this.viewportConfig);
+      attachEventListeners(client, this.makeEventListenerOpts());
+
+      logger.info(
+        { targetId: this.targetId, url: this.currentUrl },
+        'Connected to Chrome'
+      );
+
+      this.emit('browser_connected', {
+        targetId: this.targetId,
+        url: this.currentUrl
+      });
+    } catch (err) {
+      logger.warn(
+        { err, retryMs: this.retryMs },
+        'Failed to connect to Chrome, retrying...'
+      );
+      this.scheduleReconnect();
+    }
+  }
+
+  async connectExisting(opts: {
+    host?: string;
+    port?: number;
+  }): Promise<{ tabs: TabInfo[] }> {
+    if (this.chromeProcess) {
+      throw new Error(
+        'Chrome was launched by Pilot. Use browser_stop first, then browser_connect.'
+      );
+    }
+    if (this.destroyed) {
+      throw new Error(
+        'BrowserManager has been destroyed; create a new instance'
+      );
+    }
+
+    const logger = getLogger();
+    const host = opts.host ?? '127.0.0.1';
+    const port = opts.port ?? 9222;
+
+    this.external = true;
+    this.externalHost = host;
+    this.externalPort = port;
+    this.launchedCdpPort = port;
+
+    // Override connection info for external Chrome
+    const connInfo: ConnectionInfo = { host, port };
+
+    try {
+      const { client, targetId, url } = await connectToChrome(connInfo);
+
+      this.client = client;
+      this.targetId = targetId;
+      this.currentUrl = url;
+      this.retryMs = this.config.cdpRetryMs;
+
+      await enableDomains(client, this.viewportConfig);
+      attachEventListeners(client, this.makeEventListenerOpts());
+
+      logger.info(
+        { host, port, targetId, url },
+        'Connected to existing Chrome'
+      );
+
+      this.emit('browser_connected', { targetId, url });
+
+      const tabs = await this.listTabs();
+      return { tabs };
+    } catch (cause) {
+      this.external = false;
+      this.externalHost = null;
+      this.externalPort = null;
+      this.launchedCdpPort = null;
+      throw new Error(
+        `Could not connect to Chrome at ${host}:${port}. ` +
+          `Start Chrome with --remote-debugging-port=${port} or use browser_start to launch a new instance.`,
+        { cause }
+      );
+    }
+  }
+
+  private checkNetworkIdle(): void {
+    if (this.pendingNetworkRequests.size === 0) {
+      if (this.networkIdleTimer) clearTimeout(this.networkIdleTimer);
+      this.networkIdleTimer = setTimeout(() => {
+        const resolvers = this.networkIdleResolvers.splice(0);
+        resolvers.forEach((r) => r());
+      }, 500);
+      this.networkIdleTimer.unref();
+    }
+  }
+
+  waitForNetworkIdle(timeoutMs = 10000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.pendingNetworkRequests.size === 0) {
+        resolve();
+        return;
+      }
+      const timer = setTimeout(() => {
+        const idx = this.networkIdleResolvers.indexOf(resolve);
+        if (idx !== -1) this.networkIdleResolvers.splice(idx, 1);
+        reject(new Error('timeout waiting for network idle'));
+      }, timeoutMs);
+
+      this.networkIdleResolvers.push(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+
+  async listTabs(): Promise<TabInfo[]> {
+    return listTabsImpl(this.getConnectionInfo(), this.targetId);
+  }
+
+  async createTab(url?: string): Promise<TabInfo> {
+    return createTabImpl(this.getConnectionInfo(), url);
+  }
+
+  async closeTab(targetId: string): Promise<void> {
+    return closeTabImpl(this.getConnectionInfo(), targetId, this.targetId);
+  }
+
+  async switchTab(targetId: string): Promise<void> {
+    if (targetId === this.targetId) return;
+
+    // Clear any pending reconnect from a prior disconnect
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+
+    this.intentionalClose = true;
+
+    const result = await switchTabImpl(
+      this.getConnectionInfo(),
+      targetId,
+      this.targetId,
+      this.client,
+      this.viewportConfig,
+      this.makeEventListenerOpts()
+    );
+
+    this.client = result.client;
+    this.targetId = result.targetId;
+    this.currentUrl = result.url;
+    this.retryMs = this.config.cdpRetryMs;
+  }
+
+  private scheduleReconnect(): void {
+    if (this.destroyed) return;
+    if (this.retryTimer) return;
+
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      this.retryMs = Math.min(this.retryMs * 2, this.config.cdpMaxRetryMs);
+      void this.connect();
+    }, this.retryMs);
+    this.retryTimer.unref();
+  }
+
+  private cleanupUserDataDir(): void {
+    if (this.launchedUserDataDir) {
+      cleanupLockFiles(this.launchedUserDataDir);
+    }
+    this.launchedUserDataDir = null;
+  }
+
+  async destroy(): Promise<void> {
+    this.destroyed = true;
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+    if (this.networkIdleTimer) {
+      clearTimeout(this.networkIdleTimer);
+    }
+    if (this.client) {
+      await this.client.close();
+      this.client = null;
+    }
+    // External Chrome: just disconnect, don't kill the process
+    if (this.external) {
+      this.external = false;
+      this.externalHost = null;
+      this.externalPort = null;
+      this.launchedCdpPort = null;
+      return;
+    }
+    if (this.chromeProcess) {
+      const proc = this.chromeProcess;
+      this.chromeProcess = null;
+      this.launchedCdpPort = null;
+      try {
+        proc.kill();
+      } catch {
+        // process may have already exited
+      }
+      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();
+    }
+  }
+}