@everydaydevopsio/pilot 0.5.2 → 0.6.1

package/src/mcp/console-buffer.ts

@@ -1,11 +1,21 @@
 export type ConsoleLevel = 'log' | 'warn' | 'error' | 'info' | 'debug';
 
+export interface StackFrame {
+  url: string;
+  functionName: string;
+  lineNumber: number;
+  columnNumber: number;
+}
+
 export interface ConsoleMessage {
   level: ConsoleLevel;
   text: string;
   url: string;
   lineNumber: number;
+  columnNumber?: number;
   timestamp: number;
+  stackFrames?: StackFrame[];
+  isException?: boolean;
 }
 
 export interface ConsoleFilter {

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/server.ts

@@ -1,9 +1,29 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { BrowserManager } from '../browser.js';
+import { ElementRefMap } from '../browser/inspect/element-ref.js';
+import { resetCssState } from '../browser/inspect/styles.js';
+import { DialogQueue } from '../browser/interaction/dialogs.js';
+import { attachDialogHandler } from '../browser/interaction/dialogs.js';
+import {
+  DownloadTracker,
+  enableDownloads,
+  attachDownloadHandler
+} from '../browser/interaction/downloads.js';
+import { NetworkBuffer } from '../browser/network/network-buffer.js';
+import { attachNetworkMonitor } from '../browser/network/network-monitor.js';
 import { loadConfig } from '../util/config.js';
 import { ConsoleBuffer, type ConsoleMessage } from './console-buffer.js';
 import { registerBrowserTools } from './tools/browser.js';
 import { registerErrorTools } from './tools/errors.js';
+import { registerSnapshotTools } from './tools/snapshot.js';
+import { registerInteractionTools } from './tools/interaction.js';
+import { registerNetworkTools } from './tools/network.js';
+import { registerRuntimeTools } from './tools/runtime.js';
+import { registerStylesTools } from './tools/styles.js';
+import { registerFilesTools } from './tools/files.js';
+import { createTraceState } from '../browser/performance/trace.js';
+import { registerPerformanceTools } from './tools/performance.js';
+import { registerConnectTools } from './tools/connect.js';
 
 export interface McpConfig {
   bufferSize: number;
@@ -14,6 +34,11 @@ export interface McpConfig {
 export interface BrowserContext {
   manager: BrowserManager | null;
   consoleBuffer: ConsoleBuffer;
+  elementRefMap: ElementRefMap;
+  networkBuffer: NetworkBuffer;
+  dialogQueue: DialogQueue;
+  downloadTracker: DownloadTracker;
+  traceState: ReturnType<typeof createTraceState>;
   baseConfig: McpConfig;
 }
 
@@ -27,18 +52,57 @@ export async function createMcpServer(config: McpConfig): Promise<{
   });
 
   const consoleBuffer = new ConsoleBuffer(config.bufferSize);
+  const elementRefMap = new ElementRefMap();
+  const networkBuffer = new NetworkBuffer();
+  const dialogQueue = new DialogQueue();
+  const downloadTracker = new DownloadTracker();
+  const traceState = createTraceState();
 
   const context: BrowserContext = {
     manager: null,
     consoleBuffer,
+    elementRefMap,
+    networkBuffer,
+    dialogQueue,
+    downloadTracker,
+    traceState,
     baseConfig: config
   };
 
-  function attachConsoleBuffer(manager: BrowserManager): void {
+  function attachEventHandlers(manager: BrowserManager): void {
+    let monitoredClient: unknown = null;
+
+    function ensureMonitors(): void {
+      const client = manager.getClient();
+      if (client && client !== monitoredClient) {
+        attachNetworkMonitor(client, networkBuffer);
+        attachDialogHandler(client, dialogQueue);
+        attachDownloadHandler(client, downloadTracker);
+        void enableDownloads(client).catch(() => {
+          // Download behavior setup may fail in some environments
+        });
+        monitoredClient = client;
+      }
+    }
+
     manager.setEventCallback((event, data) => {
       if (event === 'console_message') {
         consoleBuffer.push(data as ConsoleMessage);
       }
+      if (event === 'page_navigated') {
+        elementRefMap.invalidate();
+      }
+      if (event === 'browser_connected') {
+        ensureMonitors();
+      }
+      if (event === 'browser_disconnected') {
+        monitoredClient = null;
+        resetCssState();
+        dialogQueue.clear();
+        downloadTracker.clear();
+      }
+      // Reattach after tab switch (new client, no connect event)
+      ensureMonitors();
     });
   }
 
@@ -48,12 +112,20 @@ export async function createMcpServer(config: McpConfig): Promise<{
       cdpHost: config.cdpHost
     });
     const manager = new BrowserManager(browserConfig);
-    attachConsoleBuffer(manager);
+    attachEventHandlers(manager);
     return manager;
   }
 
   registerBrowserTools(server, context, makeBrowserManager);
   registerErrorTools(server, consoleBuffer);
+  registerSnapshotTools(server, context);
+  registerInteractionTools(server, context);
+  registerNetworkTools(server, context);
+  registerRuntimeTools(server, consoleBuffer);
+  registerStylesTools(server, context);
+  registerFilesTools(server, context);
+  registerPerformanceTools(server, context);
+  registerConnectTools(server, context, makeBrowserManager);
 
   return {
     server,

package/src/mcp/tools/browser.ts

@@ -57,6 +57,10 @@ const navigateShape = {
 };
 
 const clickShape = {
+  ref: z
+    .string()
+    .optional()
+    .describe('Element ref from browser_snapshot (e.g. "e3")'),
   selector: z.string().optional().describe('CSS selector to click'),
   x: z.number().optional().describe('Viewport X coordinate'),
   y: z.number().optional().describe('Viewport Y coordinate'),
@@ -80,6 +84,10 @@ const clickShape = {
 
 const typeShape = {
   text: z.string().describe('Text to type'),
+  ref: z
+    .string()
+    .optional()
+    .describe('Element ref from browser_snapshot (e.g. "e3")'),
   selector: z.string().optional().describe('CSS selector to focus first'),
   clearFirst: z
     .boolean()
@@ -128,7 +136,7 @@ const startShape = {
     .boolean()
     .optional()
     .describe(
-      'Run Chrome headless. When omitted, falls back to PILOT_HEADLESS (default: true).'
+      'Run Chrome headless. When omitted, falls back to PILOT_HEADLESS (accepts true/1 or false/0; default: false).'
     ),
   chromePath: z
     .string()
@@ -172,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.'
     )
 };
 
@@ -190,6 +206,24 @@ const switchTabShape = {
   targetId: z.string().describe('Target ID of the tab to switch to')
 };
 
+const tabsShape = {
+  action: z
+    .enum(['list', 'new', 'select', 'close'])
+    .describe(
+      'Action: list tabs, open new tab, select/switch tab, or close tab'
+    ),
+  targetId: z
+    .string()
+    .optional()
+    .describe('Target ID (required for select and close actions)'),
+  url: z
+    .string()
+    .optional()
+    .describe(
+      'URL to open in the new tab (new action only, opens blank tab if omitted)'
+    )
+};
+
 const viewportResizeShape = {
   width: z.number().int().positive().describe('New viewport width in pixels'),
   height: z.number().int().positive().describe('New viewport height in pixels'),
@@ -237,7 +271,8 @@ export function registerBrowserTools(
       viewportWidth,
       viewportHeight,
       deviceScaleFactor,
-      responsive
+      responsive,
+      startupTimeoutMs
     }) => {
       if (context.manager?.isConnected()) {
         return {
@@ -265,7 +300,8 @@ export function registerBrowserTools(
           viewportWidth,
           viewportHeight,
           deviceScaleFactor,
-          responsive
+          responsive,
+          startupTimeoutMs
         });
       context.manager = manager;
 
@@ -361,10 +397,11 @@ export function registerBrowserTools(
 
   server.tool(
     'browser_click',
-    'Click an element by CSS selector or coordinates. Either selector or x/y coordinates required.',
+    'Click an element by ref (from browser_snapshot), CSS selector, or coordinates.',
     clickShape,
     async (params) => {
       if (
+        params.ref === undefined &&
         params.selector === undefined &&
         (params.x === undefined || params.y === undefined)
       ) {
@@ -372,7 +409,7 @@ export function registerBrowserTools(
           content: [
             {
               type: 'text' as const,
-              text: 'Error: Either selector or x/y coordinates are required'
+              text: 'Error: Either ref, selector, or x/y coordinates are required'
             }
           ],
           isError: true
@@ -380,7 +417,7 @@ export function registerBrowserTools(
       }
 
       const { client } = requireClient(context);
-      const result = await executeClick(client, params);
+      const result = await executeClick(client, params, context.elementRefMap);
 
       return {
         content: [
@@ -395,17 +432,18 @@ export function registerBrowserTools(
 
   server.tool(
     'browser_type',
-    'Type text into the focused element or a specified selector',
+    'Type text into the focused element, a ref (from browser_snapshot), or a CSS selector. Generates keystroke events (use browser_fill to replace a field value entirely).',
     typeShape,
     async (params) => {
       const { client } = requireClient(context);
-      await executeType(client, params);
+      await executeType(client, params, context.elementRefMap);
 
+      const target = params.ref ?? params.selector;
       return {
         content: [
           {
             type: 'text' as const,
-            text: `Typed "${params.text}"${params.selector ? ` into ${params.selector}` : ''}`
+            text: `Typed "${params.text}"${target ? ` into ${target}` : ''}`
           }
         ]
       };
@@ -602,4 +640,82 @@ export function registerBrowserTools(
       };
     }
   );
+
+  server.tool(
+    'browser_tabs',
+    'Manage browser tabs. Actions: "list" shows all tabs, "new" opens a tab (optional url), "select" switches to a tab (requires targetId), "close" closes a tab (requires targetId).',
+    tabsShape,
+    async ({ action, targetId, url }) => {
+      const { manager } = requireClient(context);
+
+      switch (action) {
+        case 'list': {
+          const tabs = await executeListTabs(manager);
+          return {
+            content: [
+              { type: 'text' as const, text: JSON.stringify(tabs, null, 2) }
+            ]
+          };
+        }
+
+        case 'new': {
+          const result = await executeNewTab(manager, url);
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `New tab opened (targetId: ${result.targetId}, url: ${result.url})`
+              }
+            ]
+          };
+        }
+
+        case 'select': {
+          if (!targetId) {
+            return {
+              content: [
+                {
+                  type: 'text' as const,
+                  text: 'Error: targetId is required for select action'
+                }
+              ],
+              isError: true
+            };
+          }
+          await executeSwitchTab(manager, targetId);
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `Switched to tab ${targetId}.`
+              }
+            ]
+          };
+        }
+
+        case 'close': {
+          if (!targetId) {
+            return {
+              content: [
+                {
+                  type: 'text' as const,
+                  text: 'Error: targetId is required for close action'
+                }
+              ],
+              isError: true
+            };
+          }
+          await executeCloseTab(manager, targetId);
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `Tab ${targetId} closed.`
+              }
+            ]
+          };
+        }
+      }
+    }
+  );
 }

package/src/mcp/tools/connect.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BrowserContext } from '../server.js';
+import type { BrowserManager } from '../../browser/browser-manager.js';
+import { executeConnect, formatConnectResult } from '../../commands/connect.js';
+
+const connectShape = {
+  host: z
+    .string()
+    .default('127.0.0.1')
+    .describe('Chrome debugging host (default: 127.0.0.1)'),
+  port: z
+    .number()
+    .int()
+    .min(1)
+    .max(65535)
+    .default(9222)
+    .describe('Chrome debugging port (default: 9222)')
+};
+
+export function registerConnectTools(
+  server: McpServer,
+  context: BrowserContext,
+  makeBrowserManager: () => BrowserManager
+): void {
+  server.tool(
+    'browser_connect',
+    'Connect to an existing Chrome instance with remote debugging enabled. Start Chrome with --remote-debugging-port=PORT, then use this tool to connect. Lists available tabs after connecting. Use browser_switch_tab to select a specific tab.',
+    connectShape,
+    async ({ host, port }) => {
+      if (context.manager?.isConnected()) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'Already connected to a browser. Call browser_stop to disconnect first.'
+            }
+          ]
+        };
+      }
+
+      if (context.manager) {
+        await context.manager.destroy();
+        context.manager = null;
+      }
+
+      const manager = makeBrowserManager();
+      try {
+        const result = await executeConnect(manager, { host, port });
+        context.manager = manager;
+        return {
+          content: [
+            { type: 'text' as const, text: formatConnectResult(result) }
+          ]
+        };
+      } catch (err) {
+        await manager.destroy();
+        throw err;
+      }
+    }
+  );
+}

