browserwright 0.6.2__py3-none-any.whl

browserwright/session.py

@@ -0,0 +1,229 @@
+"""Per-process Skill session.
+
+Holds:
+  - one ``ModeBClient`` (long-lived daemon socket)
+  - one ``CDPSession`` (lazy: opened on first primitive that touches the browser)
+  - the currently-attached target id (the "current tab")
+
+Concurrency model (v0.3 prep)
+-----------------------------
+
+Primitives reach the session through ``current_session()``. Historically this
+returned a process-wide singleton — fine for REPL / inline / single-task
+flows because there's only one Chrome ws to multiplex.
+
+Layer 3 wants to fan out multiple tasks concurrently against the same daemon.
+If two tasks ran in the same process they'd race over ``current_target_id``
+(one task's ``new_tab`` would yank the other's attached tab). So v0.3 adds:
+
+* ``Session`` instances per task, isolated state, no shared mutable surface
+  beyond the daemon CDP transport (which is already thread-safe).
+* ``with_session(sess)`` context manager that pushes ``sess`` onto a
+  ``ContextVar`` for the duration of the ``with`` block. Threads that enter
+  the context see *that* session via ``current_session()``; outside the
+  context they see the default singleton.
+
+The default singleton stays — REPL / inline never need a fresh session and
+overriding it would force callers to pass it through explicitly. The
+``ContextVar`` is the override knob.
+"""
+from __future__ import annotations
+
+import contextvars
+import os
+import threading
+from contextlib import contextmanager
+from typing import Iterator, Optional
+
+from .cdp import CDPSession
+from .errors import DaemonUnavailable
+
+
+class Session:
+    def __init__(self, daemon=None, *, record=None):
+        # ``daemon`` is a ``ModeBClient`` (long-lived socket), exposing
+        # ``resolve_ws_url`` / ``ws_url`` semantics through the methods we use
+        # below. (Mode A — the subprocess resolver — was removed.)
+        #
+        # ``record`` is a resolved session ledger record. There is one global
+        # daemon on a fixed socket; the session's ``id`` is carried as the ws
+        # client label (``skill-s<id>``) so the daemon routes this client to the
+        # session's UpstreamContext (per-session isolation lives daemon-side now).
+        # Stored as ``session_record`` to avoid shadowing the ``record()`` method.
+        self.session_record = record
+        if daemon is None:
+            if record is None:
+                from .errors import NoSession
+                raise NoSession(
+                    "no session bound: a Session needs an explicit ledger "
+                    "record (its backend/daemon comes from `session new`). "
+                    "Pass record=/daemon= explicitly."
+                )
+            from .mode_b_client import client_for_session
+            daemon = client_for_session(record)
+        self.daemon = daemon
+        self._cdp: Optional[CDPSession] = None
+        self._cdp_lock = threading.Lock()
+        self.current_target_id: Optional[str] = None
+        # Last-seen accuracy from getActiveTab for warn-on-stale UX.
+        self.last_active_tab: Optional[dict] = None
+        # Caches keyed by host name → memory dict for performance.
+        self._site_mem_cache: dict[str, dict] = {}
+        # ``BS_HOME`` resolved once.
+        self.home = os.path.expanduser(os.environ.get("BS_HOME", "~/.browserwright"))
+        # Whether this Session was created for an isolated scope (with_session
+        # / task_runner per-task). Affects close(): we leave shared CDP
+        # transports alone, but isolated ones get their CDP closed too if it
+        # was opened just for this scope.
+        self._owns_cdp = True
+
+    @property
+    def cdp(self) -> CDPSession:
+        if self._cdp is not None and not self._cdp._closed:
+            return self._cdp
+        with self._cdp_lock:
+            if self._cdp is not None and not self._cdp._closed:
+                return self._cdp
+            url = self._resolve_ws_url()
+            self._cdp = CDPSession(url)
+            return self._cdp
+
+    def _resolve_ws_url(self) -> str:
+        """Ask the underlying daemon client for a CDP ws URL.
+
+        ``ModeBClient.resolve_ws_url`` aliases ``ws_url()``. On failure, retry
+        once after dropping the cached URL — spec §D.7.
+        """
+        try:
+            return self.daemon.resolve_ws_url()
+        except DaemonUnavailable:
+            self.daemon.invalidate()
+            return self.daemon.resolve_ws_url()
+
+    def close(self) -> None:
+        if self._cdp is not None and self._owns_cdp:
+            self._cdp.close()
+        self._cdp = None
+
+    @property
+    def backend_name(self) -> str:
+        """Lazy-resolved daemon backend name (``"rdp"``, ``"extension"``, …).
+
+        Diagnostics only — the downstream API is unified, so primitives no
+        longer branch on the backend (backend divergence is absorbed daemon-side;
+        see docs/refactor-single-daemon.md). Surfaced for doctor / debugging.
+        Falls back to ``""`` when the daemon doesn't surface backend info.
+        """
+        cached = getattr(self, "_backend_name_cache", None)
+        if cached is not None:
+            return cached
+        if isinstance(self.session_record, dict):
+            name = self.session_record.get("backend") or ""
+            if name:
+                self._backend_name_cache = name  # type: ignore[attr-defined]
+                return name
+        info = None
+        getter = getattr(self.daemon, "get_backend_info", None)
+        if callable(getter):
+            # Narrow the catch to the failure modes the underlying clients
+            # actually surface: ModeBClient.get_backend_info wraps subprocess
+            # plumbing (FileNotFoundError, TimeoutExpired) and JSON parsing.
+            # OSError covers low-level I/O. AttributeError absorbs a missing
+            # inner shim rather than letting an internal bug crash backend-name
+            # resolution. Truly unexpected exceptions propagate.
+            import json as _json
+            import subprocess as _subprocess
+            try:
+                info = getter()
+            except (AttributeError, OSError,
+                    _subprocess.CalledProcessError, _subprocess.TimeoutExpired,
+                    _json.JSONDecodeError):
+                info = None
+        name = ""
+        if isinstance(info, dict):
+            name = info.get("backend") or info.get("name") or ""
+        self._backend_name_cache = name  # type: ignore[attr-defined]
+        return name
+
+
+# ---- singleton + context-var override ---------------------------------
+
+# Module-level default. Lazily created on first ``current_session()`` call
+# from a context that hasn't pushed an override. Lives for the process.
+_singleton: Optional[Session] = None
+_singleton_lock = threading.Lock()
+
+# ContextVar holds the currently-active Session for this thread / task.
+# ``None`` means "no override → use the default singleton".
+_active: contextvars.ContextVar[Optional[Session]] = contextvars.ContextVar(
+    "browserwright_session", default=None
+)
+
+
+def current_session() -> Session:
+    """Return the Session bound to the current execution context.
+
+    Resolution order:
+      1. The ``ContextVar`` push (most recent ``with_session(...)`` block).
+      2. The process-wide default singleton, bound by ``set_session()``.
+
+    There is no env-guessed default: a Session's backend/daemon comes from an
+    explicit ledger record. Entry points bind one via
+    ``set_session(Session(record=...))`` before primitives run. Calling this
+    with nothing bound raises ``NoSession`` from ``Session.__init__``.
+    """
+    override = _active.get()
+    if override is not None:
+        return override
+    global _singleton
+    if _singleton is None:
+        with _singleton_lock:
+            if _singleton is None:
+                _singleton = Session()
+    return _singleton
+
+
+def set_session(sess: Optional[Session]) -> None:
+    """Bind the process-wide default Session. The CLI entry point calls
+    this with a record-bound Session; tests use it to install a mock. Pushing
+    via ``with_session()`` is preferred when the override should be scoped."""
+    global _singleton
+    _singleton = sess
+
+
+def isolated_session() -> Session:
+    """A fresh Session for fan-out / isolated task runs.
+
+    Inherits the current session's daemon binding (so it drives the *same*
+    browser) but isolates target tracking (its own ``current_target_id``), so
+    concurrent tasks don't yank each other's attached tab. Prefers the ledger
+    record (own client connection) and falls back to sharing the parent's
+    daemon when the parent was constructed without a record (tests)."""
+    parent = current_session()
+    if parent.session_record is not None:
+        return Session(record=parent.session_record)
+    return Session(daemon=parent.daemon)
+
+
+@contextmanager
+def with_session(sess: Session) -> Iterator[Session]:
+    """Run a block with ``sess`` as the active session.
+
+    Pattern (per-task isolation)::
+
+        from browserwright.session import isolated_session, with_session
+        with with_session(isolated_session()) as sess:
+            goto_url("https://example.com")
+            # this block's primitives operate on `sess`, not the default
+        # outside the `with`, primitives revert to the default singleton.
+
+    The session's CDP transport is *not* closed automatically — callers that
+    spin a Session for a one-shot task should call ``sess.close()`` after
+    the ``with``. This split exists because most callers want to reuse one
+    transport across many ``with_session`` blocks (Layer 3 task pool).
+    """
+    token = _active.set(sess)
+    try:
+        yield sess
+    finally:
+        _active.reset(token)

