browser-pilot 0.0.4 → 0.0.6

package/dist/cli.mjs

@@ -2,14 +2,14 @@
 import "./chunk-ZIQA4JOT.mjs";
 import {
   connect
-} from "./chunk-CWSTSVWO.mjs";
+} from "./chunk-PCNEJAJ7.mjs";
 import "./chunk-BCOZUKWS.mjs";
 import {
   getBrowserWebSocketUrl
 } from "./chunk-R3PS4PCM.mjs";
 import {
   addBatchToPage
-} from "./chunk-YEHK2XY3.mjs";
+} from "./chunk-6RB3GKQP.mjs";
 
 // src/cli/commands/actions.ts
 var ACTIONS_HELP = `
@@ -272,6 +272,60 @@ async function getDefaultSession() {
   return sessions[0] ?? null;
 }
 
+// src/cli/commands/clean.ts
+function parseCleanArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--max-age") {
+      const value = args[++i];
+      options.maxAge = parseInt(value ?? "24", 10);
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--all") {
+      options.all = true;
+    }
+  }
+  return options;
+}
+async function cleanCommand(args, globalOptions) {
+  const options = parseCleanArgs(args);
+  const maxAgeMs = (options.maxAge ?? 24) * 60 * 60 * 1e3;
+  const now = Date.now();
+  const sessions = await listSessions();
+  const stale = sessions.filter((s) => {
+    if (options.all) return true;
+    const age = now - new Date(s.lastActivity).getTime();
+    return age > maxAgeMs;
+  });
+  if (stale.length === 0) {
+    output({ message: "No stale sessions found", cleaned: 0 }, globalOptions.output);
+    return;
+  }
+  if (options.dryRun) {
+    output(
+      {
+        message: `Would clean ${stale.length} session(s)`,
+        sessions: stale.map((s) => s.id),
+        dryRun: true
+      },
+      globalOptions.output
+    );
+    return;
+  }
+  for (const session of stale) {
+    await deleteSession(session.id);
+  }
+  output(
+    {
+      message: `Cleaned ${stale.length} session(s)`,
+      cleaned: stale.length,
+      sessions: stale.map((s) => s.id)
+    },
+    globalOptions.output
+  );
+}
+
 // src/cli/commands/close.ts
 async function closeCommand(args, globalOptions) {
   let session;
@@ -390,6 +444,17 @@ async function connectCommand(args, globalOptions) {
 }
 
 // src/cli/commands/exec.ts
+async function validateSession(session) {
+  try {
+    const wsUrl = new URL(session.wsUrl);
+    const protocol = wsUrl.protocol === "wss:" ? "https:" : "http:";
+    const httpUrl = `${protocol}//${wsUrl.host}/json/version`;
+    const response = await fetch(httpUrl, { signal: AbortSignal.timeout(3e3) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
 function parseExecArgs(args) {
   const options = {};
   let actionsJson;
@@ -434,6 +499,14 @@ Run 'bp actions' for complete action reference.`
       throw new Error('No session found. Run "bp connect" first.');
     }
   }
+  const isValid = await validateSession(session);
+  if (!isValid) {
+    await deleteSession(session.id);
+    throw new Error(
+      `Session "${session.id}" is no longer valid (browser may have closed).
+Session file has been cleaned up. Run "bp connect" to create a new session.`
+    );
+  }
   const browser = await connect({
     provider: session.provider,
     wsUrl: session.wsUrl,
@@ -588,12 +661,760 @@ COMMON ACTIONS
   snapshot    {"action":"snapshot"}
   screenshot  {"action":"screenshot"}
 
+RECORDING (FOR HUMANS)
+  Want to create automations by demonstrating instead of coding?
+  Use 'bp record' to capture your browser interactions as replayable JSON:
+
+    bp record                 # Record from local Chrome
+    bp exec --file login.json # Replay the recording
+
+  Great for creating initial automation scripts that AI agents can refine.
+
 Run 'bp actions' for the complete action reference.
 `;
 async function quickstartCommand() {
   console.log(QUICKSTART);
 }
 
+// src/recording/aggregator.ts
+var INPUT_DEBOUNCE_MS = 300;
+var NAVIGATION_DEBOUNCE_MS = 500;
+function selectBestSelectors(candidates) {
+  const qualityOrder = {
+    "stable-attr": 0,
+    id: 1,
+    "css-path": 2
+  };
+  const sorted = [...candidates].sort((a, b) => {
+    const aOrder = qualityOrder[a.quality] ?? 3;
+    const bOrder = qualityOrder[b.quality] ?? 3;
+    return aOrder - bOrder;
+  });
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const candidate of sorted) {
+    if (!seen.has(candidate.selector)) {
+      seen.add(candidate.selector);
+      result.push(candidate.selector);
+    }
+  }
+  return result;
+}
+function debounceInputEvents(events) {
+  const result = [];
+  for (let i = 0; i < events.length; i++) {
+    const event = events[i];
+    if (event.kind !== "input") {
+      result.push(event);
+      continue;
+    }
+    const primarySelector = event.selectors[0]?.selector;
+    if (!primarySelector) {
+      result.push(event);
+      continue;
+    }
+    let finalEvent = event;
+    let j = i + 1;
+    while (j < events.length) {
+      const nextEvent = events[j];
+      if (nextEvent.timestamp - finalEvent.timestamp > INPUT_DEBOUNCE_MS) {
+        break;
+      }
+      if (nextEvent.kind !== "input") {
+        break;
+      }
+      const nextPrimarySelector = nextEvent.selectors[0]?.selector;
+      if (nextPrimarySelector !== primarySelector) {
+        break;
+      }
+      finalEvent = nextEvent;
+      j++;
+    }
+    i = j - 1;
+    result.push(finalEvent);
+  }
+  return result;
+}
+function debounceNavigationEvents(events) {
+  const result = [];
+  for (let i = 0; i < events.length; i++) {
+    const event = events[i];
+    if (event.kind !== "navigation") {
+      result.push(event);
+      continue;
+    }
+    let finalEvent = event;
+    let j = i + 1;
+    while (j < events.length) {
+      const nextEvent = events[j];
+      if (nextEvent.timestamp - finalEvent.timestamp > NAVIGATION_DEBOUNCE_MS) {
+        break;
+      }
+      if (nextEvent.kind !== "navigation") {
+        break;
+      }
+      finalEvent = nextEvent;
+      j++;
+    }
+    i = j - 1;
+    result.push(finalEvent);
+  }
+  return result;
+}
+function insertNavigationSteps(events, startUrl) {
+  const result = [];
+  let lastUrl = startUrl || null;
+  for (const event of events) {
+    if (lastUrl !== null && event.url !== lastUrl) {
+      result.push({
+        kind: "navigation",
+        timestamp: event.timestamp,
+        url: event.url,
+        selectors: []
+      });
+    }
+    result.push(event);
+    lastUrl = event.url;
+  }
+  return result;
+}
+function eventToStep(event) {
+  const selectors = selectBestSelectors(event.selectors);
+  switch (event.kind) {
+    case "click":
+    case "dblclick":
+      if (selectors.length === 0) return null;
+      return {
+        action: "click",
+        selector: selectors.length === 1 ? selectors[0] : selectors
+      };
+    case "input":
+      if (selectors.length === 0) return null;
+      return {
+        action: "fill",
+        selector: selectors.length === 1 ? selectors[0] : selectors,
+        value: event.value ?? ""
+      };
+    case "change": {
+      if (selectors.length === 0) return null;
+      const element = event.element;
+      const tag = element?.tag;
+      const type = element?.type?.toLowerCase();
+      if (tag === "select") {
+        return {
+          action: "select",
+          selector: selectors.length === 1 ? selectors[0] : selectors,
+          value: event.value ?? ""
+        };
+      }
+      if (type === "checkbox" || type === "radio") {
+        return {
+          action: event.checked ? "check" : "uncheck",
+          selector: selectors.length === 1 ? selectors[0] : selectors
+        };
+      }
+      return {
+        action: "fill",
+        selector: selectors.length === 1 ? selectors[0] : selectors,
+        value: event.value ?? ""
+      };
+    }
+    case "keydown":
+      if (event.key === "Enter") {
+        if (selectors.length === 0) return null;
+        return {
+          action: "submit",
+          selector: selectors.length === 1 ? selectors[0] : selectors,
+          method: "enter"
+        };
+      }
+      return null;
+    case "submit":
+      if (selectors.length === 0) return null;
+      return {
+        action: "submit",
+        selector: selectors.length === 1 ? selectors[0] : selectors
+      };
+    case "navigation":
+      return {
+        action: "goto",
+        url: event.url
+      };
+    default:
+      return null;
+  }
+}
+function deduplicateSteps(steps) {
+  const result = [];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const prevStep = result[result.length - 1];
+    if (step.action === "submit" && prevStep?.action === "submit" && JSON.stringify(step.selector) === JSON.stringify(prevStep.selector)) {
+      continue;
+    }
+    result.push(step);
+  }
+  return result;
+}
+function aggregateEvents(events, startUrl) {
+  if (events.length === 0) return [];
+  let processed = insertNavigationSteps(events, startUrl);
+  processed = debounceNavigationEvents(processed);
+  processed = debounceInputEvents(processed);
+  const steps = [];
+  for (const event of processed) {
+    const step = eventToStep(event);
+    if (step) {
+      steps.push(step);
+    }
+  }
+  return deduplicateSteps(steps);
+}
+
+// src/recording/script.ts
+var RECORDER_BINDING_NAME = "__recorder";
+var RECORDER_SCRIPT = `(function() {
+  // Guard against multiple installations
+  if (window.__recorderInstalled) return;
+  window.__recorderInstalled = true;
+
+  const BINDING_NAME = '__recorder';
+
+  // Safe JSON stringify
+  function safeJson(obj) {
+    try {
+      return JSON.stringify(obj);
+    } catch (e) {
+      return JSON.stringify({ error: 'unserializable' });
+    }
+  }
+
+  // Send event to CDP client via binding
+  function sendEvent(payload) {
+    try {
+      if (typeof window[BINDING_NAME] === 'function') {
+        window[BINDING_NAME](safeJson(payload));
+      }
+    } catch (e) {
+      // Binding not ready, ignore
+    }
+  }
+
+  // CSS escape for identifiers
+  function cssEscape(str) {
+    return String(str).replace(/([\\[\\]#.:>+~=|^$*!"'(){}])/g, '\\\\$1');
+  }
+
+  // Check if selector is unique in document
+  function isUnique(selector, root) {
+    try {
+      return (root || document).querySelectorAll(selector).length === 1;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  // Get stable attribute selector (data-testid, aria-label, name, etc.)
+  function getStableAttrSelector(el) {
+    if (!el || el.nodeType !== 1) return null;
+    const attrs = ['data-testid', 'data-test', 'data-qa', 'aria-label', 'name'];
+    for (const attr of attrs) {
+      const val = el.getAttribute(attr);
+      if (val && val.length <= 200) {
+        const escaped = val.replace(/"/g, '\\\\"');
+        return '[' + attr + '="' + escaped + '"]';
+      }
+    }
+    return null;
+  }
+
+  // Get ID selector
+  function getIdSelector(el) {
+    if (!el || !el.id || el.id.length > 100) return null;
+    // Skip dynamic-looking IDs
+    if (/^[0-9]|^:/.test(el.id)) return null;
+    return '#' + cssEscape(el.id);
+  }
+
+  // Build CSS path for element
+  function buildCssPath(el) {
+    if (!el || el.nodeType !== 1) return null;
+    const parts = [];
+    let cur = el;
+
+    for (let depth = 0; cur && cur !== document.body && depth < 8; depth++) {
+      let part = cur.tagName.toLowerCase();
+
+      // If ID exists and looks stable, use it and stop
+      if (cur.id && !/^[0-9]|^:/.test(cur.id) && cur.id.length <= 50) {
+        part = '#' + cssEscape(cur.id);
+        parts.unshift(part);
+        break;
+      }
+
+      // Add stable classes (skip dynamic ones)
+      const classes = Array.from(cur.classList || [])
+        .filter(c => c.length < 40 && !/^css-|^_|^[0-9]/.test(c))
+        .slice(0, 2);
+      if (classes.length) {
+        part += '.' + classes.map(cssEscape).join('.');
+      }
+
+      // Add position if siblings have same tag
+      const parent = cur.parentElement;
+      if (parent) {
+        const sameTag = Array.from(parent.children).filter(c => c.tagName === cur.tagName);
+        if (sameTag.length > 1) {
+          const idx = sameTag.indexOf(cur) + 1;
+          part += ':nth-of-type(' + idx + ')';
+        }
+      }
+
+      parts.unshift(part);
+      cur = cur.parentElement;
+    }
+
+    return parts.join(' > ');
+  }
+
+  // Generate selector candidates ordered by quality
+  function getSelectorCandidates(el) {
+    const candidates = [];
+
+    // 1. Stable attributes (highest quality)
+    const stableAttr = getStableAttrSelector(el);
+    if (stableAttr) {
+      candidates.push({ selector: stableAttr, quality: 'stable-attr' });
+    }
+
+    // 2. ID selector
+    const idSel = getIdSelector(el);
+    if (idSel) {
+      candidates.push({ selector: idSel, quality: 'id' });
+    }
+
+    // 3. CSS path (fallback)
+    const cssPath = buildCssPath(el);
+    if (cssPath) {
+      candidates.push({ selector: cssPath, quality: 'css-path' });
+    }
+
+    return candidates;
+  }
+
+  // Get element summary for debugging
+  function getElementSummary(el) {
+    if (!el || el.nodeType !== 1) return null;
+    const text = (el.innerText || '').trim().replace(/\\s+/g, ' ').slice(0, 120);
+    return {
+      tag: el.tagName.toLowerCase(),
+      id: el.id || null,
+      name: el.getAttribute('name') || null,
+      type: el.getAttribute('type') || null,
+      role: el.getAttribute('role') || null,
+      ariaLabel: el.getAttribute('aria-label') || null,
+      testid: el.getAttribute('data-testid') || null,
+      text: text || null
+    };
+  }
+
+  // Get event target, handling shadow DOM via composedPath
+  function getEventTarget(ev) {
+    const path = ev.composedPath ? ev.composedPath() : null;
+    if (path && path.length > 0) {
+      for (const node of path) {
+        if (node && node.nodeType === 1) return node;
+      }
+    }
+    return ev.target && ev.target.nodeType === 1 ? ev.target : null;
+  }
+
+  // Find clickable ancestor (button, a, [role=button])
+  function findClickableAncestor(el) {
+    if (!el) return el;
+    const clickable = el.closest('button, a, [role="button"], [role="link"]');
+    return clickable || el;
+  }
+
+  // Check if element is a password input
+  function isPasswordInput(el) {
+    if (!el) return false;
+    const tag = el.tagName.toLowerCase();
+    if (tag !== 'input') return false;
+    const type = (el.getAttribute('type') || '').toLowerCase();
+    return type === 'password';
+  }
+
+  // Get input value, redacting passwords
+  function getInputValue(el) {
+    if (isPasswordInput(el)) return '[REDACTED]';
+    if (el.value !== undefined) return el.value;
+    if (el.isContentEditable) return el.textContent || '';
+    return '';
+  }
+
+  // Current timestamp
+  function now() { return Date.now(); }
+
+  // Click handler
+  window.addEventListener('click', function(ev) {
+    const rawTarget = getEventTarget(ev);
+    if (!rawTarget) return;
+
+    // Bubble up to clickable ancestor for better selectors
+    const el = findClickableAncestor(rawTarget);
+
+    sendEvent({
+      kind: 'click',
+      timestamp: now(),
+      url: location.href,
+      element: getElementSummary(el),
+      selectors: getSelectorCandidates(el),
+      client: { x: ev.clientX, y: ev.clientY }
+    });
+  }, true);
+
+  // Double click handler
+  window.addEventListener('dblclick', function(ev) {
+    const rawTarget = getEventTarget(ev);
+    if (!rawTarget) return;
+
+    const el = findClickableAncestor(rawTarget);
+
+    sendEvent({
+      kind: 'dblclick',
+      timestamp: now(),
+      url: location.href,
+      element: getElementSummary(el),
+      selectors: getSelectorCandidates(el),
+      client: { x: ev.clientX, y: ev.clientY }
+    });
+  }, true);
+
+  // Input handler (for text inputs, textareas, contenteditable)
+  window.addEventListener('input', function(ev) {
+    const el = getEventTarget(ev);
+    if (!el) return;
+
+    const tag = el.tagName.toLowerCase();
+    const isTexty = tag === 'input' || tag === 'textarea' || el.isContentEditable;
+    if (!isTexty) return;
+
+    sendEvent({
+      kind: 'input',
+      timestamp: now(),
+      url: location.href,
+      element: getElementSummary(el),
+      selectors: getSelectorCandidates(el),
+      value: getInputValue(el)
+    });
+  }, true);
+
+  // Change handler (for select, checkbox, radio)
+  window.addEventListener('change', function(ev) {
+    const el = getEventTarget(ev);
+    if (!el) return;
+
+    const tag = el.tagName.toLowerCase();
+    const type = (el.getAttribute('type') || '').toLowerCase();
+    const isCheckable = type === 'checkbox' || type === 'radio';
+
+    sendEvent({
+      kind: 'change',
+      timestamp: now(),
+      url: location.href,
+      element: getElementSummary(el),
+      selectors: getSelectorCandidates(el),
+      value: isCheckable ? undefined : getInputValue(el),
+      checked: isCheckable ? el.checked : undefined
+    });
+  }, true);
+
+  // Keydown handler (capture Enter for form submission)
+  window.addEventListener('keydown', function(ev) {
+    if (ev.key !== 'Enter') return;
+
+    const el = getEventTarget(ev);
+
+    sendEvent({
+      kind: 'keydown',
+      timestamp: now(),
+      url: location.href,
+      key: ev.key,
+      element: el ? getElementSummary(el) : null,
+      selectors: el ? getSelectorCandidates(el) : []
+    });
+  }, true);
+
+  // Submit handler
+  window.addEventListener('submit', function(ev) {
+    const el = getEventTarget(ev);
+
+    sendEvent({
+      kind: 'submit',
+      timestamp: now(),
+      url: location.href,
+      element: el ? getElementSummary(el) : null,
+      selectors: el ? getSelectorCandidates(el) : []
+    });
+  }, true);
+})();`;
+
+// src/recording/recorder.ts
+var Recorder = class {
+  cdp;
+  events = [];
+  recording = false;
+  startTime = 0;
+  startUrl = "";
+  bindingHandler = null;
+  constructor(cdp) {
+    this.cdp = cdp;
+  }
+  /**
+   * Check if recording is currently active.
+   */
+  get isRecording() {
+    return this.recording;
+  }
+  /**
+   * Start recording browser interactions.
+   *
+   * Sets up CDP bindings and injects the recorder script into
+   * the current page and all future navigations.
+   */
+  async start() {
+    if (this.recording) {
+      throw new Error("Recording already in progress");
+    }
+    this.events = [];
+    this.startTime = Date.now();
+    this.recording = true;
+    await this.cdp.send("Runtime.enable");
+    await this.cdp.send("Page.enable");
+    try {
+      const result = await this.cdp.send("Runtime.evaluate", {
+        expression: "location.href",
+        returnByValue: true
+      });
+      this.startUrl = result.result.value;
+    } catch {
+      this.startUrl = "";
+    }
+    await this.cdp.send("Runtime.addBinding", { name: RECORDER_BINDING_NAME });
+    await this.cdp.send("Page.addScriptToEvaluateOnNewDocument", {
+      source: RECORDER_SCRIPT
+    });
+    await this.cdp.send("Runtime.evaluate", {
+      expression: RECORDER_SCRIPT,
+      awaitPromise: false
+    });
+    this.bindingHandler = (params) => {
+      if (params["name"] === RECORDER_BINDING_NAME) {
+        this.handleBindingCall(params["payload"]);
+      }
+    };
+    this.cdp.on("Runtime.bindingCalled", this.bindingHandler);
+  }
+  /**
+   * Stop recording and return aggregated output.
+   *
+   * Returns a RecordingOutput with steps compatible with page.batch().
+   */
+  async stop() {
+    if (!this.recording) {
+      throw new Error("No recording in progress");
+    }
+    this.recording = false;
+    const duration = Date.now() - this.startTime;
+    if (this.bindingHandler) {
+      this.cdp.off("Runtime.bindingCalled", this.bindingHandler);
+      this.bindingHandler = null;
+    }
+    const steps = aggregateEvents(this.events, this.startUrl);
+    return {
+      recordedAt: new Date(this.startTime).toISOString(),
+      startUrl: this.startUrl,
+      duration,
+      steps
+    };
+  }
+  /**
+   * Get raw recorded events (for debugging).
+   */
+  getEvents() {
+    return [...this.events];
+  }
+  /**
+   * Handle incoming binding call from the browser.
+   */
+  handleBindingCall(payload) {
+    if (!this.recording) return;
+    try {
+      const event = JSON.parse(payload);
+      this.events.push(event);
+    } catch {
+    }
+  }
+};
+
+// src/cli/commands/record.ts
+var RECORD_HELP = `
+bp record - Record browser actions to JSON
+
+Usage:
+  bp record [options]
+
+Options:
+  -s, --session [id]  Session to use:
+                        - omit -s: auto-connect to local browser
+                        - -s alone: use most recent session
+                        - -s <id>: use specific session
+  -f, --file <path>   Output file (default: recording.json)
+  --timeout <ms>      Auto-stop after timeout (optional)
+  -h, --help          Show this help
+
+Examples:
+  bp record                        # Auto-connect to local Chrome
+  bp record -s                     # Use most recent session
+  bp record -s mysession           # Use specific session
+  bp record -f login.json          # Save to specific file
+  bp record --timeout 60000        # Auto-stop after 60s
+
+Recording captures: clicks, inputs, form submissions, navigation.
+Password fields are automatically redacted as [REDACTED].
+
+Press Ctrl+C to stop recording and save.
+`;
+function parseRecordArgs(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-f" || arg === "--file") {
+      options.file = args[++i];
+    } else if (arg === "--timeout") {
+      options.timeout = Number.parseInt(args[++i] ?? "", 10);
+    } 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;
+      }
+    }
+  }
+  return options;
+}
+async function resolveConnection(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, isNewSession: false };
+  }
+  if (useLatestSession) {
+    const session2 = await getDefaultSession();
+    if (!session2) {
+      throw new Error(
+        'No sessions found. Run "bp connect" first or use "bp record" to auto-connect.'
+      );
+    }
+    const browser2 = await connect({
+      provider: session2.provider,
+      wsUrl: session2.wsUrl,
+      debug: trace
+    });
+    return { browser: browser2, session: session2, isNewSession: false };
+  }
+  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 record -s <session-id>\n  3. Use latest session: bp record -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, isNewSession: true };
+}
+async function recordCommand(args, globalOptions) {
+  const options = parseRecordArgs(args);
+  if (options.help || globalOptions.help) {
+    console.log(RECORD_HELP);
+    return;
+  }
+  const outputFile = options.file ?? "recording.json";
+  const { browser, session, isNewSession } = await resolveConnection(
+    globalOptions.session,
+    options.useLatestSession ?? false,
+    globalOptions.trace ?? false
+  );
+  if (isNewSession) {
+    console.log(`Created new session: ${session.id}`);
+  }
+  const page = await browser.page();
+  const cdp = page.cdpClient;
+  const recorder = new Recorder(cdp);
+  let stopping = false;
+  async function stopAndSave() {
+    if (stopping) return;
+    stopping = true;
+    try {
+      const recording = await recorder.stop();
+      const fs = await import("fs/promises");
+      await fs.writeFile(outputFile, JSON.stringify(recording, null, 2));
+      const currentUrl = await page.url();
+      await updateSession(session.id, { currentUrl });
+      await browser.disconnect();
+      console.log(`
+Saved ${recording.steps.length} steps to ${outputFile}`);
+      if (globalOptions.output === "json") {
+        output(
+          {
+            success: true,
+            file: outputFile,
+            steps: recording.steps.length,
+            duration: recording.duration
+          },
+          "json"
+        );
+      }
+      process.exit(0);
+    } catch (error) {
+      console.error("Error saving recording:", error);
+      process.exit(1);
+    }
+  }
+  process.on("SIGINT", stopAndSave);
+  process.on("SIGTERM", stopAndSave);
+  if (options.timeout && options.timeout > 0) {
+    setTimeout(stopAndSave, options.timeout);
+  }
+  await recorder.start();
+  console.log(`Recording... Press Ctrl+C to stop and save to ${outputFile}`);
+  console.log(`Session: ${session.id}`);
+  console.log(`URL: ${await page.url()}`);
+}
+
 // src/cli/commands/screenshot.ts
 function parseScreenshotArgs(args) {
   const options = {};
@@ -767,11 +1588,13 @@ Commands:
   quickstart  Getting started guide (start here!)
   connect     Create browser session
   exec        Execute actions
+  record      Record browser actions to JSON
   snapshot    Get page with element refs
   text        Extract text content
   screenshot  Take screenshot
   close       Close session
   list        List sessions
+  clean       Clean up old sessions
   actions     Complete action reference
 
 Options:
@@ -786,6 +1609,8 @@ Examples:
   bp exec '{"action":"goto","url":"https://example.com"}'
   bp snapshot --format text
   bp exec '{"action":"click","selector":"ref:e3"}'
+  bp record                        # Record from local browser
+  bp record -s -f login.json       # Record from latest session
 
 Run 'bp quickstart' for CLI workflow guide.
 Run 'bp actions' for complete action reference.
@@ -818,7 +1643,10 @@ function output(data, format = "pretty") {
     if (typeof data === "string") {
       console.log(data);
     } else if (typeof data === "object" && data !== null) {
-      prettyPrint(data);
+      const { truncated } = prettyPrint(data);
+      if (truncated) {
+        console.log("\n(Output truncated. Use -o json for full data)");
+      }
     } else {
       console.log(data);
     }
@@ -826,16 +1654,20 @@ function output(data, format = "pretty") {
 }
 function prettyPrint(obj, indent = 0) {
   const prefix = "  ".repeat(indent);
+  let truncated = false;
   for (const [key, value] of Object.entries(obj)) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
       console.log(`${prefix}${key}:`);
-      prettyPrint(value, indent + 1);
+      const result = prettyPrint(value, indent + 1);
+      if (result.truncated) truncated = true;
     } else if (Array.isArray(value)) {
       console.log(`${prefix}${key}: [${value.length} items]`);
+      truncated = true;
     } else {
       console.log(`${prefix}${key}: ${value}`);
     }
   }
+  return { truncated };
 }
 async function main() {
   const args = process.argv.slice(2);
@@ -875,9 +1707,15 @@ async function main() {
       case "list":
         await listCommand(remaining, options);
         break;
+      case "clean":
+        await cleanCommand(remaining, options);
+        break;
       case "actions":
         await actionsCommand();
         break;
+      case "record":
+        await recordCommand(remaining, options);
+        break;
       case "help":
       case "--help":
       case "-h":