better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/billing-lifecycle.md

@@ -0,0 +1,184 @@
+---
+title: "Billing Lifecycle (TUI)"
+description: "Map from every billing/subscription state and typed refusal to the exact TUI copy and recovery action"
+---
+
+# Billing lifecycle: client-side state, errors, and recovery
+
+This is the map from every `billing.*`/`subscription.*` state shape the gateway
+serves (from NAS) to what the terminal actually renders, and from every typed
+refusal/error code to its exact user-facing copy and recovery action. The
+guarantee: no NAS billing state and no typed refusal falls through to a
+generic toast — every case below is an explicit branch in
+`ui-tui/src/app/slash/commands/topup.ts`, `ui-tui/src/components/billingOverlay.tsx`,
+or `ui-tui/src/components/subscriptionOverlay.tsx`. An **unknown** code still
+degrades gracefully: it hits the `default` branch (a generic-but-real message
+pulled from the server payload, never a blank toast) rather than crashing or
+silently dropping the refusal.
+
+## 1. `billing.state` shapes → render
+
+Source: `ui-tui/src/components/billingOverlay.tsx` (`OverviewScreen`,
+`BuyScreen`, `AutoReloadScreen`), `ui-tui/src/app/slash/commands/topup.ts` (`/topup` run).
+
+| State shape | Render |
+|---|---|
+| Logged out (`s.logged_in === false`) | Overlay never opens. `sys`: `💳 Not logged into Nous Portal — run /portal to log in, then /topup.` |
+| `billing.state` RPC fetch fails (transport/timeout) | **Fail-closed**: `.catch(ctx.guardedErr)` — overlay never opens, no state is assumed. `sys`: `error: <message or "request failed">`. Never renders "no card" or any other guessed state; user must retry `/topup`. |
+| `card: null` (no saved card), full menu (`is_admin && cli_billing_enabled`) | Overview shows `No saved card on file — "Add funds" walks you through adding one.` "Add funds" opens the **add-card path**: `Add a card on the portal` / `I've added it — check again` / `Back` (never an amount picker, which would 403 `no_payment_method`). |
+| `card` present, `resolved_via` set | `Card: {display}` (e.g. `Visa ····4242 — the card on your subscription`) using the provenance-aware `display` field. |
+| `card` present, `resolved_via` absent (older NAS) | Falls back to the generic `Card: {masked}`; Confirm screen adds `Your card saved on the portal will be charged.` |
+| `auto_reload: null` | No auto-reload line at all (`autoReloadLine` returns `null`) — the feature isn't surfaced. |
+| `auto_reload.card.kind: 'canonical'` | No distinct-card warning; card line falls back to the card on file. |
+| `auto_reload.card.kind: 'distinct'` | `⚠ Auto-refill is charging {brand} ••{last4} — not your card on file.` in the Auto-reload screen (the divergence notice). |
+| `auto_reload.card.kind: 'none'` | Same as `canonical` rendering-wise — no distinct-card warning shown. |
+| `monthly_cap` present, `limit_usd != null` | `{spent_display} of {limit_display} used this month` (+ ` (default ceiling)` iff `is_default_ceiling`). |
+| `monthly_cap` absent or `limit_usd == null` | `No monthly cap visible (managed on the portal).` |
+| Role without billing capability (`!is_admin`, menu collapses) | Note: `Billing actions need someone with billing permissions (owner, admin, or finance admin).` Menu collapses to `Manage on portal` / `Cancel`. |
+| Org kill-switch off (`is_admin` but `!cli_billing_enabled`) | Note: `Remote spending is off for this org — a billing admin can turn it on from the portal's Hermes Agent page.` Same collapsed menu. |
+
+Note: `full = s.is_admin && s.cli_billing_enabled` gates the **org-level**
+switch, not the per-terminal `billing:manage` scope — that's discovered
+reactively (a charge 403s `insufficient_scope`) and routes to the resumable
+step-up screen instead of a preflight check.
+
+## 2. Refusal codes (`renderBillingError`, in code order)
+
+Source: `renderBillingError` in `ui-tui/src/app/slash/commands/topup.ts:37-149`.
+"Portal" row = `sys('Portal: {portal_url}')` is appended whenever `portal_url` is present, for every code (including default).
+
+| `error` code | Copy | Portal URL | `retry_after` |
+|---|---|:-:|:-:|
+| `insufficient_scope` | `This needs Remote Spending allowed. Start a top-up to allow it, then retry.` | if present | — |
+| `remote_spending_revoked` (CF-4) | `{An admin stopped remote spending for this terminal. \| You stopped remote spending for this terminal.}` (by `actor`) `Reconnect to restore — run /portal to re-authorize this terminal.` Also clears `billing` overlay state immediately (doesn't wait for token refresh). | if present | — |
+| `session_revoked` | `Your session was logged out. Run /portal to log in again.` Also clears `billing` overlay state. | if present | — |
+| `cli_billing_disabled` / `remote_spending_disabled` (dual-emitted) | `Remote spending is off for this account — a billing admin can turn it on from the portal's Hermes Agent page.` | if present | — |
+| `role_required` | `Adding funds needs someone with billing permissions (owner, admin, or finance admin), or manage this on the portal.` | if present | — |
+| `consent_required` | `This action needs a one-time card confirmation and consent step on the portal before it can proceed.` | if present | — |
+| `org_access_denied` | `This token isn't bound to an org you can manage. Sign in with the right org, or manage this on the portal.` | if present | — |
+| `upgrade_cap_exceeded` | `🔴 Daily plan-change limit reached (5 per org) — try again tomorrow, or manage this on the portal.` | if present | — |
+| `auto_top_up_disabled_failures` | `Auto-reload was turned off after repeated charge failures. Fix the card issue, then re-enable it from /topup → Auto-reload.` | if present | — |
+| `idempotency_conflict` | `🔴 That charge key was already used for a different amount. Start a fresh top-up.` | if present | — |
+| `no_payment_method` | `💳 No saved card for terminal charges yet. Set one up on the portal (one-time credit buys don't save a reusable card).` | if present | — |
+| `monthly_cap_exceeded` | `🔴 Monthly spend cap reached — ${remainingUsd} headroom left.` if `payload.remainingUsd` present, else `🔴 Monthly spend cap reached.` | if present | — |
+| `rate_limited` / `temporarily_unavailable` | `🟡 Too many charges right now{ (try again in ~N min)}. This isn't a payment failure.` | if present | **yes** — minutes computed as `max(1, round(retry_after/60))` |
+| `stripe_unavailable` | `🟡 Stripe is having trouble right now — try again shortly{ (try again in ~N min)}.` | if present | **yes** (same formula) |
+| *default (unknown/other)* | `🔴 {message \|\| error \|\| 'Billing request failed.'}` — still surfaces whatever the server said, never a blank toast. | if present | — |
+
+## 3. Charge settlement outcomes (`pollCharge` / `renderChargeFailed`)
+
+Source: `pollCharge` (`ui-tui/src/app/slash/commands/topup.ts:170-258`) and
+`renderChargeFailed` (`:260-290`). Poll cadence: 2s interval, 5-minute cap
+(`POLL_INTERVAL_MS=2000`, `POLL_CAP_MS=5*60*1000`), applied on **every**
+non-terminal path (pending *and* throttled), so a sustained 429/503 can't
+keep the poll alive forever.
+
+| Outcome | Copy | Notes |
+|---|---|---|
+| `status: 'settled'` | `✅ ${amount_usd} added.` (or `✅ Credits added.` if no amount) | Terminal success. |
+| `status: 'failed'`, `reason: 'authentication_required'` | `🔴 Your bank requires verification (3DS). Complete it on the portal to finish this purchase.` | + `Portal:` line if `portalUrl`. |
+| `status: 'failed'`, `reason: 'payment_method_expired'` | `🔴 Your card has expired. Update it on the portal.` | + `Portal:` line. |
+| `status: 'failed'`, `reason: 'card_declined'` | `🔴 Your card was declined. Try another card on the portal.` | + `Portal:` line. |
+| `status: 'failed'`, `reason: 'processing_error'` | `🔴 The charge didn't go through (processing_error).` | + `Portal:` line. |
+| `status: 'failed'`, unrecognized/missing `reason` | `🔴 The charge didn't go through ({reason \|\| 'processing_error'}).` | Same portal funnel — parity with `cli.py`'s `_billing_portal_hint`. |
+| Poll timeout (still `pending` past the 5-min cap) | `🟡 Still processing after 5 minutes — this is a timeout, not a failure. Check /topup or the portal shortly.` | + `Portal:` line if `portalUrl`. Explicitly NOT called a failure. |
+| Revocation mid-poll (`remote_spending_revoked` / `session_revoked` while polling) | Renders the matching §2 copy, **then** appends: `🟡 Your last charge's outcome is unconfirmed — check your balance/history before retrying.` | CF-7 rule 4: a post-revoke 403 while polling is ambiguous (the charge may have already settled) — never call it "failed". |
+| 429/503 while polling (`rate_limited`/`temporarily_unavailable`/`stripe_unavailable`) | No error shown; backs off using `retry_after` (default 5s, capped at 30s) and keeps polling until the 5-min cap, then reads as timeout. | Not a payment failure. |
+| Other `!ok` status-check error | `🔴 Could not check the charge: {message \|\| error \|\| 'error'}` | |
+| Transport loss (poll RPC throws/rejects) | `🟡 Your last charge's outcome is unconfirmed — check your balance/history before retrying.` (`UNCONFIRMED_CHARGE_MESSAGE`) | Same "unconfirmed, check balance" framing as revocation mid-poll — a dropped connection can never be read as "failed". |
+
+## 4. Subscription preview / pending-change / upgrade outcomes
+
+Source: `previewAndRoute`, `applyPendingAndRoute`, `upgradeResult`,
+`stepUpDenialResult` in `ui-tui/src/components/subscriptionOverlay.tsx`.
+
+**Preview `effect` values** (drive the Confirm screen):
+
+| `effect` | Confirm screen copy | Primary action |
+|---|---|---|
+| `charge_now` | `Upgrade to {target}. You will be charged {amount} now (prorated).` (+ monthly-credits delta, + which card if resolver confidently knows) | `Pay {amount} & upgrade now` |
+| `scheduled` | `Change to {target} — takes effect {date}. No charge now; you keep your current plan until then.` | `Schedule change to {target}` |
+| `no_op` | `You are already on {target} — nothing to change.` | none (Back only) |
+| `blocked` | `{preview.reason}` or fallback `That change cannot be made here — manage it on the portal.` | `Manage on portal` |
+| Preview RPC returns `null`/transport failure | routes straight to Result: `Could not preview that change.` | — |
+| Preview `!ok`, `insufficient_scope` | routes to `stepup` screen (`{kind:'preview', tierId}`) | — |
+| Preview `!ok`, other error | routes to Result with `errorResult(p)` (`message \|\| error \|\| 'Something went wrong. Try again, or manage on the portal.'`) | — |
+
+**Pending-change apply outcomes** (`applyPendingAndRoute`):
+
+| `pending.kind` | Success copy |
+|---|---|
+| `cancellation` | `Scheduled — your plan stays active until the end of the billing period, then it cancels. Nothing changes today.` |
+| `tier_change` (downgrade/schedule) | `Scheduled — your plan doesn't change today. You keep your current plan until the end of the billing period, then it switches.` |
+| `upgrade` | routed through `upgradeResult` (below) |
+| any kind, mutation `insufficient_scope` | routes to stepup (`{kind:'apply'}`) |
+
+**Upgrade `status` × `reason` matrix** (`upgradeResult`, checked in this
+order — `reason` is checked *before* `status`):
+
+| Condition | Result |
+|---|---|
+| `r === null` (transport failure on the charging route) | `Couldn't confirm the upgrade — your card may or may not have been charged. Re-run /subscription to check your plan before trying again.` — ambiguous, never a blind retry. |
+| `reason: 'authentication_required'` **or** `reason: 'subscription_payment_intent_requires_action'` | `Please verify your card in the portal to finish this upgrade.` → `recovery_url`. **Both reasons map to the same SCA copy** — the client branches on `reason`, not `status`, specifically so an SCA case that pre-#711 NAS mislabels with `status: 'payment_failed'` (no distinguishing reason yet) still routes to the correct "verify your card" copy instead of reading as a hard decline. |
+| `reason: 'card_declined'` | `Your card was declined — try a different card on the portal.` → `recovery_url`. |
+| `ok && status: 'already_on_tier'` | `You are already on {target_tier_name}.` (success) |
+| `ok && status: 'upgraded'` | `Upgraded to {target_tier_name}. Your new monthly credits land in a moment.` — starts the eventual-consistency apply-poll (below). |
+| `status: 'requires_action'` (no distinguishing reason) | `This upgrade needs extra verification (3DS). Finish it on the portal.` → `recovery_url`. |
+| `status: 'payment_failed'` (no distinguishing reason) | `Your card was declined. Update your payment method on the portal and try again.` → `recovery_url`. |
+| anything else | `errorResult(r)`: `message \|\| error \|\| 'Something went wrong. Try again, or manage on the portal.'` |
+
+**Eventual-consistency apply-poll** (`ResultScreen`, only after `status:
+'upgraded'`): polls `billing`/subscription state every 2s
+(`UPGRADE_CONFIRM_INTERVAL_MS`) up to 15 attempts
+(`UPGRADE_CONFIRM_ATTEMPTS`, i.e. ~30s) until `current.tier_id` flips to the
+target. While waiting the screen reads `Applying…`; if it never flips inside
+the budget it reads `Still applying` / `Your upgrade succeeded and is still
+applying — refresh in a moment.` — the upgrade is never re-reported as failed
+just because NAS hasn't caught up yet.
+
+**Step-up denial copy** (`stepUpDenialResult`, subscription flow):
+
+| `error` | Copy |
+|---|---|
+| `session_revoked` | `Your session expired — run /portal to log in again, then retry the change.` |
+| `remote_spending_revoked` | `{message}` or `Remote spending was stopped for this terminal — reconnect from the portal, then retry.` |
+| `rate_limited` | `Too many attempts — wait a moment, then try again.` |
+| other/unknown | `{message}` or `Remote Spending was not allowed — someone with billing permissions (owner, admin, or finance admin) must approve it. You can also make this change on the portal.` |
+
+A **repeat** scope denial during a post-grant replay never re-enters the
+step-up screen (it's already mounted there — re-patching would freeze it);
+`allowStepUp=false` instead surfaces a terminal result: `Remote Spending still
+isn’t active for this terminal — the authorization didn’t take. Retry, or make
+this change on the portal.`
+
+## Text-mode (CLI) parity
+
+`cli.py`'s `_show_billing` / `_billing_overview` and `_show_subscription` /
+`_subscription_overview` render the same state shapes (balance title, two-bar
+dollar usage, auto-reload line, card line, monthly cap) and share the
+"fail-open on logged-out/portal-hiccup, never crash" discipline. The CLI's
+`/subscription` gives a paid admin/owner in an interactive context the **full
+in-terminal change flow** (tier picker → preview → confirm → apply, parity
+with the TUI overlay); members and non-interactive contexts fall back to
+`_billing_portal_hint`'s deep-link to `subscription_manage_url`. `/topup`'s
+interactive modal (prompt_toolkit) mirrors the TUI overlay the same way, and
+non-interactive contexts fall back to the same text + portal-link rendering,
+never prompting.
+
+| CLI surface / state | Behavior (parity with TUI / desktop) |
+| --- | --- |
+| `/subscription` on **Free** + admin/owner + interactive | `_subscription_free_catalog` prints the plan catalog from the same `tiers[]` data the TUI uses — one row per enabled paid tier, cheapest first, `name · $/mo · $credits/mo` (monthly credits are DOLLARS → `$22 credits/mo`, never a bare number). A numbered pick opens the `/manage-subscription` deep-link with `plan=<tier_id>` appended so the portal preselects the chosen plan. Starting a new subscription needs a fresh card, so the only action is the portal hand-off (the terminal never charges here). |
+| Any CLI-built manage/subscribe URL | `subscription_manage_url(state, tier_id=…)` appends `plan=<tier_id>` (the stable `tiers[]` id, never a name/slug) **only when a tier was picked** (the Free catalog). The portal validates it server-side and ignores an unknown tier, so the CLI appends unconditionally on a pick, mirroring the TUI's `?plan=`. `org_id` is emitted first, `plan` second. |
+| **Downgrades** in the CLI | Stay **native / in-app** for normal changes (chargeless scheduling via `put_subscription_pending_change`). A blocked downgrade may still print the generic manage URL, but it never carries `plan=<tier_id>` — selected-tier deep-links are reserved for new subscriptions and upgrades. |
+| `/topup` overview action copy | Splits one-time top-up from automatic refill, the distinction stated up front in each first sentence: `Add funds now — a single charge, added to your balance today.` vs `Refill when low — charges $X automatically when your balance falls below $Y.` ("credits" stays out of the dollars-only `/topup` surface — "Add funds now" carries the one-time meaning without it). When auto-reload is off, the automatic line omits concrete amounts. |
+
+## Forward compatibility
+
+Any `error`/`status`/`reason` code not in the tables above lands on the
+`default` branch in `renderBillingError` (§2) or `errorResult`/`upgradeResult`'s
+fallthrough (§4): it still renders the server's own `message` (never blank,
+never a crash), just without bespoke copy or a typed recovery affordance.
+NAS W3 introduces card-health codes (`card_paused`, `card_expired`,
+`card_mismatch`) that are not yet typed here — until a client update adds
+explicit branches, they will arrive as unknown codes and degrade to this
+default path.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/browser-provider-plugin.md

@@ -0,0 +1,153 @@
+---
+sidebar_position: 13
+title: "Browser Provider Plugins"
+description: "How to build a cloud browser backend plugin for Hermes Agent"
+---
+
+# Building a Browser Provider Plugin
+
+Browser provider plugins register a **cloud browser backend** that services cloud-mode `browser_*` tool calls (navigate, click, screenshot, …). Built-in providers — Browserbase, Browser Use, and Firecrawl — all ship as plugins under `plugins/browser/<name>/`. You can add a new one, or override a bundled one, by dropping a directory next to them.
+
+:::tip
+Browser backends are one of several **backend plugins** Hermes supports. The others (with their own ABCs) are [Web Search Provider Plugins](/developer-guide/web-search-provider-plugin) (which this ABC deliberately mirrors), [Image Generation](/developer-guide/image-gen-provider-plugin), [Video Generation](/developer-guide/video-gen-provider-plugin), [Memory Providers](/developer-guide/memory-provider-plugin), [Context Engines](/developer-guide/context-engine-plugin), [Secret Sources](/developer-guide/secret-source-plugin), and [Model Providers](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/developer-guide/plugins).
+:::
+
+## How it fits together
+
+A browser provider does **not** implement browsing. It implements **session lifecycle**: create a remote browser session, hand back a CDP websocket URL, and tear the session down. Hermes' own browser stack (`agent-browser` + `tools/browser_tool.py`) connects to whatever CDP URL you return and drives the page from there — every provider gets the full `browser_*` toolset for free.
+
+The active provider is selected by `browser.cloud_provider` in `config.yaml`; the dispatcher in `tools/browser_tool.py` is a pure registry lookup with no per-provider conditionals.
+
+## Discovery
+
+Hermes scans for browser backends in three places:
+
+1. **Bundled** — `<repo>/plugins/browser/<name>/` (auto-loaded with `kind: backend`)
+2. **User** — `~/.hermes/plugins/browser/<name>/` (opt-in via `plugins.enabled` or `hermes plugins enable <name>`)
+3. **Pip** — packages declaring a `hermes_agent.plugins` entry point
+
+Each plugin's `register(ctx)` calls `ctx.register_browser_provider(...)`, which puts the instance into the registry in `agent/browser_registry.py`.
+
+## Directory structure
+
+```
+plugins/browser/my-backend/
+├── __init__.py     # register() entry point
+├── provider.py     # BrowserProvider subclass
+└── plugin.yaml     # Manifest with kind: backend and provides_browser_providers
+```
+
+`plugin.yaml`:
+
+```yaml
+name: browser-my-backend
+version: 1.0.0
+description: "My cloud browser backend. Requires MY_BACKEND_API_KEY."
+author: you
+kind: backend
+provides_browser_providers:
+  - my-backend
+```
+
+`__init__.py`:
+
+```python
+from plugins.browser.my_backend.provider import MyBackendProvider
+
+
+def register(ctx) -> None:
+    ctx.register_browser_provider(MyBackendProvider())
+```
+
+## The BrowserProvider ABC
+
+Implement `agent.browser_provider.BrowserProvider`. Three lifecycle methods plus identity:
+
+```python
+from agent.browser_provider import BrowserProvider
+
+
+class MyBackendProvider(BrowserProvider):
+    @property
+    def name(self) -> str:
+        return "my-backend"          # the browser.cloud_provider config value
+
+    @property
+    def display_name(self) -> str:
+        return "My Backend"          # shown in `hermes tools`
+
+    def is_available(self) -> bool:
+        """Cheap check only — env var present, dep importable.
+        NO network calls: runs at tool-registration time and on every
+        `hermes tools` paint."""
+        return bool(os.environ.get("MY_BACKEND_API_KEY"))
+
+    def create_session(self, task_id: str) -> dict:
+        """Create a remote browser session; return the session-metadata contract."""
+        session = my_api.create_browser(...)
+        return {
+            "session_name": f"my-backend-{task_id}",  # unique agent-browser session name
+            "bb_session_id": session.id,              # provider session ID (for cleanup)
+            "cdp_url": session.cdp_ws_url,            # CDP websocket URL
+            "features": {"stealth": True},            # feature flags you enabled
+        }
+
+    def close_session(self, session_id: str) -> bool:
+        """Terminate by provider session ID. Log-and-return-False on error —
+        never raise, so the dispatcher's cleanup loop keeps moving."""
+        ...
+
+    def emergency_cleanup(self, session_id: str) -> None:
+        """Best-effort teardown from atexit/signal handlers. Must not raise."""
+        ...
+```
+
+### The session-metadata contract
+
+`create_session()` must return at least `session_name`, `bb_session_id`, `cdp_url`, and `features`. Two quirks worth knowing:
+
+- **`bb_session_id` is a legacy key name** kept verbatim for backward compatibility with `tools/browser_tool.py` — it holds *your* provider's session ID regardless of vendor. Don't rename it.
+- `create_session()` **may raise** — `ValueError` for missing credentials, `RuntimeError` for network/API failures. The dispatcher surfaces these to the user. This differs from `close_session`/`emergency_cleanup`, which must never raise.
+
+An optional `external_call_id` key supports managed-gateway billing.
+
+### `get_setup_schema()` — the `hermes tools` picker row
+
+Override this to appear as a first-class option in the Browser Automation picker with API-key prompts and an install hook:
+
+```python
+def get_setup_schema(self) -> dict:
+    return {
+        "name": "My Backend",
+        "badge": "paid",
+        "tag": "Cloud browser with stealth and proxies",
+        "env_vars": [
+            {"key": "MY_BACKEND_API_KEY",
+             "prompt": "My Backend API key",
+             "url": "https://mybackend.example"},
+        ],
+        "post_setup": "agent_browser",   # ensures local Chromium is installed (agent-browser itself resolves via npx)
+    }
+```
+
+Per the project standard for tool backends: if a backend can't be selected and configured through `hermes tools`, it isn't done — "set this env var manually" is not an integration.
+
+## Users configure it
+
+```yaml
+browser:
+  cloud_provider: my-backend
+```
+
+## Reference implementations
+
+The three bundled providers under `plugins/browser/` are the canonical examples, in ascending complexity: `firecrawl` (simplest), `browser_use`, and `browserbase` (stealth/proxy/keep-alive feature flags with graceful fallback when paid features are unavailable). Copy the closest one.
+
+## Checklist
+
+- [ ] `name` is lowercase and stable (it's a config value users write)
+- [ ] `is_available()` makes zero network calls
+- [ ] `create_session()` returns the full metadata contract (`bb_session_id` key name intact)
+- [ ] `close_session()` / `emergency_cleanup()` never raise
+- [ ] `get_setup_schema()` exposes your env vars so `hermes tools` can configure the backend
+- [ ] `plugin.yaml` declares `kind: backend` + `provides_browser_providers`

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/browser-supervisor.md

@@ -0,0 +1,198 @@
+---
+sidebar_position: 18
+title: "Browser CDP Supervisor"
+description: "How Hermes detects and responds to native JS dialogs and interacts with cross-origin iframes via a persistent CDP connection."
+---
+
+# Browser CDP Supervisor
+
+The CDP supervisor closes two long-standing gaps in Hermes' browser tooling:
+
+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.
+
+The supervisor solves both by holding a persistent WebSocket to the backend's
+CDP endpoint per browser task, surfacing pending dialogs and frame structure
+into `browser_snapshot`, and exposing a `browser_dialog` tool for explicit
+responses.
+
+## Backend support
+
+| Backend | Dialog detect | Dialog respond | Frame tree | OOPIF `Runtime.evaluate` via `browser_cdp(frame_id=...)` |
+|---|---|---|---|---|
+| Local Chrome (`--remote-debugging-port`) / `/browser connect` | ✓ | ✓ full workflow | ✓ | ✓ |
+| Browserbase | ✓ (via bridge) | ✓ full workflow (via bridge) | ✓ | ✓ |
+| Camofox | ✗ no CDP (REST-only) | ✗ | partial via DOM snapshot | ✗ |
+
+**Browserbase quirk.** Browserbase's CDP proxy uses Playwright internally and
+auto-dismisses native dialogs within ~10ms, so `Page.handleJavaScriptDialog`
+can't keep up. The supervisor injects a bridge script via
+`Page.addScriptToEvaluateOnNewDocument` that overrides
+`window.alert`/`confirm`/`prompt` with a synchronous XHR to a magic host
+(`hermes-dialog-bridge.invalid`). `Fetch.enable` intercepts those XHRs before
+they touch the network — the dialog becomes a `Fetch.requestPaused` event the
+supervisor captures, and `respond_to_dialog` fulfills via
+`Fetch.fulfillRequest` with a JSON body the injected script decodes.
+
+From the page's perspective, `prompt()` still returns the agent-supplied
+string. From the agent's perspective, it's the same `browser_dialog(action=...)`
+API either way.
+
+Camofox is unsupported — no CDP surface, REST-only.
+
+## Architecture
+
+### CDPSupervisor
+
+One `asyncio.Task` running in a background daemon thread per Hermes `task_id`.
+Holds a persistent WebSocket to the backend's CDP endpoint. Maintains:
+
+- **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
+
+Subscribes on attach:
+
+- `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
+
+Thread-safe state access via a snapshot lock; tool handlers (sync) read the
+frozen snapshot without awaiting.
+
+### 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.
+- **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
+
+Configurable via `config.yaml` under `browser.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).
+
+Policy is per-task; no per-dialog overrides.
+
+## 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)
+
+Tool is response-only. The agent reads pending dialogs from `browser_snapshot`
+output before calling.
+
+### `browser_snapshot` extension
+
+Adds three optional fields to the existing snapshot output when a supervisor
+is attached:
+
+```json
+{
+  "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`.
+
+No new tool schema surface for any of these — the agent reads the snapshot it
+already requests.
+
+### Availability gating
+
+Both surfaces gate on `_browser_cdp_check` (supervisor can only run when a CDP
+endpoint is reachable). On Camofox / no-backend sessions, the dialog tool is
+hidden and the snapshot omits the new fields — no schema bloat.
+
+## Cross-origin iframe interaction
+
+`browser_cdp(frame_id=...)` routes CDP calls (notably `Runtime.evaluate`)
+through the supervisor's already-connected WebSocket using the OOPIF's child
+`sessionId`. Agents pick frame_ids out of
+`browser_snapshot.frame_tree.children[]` where `is_oopif=true` and pass them
+to `browser_cdp`. For same-origin iframes (no dedicated CDP session), the
+agent uses `contentWindow`/`contentDocument` from a top-level
+`Runtime.evaluate` instead — the supervisor surfaces an error pointing at that
+fallback when `frame_id` belongs to a non-OOPIF.
+
+On Browserbase, this is the only reliable path for iframe interaction —
+stateless CDP connections (opened per `browser_cdp` call) hit signed-URL
+expiry, while the supervisor's long-lived connection keeps a valid session.
+
+## 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`, `hermes-acp`, `hermes-api-server`, and core toolsets (gated on CDP reachability)
+- `hermes_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
+
+Unit tests (`tests/tools/test_browser_supervisor.py`) use an asyncio mock CDP
+server that speaks enough of the protocol to exercise all state transitions:
+attach, enable, navigate, dialog fire, dialog dismiss, frame attach/detach,
+child target attach, session teardown. Real-backend E2E (Browserbase + local
+Chromium-family browser) is manual — exercise via `/browser connect` to a
+live Chromium-family browser and run the dialog/frame test cases described
+above.