browser-workspace 0.4.3__tar.gz

browser_workspace-0.4.3/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: browser-workspace
+Version: 0.4.3
+Summary: Agent browser workspace with persistent Python sessions, tab leasing, snapshots, and platform workflows.
+Requires-Python: >=3.11
+Requires-Dist: cdp-use==1.4.5
+Requires-Dist: fetch-use==0.4.0
+Requires-Dist: pillow==12.3.0
+Requires-Dist: PyYAML==6.0.2
+Requires-Dist: websockets==15.0.1

browser_workspace-0.4.3/README.md

@@ -0,0 +1,152 @@
+# Browser Workspace
+
+Browser Workspace is a single browser automation skill and CLI built around persistent Python sessions, workspace-owned Chrome tabs, compact snapshot refs, and built-in platform workflows.
+
+## Public interface
+
+The CLI has two public execution paths:
+
+```bash
+# Known platform action: runner owns start/stop.
+browser-workspace platform run PLATFORM ACTION [--config FILE] [--url URL]
+
+# Custom browser workflow: caller owns lifecycle.
+browser-workspace session start [--url URL]
+browser-workspace session exec SESSION_ID <<'PY'
+print(snapshot())
+PY
+browser-workspace session stop SESSION_ID
+```
+
+`--workspace` is hidden from normal CLI help. Normal sessions use `Harness`; product integrations may set an explicit workspace internally when they require isolation.
+
+`session stop` closes all tabs created/owned by that session while leaving unrelated browser tabs untouched. Raw session CDP cannot create targets: `Target.createTarget` is rejected and callers must use `new_tab()` so workspace/session ownership is preserved.
+
+## Included layers
+
+```text
+browser-workspace
+├── src/browser_harness/     low-level browser/CDP runtime (forked internally)
+├── agent-workspace/         Browser Workspace helper layer
+├── extension/               Chrome workspace/tab manager
+├── session_daemon.py        persistent Python session service
+├── platforms/               site/domain actions + verification metadata
+├── interaction-skills/      browser interaction references
+└── SKILL.md                 single agent-facing skill contract
+```
+
+Agents should load only the Browser Workspace skill. `browser-harness` and `browser-platforms` are no longer separate runtime/skill dependencies.
+
+## Install
+
+```bash
+./scripts/install.sh
+```
+
+The installer creates the skill-owned `.venv` and links `browser-workspace` to `~/.local/bin` by default.
+
+By default Browser Workspace owns exactly one machine-wide persistent, visible Chrome instance. Every session and runtime reuses that same Browser Workspace Chrome; config/runtime overrides never create another Chrome. It uses a Browser Workspace-managed user-data directory, prefers CDP port 9222, and selects the next available candidate only when starting the singleton for the first time. Users do not manage Chrome profiles or remote-debugging settings. Chrome Stable no longer permits silent `--load-extension` for local unpacked extensions, so the extension is treated as an optional workspace-grouping enhancement rather than a prerequisite for browser sessions.
+
+`BU_CDP_URL` / `BU_CDP_WS` remain advanced overrides for callers that intentionally provide their own browser endpoint. `BROWSER_WORKSPACE_CDP_PORT` changes the preferred managed port.
+
+The Web Store build remains available for ordinary interactive Chrome installs, but the managed runtime does not depend on it: `https://chromewebstore.google.com/detail/kgbghhigmbpefppgkocgjgnnnbhjchic`.
+
+## Snapshot model
+
+`snapshot()` uses Chrome's accessibility tree to identify useful controls/content, annotates the corresponding live DOM elements with `data-ref="eN"`, and emits a compact representation. Interact using normal CSS selectors:
+
+```python
+print(snapshot())
+click('[data-ref="e2"]')
+fill_input('[data-ref="e3"]', 'hello')
+```
+
+There is no separate ref registry.
+
+## Upstream
+
+The internal browser-control core is forked from `browser-use/browser-harness`. Its license is retained in `licenses/browser-harness-MIT.txt`.
+
+
+
+## Product-owned workspaces
+
+Normal browser automation uses the default `Harness` workspace. Ordinary agents manage browser sessions only; they do not create, resize, or delete workspaces. Workspace lifecycle belongs to product runtimes such as Agents Relay or NeoY.
+
+Products discover the installed Browser Workspace instance with:
+
+```bash
+browser-workspace status
+```
+
+The command returns machine-readable JSON including the resolved installation `root`, absolute `admin_helper` path, and daemon status. Calling `status` also ensures the existing Browser Workspace session daemon is ready; it does not create a separate service.
+
+A Node.js product can then load the product-only helper without depending on the `browser-workspace` npm package or hardcoding an install path:
+
+```js
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+const status = JSON.parse(
+  execFileSync("browser-workspace", ["status"], { encoding: "utf8" })
+);
+const { ensureWorkspace, deleteWorkspace } =
+  await import(pathToFileURL(status.admin_helper).href);
+
+await ensureWorkspace("Relay", 6);
+// later, if the product owns and no longer needs it:
+await deleteWorkspace("Relay", { force: true });
+```
+
+`ensureWorkspace(name, size)` is idempotent: it creates a missing workspace, keeps one with the same capacity, and reconfigures an existing workspace when the requested size changes. The physical tab pool still grows lazily up to that capacity. `deleteWorkspace(name, { force })` removes the workspace through the existing daemon/extension RPC path.
+
+There is intentionally no `browser-workspace workspace create/delete` CLI. Workspace lifecycle is a product API, not an agent command.
+
+### Start a session in a product-owned workspace
+
+`--workspace` remains an internal integration option for product code:
+
+```bash
+browser-workspace session start --workspace "Relay" --url https://example.com
+```
+
+It is hidden from normal CLI help. Product code owns the workspace choice; platform actions remain unaware of workspace/session policy.
+
+Recommended product lifecycle:
+
+```text
+product startup
+  -> browser-workspace status
+  -> import status.admin_helper
+  -> ensureWorkspace("Relay", 6)
+
+browser task
+  -> browser-workspace session start --workspace "Relay"
+  -> browser-workspace session exec <session_id>
+  -> browser-workspace session stop <session_id>
+```
+
+## Platform boundary
+
+Platform action code is infrastructure-agnostic. It may use browser helpers, but it must not create/stop Browser Workspace sessions, choose workspaces, or import session/workspace infrastructure. The generic platform runner wraps actions in a default Harness session and always cleans up. Product code may execute the same action in a product-owned browser context when longer-lived isolation is required.
+
+Each platform manifest records explicit verification status and evidence. `verified` means live-site verification; migrated code is labeled `migrated_unverified` until exercised in the current integration.
+
+
+## npx skills installation
+
+After `npx skills add ...`, invoke `~/.agents/skills/browser-workspace/bin/browser-workspace` directly. The first session start bootstraps the skill-owned Python virtual environment automatically; running `scripts/install.sh` is optional.
+
+### Python distribution (PyPI)
+
+Browser Workspace is also packaged as a Python CLI. Once its PyPI trusted publisher is configured and a `pypi-v*` release tag is published, invoke it with:
+
+```bash
+uvx browser-workspace status
+uvx browser-workspace session list
+uvx browser-workspace platform profile wechat-channels
+```
+
+The package entry point is `browser_workspace_app.cli:main`, and Python dependencies are managed by `pyproject.toml`. This uses the same existing Chrome profile and Session Daemon socket as the previous npm CLI; it does **not** start a second browser or daemon when the existing one is healthy.
+
+Before building, run `python tools/sync-pypi-package.py` to copy canonical Python and packaged platform assets to the wheel source. Run `uv build`, then validate with `uvx --from dist/browser_workspace-<version>-py3-none-any.whl browser-workspace status`. The PyPI publishing workflow uses GitHub OIDC trusted publishing; configure `lalalic/browser-workspace` with the `pypi` environment as the publisher on PyPI before the first tag release.

