claros-browser 0.1.0__tar.gz

claros_browser-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.env
+data/*
+node_modules/
+.venv/
+__pycache__/
+.next/
+*.db
+!data/fixtures/
+!data/demo/
+!data/golden/
+!data/judge_dev/
+.env.bak

claros_browser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timur Monasypov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claros_browser-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: claros-browser
+Version: 0.1.0
+Summary: Claros guard for browser-use agents: consequential clicks and submits are checked against your experts' rules before they reach the app
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: browser-use==0.13.11
+Description-Content-Type: text/markdown
+
+# claros-browser
+
+Claros guard for [browser-use](https://github.com/browser-use/browser-use) agents. Consequential clicks, submits and
+Enter presses are held in the page and checked against your team's rules before they reach the app: **stop**, **ask**
+a person, or **nudge** with a fix.
+
+```python
+from browser_use import Agent, Tools
+from claros_browser import guard_tools
+
+tools = Tools()
+guard_tools(tools)          # CLAROS_KEY from the env; the server is found via the Claros web app
+Agent(task=..., llm=..., tools=tools)
+```
+
+Claros unreachable means stopped (fail closed) unless `fail_open=True`. Docs: https://claros-eta.vercel.app/docs
+
+MIT licence.

claros_browser-0.1.0/README.md

@@ -0,0 +1,18 @@
+# claros-browser
+
+Claros guard for [browser-use](https://github.com/browser-use/browser-use) agents. Consequential clicks, submits and
+Enter presses are held in the page and checked against your team's rules before they reach the app: **stop**, **ask**
+a person, or **nudge** with a fix.
+
+```python
+from browser_use import Agent, Tools
+from claros_browser import guard_tools
+
+tools = Tools()
+guard_tools(tools)          # CLAROS_KEY from the env; the server is found via the Claros web app
+Agent(task=..., llm=..., tools=tools)
+```
+
+Claros unreachable means stopped (fail closed) unless `fail_open=True`. Docs: https://claros-eta.vercel.app/docs
+
+MIT licence.

claros_browser-0.1.0/claros_browser/__init__.py

@@ -0,0 +1,242 @@
+"""Claros guard for browser-use agents (browser-use 0.13.11).
+
+    from browser_use import Agent, Tools
+    from claros_browser import guard_tools
+    tools = Tools(); guard_tools(tools)          # CLAROS_URL / CLAROS_KEY from the env
+    Agent(task=..., llm=..., tools=tools)
+
+page.js (the same file as packages/browser/src/page.js) is injected into every page: a consequential click / submit /
+Enter is held in the page, never reaching the app. After each agent action the guard takes the held actions, checks
+each with Claros (POST /v1/check/page, or /v1/check/screen from a screenshot when the DOM shows no record), replays the
+allowed ones and drops the stopped ones; the action then returns ActionResult(error=<the rule, the expert's words, who
+to ask>) so the agent sees why. Claros unreachable → stopped (fail closed) unless fail_open=True. A nudge (only
+`nudge` rules broken) lets the action through; its text (rule, expert's words, suggested fix) is appended to the
+action result's extracted_content (and long_term_memory when set), logged as a warning and passed to on_nudge.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+PAGE_JS = (Path(__file__).parent / "page.js").read_text(encoding="utf-8")
+DEFAULT_WEB = "https://claros-eta.vercel.app"
+
+
+def discover(web: Optional[str] = None) -> str:
+    """The web app says where its server is (<web>/.well-known/claros.json → {"api": …}), so a moved server needs no
+    release."""
+    web = (web or os.getenv("CLAROS_WEB_URL") or DEFAULT_WEB).rstrip("/")
+    try:
+        with urllib.request.urlopen(f"{web}/.well-known/claros.json", timeout=5) as r:
+            return json.load(r)["api"]
+    except (urllib.error.URLError, OSError, KeyError, ValueError) as e:
+        raise RuntimeError(f"Claros: {web} did not say where its server is ({e}); set CLAROS_URL") from e
+log = logging.getLogger("claros_browser")
+
+
+class ClarosStop(Exception):
+    def __init__(self, result: Optional[dict], message: str, item: Optional[dict] = None) -> None:
+        super().__init__(message)
+        self.result = result  # the /v1/check answer; None when Claros couldn't be reached
+        self.action = (item or {}).get("action")
+        self.url = (item or {}).get("url")
+        self.violations = [v for v in (result or {}).get("violations", []) if v.get("action") in ("stop", "ask")]
+        v = self.violations[0] if self.violations else {}
+        self.rule, self.quote, self.expert = v.get("rule"), v.get("quote"), v.get("expert")
+        self.who_to_ask = v.get("who_to_ask") or v.get("owner") or v.get("expert")
+        self.check_id = (result or {}).get("check_id")
+
+
+def stop_text(r: dict, action: str) -> str:
+    """Same wording as the MCP guard and the Playwright hook."""
+    hits = [v for v in r.get("violations", []) if v.get("action") in ("stop", "ask")]
+    out = [f'Claros stopped "{action}": it breaks {"a rule" if len(hits) == 1 else "rules"} from the expert-approved '
+           f'Work Map "{r.get("workflow_id")}". The click never reached the app. Do not retry it as is.']
+    for v in hits:
+        who = v.get("who_to_ask") or v.get("owner") or v.get("expert") or "the process owner"
+        out += ["", f"Rule: {v.get('rule')}"]
+        if v.get("reason"):
+            out.append(f"Why Claros stopped it: {v['reason']}")
+        if v.get("quote"):
+            by = f" ({v['expert']})" if v.get("expert") else ""
+            out.append(f"In the expert's words{by}: \"{v['quote']}\"")
+        out.append(f"Who to ask: {who}")
+        out.append(f"Next: stop and ask {who} before doing this; continue only with their answer." if v["action"] == "ask"
+                   else f"Next: change the record so the rule holds, or ask {who} to approve an exception. Tell the user why.")
+    return "\n".join(out)
+
+
+def nudges_of(r: Optional[dict]) -> list[dict]:
+    """The rules a nudge let through ("warn" is the nudge's old name, from older Claros servers)."""
+    return [v for v in (r or {}).get("violations", []) if v.get("action") in ("nudge", "warn")]
+
+
+def nudge_text(r: dict, action: str) -> str:
+    """Same wording as the MCP guard's nudge and the Playwright hook's."""
+    hits = nudges_of(r)
+    one = len(hits) == 1
+    out = [f'Claros nudge: "{action}" went through, but it doesn\'t follow {"a rule" if one else "rules"} your team '
+           f'holds. Fix it if you still can, and follow {"it" if one else "them"} from now on.']
+    for v in hits:
+        out += ["", f"Rule: {v.get('rule')}"]
+        if v.get("reason"):
+            out.append(f"Why: {v['reason']}")
+        if v.get("quote"):
+            by = f" ({v['expert']})" if v.get("expert") else ""
+            out.append(f"In the expert's words{by}: \"{v['quote']}\"")
+        if v.get("fix"):
+            out.append(f"Suggested fix: {v['fix']}")
+    return "\n".join(out)
+
+
+class Guard:
+    def __init__(self, url: Optional[str] = None, key: Optional[str] = None, timeout: float = 5.0,
+                 fail_open: bool = False, actor: Optional[str] = None, workflow_id: Optional[str] = None,
+                 on_nudge: Optional[Callable[[dict], Any]] = None) -> None:
+        self.url = (url or os.getenv("CLAROS_URL") or discover()).rstrip("/")
+        self.key = key if key is not None else os.getenv("CLAROS_KEY", "")
+        self.timeout, self.fail_open, self.actor, self.workflow_id = timeout, fail_open, actor, workflow_id
+        self.on_nudge = on_nudge
+        self.decisions: list[dict] = []
+        self.stops: list[ClarosStop] = []
+        self.nudges: list[dict] = []
+        self._targets: set[str] = set()
+        self._kinds: dict[str, dict] = {}
+
+    # ---- Claros ----
+    def _http(self, path: str, body: Optional[dict] = None) -> dict:
+        req = urllib.request.Request(self.url + path, method="POST" if body is not None else "GET",
+                                     data=json.dumps(body).encode() if body is not None else None,
+                                     headers={"content-type": "application/json",
+                                              **({"authorization": f"Bearer {self.key}"} if self.key else {})})
+        with urllib.request.urlopen(req, timeout=self.timeout) as r:  # noqa: S310 (the configured Claros URL)
+            return json.loads(r.read())
+
+    async def _kinds_for(self, origin: str) -> dict:
+        if origin not in self._kinds:
+            self._kinds[origin] = {}
+            if origin.startswith("http"):
+                try:
+                    q = urllib.parse.urlencode({"app": origin})
+                    self._kinds[origin] = (await asyncio.to_thread(self._http, f"/v1/tools/kinds?{q}")).get("kinds") or {}
+                except Exception:  # noqa: BLE001  no kinds: the vocabulary decides
+                    pass
+        return self._kinds[origin]
+
+    async def decide(self, item: dict, session: Any = None) -> dict:
+        t0 = time.perf_counter()
+        meta = {"app": item.get("app"), "action": item.get("action"), "url": item.get("url"),
+                "title": item.get("title"), "actor": self.actor, "workflow_id": self.workflow_id}
+        r, how, error = None, "page", None
+        try:
+            if (await self._kinds_for(item.get("app") or "")).get(item.get("action")) == "read":
+                r = {"allowed": True, "reason": "read (tool kinds)"}
+            elif not item.get("state") and not item.get("rows") and session is not None:
+                how = "screen"  # canvas, cross-origin frame: read the pixels
+                img = await session.take_screenshot(format="jpeg", quality=70)
+                r = await asyncio.to_thread(self._http, "/v1/check/screen",
+                                            {**meta, "image": base64.b64encode(img).decode()})
+            else:
+                r = await asyncio.to_thread(self._http, "/v1/check/page",
+                                            {**meta, "state": item.get("state") or {}, "rows": item.get("rows") or []})
+        except Exception as e:  # noqa: BLE001
+            error = f"timed out after {self.timeout}s" if isinstance(e, TimeoutError) else str(e) or type(e).__name__
+        d = {"action": item.get("action"), "kind": item.get("kind"), "url": item.get("url"), "via": how,
+             "ms": round((time.perf_counter() - t0) * 1000), "server_ms": (r or {}).get("latency_ms"),
+             "allowed": self.fail_open if error else bool(r.get("allowed")), "workflow_id": (r or {}).get("workflow_id"),
+             "violations": [v.get("guardrail_id") for v in (r or {}).get("violations", [])],
+             "check_id": (r or {}).get("check_id"), "error": error, "result": r}
+        self.decisions.append(d)
+        if d["allowed"] and nudges_of(r):  # the action proceeds; the nudge goes back to the agent
+            d["nudge"] = {"action": item.get("action"), "url": item.get("url"), "text": nudge_text(r, item.get("action")),
+                          "violations": nudges_of(r), "check_id": r.get("check_id")}
+            self.nudges.append(d["nudge"])
+            log.warning(d["nudge"]["text"])
+            if self.on_nudge:
+                self.on_nudge(d["nudge"])
+        if not d["allowed"]:
+            d["stop"] = (ClarosStop(None, f'Claros couldn\'t check "{item.get("action")}" ({error}), so it was not '
+                                          "done. Ask a person to confirm it is allowed before trying again.", item)
+                         if error else ClarosStop(r, stop_text(r, item.get("action")), item))
+            self.stops.append(d["stop"])
+        return d
+
+    # ---- the page (CDP through browser-use's session) ----
+    async def _eval(self, session: Any, expr: str) -> Any:
+        cdp = await session.get_or_create_cdp_session()
+        r = await cdp.cdp_client.send.Runtime.evaluate(
+            params={"expression": expr, "returnByValue": True, "awaitPromise": True}, session_id=cdp.session_id)
+        return (r.get("result") or {}).get("value")
+
+    async def install(self, session: Any) -> None:
+        """page.js on every new document of the focused tab (once per tab) and on the current one (idempotent)."""
+        cdp = await session.get_or_create_cdp_session()
+        tid = getattr(cdp, "target_id", None) or ""
+        if tid not in self._targets:
+            await session._cdp_add_init_script(PAGE_JS)  # noqa: SLF001  browser-use 0.13.11: Page.addScriptToEvaluateOnNewDocument
+            self._targets.add(tid)
+        await self._eval(session, PAGE_JS)
+        origin = await self._eval(session, "location.origin") or ""
+        kinds = await self._kinds_for(origin)
+        if kinds:
+            await self._eval(session, f"window.__claros && window.__claros.setKinds({json.dumps(kinds)})")
+
+    async def drain(self, session: Any) -> Optional[ClarosStop]:
+        """Take the held actions, check each, replay the allowed ones, drop the stopped ones. Main frame only."""
+        stop = None
+        try:
+            items = await self._eval(session, "window.__claros ? window.__claros.take() : []") or []
+        except Exception:  # noqa: BLE001  the page is gone (navigation): anything it held went with it, unsent
+            items = []
+        for it in items:
+            d = await self.decide(it, session)
+            fn = "release" if d["allowed"] else "drop"
+            try:
+                await self._eval(session, f"window.__claros.{fn}({int(it['id'])})")
+            except Exception:  # noqa: BLE001  navigated away: the held action is gone with its page
+                pass
+            stop = stop or d.get("stop")
+        return stop
+
+
+def guard_tools(tools: Any, **opts: Any) -> Guard:
+    """Wraps a browser-use Tools (Controller) instance: every action runs with page.js installed, and the actions it
+    caused are checked before they reach the app. Returns the Guard (decisions, stops)."""
+    from browser_use.agent.views import ActionResult
+
+    g = Guard(**opts)
+    orig = tools.act
+
+    async def act(action: Any, browser_session: Any, *a: Any, **kw: Any) -> Any:
+        try:
+            await g.install(browser_session)
+        except Exception:  # noqa: BLE001  no page yet (about:blank startup): nothing to hold
+            pass
+        res = await orig(action, browser_session, *a, **kw)
+        seen = len(g.nudges)
+        stop = await g.drain(browser_session)
+        if stop:
+            return ActionResult(error=str(stop))
+        if new := "\n\n".join(n["text"] for n in g.nudges[seen:]):  # into the agent's memory, so it self-corrects
+            res = res if isinstance(res, ActionResult) else ActionResult()
+            res.extracted_content = "\n\n".join(x for x in (res.extracted_content, new) if x)
+            res.include_extracted_content_only_once = False
+            if res.long_term_memory:  # set → extracted_content wouldn't reach the memory
+                res.long_term_memory += "\n\n" + new
+        return res
+
+    tools.act = act
+    tools.claros = g
+    return g
+
+
+__all__ = ["ClarosStop", "Guard", "PAGE_JS", "guard_tools", "nudge_text", "stop_text"]