@everydaydevopsio/pilot 0.6.0 → 0.6.2

package/src/browser/preflight.ts

@@ -0,0 +1,144 @@
+import { constants } from 'fs';
+import { access, mkdir } from 'fs/promises';
+import { request } from 'https';
+import {
+  findChromeExecutable,
+  findFreePort,
+  resolveUserDataDir
+} from './chrome-launcher.js';
+
+export interface LinuxCheckResult {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+export interface LinuxCheckOptions {
+  headless: boolean;
+  chromePath?: string;
+  profileName: string;
+  checkNetwork?: boolean;
+}
+
+export function checkDisplay(headless: boolean): LinuxCheckResult {
+  if (headless) {
+    return {
+      name: 'display',
+      ok: true,
+      detail: 'not required in headless mode'
+    };
+  }
+  const display = process.env.DISPLAY || process.env.WAYLAND_DISPLAY;
+  return display
+    ? { name: 'display', ok: true, detail: display }
+    : {
+        name: 'display',
+        ok: false,
+        detail:
+          'headless:false requires DISPLAY or WAYLAND_DISPLAY; use a desktop session, xvfb-run, or headless:true'
+      };
+}
+
+export async function checkChrome(
+  chromePath?: string
+): Promise<LinuxCheckResult> {
+  try {
+    const resolved = findChromeExecutable(chromePath);
+    await access(resolved, constants.X_OK);
+    return { name: 'chrome', ok: true, detail: resolved };
+  } catch (error) {
+    return { name: 'chrome', ok: false, detail: String(error) };
+  }
+}
+
+export async function checkProfile(
+  profileName: string
+): Promise<LinuxCheckResult> {
+  let profileDir: string;
+  try {
+    profileDir = resolveUserDataDir(profileName);
+  } catch (error) {
+    return { name: 'profile', ok: false, detail: String(error) };
+  }
+
+  try {
+    await mkdir(profileDir, { recursive: true });
+    await access(profileDir, constants.R_OK | constants.W_OK | constants.X_OK);
+    return { name: 'profile', ok: true, detail: profileDir };
+  } catch (error) {
+    return {
+      name: 'profile',
+      ok: false,
+      detail: `${profileDir} is not writable: ${String(error)}; set XDG_DATA_HOME to a writable directory`
+    };
+  }
+}
+
+export async function checkLoopback(): Promise<LinuxCheckResult> {
+  try {
+    const port = await findFreePort();
+    return { name: 'loopback', ok: true, detail: `127.0.0.1:${port}` };
+  } catch (error) {
+    return {
+      name: 'loopback',
+      ok: false,
+      detail: `${String(error)}; Pilot requires permission to bind an ephemeral CDP port on 127.0.0.1`
+    };
+  }
+}
+
+export async function checkOutboundHttps(
+  timeoutMs = 5000,
+  requestFn: typeof request = request
+): Promise<LinuxCheckResult> {
+  return new Promise((resolve) => {
+    const req = requestFn(
+      'https://clients3.google.com/generate_204',
+      { method: 'HEAD', timeout: timeoutMs },
+      (response) => {
+        response.resume();
+        resolve({
+          name: 'network',
+          ok: response.statusCode === 204,
+          detail: `HTTPS status ${response.statusCode ?? 'unknown'} (expected 204)`
+        });
+      }
+    );
+    req.on('timeout', () =>
+      req.destroy(new Error(`timeout after ${timeoutMs}ms`))
+    );
+    req.on('error', (error) =>
+      resolve({ name: 'network', ok: false, detail: String(error) })
+    );
+    req.end();
+  });
+}
+
+export async function runLinuxChecks(
+  options: LinuxCheckOptions
+): Promise<LinuxCheckResult[]> {
+  if (process.platform !== 'linux') return [];
+  const checks = await Promise.all([
+    checkChrome(options.chromePath),
+    Promise.resolve(checkDisplay(options.headless)),
+    checkProfile(options.profileName),
+    checkLoopback()
+  ]);
+  if (options.checkNetwork !== false) checks.push(await checkOutboundHttps());
+  return checks;
+}
+
+export async function assertLinuxBrowserPrerequisites(
+  options: LinuxCheckOptions
+): Promise<void> {
+  if (process.platform !== 'linux') return;
+  const checks = await runLinuxChecks({ ...options, checkNetwork: false });
+  const failures = checks.filter((check) => !check.ok);
+  if (failures.length > 0) {
+    throw new Error(
+      `Linux browser preflight failed:\n${failures
+        .map((failure) => `- ${failure.name}: ${failure.detail}`)
+        .join('\n')}\nRun "pilot check" for complete diagnostics.`
+    );
+  }
+}

package/src/browser/types.ts

@@ -25,6 +25,7 @@ export interface LaunchOptions {
   viewportHeight?: number;
   deviceScaleFactor?: number;
   responsive?: boolean;
+  startupTimeoutMs?: number;
 }
 
 export type SandboxDecision =

package/src/cli/init.ts

@@ -1,62 +1,53 @@
-import { mkdir, writeFile, stat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { SKILL_CONTENT } from './skill-template.js';
 
-const SKILL_DIR = '.claude/skills/debug-browser';
-const SKILL_FILE = 'SKILL.md';
+export type SkillAgent = 'claude' | 'codex' | 'both';
+
+const SKILL_DIRS: Record<Exclude<SkillAgent, 'both'>, string> = {
+  claude: '.claude/skills/pilot',
+  codex: '.agents/skills/pilot'
+};
 
 export async function runInit(
-  options: { force?: boolean } = {}
+  options: { force?: boolean; agent?: SkillAgent; cwd?: string } = {}
 ): Promise<void> {
-  const cwd = process.cwd();
-  const skillDir = join(cwd, SKILL_DIR);
-  const skillPath = join(skillDir, SKILL_FILE);
+  const cwd = options.cwd ?? process.cwd();
+  const agent = options.agent ?? 'claude';
+  const agents: Array<Exclude<SkillAgent, 'both'>> =
+    agent === 'both' ? ['claude', 'codex'] : [agent];
+  const skillPaths = agents.map((target) => ({
+    target,
+    path: join(cwd, SKILL_DIRS[target], 'SKILL.md')
+  }));
 
-  // Check if skill already exists
-  try {
-    await stat(skillPath);
-    if (!options.force) {
-      console.log(`\x1b[33mSkill already exists:\x1b[0m ${skillPath}`);
-      console.log('Use --force to overwrite.');
-      process.exit(1);
+  for (const skill of skillPaths) {
+    try {
+      await stat(skill.path);
+      if (!options.force) {
+        throw new Error(
+          `Skill already exists: ${skill.path}\nUse --force to overwrite.`
+        );
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        continue;
+      }
+      throw error;
     }
-  } catch {
-    // File doesn't exist, continue
-  }
-
-  // Create directory structure
-  try {
-    await mkdir(skillDir, { recursive: true });
-  } catch (err) {
-    console.error(`\x1b[31mFailed to create directory:\x1b[0m ${skillDir}`);
-    console.error(err);
-    process.exit(1);
   }
 
-  // Write SKILL.md
-  try {
-    await writeFile(skillPath, SKILL_CONTENT, 'utf-8');
-  } catch (err) {
-    console.error(`\x1b[31mFailed to write skill file:\x1b[0m ${skillPath}`);
-    console.error(err);
-    process.exit(1);
+  for (const skill of skillPaths) {
+    await mkdir(dirname(skill.path), { recursive: true });
+    await writeFile(skill.path, SKILL_CONTENT, 'utf8');
+    console.log(
+      `\x1b[32m✓ Installed Pilot skill for ${skill.target}:\x1b[0m ${skill.path}`
+    );
   }
 
-  // Success message
-  console.log(`\x1b[32m✓ Created Claude Code skill:\x1b[0m ${skillPath}`);
-  console.log('');
-  console.log('\x1b[1mUsage:\x1b[0m');
-  console.log('  In Claude Code, say "debug in browser" or use /debug-browser');
-  console.log('');
-  console.log('\x1b[1mThe skill will:\x1b[0m');
-  console.log('  1. Start Chrome with remote debugging');
-  console.log('  2. Launch the pilot browser service');
-  console.log('  3. Add the MCP server to your session');
-  console.log('  4. Spawn an error-watching sub-agent');
   console.log('');
-  console.log('\x1b[1mPrerequisites:\x1b[0m');
-  console.log('  - Google Chrome installed');
-  console.log(
-    '  - pilot (install with: npm install -g @everydaydevopsio/pilot)'
-  );
+  console.log('\x1b[1mNext steps:\x1b[0m');
+  console.log('  1. Configure the pilot MCP server for your agent.');
+  console.log('  2. Restart the agent so it discovers the installed skill.');
+  console.log('  3. Ask it to use Pilot to open or debug a web page.');
 }

package/src/cli/linux-check.ts

@@ -0,0 +1,23 @@
+import { runLinuxChecks } from '../browser/preflight.js';
+
+export async function runCheck(): Promise<void> {
+  if (process.platform !== 'linux') {
+    console.log(
+      'pilot check: Linux preflight is not required on this platform.'
+    );
+    return;
+  }
+  const { loadConfig } = await import('../util/config.js');
+  const config = loadConfig();
+  const checks = await runLinuxChecks({
+    headless: config.headless,
+    chromePath: config.chromePath,
+    profileName: config.profileName
+  });
+  for (const check of checks) {
+    console.log(
+      `[${check.ok ? 'PASS' : 'FAIL'}] ${check.name}: ${check.detail}`
+    );
+  }
+  if (checks.some((check) => !check.ok)) process.exitCode = 1;
+}

package/src/cli/skill-template.ts

@@ -1,113 +1,4 @@
-export const SKILL_CONTENT = `---
-name: debug-browser
-description: Add the pilot MCP server and watch for console errors. Use this skill when the user wants to debug a web application, watch for JavaScript errors, or test their app with AI assistance.
-tools:
-  - Bash
-  - Task
----
-
-# Debug Browser Skill
-
-This skill sets up a browser debugging environment for AI-assisted development using the pilot MCP server. The MCP server manages the Chrome lifecycle automatically via \`browser_start\`.
-
-## What This Skill Does
-
-1. Adds the pilot MCP server to your Claude Code session
-2. Starts the browser via \`browser_start\`
-3. Spawns a sub-agent to watch for console errors
-
-## Instructions
-
-Follow these steps in order.
-
-### Step 1: Add MCP Server to Claude Code Session
-
-Add the pilot MCP server to the current Claude Code session:
-
-\`\`\`bash
-claude mcp add pilot --scope session -- npx @everydaydevopsio/pilot
-\`\`\`
-
-This gives you access to browser control tools like:
-- \`browser_start\` - Launch Chrome
-- \`browser_stop\` - Stop Chrome
-- \`browser_screenshot\` - Capture screenshots
-- \`browser_navigate\` - Navigate to URLs
-- \`browser_click\` - Click elements
-- \`browser_type\` - Type text
-- \`browser_evaluate\` - Run JavaScript
-- \`browser_get_errors\` - Get console errors
-- \`browser_clear_errors\` - Clear error buffer
-
-### Step 2: Start the Browser
-
-Use the \`browser_start\` MCP tool to launch Chrome:
-
-\`\`\`
-Call browser_start with headless: false to open a visible Chrome window.
-\`\`\`
-
-### Step 3: Spawn Error-Watching Sub-Agent
-
-Use the Task tool to spawn a background sub-agent that monitors for console errors:
-
-\`\`\`
-Spawn a sub-agent with subagent_type "general-purpose" and run_in_background: true with this prompt:
-
-"You are an error-watching agent monitoring the browser for console errors.
-
-Your job:
-1. First, call browser_clear_errors to start with a clean slate
-2. Report back that monitoring has started
-3. Every 15-20 seconds, call browser_get_errors with includeWarnings: true
-4. If you find errors, report them with:
-   - The error message
-   - The source file and line number
-   - A brief analysis of what might be wrong
-5. Continue monitoring until the main conversation ends
-
-Be concise but informative when reporting errors."
-\`\`\`
-
-### Step 4: Inform the User
-
-Tell the user:
-- The browser debugging environment is ready
-- They can navigate to their app using \`browser_navigate\`
-- You will be notified of any console errors automatically
-- They can ask you to take screenshots, click elements, or run JavaScript
-
-## Cleanup
-
-When done debugging, call \`browser_stop\` to shut down Chrome cleanly.
-
-## Troubleshooting
-
-### browser_start fails
-- Check if Chrome is installed: the MCP server auto-detects common paths
-- Set \`PILOT_CHROME_PATH\` env var to the Chrome executable if auto-detect fails
-
-### No errors detected
-- Errors are only captured while connected
-- Try \`browser_get_errors\` with \`includeWarnings: true\` to see all console output
-- Verify the page has loaded: \`browser_page_info\`
-
-## Example Session
-
-User: "debug in browser"
-
-Claude executes:
-1. Adds MCP server to session
-2. Calls \`browser_start\` (headless: false)
-3. Spawns error-watching sub-agent
-4. Reports: "Browser debugging environment ready! Navigate to your app and I'll watch for errors."
-
-User: "go to localhost:3000"
-Claude: Uses \`browser_navigate\` to go to http://localhost:3000
-
-[User interacts with the app, an error occurs]
-
-Sub-agent reports: "Error detected: TypeError: Cannot read property 'map' of undefined at App.tsx:42"
-
-Claude: Reads App.tsx, identifies the bug, suggests a fix.
-`;
+// 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';

package/src/mcp/index.ts

@@ -28,8 +28,12 @@ async function run(): Promise<void> {
     console.log('Usage: pilot [command] [options]');
     console.log('');
     console.log('Commands:');
+    console.log('  init [--agent claude|codex|both] [--force]');
     console.log(
-      '  init [--force]    Install the Claude Code debug-browser skill'
+      '                    Install the Pilot skill (default: claude)'
+    );
+    console.log(
+      '  check             Run Linux browser-launch preflight checks'
     );
     console.log('  (default)         Start the MCP server on stdio');
     console.log('');
@@ -74,7 +78,25 @@ async function run(): Promise<void> {
   if (subcommand === 'init') {
     const { runInit } = await import('../cli/init.js');
     const force = args.includes('--force');
-    await runInit({ force });
+    const agentArg = args.find((arg) => arg.startsWith('--agent='));
+    const agentIndex = args.indexOf('--agent');
+    const agent =
+      agentArg?.slice('--agent='.length) ??
+      (agentIndex >= 0 ? args[agentIndex + 1] : undefined) ??
+      'claude';
+    if (!['claude', 'codex', 'both'].includes(agent)) {
+      throw new Error('--agent must be one of: claude, codex, both');
+    }
+    await runInit({
+      force,
+      agent: agent as 'claude' | 'codex' | 'both'
+    });
+    return;
+  }
+
+  if (subcommand === 'check') {
+    const { runCheck } = await import('../cli/linux-check.js');
+    await runCheck();
     return;
   }
 

package/src/mcp/tools/browser.ts

@@ -180,6 +180,14 @@ const startShape = {
     .optional()
     .describe(
       'Responsive mode. When true, the page uses real window dimensions and reflows on resize (like a normal browser). Desktop presets default to true; mobile/tablet presets leave this unset (locked viewport). Set to false to lock the viewport with setDeviceMetricsOverride.'
+    ),
+  startupTimeoutMs: z
+    .number()
+    .int()
+    .positive()
+    .default(30000)
+    .describe(
+      'Timeout waiting for Chrome DevTools to become ready, in milliseconds.'
     )
 };
 
@@ -263,7 +271,8 @@ export function registerBrowserTools(
       viewportWidth,
       viewportHeight,
       deviceScaleFactor,
-      responsive
+      responsive,
+      startupTimeoutMs
     }) => {
       if (context.manager?.isConnected()) {
         return {
@@ -291,7 +300,8 @@ export function registerBrowserTools(
           viewportWidth,
           viewportHeight,
           deviceScaleFactor,
-          responsive
+          responsive,
+          startupTimeoutMs
         });
       context.manager = manager;