better-dsh 0.2.5-c → 0.2.5-d

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

@@ -1,184 +0,0 @@
----
-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

@@ -1,153 +0,0 @@
----
-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

@@ -1,198 +0,0 @@
----
-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.