HeyRocky

Understand the Hermes Browser CDP Supervisor

Native JavaScript dialogs can block a page’s thread, while cross-origin iframes can sit outside top-level JavaScript evaluation. Hermes’ Browser CDP Supervisor addresses both problems by keeping a persistent DevTools Protocol connection for the browser task, surfacing state through snapshots, and routing explicit responses or frame-scoped evaluation to the correct session.

What the supervisor tracks

For a supported CDP backend, the supervisor maintains pending and recent dialogs, a bounded frame tree, attached child sessions for out-of-process iframes, and recent console errors. browser_snapshot can then include pending_dialogs, recent_dialogs, and frame_tree without adding those fields when no supervisor is available.

Local Chromium with remote debugging and Browserbase support the full frame workflow. Browserbase uses a bridge for dialogs because its proxy dismisses native dialogs too quickly for the ordinary event path. Camofox is REST-only and does not expose the required CDP surface.

Operator checklist

  • Confirm the selected browser backend exposes a reachable CDP endpoint.
  • Navigate once so Hermes can start or bind the supervisor.
  • Read browser_snapshot before responding to a dialog.
  • Use the dialog ID when more than one dialog is queued.
  • Supply prompt text only for a prompt dialog.
  • Read frame_tree and target only entries marked as out-of-process when using frame-scoped CDP evaluation.
  • Treat a truncated frame tree as a signal to query the full CDP tree deliberately.
  • Disconnect cleanly so the background WebSocket and state are discarded.

Dialog policy

The default must_respond policy surfaces a dialog and waits for an explicit response, with a safety timeout to prevent permanent stalls. auto_dismiss and auto_accept are broader per-task policies. Choose them based on the workflow; auto-accepting every confirmation can create side effects, while auto-dismissing every prompt can break valid flows.

Recent-dialog records distinguish agent action, automatic policy, watchdog timeout, and remote closure. That history is particularly useful on Browserbase, where the native dialog may close before an agent could respond normally.

Common pitfalls

  • Assuming every browser backend supports CDP supervision.
  • Clicking repeatedly while a native dialog is blocking the page.
  • Auto-accepting confirmations on workflows with destructive or paid actions.
  • Passing a same-origin frame ID to the OOPIF route instead of using normal contentDocument access.
  • Treating a truncated frame tree as complete.
  • Reusing frame or dialog IDs after navigation, reconnect, or endpoint rebind.
  • Forgetting that dialog and frame history is in memory and does not persist across sessions.

Verification steps

  1. Connect to a supported Chromium-family backend and open a harmless page with alert, confirm, and prompt fixtures.
  2. Confirm snapshots expose the pending dialog, then accept or dismiss it explicitly.
  3. Verify the page receives the expected prompt result.
  4. Open a cross-origin iframe fixture and confirm it appears with an OOPIF frame ID.
  5. Run a harmless frame-scoped evaluation and verify it executes in the child target.
  6. Disconnect, reconnect, and confirm old IDs and state are not reused.
  7. Repeat on each production browser backend and record unsupported capabilities honestly.

Official documentation

https://hermes-agent.nousresearch.com/docs/developer-guide/browser-supervisor

Related pages