browser-pilot 0.0.9 → 0.0.10

package/README.md

@@ -376,6 +376,7 @@ bp exec --dialog accept '{"action":"click","selector":"#delete-btn"}'
 # Other commands
 bp text -s my-session --selector ".main-content"
 bp screenshot -s my-session --output page.png
+bp listen ws -m "*voice*"  # monitor WebSocket traffic
 bp list                    # list all sessions
 bp close -s my-session     # close session
 bp actions                 # show complete action reference

package/dist/cli.mjs

@@ -7487,6 +7487,357 @@ function getAge(date) {
   return `${days}d ago`;
 }
 
+// src/cli/commands/listen.ts
+var LISTEN_HELP = `
+bp listen - Monitor network traffic (WebSocket/HTTP)
+
+Attach to a browser session and stream network events as JSONL.
+Status messages go to stderr; stdout is clean JSONL (pipeable to jq).
+
+Usage:
+  bp listen <mode> [options]
+
+Modes:
+  ws      WebSocket traffic only
+  http    HTTP requests/responses only
+  all     Both WebSocket and HTTP
+
+Options:
+  -s, --session [id]     Session to use (omit: auto-connect, -s: latest, -s <id>: specific)
+  -m, --match <glob>     Filter by URL glob pattern (e.g. "*realtime*")
+  -o, --output <file>    Write JSONL to file instead of stdout
+  --max-payload <n>      Max text payload preview length (default: 256)
+  --timeout <ms>         Auto-stop after N milliseconds
+  -q, --quiet            Suppress stderr status messages
+  -h, --help             Show this help
+
+Output Format (JSONL):
+  {"ts":"...","type":"ws:created","requestId":"1.2","url":"wss://..."}
+  {"ts":"...","type":"ws:frame:sent","requestId":"1.2","opcode":1,"length":142,"payload":"..."}
+  {"ts":"...","type":"ws:frame:recv","requestId":"1.2","opcode":2,"length":24000,"payload":"[binary: 18000 bytes]"}
+  {"ts":"...","type":"ws:closed","requestId":"1.2"}
+  {"ts":"...","type":"http:request","requestId":"3.1","method":"POST","url":"https://..."}
+  {"ts":"...","type":"http:response","requestId":"3.1","status":200,"mimeType":"application/json"}
+
+Examples:
+  # Debug a voice agent's WebSocket protocol
+  bp listen ws -m "*voice*" -o voice-traffic.jsonl
+
+  # Watch all API calls during a session
+  bp listen http -m "*/api/*" --max-payload 1024
+
+  # Capture everything for 60 seconds
+  bp listen all -o full-trace.jsonl --timeout 60000
+
+  # Pipe to jq for live filtering
+  bp listen ws | jq 'select(.type == "ws:frame:recv")'
+`;
+function parseListenArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-m" || arg === "--match") {
+      options.match = args[++i];
+    } else if (arg === "-o" || arg === "--output") {
+      options.output = args[++i];
+    } else if (arg === "--max-payload") {
+      options.maxPayload = Number.parseInt(args[++i] ?? "", 10);
+    } else if (arg === "--timeout") {
+      options.timeout = Number.parseInt(args[++i] ?? "", 10);
+    } else if (arg === "-q" || arg === "--quiet") {
+      options.quiet = true;
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "-s" || arg === "--session") {
+      const nextArg = args[i + 1];
+      if (!nextArg || nextArg.startsWith("-")) {
+        options.useLatestSession = true;
+      }
+    } else if (!arg.startsWith("-") && !options.mode) {
+      if (arg === "ws" || arg === "http" || arg === "all") {
+        options.mode = arg;
+      }
+    }
+  }
+  return options;
+}
+function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const withWildcards = escaped.replace(/\*/g, ".*");
+  return new RegExp(`^${withWildcards}$`);
+}
+var TrafficMonitor = class {
+  cdp;
+  opts;
+  matchRegex;
+  wsUrls = /* @__PURE__ */ new Map();
+  httpUrls = /* @__PURE__ */ new Map();
+  handlers = [];
+  lineCount = 0;
+  constructor(cdp, opts) {
+    this.cdp = cdp;
+    this.opts = opts;
+    this.matchRegex = opts.match ? globToRegex(opts.match) : null;
+  }
+  emit(record) {
+    this.opts.write(JSON.stringify(record));
+    this.lineCount++;
+  }
+  matchesUrl(url) {
+    if (!this.matchRegex) return true;
+    return this.matchRegex.test(url);
+  }
+  formatPayload(payloadData, opcode) {
+    const data = payloadData ?? "";
+    if (opcode === 2) {
+      const byteLength = Math.floor(data.length * 3 / 4);
+      return { payload: `[binary: ${byteLength} bytes]`, length: data.length };
+    }
+    const length = data.length;
+    if (length > this.opts.maxPayload) {
+      return {
+        payload: `${data.slice(0, this.opts.maxPayload)}... [truncated, ${length} total]`,
+        length
+      };
+    }
+    return { payload: data, length };
+  }
+  subscribe(event, handler) {
+    this.cdp.on(event, handler);
+    this.handlers.push({ event, handler });
+  }
+  start() {
+    const mode = this.opts.mode;
+    if (mode === "ws" || mode === "all") {
+      this.subscribe("Network.webSocketCreated", (params) => {
+        const url = params["url"];
+        const requestId = params["requestId"];
+        if (!this.matchesUrl(url)) return;
+        this.wsUrls.set(requestId, url);
+        this.emit({
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          type: "ws:created",
+          requestId,
+          url
+        });
+      });
+      this.subscribe("Network.webSocketFrameSent", (params) => {
+        const requestId = params["requestId"];
+        if (!this.wsUrls.has(requestId)) return;
+        const response = params["response"];
+        const opcode = response?.opcode ?? 1;
+        const { payload, length } = this.formatPayload(response?.payloadData, opcode);
+        this.emit({
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          type: "ws:frame:sent",
+          requestId,
+          opcode,
+          length,
+          payload
+        });
+      });
+      this.subscribe("Network.webSocketFrameReceived", (params) => {
+        const requestId = params["requestId"];
+        if (!this.wsUrls.has(requestId)) return;
+        const response = params["response"];
+        const opcode = response?.opcode ?? 1;
+        const { payload, length } = this.formatPayload(response?.payloadData, opcode);
+        this.emit({
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          type: "ws:frame:recv",
+          requestId,
+          opcode,
+          length,
+          payload
+        });
+      });
+      this.subscribe("Network.webSocketClosed", (params) => {
+        const requestId = params["requestId"];
+        if (!this.wsUrls.has(requestId)) return;
+        this.wsUrls.delete(requestId);
+        this.emit({
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          type: "ws:closed",
+          requestId
+        });
+      });
+    }
+    if (mode === "http" || mode === "all") {
+      this.subscribe("Network.requestWillBeSent", (params) => {
+        const request = params["request"];
+        const url = request?.url ?? "";
+        const requestId = params["requestId"];
+        if (!this.matchesUrl(url)) return;
+        this.httpUrls.set(requestId, url);
+        this.emit({
+          ts: params["wallTime"] ? new Date(params["wallTime"] * 1e3).toISOString() : (/* @__PURE__ */ new Date()).toISOString(),
+          type: "http:request",
+          requestId,
+          method: request?.method ?? "GET",
+          url
+        });
+      });
+      this.subscribe("Network.responseReceived", (params) => {
+        const requestId = params["requestId"];
+        if (!this.httpUrls.has(requestId)) return;
+        const response = params["response"];
+        this.emit({
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          type: "http:response",
+          requestId,
+          status: response?.status ?? 0,
+          mimeType: response?.mimeType ?? ""
+        });
+      });
+      this.subscribe("Network.loadingFailed", (params) => {
+        const requestId = params["requestId"];
+        if (!this.httpUrls.has(requestId)) return;
+        this.emit({
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          type: "http:failed",
+          requestId,
+          errorText: params["errorText"] ?? ""
+        });
+      });
+    }
+  }
+  stop() {
+    for (const { event, handler } of this.handlers) {
+      this.cdp.off(event, handler);
+    }
+    this.handlers = [];
+  }
+};
+async function resolveConnection2(sessionId, useLatestSession, trace) {
+  if (sessionId) {
+    const session2 = await loadSession(sessionId);
+    const browser2 = await connect({
+      provider: session2.provider,
+      wsUrl: session2.wsUrl,
+      debug: trace
+    });
+    return { browser: browser2, session: session2 };
+  }
+  if (useLatestSession) {
+    const session2 = await getDefaultSession();
+    if (!session2) {
+      throw new Error('No sessions found. Run "bp connect" first or omit -s to auto-connect.');
+    }
+    const browser2 = await connect({
+      provider: session2.provider,
+      wsUrl: session2.wsUrl,
+      debug: trace
+    });
+    return { browser: browser2, session: session2 };
+  }
+  let wsUrl;
+  try {
+    wsUrl = await getBrowserWebSocketUrl("localhost:9222");
+  } catch {
+    throw new Error(
+      "Could not auto-discover browser.\nEither:\n  1. Start Chrome with: --remote-debugging-port=9222\n  2. Use an existing session: bp listen -s <session-id>\n  3. Use latest session: bp listen -s"
+    );
+  }
+  const browser = await connect({ provider: "generic", wsUrl, debug: trace });
+  const page = await browser.page();
+  const currentUrl = await page.url();
+  const newSessionId = generateSessionId();
+  const session = {
+    id: newSessionId,
+    provider: "generic",
+    wsUrl: browser.wsUrl,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastActivity: (/* @__PURE__ */ new Date()).toISOString(),
+    currentUrl
+  };
+  await saveSession(session);
+  return { browser, session };
+}
+async function listenCommand(args, globalOptions) {
+  const options = parseListenArgs(args);
+  if (options.help || globalOptions.help || !options.mode) {
+    console.log(LISTEN_HELP);
+    return;
+  }
+  const log = options.quiet ? () => {
+  } : (msg) => process.stderr.write(`${msg}
+`);
+  const { browser, session } = await resolveConnection2(
+    globalOptions.session,
+    options.useLatestSession ?? false,
+    globalOptions.trace ?? false
+  );
+  let outputStream;
+  if (options.output) {
+    const fs3 = await import("fs");
+    const fileStream = fs3.createWriteStream(options.output, { flags: "w" });
+    outputStream = {
+      write: (line) => fileStream.write(`${line}
+`),
+      close: () => fileStream.end()
+    };
+    log(`Writing to ${options.output}`);
+  } else {
+    outputStream = {
+      write: (line) => {
+        try {
+          process.stdout.write(`${line}
+`);
+        } catch {
+          process.exit(0);
+        }
+      }
+    };
+    process.stdout.on("error", (err) => {
+      if (err.code === "EPIPE") {
+        process.exit(0);
+      }
+    });
+  }
+  try {
+    const page = await browser.page(void 0, { targetId: session.targetId });
+    const cdp = page.cdpClient;
+    await cdp.send("Network.enable");
+    const monitor = new TrafficMonitor(cdp, {
+      mode: options.mode,
+      match: options.match,
+      maxPayload: options.maxPayload ?? 256,
+      write: (line) => outputStream.write(line)
+    });
+    monitor.start();
+    const matchLabel = options.match ? ` matching "${options.match}"` : "";
+    log(`Listening for ${options.mode} traffic${matchLabel} (session: ${session.id})`);
+    log("Press Ctrl+C to stop.");
+    let cleaned = false;
+    const cleanup = () => {
+      if (cleaned) return;
+      cleaned = true;
+      monitor.stop();
+      log(`
+Stopped. ${monitor.lineCount} events captured.`);
+      outputStream.close?.();
+      browser.disconnect().catch(() => {
+      });
+      process.exit(0);
+    };
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    if (options.timeout && options.timeout > 0) {
+      setTimeout(() => {
+        log(`
+Timeout reached (${options.timeout}ms).`);
+        cleanup();
+      }, options.timeout);
+    }
+    await new Promise(() => {
+    });
+  } catch (error) {
+    outputStream.close?.();
+    await browser.disconnect();
+    throw error;
+  }
+}
+
 // src/cli/commands/quickstart.ts
 var QUICKSTART = `
 browser-pilot CLI - Quick Start Guide
@@ -8465,7 +8816,7 @@ function parseRecordArgs(args) {
   }
   return options;
 }
-async function resolveConnection2(sessionId, useLatestSession, trace) {
+async function resolveConnection3(sessionId, useLatestSession, trace) {
   if (sessionId) {
     const session2 = await loadSession(sessionId);
     const browser2 = await connect({
@@ -8523,7 +8874,7 @@ async function recordCommand(args, globalOptions) {
     return;
   }
   const outputFile = options.file ?? "recording.json";
-  const { browser, session, isNewSession } = await resolveConnection2(
+  const { browser, session, isNewSession } = await resolveConnection3(
     globalOptions.session,
     options.useLatestSession ?? false,
     globalOptions.trace ?? false
@@ -9123,6 +9474,7 @@ Commands:
   eval        Evaluate JavaScript expression
   record      Record browser actions to JSON
   audio       Audio I/O for voice agent testing
+  listen      Monitor network traffic (WebSocket/HTTP)
   snapshot    Get page with element refs
   diagnose    Debug element selection issues
   text        Extract text content
@@ -9271,6 +9623,9 @@ async function main() {
       case "audio":
         await audioCommand(remaining, options);
         break;
+      case "listen":
+        await listenCommand(remaining, options);
+        break;
       case "help":
       case "--help":
       case "-h":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-pilot",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Lightweight CDP-based browser automation for Node.js, Bun, and Cloudflare Workers",
   "type": "module",
   "main": "./dist/index.cjs",