@everydaydevopsio/pilot 0.6.2 → 0.6.3

package/src/browser/sessions.ts

@@ -0,0 +1,299 @@
+import { execFileSync } from 'child_process';
+import { existsSync, lstatSync, readdirSync, statSync } from 'fs';
+import { hostname } from 'os';
+import { basename, dirname, join } from 'path';
+import {
+  PROFILE_NAME_RE,
+  cleanupLockFiles,
+  isProcessAlive,
+  profileLockOwner,
+  resolveUserDataDir
+} from './chrome-launcher.js';
+
+export type ProfileLockState =
+  /** No lock files: the profile is free. */
+  | 'unlocked'
+  /** Locked by a live process on this host. */
+  | 'locked'
+  /** Locked by a process on this host that is no longer running. */
+  | 'stale'
+  /** Locked from another host; liveness cannot be checked here. */
+  | 'locked_other_host'
+  /** Lock files exist but name no owner Pilot can read. */
+  | 'locked_unknown';
+
+export interface ProfileStatus {
+  profile: string;
+  userDataDir: string;
+  state: ProfileLockState;
+  pid?: number;
+  host?: string;
+  /** True when the lock owner's command line shows Chrome using this Pilot profile. */
+  pilotChrome?: boolean;
+}
+
+export function pilotDataDir(): string {
+  // resolveUserDataDir validates the name; any valid name gives the parent.
+  return dirname(resolveUserDataDir('profile1'));
+}
+
+/**
+ * Report the lock state of every Pilot profile. Read-only: unlike
+ * isProfileLocked, it never removes stale locks.
+ */
+export function listProfiles(): ProfileStatus[] {
+  const dataDir = pilotDataDir();
+  let names: string[];
+  try {
+    names = readdirSync(dataDir);
+  } catch {
+    return [];
+  }
+
+  return names
+    .filter((name) => PROFILE_NAME_RE.test(name))
+    .filter((name) => {
+      try {
+        return statSync(join(dataDir, name)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .sort()
+    .map((profile) => profileStatus(profile, join(dataDir, profile)));
+}
+
+function profileStatus(profile: string, userDataDir: string): ProfileStatus {
+  const owner = profileLockOwner(userDataDir);
+  const base = { profile, userDataDir };
+
+  if (!owner) {
+    const hasLock =
+      lockPresent(join(userDataDir, 'SingletonLock')) ||
+      existsSync(join(userDataDir, 'lockfile'));
+    return { ...base, state: hasLock ? 'locked_unknown' : 'unlocked' };
+  }
+  if (owner.lockHost !== hostname()) {
+    return {
+      ...base,
+      state: 'locked_other_host',
+      pid: owner.pid,
+      host: owner.lockHost
+    };
+  }
+  if (!isProcessAlive(owner.pid)) {
+    return { ...base, state: 'stale', pid: owner.pid, host: owner.lockHost };
+  }
+  return {
+    ...base,
+    state: 'locked',
+    pid: owner.pid,
+    host: owner.lockHost,
+    pilotChrome: isPilotChrome(owner.pid, userDataDir)
+  };
+}
+
+function lockPresent(path: string): boolean {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ps(pid: number, field: 'args' | 'comm'): string | null {
+  if (process.platform === 'win32') return null;
+  try {
+    const out = execFileSync('ps', ['-o', `${field}=`, '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The full command line of a process, or null when it cannot be read. */
+export function readProcessCommand(pid: number): string | null {
+  return ps(pid, 'args');
+}
+
+// Chrome's main executable: "chrome" or "chromium-browser" on Linux (comm is
+// truncated to 15 characters), "Google Chrome" or "Chromium" on macOS.
+const CHROME_EXECUTABLE_RE = /chrom(e|ium)/i;
+
+/**
+ * Whether pid is a Chrome or Chromium browser started with exactly this Pilot
+ * profile directory. A pid read from a lock can be reused by an unrelated
+ * process, so stop-all only signals processes that pass this check.
+ */
+export function isPilotChrome(pid: number, userDataDir: string): boolean {
+  const executable = ps(pid, 'comm');
+  if (!executable || !CHROME_EXECUTABLE_RE.test(basename(executable))) {
+    return false;
+  }
+  const command = readProcessCommand(pid);
+  if (!command) return false;
+  const flag = ` --user-data-dir=${userDataDir}`;
+  let at = command.indexOf(flag);
+  while (at !== -1) {
+    const next = command.charAt(at + flag.length);
+    if (next === '' || next === ' ') return true;
+    at = command.indexOf(flag, at + 1);
+  }
+  return false;
+}
+
+export interface StopResult {
+  profile: string;
+  pid?: number;
+  outcome: 'stopped' | 'cleaned' | 'failed' | 'skipped';
+  detail: string;
+}
+
+async function waitForProcessExit(pid: number, ms: number): Promise<boolean> {
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) return true;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  return !isProcessAlive(pid);
+}
+
+type TerminateResult =
+  | { outcome: 'stopped' }
+  | { outcome: 'not_pilot' }
+  | { outcome: 'failed'; detail: string };
+
+/**
+ * SIGTERM, then SIGKILL. The pid's identity is re-checked right before each
+ * signal: a process seen earlier can exit and its pid be reused while
+ * other browsers are being stopped.
+ */
+async function terminate(
+  pid: number,
+  userDataDir: string
+): Promise<TerminateResult> {
+  const signal = (sig: NodeJS.Signals): 'sent' | 'gone' | { error: string } => {
+    if (!isPilotChrome(pid, userDataDir)) return 'gone';
+    try {
+      process.kill(pid, sig);
+      return 'sent';
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ESRCH') return 'gone';
+      return { error: `could not send ${sig} to pid ${pid} (${code})` };
+    }
+  };
+
+  const term = signal('SIGTERM');
+  if (term === 'gone') {
+    return isProcessAlive(pid)
+      ? { outcome: 'not_pilot' }
+      : { outcome: 'stopped' };
+  }
+  if (typeof term === 'object')
+    return { outcome: 'failed', detail: term.error };
+  if (await waitForProcessExit(pid, 5000)) return { outcome: 'stopped' };
+
+  const kill = signal('SIGKILL');
+  if (kill === 'gone') {
+    // Only a confirmed exit counts as stopped. A live pid that no longer
+    // verifies (ps failed, or the process changed) is left alone.
+    return isProcessAlive(pid)
+      ? {
+          outcome: 'failed',
+          detail: `pid ${pid} did not exit after SIGTERM and could no longer be verified as Chrome using ${userDataDir}; not killed, lock kept`
+        }
+      : { outcome: 'stopped' };
+  }
+  if (typeof kill === 'object')
+    return { outcome: 'failed', detail: kill.error };
+  return (await waitForProcessExit(pid, 2000))
+    ? { outcome: 'stopped' }
+    : { outcome: 'failed', detail: `pid ${pid} did not exit after SIGKILL` };
+}
+
+/**
+ * Stop every Chrome on this host that holds a Pilot profile lock. Processes
+ * are only signalled after their command line confirms they use that
+ * profile's directory; nothing else is touched.
+ */
+export async function stopPilotBrowsers(): Promise<StopResult[]> {
+  const results: StopResult[] = [];
+  for (const status of listProfiles()) {
+    const { profile, pid } = status;
+    switch (status.state) {
+      case 'unlocked':
+        continue;
+      case 'stale': {
+        const removed = cleanupLockFiles(status.userDataDir, pid!);
+        results.push(
+          removed
+            ? {
+                profile,
+                pid,
+                outcome: 'cleaned',
+                detail: `removed stale lock left by pid ${pid}, which is no longer running`
+              }
+            : {
+                profile,
+                pid,
+                outcome: 'failed',
+                detail: `stale lock left by pid ${pid} could not be removed (the lock changed owner or is not writable)`
+              }
+        );
+        continue;
+      }
+      case 'locked_other_host':
+        results.push({
+          profile,
+          pid,
+          outcome: 'skipped',
+          detail: `locked by pid ${pid} on host "${status.host}"; Pilot can only stop browsers on this host`
+        });
+        continue;
+      case 'locked_unknown':
+        results.push({
+          profile,
+          outcome: 'skipped',
+          detail: 'lock files name no owner; left in place'
+        });
+        continue;
+      case 'locked':
+        results.push(await stopLockedProfile(status));
+    }
+  }
+  return results;
+}
+
+/** Stop the Chrome holding a profile lock, if it is verifiably Pilot's. */
+export async function stopLockedProfile(
+  status: ProfileStatus
+): Promise<StopResult> {
+  const { profile, pid, userDataDir } = status;
+  const notPilot: StopResult = {
+    profile,
+    pid,
+    outcome: 'skipped',
+    detail: `pid ${pid} holds the lock but its command line does not show Chrome using ${userDataDir}; not stopped`
+  };
+  if (pid === undefined || !status.pilotChrome) return notPilot;
+
+  const result = await terminate(pid, userDataDir);
+  if (result.outcome === 'not_pilot') return notPilot;
+  if (result.outcome === 'failed') {
+    return { profile, pid, outcome: 'failed', detail: result.detail };
+  }
+  const removed = cleanupLockFiles(userDataDir, pid);
+  return {
+    profile,
+    pid,
+    outcome: 'stopped',
+    detail: removed
+      ? `stopped Chrome pid ${pid}`
+      : `stopped Chrome pid ${pid}, but its lock could not be removed`
+  };
+}

package/src/browser/types.ts

@@ -28,5 +28,16 @@ export interface LaunchOptions {
   startupTimeoutMs?: number;
 }
 
+export interface SessionInfo {
+  /** launched: Chrome started by this session; external: browser_connect. */
+  mode: 'launched' | 'external' | 'none';
+  connected: boolean;
+  profile?: string;
+  userDataDir?: string;
+  pid?: number;
+  host?: string;
+  cdpPort?: number;
+}
+
 export type SandboxDecision =
   { disable: false } | { disable: true; reason: 'env_override' | 'root_user' };

package/src/cli/skill-template.ts

@@ -1,4 +1,4 @@
 // Generated by scripts/build-skill.mjs from skills/pilot/SKILL.md.
 // Do not edit this file directly.
 export const SKILL_CONTENT =
-  '---\nname: pilot\ndescription: 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.\n---\n\n# Pilot browser workflow\n\nUse the `pilot` MCP tools to operate Chrome through the Chrome DevTools Protocol.\n\n## Start and inspect\n\n1. 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.\n2. Navigate with `browser_navigate`, then confirm the result with `browser_page_info` or `browser_snapshot`.\n3. 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.\n4. 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.\n5. Call `browser_stop` when the browser is no longer needed.\n\nDo not enter credentials, submit consequential forms, upload files, or make other externally visible changes unless the user authorized that action.\n\n## Troubleshooting\n\n### Visible Chrome on Linux\n\nRun `pilot check` when `browser_start` fails. Visible Chrome requires `DISPLAY` or `WAYLAND_DISPLAY` in the Pilot MCP server process. Headless operation does not.\n\nIf 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:\n\n```toml\n[mcp_servers.pilot]\ncommand = "npx"\nargs = ["-y", "@everydaydevopsio/pilot"]\nenv = { DISPLAY = ":1" }\n```\n\nReplace `: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.\n\n### Other Linux preflight failures\n\n- If the profile directory is not writable, set `XDG_DATA_HOME` to a writable directory.\n- 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.\n- If Chrome is not detected, set `PILOT_CHROME_PATH` to its executable.\n- Avoid `PILOT_CHROME_NO_SANDBOX=true` unless the runtime genuinely cannot support Chrome\'s sandbox and the user accepts the security tradeoff.\n\n### Connection and page failures\n\n- Confirm the active page with `browser_page_info` and list tabs if Pilot controls the wrong tab.\n- Inspect failed document, script, XHR, and fetch requests with `browser_network`.\n- If element refs stop resolving after a page update, take another snapshot and retry with the new refs.\n';
+  '---\nname: pilot\ndescription: 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.\n---\n\n# Pilot browser workflow\n\nUse the `pilot` MCP tools to operate Chrome through the Chrome DevTools Protocol.\n\n## Start and inspect\n\n1. 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.\n2. Navigate with `browser_navigate`, then confirm the result with `browser_page_info` or `browser_snapshot`.\n3. 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.\n4. 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.\n5. Call `browser_stop` when the browser is no longer needed.\n\nDo not enter credentials, submit consequential forms, upload files, or make other externally visible changes unless the user authorized that action.\n\n## Troubleshooting\n\n### Visible Chrome on Linux\n\nRun `pilot check` when `browser_start` fails. Visible Chrome requires `DISPLAY` or `WAYLAND_DISPLAY` in the Pilot MCP server process. Headless operation does not.\n\nIf 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:\n\n```toml\n[mcp_servers.pilot]\ncommand = "npx"\nargs = ["-y", "@everydaydevopsio/pilot"]\nenv = { DISPLAY = ":1" }\n```\n\nReplace `: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.\n\n### Startup failures\n\nRead the `Launch:`, `Cleanup:`, and `Next:` lines in the `browser_start` error before retrying.\n\n- A failed `browser_start` stops the Chrome it launched and frees the profile unless `Cleanup:` names a pid that did not stop. Do not switch profiles just because a start failed.\n- On a timeout, retry once with a larger `startupTimeoutMs` (for example `180000`). First runs and software-rendered Linux desktops can be slow.\n- If Chrome exited in visible mode, check the display (above) or retry with `headless: true`.\n- If the profile is already in use, the error names the owning Chrome pid and host. `browser_stop` cannot stop a browser that this session did not launch. Call `browser_status` to see which profiles are free and who holds the others. Use a different `profileName`, or, only after the user agrees, call `browser_stop_all`. It also stops browsers that other agents may be using.\n\n### Other Linux preflight failures\n\n- If the profile directory is not writable, set `XDG_DATA_HOME` to a writable directory.\n- 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.\n- If Chrome is not detected, set `PILOT_CHROME_PATH` to its executable.\n- Avoid `PILOT_CHROME_NO_SANDBOX=true` unless the runtime genuinely cannot support Chrome\'s sandbox and the user accepts the security tradeoff.\n\n### Connection and page failures\n\n- Confirm the active page with `browser_page_info` and list tabs if Pilot controls the wrong tab.\n- Inspect failed document, script, XHR, and fetch requests with `browser_network`.\n- If element refs stop resolving after a page update, take another snapshot and retry with the new refs.\n';

package/src/mcp/tools/browser.ts

@@ -3,6 +3,12 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { Client } from 'chrome-remote-interface';
 import type { BrowserManager } from '../../browser.js';
 import type { BrowserContext } from '../server.js';
+import { DEFAULT_STARTUP_TIMEOUT_MS } from '../../browser/chrome-launcher.js';
+import {
+  listProfiles,
+  pilotDataDir,
+  stopPilotBrowsers
+} from '../../browser/sessions.js';
 import { executeScreenshot } from '../../commands/screenshot.js';
 import { executeNavigate } from '../../commands/navigate.js';
 import { executeClick } from '../../commands/click.js';
@@ -185,9 +191,9 @@ const startShape = {
     .number()
     .int()
     .positive()
-    .default(30000)
+    .default(DEFAULT_STARTUP_TIMEOUT_MS)
     .describe(
-      'Timeout waiting for Chrome DevTools to become ready, in milliseconds.'
+      `Timeout waiting for Chrome DevTools to become ready, in milliseconds. Defaults to ${DEFAULT_STARTUP_TIMEOUT_MS}. Startup fails immediately if Chrome exits, so raising this only helps when Chrome is slow to start (for example a first run on a Linux server with software rendering).`
     )
 };
 
@@ -323,7 +329,12 @@ export function registerBrowserTools(
     async () => {
       if (!context.manager) {
         return {
-          content: [{ type: 'text' as const, text: 'Browser is not running.' }]
+          content: [
+            {
+              type: 'text' as const,
+              text: 'Browser is not running. This Pilot session is not tracking a launched or connected browser; a failed browser_start stops the Chrome it launched and reports the outcome in its error.'
+            }
+          ]
         };
       }
 
@@ -336,6 +347,64 @@ export function registerBrowserTools(
     }
   );
 
+  server.tool(
+    'browser_status',
+    'Show the browser tracked by this Pilot session and the lock state of every Pilot profile on this machine (including browsers started by other Pilot sessions). Read-only. Use it to diagnose "profile already in use" errors.',
+    {},
+    async () => {
+      const status = {
+        session: context.manager?.getSessionInfo() ?? {
+          mode: 'none',
+          connected: false
+        },
+        dataDir: pilotDataDir(),
+        profiles: listProfiles()
+      };
+      return {
+        content: [
+          { type: 'text' as const, text: JSON.stringify(status, null, 2) }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_stop_all',
+    'Stop every Pilot-managed Chrome on this machine: the browser in this session plus any Chrome holding a Pilot profile lock, including ones started by other Pilot sessions. Only processes whose command line shows Chrome using a Pilot profile directory are stopped; browsers on other hosts and unverifiable locks are skipped. Also removes stale locks. Ask the user before calling this, since it can close browsers other agents are using.',
+    {},
+    async () => {
+      const lines: string[] = [];
+      if (context.manager) {
+        const info = context.manager.getSessionInfo();
+        await context.manager.destroy();
+        context.manager = null;
+        if (info.mode === 'launched') {
+          lines.push(
+            `this session: stopped Chrome pid ${info.pid} (profile "${info.profile}")`
+          );
+        } else if (info.mode === 'external') {
+          lines.push(
+            `this session: disconnected from ${info.host}:${info.cdpPort} (not stopped; Pilot did not launch it)`
+          );
+        }
+      }
+      for (const result of await stopPilotBrowsers()) {
+        lines.push(`${result.profile}: ${result.outcome} - ${result.detail}`);
+      }
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text:
+              lines.length > 0
+                ? lines.join('\n')
+                : 'No Pilot-managed browsers were running.'
+          }
+        ]
+      };
+    }
+  );
+
   server.tool(
     'browser_screenshot',
     'Capture a screenshot of the current browser viewport or full page',

package/src/mcp/tools/names.ts

@@ -5,6 +5,8 @@
 export const EXPECTED_TOOLS = [
   'browser_start',
   'browser_stop',
+  'browser_status',
+  'browser_stop_all',
   'browser_screenshot',
   'browser_navigate',
   'browser_click',