package/src/mcp/tools/files.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BrowserContext } from '../server.js';
+import { executeDialog, formatDialogResult } from '../../commands/dialog.js';
+import { executeUpload } from '../../commands/upload.js';
+import {
+  executeDownloads,
+  formatDownloadsResult
+} from '../../commands/downloads.js';
+
+const dialogShape = {
+  action: z
+    .enum(['list', 'accept', 'dismiss'])
+    .describe(
+      'Action: list pending dialogs, accept (OK/Yes), or dismiss (Cancel/No)'
+    ),
+  promptText: z
+    .string()
+    .optional()
+    .describe('Text to enter for prompt dialogs (accept action only)')
+};
+
+const uploadShape = {
+  ref: z
+    .string()
+    .describe('Element ref of a file input (from browser_snapshot)'),
+  files: z
+    .array(z.string())
+    .describe(
+      'File paths to upload. Must exist, be regular files, and be under PILOT_UPLOAD_ROOTS (default: cwd).'
+    )
+};
+
+const downloadsShape = {
+  action: z
+    .enum(['list', 'wait', 'clear'])
+    .describe(
+      'Action: list tracked downloads, wait for one to complete, or clear'
+    ),
+  guid: z
+    .string()
+    .optional()
+    .describe('Download GUID (required for wait action)'),
+  timeoutMs: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Timeout for wait action in milliseconds (default: 30000)')
+};
+
+function requireContext(context: BrowserContext) {
+  const manager = context.manager;
+  if (!manager || !manager.isConnected()) {
+    throw new Error('Browser not started. Call browser_start first.');
+  }
+  const client = manager.getClient()!;
+  return { client };
+}
+
+export function registerFilesTools(
+  server: McpServer,
+  context: BrowserContext
+): void {
+  server.tool(
+    'browser_dialog',
+    'Handle browser dialogs (alert, confirm, prompt). Use "list" to see pending dialogs, "accept" to click OK/Yes, or "dismiss" to click Cancel/No. For prompt dialogs, provide promptText with accept.',
+    dialogShape,
+    async ({ action, promptText }) => {
+      const { client } = requireContext(context);
+      const result = await executeDialog(client, context.dialogQueue, {
+        action,
+        promptText
+      });
+      return {
+        content: [{ type: 'text' as const, text: formatDialogResult(result) }]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_upload',
+    'Upload files to a file input element by ref. Files must exist, be regular files, and be under allowed roots (PILOT_UPLOAD_ROOTS env, default: cwd). Use browser_snapshot to find file input refs.',
+    uploadShape,
+    async ({ ref, files }) => {
+      const { client } = requireContext(context);
+      const result = await executeUpload(client, context.elementRefMap, {
+        ref,
+        files
+      });
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Uploaded ${result.files.length} file(s) to ${result.ref}`
+          }
+        ]
+      };
+    }
+  );
+
+  server.tool(
+    'browser_downloads',
+    'Track file downloads. Actions: "list" shows tracked downloads with status/progress; "wait" blocks until a download (by GUID) completes; "clear" resets the tracker.',
+    downloadsShape,
+    async ({ action, guid, timeoutMs }) => {
+      requireContext(context);
+      const result = await executeDownloads(context.downloadTracker, {
+        action,
+        guid,
+        timeoutMs
+      });
+      return {
+        content: [
+          { type: 'text' as const, text: formatDownloadsResult(result) }
+        ]
+      };
+    }
+  );
+}