browser_workspace-0.4.3/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools==84.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "browser-workspace"
+version = "0.4.3"
+description = "Agent browser workspace with persistent Python sessions, tab leasing, snapshots, and platform workflows."
+requires-python = ">=3.11"
+dependencies = [
+  "cdp-use==1.4.5",
+  "fetch-use==0.4.0",
+  "pillow==12.3.0",
+  "PyYAML==6.0.2",
+  "websockets==15.0.1",
+]
+
+[project.scripts]
+browser-workspace = "browser_workspace_app.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+browser_harness = ["video-template.html"]
+browser_workspace_app = ["**/*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "--import-mode=importlib"

browser_workspace-0.4.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

browser_workspace-0.4.3/src/browser_harness/__init__.py

@@ -0,0 +1,2 @@
+"""Browser Harness core package."""
+

browser_workspace-0.4.3/src/browser_harness/_ipc.py

@@ -0,0 +1,201 @@
+"""Daemon IPC plumbing. AF_UNIX socket on POSIX, TCP loopback on Windows."""
+import asyncio, json, os, re, secrets, socket, subprocess, sys
+from pathlib import Path
+
+from . import paths
+
+IS_WINDOWS = sys.platform == "win32"
+# Two caller-supplied dirs:
+#   BH_RUNTIME_DIR — sock/port/pid. AF_UNIX sun_path is 104 bytes on macOS, so
+#       the runtime dir must be short. Caller is responsible for keeping it
+#       within budget. Falls back to BH_TMP_DIR (legacy single-dir callers),
+#       then to the browser-harness runtime dir.
+#   BH_TMP_DIR — screenshots, debug overlays, daemon log. No path-length
+#       sensitivity; caller can use a deep persistent path.
+# By default, a caller-supplied dir is treated as per-instance and files use
+# bare "bu" stems. Set BH_RUNTIME_DIR_SHARED=1 or BH_TMP_DIR_SHARED=1 when the
+# dir is shared by multiple BU_NAME values and the filename must carry the name.
+BH_TMP_DIR = os.environ.get("BH_TMP_DIR")
+BH_RUNTIME_DIR = os.environ.get("BH_RUNTIME_DIR") or BH_TMP_DIR
+BH_RUNTIME_DIR_SHARED = os.environ.get("BH_RUNTIME_DIR_SHARED") == "1"
+BH_TMP_DIR_SHARED = os.environ.get("BH_TMP_DIR_SHARED") == "1"
+_TMP = paths.tmp_dir()
+_RUNTIME = paths.ensure_private_dir(Path(BH_RUNTIME_DIR).expanduser().resolve()) if BH_RUNTIME_DIR else paths.runtime_dir()
+_TMP.mkdir(parents=True, exist_ok=True)
+_RUNTIME.mkdir(parents=True, exist_ok=True)
+_NAME_RE = re.compile(r"\A[A-Za-z0-9_-]{1,64}\Z")
+
+# Set by serve() on Windows. Daemon's handle() requires every request to carry
+# this token (TCP loopback has no chmod-equivalent so any local process could
+# otherwise issue CDP commands). Stays None on POSIX where AF_UNIX + chmod 600
+# is the boundary.
+_server_token = None
+
+
+def _check(name):  # path-traversal guard for BU_NAME
+    if not _NAME_RE.match(name or ""):
+        raise ValueError(f"invalid BU_NAME {name!r}: must match [A-Za-z0-9_-]{{1,64}}")
+    return name
+
+
+def _runtime_stem(name):  # "bu" when BH_RUNTIME_DIR isolates us, else "bu-<NAME>"
+    _check(name)
+    return "bu" if BH_RUNTIME_DIR and not BH_RUNTIME_DIR_SHARED else f"bu-{name}"
+
+
+def _tmp_stem(name):  # "bu" when BH_TMP_DIR isolates us, else "bu-<NAME>"
+    _check(name)
+    return "bu" if BH_TMP_DIR and not BH_TMP_DIR_SHARED else f"bu-{name}"
+
+
+def log_path(name):   return _TMP / f"{_tmp_stem(name)}.log"
+def pid_path(name):   return _RUNTIME / f"{_runtime_stem(name)}.pid"
+def port_path(name):  return _RUNTIME / f"{_runtime_stem(name)}.port"  # Windows-only: holds {"port","token"} JSON
+def _sock_path(name): return _RUNTIME / f"{_runtime_stem(name)}.sock"
+
+
+def _read_port_file(name):
+    """(port, token) from the Windows port file, or (None, None) on any failure."""
+    try:
+        d = json.loads(port_path(name).read_text(encoding="utf-8"))
+        return int(d["port"]), d["token"]
+    except (FileNotFoundError, ValueError, KeyError, TypeError, OSError):
+        return None, None
+
+
+def sock_addr(name):  # display-only, used in log lines
+    if not IS_WINDOWS: return str(_sock_path(name))
+    port, _ = _read_port_file(name)
+    return f"127.0.0.1:{port}" if port else f"tcp:{_runtime_stem(name)}"
+
+
+def spawn_kwargs():  # subprocess.Popen flags so the daemon detaches from this terminal
+    if IS_WINDOWS:
+        # CREATE_NO_WINDOW: no console window for the daemon. CREATE_NEW_PROCESS_GROUP:
+        # daemon doesn't receive Ctrl-C/Ctrl-Break sent to the parent terminal, so
+        # closing that terminal doesn't kill it. DETACHED_PROCESS is intentionally
+        # omitted: per Win32 docs it overrides CREATE_NO_WINDOW, causing Windows to
+        # allocate a fresh console for the (still console-subsystem) python.exe.
+        return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW}
+    return {"start_new_session": True}
+
+
+def connect(name, timeout=1.0):
+    """Blocking client. Returns (sock, token); token is None on POSIX, hex string on Windows.
+    Callers sending JSON requests MUST include the token as req["token"] on Windows."""
+    if not IS_WINDOWS:
+        # uv-Python on Windows lacks socket.AF_UNIX, so this branch must be gated.
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(timeout); s.connect(str(_sock_path(name))); return s, None
+    port, token = _read_port_file(name)
+    if port is None: raise FileNotFoundError(str(port_path(name)))
+    s = socket.create_connection(("127.0.0.1", port), timeout=timeout)
+    s.settimeout(timeout); return s, token
+
+
+def request(c, token, req):
+    """One-shot send + recv + parse on an open socket. Injects token on Windows.
+    Returns the parsed JSON response. Caller closes the socket."""
+    if token: req = {**req, "token": token}
+    c.sendall((json.dumps(req) + "\n").encode())
+    data = b""
+    while not data.endswith(b"\n"):
+        chunk = c.recv(1 << 16)
+        if not chunk: break
+        data += chunk
+    return json.loads(data or b"{}")
+
+
+def ping(name, timeout=1.0):
+    """True iff a live daemon answers our ping. Defends against stale .port files
+    + port reuse: a bare TCP connect can succeed against an unrelated process that
+    grabbed the port after our daemon crashed; only our daemon answers {"pong":true}."""
+    try:
+        c, token = connect(name, timeout=timeout)
+    except (FileNotFoundError, ConnectionRefusedError, TimeoutError, socket.timeout, OSError):
+        return False
+    try:
+        resp = request(c, token, {"meta": "ping"})
+        # request() returns parsed JSON, which may be any valid value (a list,
+        # scalar, etc. from a stale or hostile endpoint). Anything that isn't
+        # a {pong: true} dict counts as "not our daemon" — never .get() blindly.
+        return isinstance(resp, dict) and resp.get("pong") is True
+    except (OSError, ValueError, AttributeError):
+        return False
+    finally:
+        try: c.close()
+        except OSError: pass
+
+
+def identify(name, timeout=1.0):
+    """Return the live daemon's PID, or None if unreachable.
+
+    Used by restart_daemon() to signal a process whose identity has been
+    verified end-to-end (live IPC + self-reported PID), instead of trusting
+    a pid file whose number may have been reused by an unrelated process."""
+    try:
+        c, token = connect(name, timeout=timeout)
+    except (FileNotFoundError, ConnectionRefusedError, TimeoutError, socket.timeout, OSError):
+        return None
+    try:
+        resp = request(c, token, {"meta": "ping"})
+        # request() returns parsed JSON, which may be any valid value (a list,
+        # scalar, etc. from a stale or hostile endpoint). Anything that isn't
+        # a {pong: true} dict gets None — never .get() on a non-dict.
+        if not isinstance(resp, dict) or resp.get("pong") is not True:
+            return None
+        pid = resp.get("pid")
+        # `type(pid) is int` (not isinstance) intentionally rejects bool: in
+        # Python, isinstance(True, int) is True, so a hostile/buggy daemon
+        # could reply with {"pid": True} and we'd treat that as PID 1 (init).
+        # Also reject 0/negatives — os.kill(0, sig) signals every process in
+        # the calling process group, os.kill(-1, sig) signals every process
+        # the caller can. Upper bound is 2**31 because C pid_t is typically
+        # signed 32-bit and a value outside that range makes os.kill() raise
+        # OverflowError, which would propagate out of restart_daemon() before
+        # its cleanup. Linux pid_max is also bounded at 2**22 in practice.
+        return pid if type(pid) is int and 0 < pid < (1 << 31) else None
+    except (OSError, ValueError, AttributeError):
+        return None
+    finally:
+        try: c.close()
+        except OSError: pass
+
+
+async def serve(name, handler):
+    """Run the server until cancelled. handler(reader, writer) sees the same interface either way."""
+    global _server_token
+    if not IS_WINDOWS:
+        path = str(_sock_path(name))
+        if os.path.exists(path): os.unlink(path)
+        # umask 0o077 makes bind() create the socket as 0600 — no TOCTOU window before chmod.
+        old_umask = os.umask(0o077)
+        try: server = await asyncio.start_unix_server(handler, path=path)
+        finally: os.umask(old_umask)
+        _server_token = None
+        async with server: await asyncio.Event().wait()
+        return
+    server = await asyncio.start_server(handler, "127.0.0.1", 0)
+    port = server.sockets[0].getsockname()[1]
+    _server_token = secrets.token_hex(32)
+    pf = port_path(name)
+    # Atomic write so a concurrent reader never sees a half-written file.
+    tmp = pf.with_name(pf.name + ".tmp")
+    tmp.write_text(json.dumps({"port": port, "token": _server_token}), encoding="utf-8")
+    os.replace(tmp, pf)
+    try:
+        async with server: await asyncio.Event().wait()
+    finally:
+        try: pf.unlink()
+        except FileNotFoundError: pass
+
+
+def expected_token():
+    """The token the running daemon will accept, or None on POSIX."""
+    return _server_token
+
+
+def cleanup_endpoint(name):  # best-effort; silent if already gone
+    p = _sock_path(name) if not IS_WINDOWS else port_path(name)
+    try: p.unlink()
+    except FileNotFoundError: pass