Browser CDP Supervisor

1. Native JS dialogs (alert/confirm/prompt/beforeunload) block the page’s JS thread. Without supervision, the agent has no way to know a dialog is open — subsequent tool calls hang or throw opaque errors.
2. Cross-origin iframes (OOPIFs) are invisible to top-level Runtime.evaluate. The agent can see iframe nodes in the DOM snapshot but can’t click, type, or eval inside them without a CDP session attached to the child target.

​

Backend support

​

Architecture

​

CDPSupervisor

• Dialog queue — List[PendingDialog] with {id, type, message, default_prompt, session_id, opened_at}
• Frame tree — Dict[frame_id, FrameInfo] with parent relationships, URL, origin, whether cross-origin child session
• Session map — Dict[session_id, SessionInfo] so interaction tools can route to the right attached session for OOPIF operations
• Recent console errors — ring buffer of the last 50 for diagnostics

• Page.enable — javascriptDialogOpening, frameAttached, frameNavigated, frameDetached
• Runtime.enable — executionContextCreated, consoleAPICalled, exceptionThrown
• Target.setAutoAttach {autoAttach: true, flatten: true} — surfaces child OOPIF targets; supervisor enables Page+Runtime on each

​

Lifecycle

• Start: SupervisorRegistry.get_or_start(task_id, cdp_url) — called by browser_navigate, Browserbase session create, /browser connect. Idempotent.
• Stop: session teardown or /browser disconnect. Cancels the asyncio task, closes the WebSocket, discards state.
• Dropped endpoint: after a successful attach the supervisor reconnects with backoff (≤10 s) but gives up after MAX_POST_ATTACH_RECONNECT_FAILURES consecutive failures — one final warning, the thread exits and the registry entry is dropped. A dead local Chrome (its task finished) therefore never leaves a retrying thread behind; the next browser call starts a fresh supervisor.
• Rebind: if the CDP URL changes (user reconnects to a new Chrome), the old supervisor is stopped and a fresh one started — state is never reused across endpoints.

​

Dialog policy

• must_respond (default) — capture, surface in browser_snapshot, wait for explicit browser_dialog(action=...) call. After a 300s safety timeout with no response, auto-dismiss and log. Prevents a buggy agent from stalling forever.
• auto_dismiss — record and dismiss immediately; agent sees it after the fact via browser_state inside browser_snapshot.
• auto_accept — record and accept (useful for beforeunload where the workflow wants to navigate away cleanly).

​

Agent surface

​

browser_dialog tool

browser_dialog(action, prompt_text=None, dialog_id=None)

• action="accept" / "dismiss" → responds to the specified or sole pending dialog (required)
• prompt_text=... → text to supply to a prompt() dialog
• dialog_id=... → disambiguate when multiple dialogs are queued (rare)

​

browser_snapshot extension

{
  "pending_dialogs": [
    {"id": "d-1", "type": "alert", "message": "Hello", "opened_at": 1650000000.0}
  ],
  "recent_dialogs": [
    {"id": "d-1", "type": "alert", "message": "...", "opened_at": 1650000000.0,
     "closed_at": 1650000000.1, "closed_by": "remote"}
  ],
  "frame_tree": {
    "top": {"frame_id": "FRAME_A", "url": "https://example.com/", "origin": "https://example.com"},
    "children": [
      {"frame_id": "FRAME_B", "url": "about:srcdoc", "is_oopif": false},
      {"frame_id": "FRAME_C", "url": "https://ads.example.net/", "is_oopif": true, "session_id": "SID_C"}
    ],
    "truncated": false
  }
}

• pending_dialogs — dialogs currently blocking the page’s JS thread. The agent must call browser_dialog(action=...) to respond. Empty on Browserbase because their CDP proxy auto-dismisses within ~10ms.
• recent_dialogs — ring buffer of up to 20 recently-closed dialogs with a closed_by tag: "agent" (we responded), "auto_policy" (local auto_dismiss/auto_accept), "watchdog" (must_respond timeout hit), or "remote" (browser/backend closed it on us, e.g. Browserbase). This is how agents on Browserbase still get visibility into what happened.
• frame_tree — frame structure including cross-origin (OOPIF) children. Capped at 30 entries + OOPIF depth 2 to bound snapshot size on ad-heavy pages. truncated: true surfaces when limits were hit; agents needing the full tree can use browser_cdp with Page.getFrameTree.

​

Availability gating

​

Cross-origin iframe interaction

​

File layout

• tools/browser_supervisor.py — CDPSupervisor, SupervisorRegistry, PendingDialog, FrameInfo
• tools/browser_dialog_tool.py — browser_dialog tool handler
• tools/browser_tool.py — browser_navigate start-hook, browser_snapshot merge, /browser connect reattach, _cleanup_browser_session teardown
• toolsets.py — registers browser_dialog in browser, mibyan-acp, mibyan-api-server, and core toolsets (gated on CDP reachability)
• mibyan_cli/config.py — browser.dialog_policy and browser.dialog_timeout_s defaults

​

Non-goals

• Detection/interaction for Camofox (upstream gap; tracked separately)
• Streaming dialog/frame events live to the user (would require gateway hooks)
• Persisting dialog history across sessions (in-memory only)
• Per-iframe dialog policies (agent can express this via dialog_id)
• Replacing browser_cdp — it stays as the escape hatch for the long tail (cookies, viewport, network throttling)

​

Testing