[lahfir]

1. Firefox sessions did not show in the dashboard live view, and the engine had no documentation.
2. This adds Firefox live view and documentation, moves handlers into bidi, and defines their routing once.
3. Builds on feat(firefox): network control and emulation on Firefox #2207.

Demo

The terminal drives a Firefox session over WebDriver BiDi; the right side shows that Firefox page as each command runs.

demo.mp4

Architecture

flowchart TB
  subgraph Clients
    CLI[CLI]
    MCP[MCP server]
    DASH[Dashboard]
  end

  CLI & MCP & DASH -->|JSON over daemon socket| EX

  subgraph Daemon["Daemon (native/actions.rs)"]
    EX[execute_command]
    GATES[Policy + confirmation gates<br/>implicit launch / relaunch]
    ROUTE{engine == firefox?}
    CDPH[Existing CDP handlers<br/>Chrome, Lightpanda, Obscura,<br/>--cdp, providers]
    WD[WebDriver path<br/>Safari / iOS]
    EX --> GATES --> ROUTE
    ROUTE -->|no| CDPH
    ROUTE -->|no, provider ios/safari| WD
  end

  ROUTE -->|yes| BA

  subgraph Bidi["native/bidi/ (BiDi protocol module)"]
    BA[actions.rs<br/>One handler declaration / Chrome-only errors<br/>dialog guard, dispatch]
    subgraph Handlers["Handlers (any BiDi browser)"]
      PAGE[page: navigate, history, waits, content]
      TABS[tabs: t1..tN ids, new/switch/close]
      FORMS[forms: fill, type, press, select, check, upload, inserttext]
      INTER[interact: click, hover, drag, scroll, tap, dialog]
      QUERY[query: get/is, find/getby*, frame]
      CAP[capture: screenshot, annotate, pdf]
      STOR[storage: cookies, storage, state save/load]
      NET[network: route, HAR, requests, headers, auth, downloads]
      EMU[emulation: viewport, device, geo, media, offline]
      SNAP[snapshot: tree + refs]
      TGT[target: ref / selector resolver]
      INP[input: key + pointer action builders]
      STRM[stream: dashboard polling + input]
    end
    SESS[session.rs FirefoxSession<br/>active/top context, tab ids,<br/>ref side table i64 to sharedId,<br/>event pump]
    CLIENT[client.rs BiDi WebSocket client<br/>send, send_typed, events]
    TYPES[types.rs LocalValue, RemoteValue,<br/>BytesValue, Cookie, events]
    FF[firefox.rs find, validate, launch<br/>temp profile, prefs, process group]
    DEVT[firefox_devtools.rs RDP client<br/>accessibility tree, media simulation]
    BA --> Handlers
    Handlers --> SESS
    SESS --> CLIENT
    CLIENT --- TYPES
    SESS --> DEVT
    FF --> SESS
  end

  subgraph Shared["Shared with Chrome (reused, not copied)"]
    JS[Page JS constants<br/>element.rs / interaction.rs]
    RENDER[Snapshot renderer + RefMap<br/>build_tree / render_tree]
    POLICY[DomainFilter, route matching,<br/>state format, screenshot/pdf/upload helpers]
  end

  FORMS & INTER & QUERY -.-> JS
  SNAP -.-> RENDER
  NET & STOR & CAP -.-> POLICY
  CDPH -.-> JS & RENDER & POLICY

  subgraph Firefox["Firefox 150+ (owned temp profile)"]
    RA[Remote Agent<br/>WebDriver BiDi]
    DS[DevTools server<br/>accessibility actor]
  end

  CLIENT <-->|ws://127.0.0.1:random/session| RA
  DEVT <-->|unix socket in 0700 dir<br/>or loopback port on Windows| DS
  FF -->|spawn| Firefox

Loading

Launch sequence

sequenceDiagram
  participant C as CLI
  participant D as Daemon
  participant FF as firefox.rs
  participant S as FirefoxSession
  participant B as Firefox BiDi
  participant R as Firefox DevTools
  C->>D: open --engine firefox URL
  D->>FF: validate options (reject --cdp, --profile, --args, ...)
  FF->>FF: temp profile + user.js prefs, socket dir 0700
  FF->>B: spawn firefox --headless --remote-debugging-port 0 --start-debugger-server sock
  B-->>FF: stderr "WebDriver BiDi listening on ws://..."
  FF->>S: create session
  S->>B: session.new (proxy, prompts: accept alert/beforeunload, ignore others)
  B-->>S: browserVersion (must be >= 150)
  S->>R: connect, parentAccessibilityActor.enable
  S->>B: session.subscribe (log, network, prompts, downloads, contexts)
  D->>B: browsingContext.navigate URL (wait complete)
  D-->>C: title + url
  Note over D,B: close / idle / crash: end session, kill process group, delete profile

Loading

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
agent-browser	Ready	Preview, v0	Nov 9, 2026 10:46pm UTC
agent-browser-env-demo	Ready	Preview, v0	Nov 9, 2026 10:46pm UTC

[vercel-internal-security-reviewer]

Security review details

[ctate]

With streaming enabled this runs after every Firefox command and issues a getTree plus one document.title eval per tab even when no dashboard client is connected, so a stalled page adds up to ~1.25 s to each CLI command. Not reproduced.

[ctate]

The poll loop awaits this call and the screenshot before it can select again, both with the 30 s default timeout, so one unresponsive tab freezes frame publishing and prompt-pause tracking for up to 30 s. Not reproduced.