2776813df3
The Sep 2026 decomposition (PR #102117) makes internal import paths a non-API: names now live in the focused modules that define them. This commit is the ONLY thing keeping the old paths alive, so external plugins have time to update. It is deliberately a single, unsquashed commit: git revert <this sha> removes every shim, stub and manifest at once on the announced date. Nothing in-tree may depend on these pointers: scripts/check_compat_pointers.py (wired into lint.yml) fails CI if it does. What it adds (see COMPAT_MANIFEST.md, compat_manifest.json): - 332 facade modules get one delimited `PLUGIN-COMPAT` block appended at the end of the file - 1,172 moved names resolved lazily via a module `__getattr__` (PEP 562) — never a top-level import, so no import cycles; facades that already had `__getattr__` get a chained one - 592 third-party/stdlib names the old modules used to expose, with their original import statements - 266 public definitions that had been deleted as unused, restored byte-for-byte from the pre-decomposition tree (+40 private helpers and 16 imports pulled in only because a restored definition needs them) - 3 deleted modules recreated as re-export stubs (gateway/startup_watchdog, hermes_cli/observability/ relay_runtime, tools/environments/modal_utils) - private names (`_x`) get no pointer: they were never API (3,792 skipped) Verified: all 335 touched modules import under a fresh HERMES_HOME and every manifest name resolves; the lint reports zero in-tree uses; ruff clean; targeted suites unchanged.
67 lines
3.1 KiB
Python
67 lines
3.1 KiB
Python
"""Browser Provider ABC: pluggable cloud browser backends (Browserbase, Browser Use, Firecrawl, …).
|
|
|
|
Providers register via :meth:`PluginContext.register_browser_provider`; the active one (selected by
|
|
``browser.cloud_provider``) services every cloud-mode ``browser_*`` tool call. They live in
|
|
``<repo>/plugins/browser/<name>/`` (built-in) or ``~/.hermes/plugins/browser/<name>/`` (user).
|
|
|
|
Session metadata contract (legacy ``CloudBrowserProvider`` shape; ``tools.browser_tool`` needs no
|
|
translation). ``bb_session_id`` is a legacy key name kept verbatim — it holds the provider's session ID
|
|
regardless of provider::
|
|
|
|
{
|
|
"session_name": str, # unique name for agent-browser --session
|
|
"bb_session_id": str, # provider session ID (for close/cleanup)
|
|
"cdp_url": str, # CDP websocket URL
|
|
"expires_at": str, # optional provider-authoritative ISO timestamp
|
|
"features": dict, # feature flags that were enabled
|
|
"external_call_id": str, # optional, managed-gateway billing key
|
|
}
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import abc
|
|
from typing import Dict
|
|
|
|
from agent.provider_base import ProviderBase
|
|
|
|
|
|
class BrowserProvider(ProviderBase):
|
|
"""Abstract base class for a cloud browser backend.
|
|
|
|
Subclasses implement :attr:`name` (the ``browser.cloud_provider`` value), :meth:`is_available`, and
|
|
the lifecycle trio :meth:`create_session` / :meth:`close_session` / :meth:`emergency_cleanup`.
|
|
``get_setup_schema`` may add ``"post_setup"`` (e.g. ``"agent_browser"``) to trigger the install hook.
|
|
"""
|
|
|
|
@abc.abstractmethod
|
|
def is_available(self) -> bool:
|
|
"""True when this provider can service calls. Cheap check only (env var, token readable, dep
|
|
importable) — must NOT make network calls; runs at tool-registration time and on every
|
|
``hermes tools`` paint."""
|
|
|
|
@abc.abstractmethod
|
|
def create_session(self, task_id: str) -> Dict[str, object]:
|
|
"""Create a cloud browser session and return the metadata dict from the module docstring.
|
|
May raise ``ValueError`` (missing credentials) or ``RuntimeError`` (network / API failure);
|
|
the dispatcher surfaces these to the user."""
|
|
|
|
@abc.abstractmethod
|
|
def close_session(self, session_id: str) -> bool:
|
|
"""Release a cloud session by provider session ID. Returns True on success, False on failure;
|
|
should not raise (log and return False so the dispatcher's cleanup loop keeps moving)."""
|
|
|
|
@abc.abstractmethod
|
|
def emergency_cleanup(self, session_id: str) -> None:
|
|
"""Best-effort teardown from atexit / signal handlers. Must tolerate missing credentials and
|
|
network errors; must not raise."""
|
|
|
|
|
|
# ---- BEGIN PLUGIN-COMPAT (revert-scheduled; see COMPAT_MANIFEST.md) ----
|
|
# Names external plugins imported from this module before the Sep 2026 decomposition.
|
|
# Internal code MUST NOT use these (scripts/check_compat_pointers.py fails CI if it does).
|
|
# The whole block is removed by reverting the commit that added it.
|
|
from typing import Any # noqa: F401,E402
|
|
from typing import Optional # noqa: F401,E402
|
|
# ---- END PLUGIN-COMPAT ----
|