browserwright/session_create.py

@@ -0,0 +1,252 @@
+"""Session creation/teardown per backend.
+
+Creation is **explicit**: an agent picks ``extension`` / ``rdp --create`` /
+``rdp --attach``. This module allocates the ledger entry and makes sure the
+ONE global daemon is running.
+
+Single-daemon model (docs/refactor-single-daemon.md §P3): there is exactly one
+global daemon on a fixed socket (no ``--name`` / ``BD_NAME``). It serves both
+backends simultaneously, routing per session. For rdp the daemon itself launches
+and owns the per-session Chrome on ``ensureSession`` and tears it down on
+``endSession`` — this module no longer spawns a per-session daemon or launches
+Chrome directly. ``new()`` only:
+  - allocates the ledger entry (recording the chosen port in ``workspace`` so
+    the daemon pins the rdp Chrome to it), and
+  - ensures the single daemon is up.
+
+Teardown talks to the single daemon via the ``browserwright-daemon`` CLI
+(``end-session`` / ``disconnect``), which the daemon already understands — no
+``--name`` is passed anymore.
+
+Ownership rule: who ``create``s, closes; ``attach`` only reminds.
+"""
+from __future__ import annotations
+
+import socket
+import subprocess
+from typing import Optional
+
+from . import session_registry as reg
+
+
+def _free_port() -> int:
+    """Ask the OS for an unused localhost TCP port."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+    finally:
+        s.close()
+
+
+def _spawn_detached(cmd: list[str]) -> int:
+    """Start a long-lived background process detached from this one; return pid."""
+    proc = subprocess.Popen(
+        cmd,
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL, start_new_session=True,
+    )
+    return proc.pid
+
+
+def _run(cmd: list[str]) -> int:
+    """Run a short-lived command; return its exit code (best-effort)."""
+    try:
+        return subprocess.run(cmd, capture_output=True, timeout=10).returncode
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return 1
+
+
+def _ensure_daemon_running() -> None:
+    """Make sure the ONE global daemon is up; spawn ``serve`` detached if not.
+
+    There is no ``--name`` anymore — a single fixed-socket daemon serves every
+    session. ``serve`` itself stale-detects an already-running daemon and exits
+    1, so spawning unconditionally is safe (a redundant spawn is a no-op), but
+    we ping first to avoid the churn.
+    """
+    from .daemon import _ipc
+    from .version import package_version
+    try:
+        pid, running_version = _ipc.ping_status_sync(timeout=1.0)
+        if pid is not None and running_version == package_version():
+            return  # already running the installed version
+        if pid is not None:
+            _run(["browserwright-daemon", "stop"])
+    except Exception:
+        pass
+    _spawn_detached(["browserwright-daemon", "serve"])
+
+
+def _close_browser(record: dict) -> None:
+    """Tear down a create-owned rdp session's browser via the single daemon.
+
+    The daemon owns the per-session Chrome (launched on ``ensureSession``), so
+    ``endSession`` closes the upstream + SIGTERMs that Chrome + drops the
+    context. Best-effort: a dead daemon just means the (ephemeral, C2) Chrome
+    already died with it. Only create-owned sessions reach here — attach
+    sessions never launched a browser we own."""
+    sid = record.get("id")
+    if sid:
+        _run(["browserwright-daemon", "end-session", "--session", str(sid)])
+
+
+def _reap_executor(record: dict) -> None:
+    """Best-effort: reap this session's resident Phase B executor (no browser
+    teardown). Called for EVERY owner on `end()` so an attach session's
+    long-lived executor subprocess doesn't leak — the full `endSession` path is
+    create-only and would also close the browser an attach session must keep.
+
+    Best-effort by contract: a dead daemon / no-executor / stale binary all
+    return non-zero from `_run`, which we ignore — `session end` must never fail
+    because the executor couldn't be reaped (the orphan-sweep on the next daemon
+    start is the backstop)."""
+    sid = record.get("id")
+    if sid:
+        _run(["browserwright-daemon", "kill-executor", "--session", str(sid)])
+
+
+def reset_executor(record: dict) -> str:
+    """Recycle only this session's resident executor.
+
+    The session ledger entry, browser, context, tabs, and ownership semantics
+    are intentionally left intact. The next ``browserwright -s <id> -e ...``
+    call cold-starts a fresh executor against the same session.
+    """
+    _ensure_daemon_running()
+    _reap_executor(record)
+    sid = record["id"]
+    return (
+        f"session {sid} reset; executor was recycled. "
+        "The browser and tabs were left untouched."
+    )
+
+
+def reap(*, idle_seconds: float) -> list[dict]:
+    """Prune idle sessions; for create-owned ones, also tear down the browser
+    the daemon launched. Returns the pruned records."""
+    pruned = reg.prune(idle_seconds=idle_seconds)
+    for rec in pruned:
+        if rec.get("owner") == "create":
+            _close_browser(rec)
+    return pruned
+
+
+def new(*, backend: str, create: bool = False, attach: Optional[object] = None,
+        name: Optional[str] = None) -> str:
+    """Register a session and return its id.
+
+    - ``extension`` → an *attach* session sharing the one global daemon's
+      relay-backed upstream; the tab group is created lazily on first use, so
+      ``workspace`` is None.
+    - ``rdp --create`` → owns an isolated browser the daemon launches on
+      ``ensureSession``. We pick a free port now and record it in ``workspace``
+      so the daemon pins the per-session Chrome to it.
+    - ``rdp --attach <target>`` → attaches to an already-running browser; the
+      target (port) is recorded and the browser is left alone on end.
+
+    In every case we only allocate the ledger entry + ensure the one daemon is
+    running. The daemon does the Chrome launch on ``ensureSession``.
+    """
+    name = name.strip() if isinstance(name, str) else None
+    if not name:
+        raise ValueError(
+            "session new requires --name=NAME — a short label (e.g. "
+            "--name=cf-bots). For extension sessions this becomes the Chrome "
+            "tab group title; for RDP sessions it labels the isolated browser "
+            "session. It need not be unique."
+        )
+    if backend == "extension":
+        sid = reg.allocate(backend="extension",
+                           owner="attach", name=name)
+        _ensure_daemon_running()
+        return sid
+    if backend == "rdp":
+        owner = "create" if create else "attach"
+        # workspace["port"]: for --create pick a free port the daemon launches
+        # Chrome on; for --attach record the target port the daemon resolves.
+        if create:
+            workspace = {"port": _free_port()}
+        elif attach is not None:
+            workspace = {"port": int(attach), "target": attach}
+        else:
+            workspace = None
+        sid = reg.allocate(backend="rdp", owner=owner,
+                           name=name, workspace=workspace)
+        _ensure_daemon_running()
+        return sid
+    raise ValueError(f"unknown backend {backend!r} (use extension|rdp)")
+
+
+def choose(situation: str) -> dict:
+    """Decide how to start a session for ``situation``.
+
+    Hit → return the recorded decision (auto-start). Miss → raise
+    :class:`NeedsUserConfirm` carrying a proposal that lists the three modes,
+    so the agent asks the user and then records the answer.
+    """
+    from .errors import NeedsUserConfirm
+    from .memory import session_decisions
+
+    hit = session_decisions.lookup(situation)
+    if hit is not None:
+        return hit
+    raise NeedsUserConfirm(
+        what=f"how to start a browser session for: {situation}",
+        proposal={
+            "situation": situation,
+            "options": [
+                {"backend": "extension", "mode": "attach",
+                 "desc": "drive the user's everyday Chrome via the extension (shared)"},
+                {"backend": "rdp", "mode": "create",
+                 "desc": "launch a fresh isolated Chrome the session owns"},
+                {"backend": "rdp", "mode": "attach", "target": "<port|recipe>",
+                 "desc": "attach to an already-running browser (e.g. a fingerprint browser)"},
+            ],
+            "after_choice": "record it via memory.session_decisions.record(situation, decision)",
+        },
+    )
+
+
+def _end_extension_workspace(record: dict) -> None:
+    """Close the session's agent-owned extension tabs via the single daemon.
+
+    Best-effort: the shared browser itself stays open (extension sessions are
+    attach-owned); only the tabs this session opened are closed. The
+    ``end-session`` CLI no longer takes ``--name`` — there is one daemon."""
+    cmd = ["browserwright-daemon", "end-session", "--session", record["id"]]
+    # Thread the durable numeric groupId (persisted in ledger.runtime on every
+    # open) so the daemon can close the whole group even when its in-memory
+    # binding was wiped (restart). The title is not used — names aren't unique.
+    runtime = record.get("runtime") or {}
+    gid = runtime.get("group_id")
+    if isinstance(gid, int) and gid >= 0:
+        cmd += ["--group-id", str(gid)]
+    _run(cmd)
+
+
+def end(record: dict) -> str:
+    """Tear down a session honoring ownership. Returns a human-readable line.
+
+    create-owned → the daemon closes the browser it launched (endSession).
+    attach       → leave the browser running, remind the user.
+    extension    → also close the session's agent-owned tabs (browser stays).
+    Always removes the ledger entry.
+    """
+    sid = record["id"]
+    if record.get("backend") == "extension":
+        _end_extension_workspace(record)
+    if record.get("owner") == "create":
+        # `_close_browser` → daemon `endSession`, which ALSO kills the executor
+        # (symmetric in `_handle_end_session`), so no separate reap needed here.
+        _close_browser(record)
+        msg = f"session {sid} ended; the browser it launched was closed."
+    else:
+        # attach: leave the browser running (semantics unchanged) but still reap
+        # the session's resident executor so it doesn't leak — `endSession` is
+        # create-only and the attach path never otherwise contacts the daemon.
+        _reap_executor(record)
+        msg = (f"session {sid} ended. The browser is still running — you "
+               f"attached to it, so it was left untouched.")
+    reg.remove(sid)
+    return msg

browserwright/session_ctx.py

@@ -0,0 +1,24 @@
+"""Resolve an explicitly requested session record (P1)."""
+from __future__ import annotations
+
+from typing import Optional
+
+from . import session_registry as reg
+from .errors import NoSession
+
+
+def resolve_session(session_id: Optional[str] = None) -> dict:
+    """Return the ledger record for the current session.
+
+    Raises :class:`NoSession` when no id is provided or the id is unknown.
+    On success, bumps the record's ``last_seen`` and returns it.
+    """
+    raw = session_id
+    sid = str(raw) if raw not in (None, "") else ""
+    if not sid:
+        raise NoSession()
+    rec = reg.get(sid)
+    if rec is None:
+        raise NoSession(f"unknown session id {sid!r} (not in ledger).")
+    reg.touch(sid)
+    return rec

browserwright/session_registry.py

@@ -0,0 +1,133 @@
+"""File-locked session ledger: short id → session record (P1 isolation key)."""
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Callable, Iterator, Optional
+
+
+def _home() -> Path:
+    return Path(os.path.expanduser(os.environ.get("BS_HOME", "~/.browserwright")))
+
+
+def _dir() -> Path:
+    d = _home() / "sessions"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _ledger_path() -> Path:
+    return _dir() / "ledger.json"
+
+
+@contextmanager
+def _locked() -> Iterator[dict]:
+    """Exclusive flock around a read-modify-write of the ledger."""
+    lock = _dir() / ".lock"
+    with open(lock, "w") as lf:
+        fcntl.flock(lf, fcntl.LOCK_EX)
+        try:
+            p = _ledger_path()
+            data = json.loads(p.read_text()) if p.exists() else {"next_id": 1, "sessions": {}}
+            yield data
+            p.write_text(json.dumps(data))
+        finally:
+            fcntl.flock(lf, fcntl.LOCK_UN)
+
+
+def allocate(*, backend: str, owner: str,
+             workspace: Optional[object] = None, name: Optional[str] = None,
+             unique_name: bool = False) -> str:
+    now = time.time()
+    with _locked() as data:
+        if unique_name:
+            # Globally-unique name guard. Raising here (after the `yield` in
+            # _locked) aborts before `p.write_text`, so a rejected allocation
+            # leaves the ledger untouched.
+            for e in data["sessions"].values():
+                if e.get("name") == name:
+                    conflict = e.get("id")
+                    raise ValueError(
+                        f"session name {name!r} is already taken by session "
+                        f"{conflict!r}. Names must be globally unique. Either "
+                        f"pick a different --name, reuse the existing session "
+                        f"with `browserwright -s {conflict} -e ...`, or "
+                        f"end it first: browserwright session end "
+                        f"--session={conflict}"
+                    )
+        sid = str(data["next_id"])
+        data["next_id"] += 1
+        data["sessions"][sid] = {
+            "id": sid, "backend": backend,
+            "workspace": workspace, "owner": owner, "name": name,
+            "created_at": now, "last_seen": now,
+        }
+        return sid
+
+
+def get(session_id: str) -> Optional[dict]:
+    p = _ledger_path()
+    if not p.exists():
+        return None
+    return json.loads(p.read_text())["sessions"].get(session_id)
+
+
+def _with_entry(session_id: str, fn: Callable[[dict], object]) -> Optional[dict]:
+    """Apply ``fn`` to a session entry in-place under the lock; return the entry."""
+    with _locked() as data:
+        entry = data["sessions"].get(session_id)
+        if entry is None:
+            return None
+        fn(entry)
+        return entry
+
+
+def touch(session_id: str) -> Optional[dict]:
+    """Bump ``last_seen`` to now."""
+    now = time.time()
+    return _with_entry(session_id, lambda e: e.update(last_seen=now))
+
+
+def update(session_id: str, **fields) -> Optional[dict]:
+    """Patch fields on a session record.
+
+    ``backend`` is fixed at creation and immutable for the session's whole life
+    (single-daemon refactor, decision 2): a change to a DIFFERENT backend is
+    rejected. Raising before ``e.update`` (and before ``_locked``'s post-yield
+    ``write_text``) leaves the ledger untouched. A no-op same-value patch is
+    allowed so callers that re-write the whole record don't trip the guard."""
+    def _patch(e: dict) -> None:
+        if "backend" in fields and fields["backend"] != e.get("backend"):
+            raise ValueError(
+                f"session {session_id!r} backend is immutable: refusing to "
+                f"change {e.get('backend')!r} → {fields['backend']!r}")
+        e.update(**fields)
+    return _with_entry(session_id, _patch)
+
+
+def remove(session_id: str) -> Optional[dict]:
+    """Drop a session from the ledger; return the removed record (or None)."""
+    with _locked() as data:
+        return data["sessions"].pop(session_id, None)
+
+
+def list_all() -> list[dict]:
+    """All session records, ordered by id."""
+    p = _ledger_path()
+    if not p.exists():
+        return []
+    sessions = json.loads(p.read_text())["sessions"]
+    return [sessions[k] for k in sorted(sessions, key=int)]
+
+
+def prune(*, idle_seconds: float) -> list[dict]:
+    """Remove sessions idle longer than ``idle_seconds``; return removed records."""
+    now = time.time()
+    with _locked() as data:
+        stale = [sid for sid, e in data["sessions"].items()
+                 if now - e.get("last_seen", 0.0) >= idle_seconds]
+        return [data["sessions"].pop(sid) for sid in stale]