claros-browser 0.1.0__py3-none-any.whl

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"]

claros_browser/page.js

@@ -0,0 +1,340 @@
+// Claros browser hook, in-page half. Injected into every frame by the harness adapter (Playwright: addInitScript;
+// browser-use: Page.addScriptToEvaluateOnNewDocument). App-agnostic: no app names, selectors or URLs.
+//
+// A capture-phase listener on window sees every click / submit / Enter before the app does. A consequential one
+// (a submit of a POST form, or a button/link whose accessible name says commit: submit, save, send, pay, approve,
+// delete, deploy, merge, confirm … in several languages, or that Claros's tool kinds call a write) is held: its
+// default and the app's handlers never run. The record the page shows is read at that moment. The harness takes the
+// held actions (__claros.take()), checks them with Claros, then replays the allowed ones (release) and drops the
+// stopped ones (drop). Reads and typing pass through untouched. No harness → held forever (fail closed).
+(() => {
+  if (window.__claros) return;
+
+  const norm = (s) => String(s ?? "").replace(/\s+/g, " ").trim();
+  const words = (s) => norm(s).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+
+  // commit vocabulary: whole words, and stems (prefixes) for inflected languages
+  const WORDS = new Set(("submit save send pay post book buy merge update create approve reject delete " +
+    "remove deploy confirm publish checkout transfer refund release execute archive purchase revoke grant " +
+    // de
+    "senden absenden speichern buchen bezahlen zahlen genehmigen freigeben löschen bestätigen einreichen " +
+    "übermitteln veröffentlichen erstellen anlegen überweisen erstatten ablehnen aktualisieren bereitstellen " +
+    // fr
+    "envoyer enregistrer soumettre payer approuver valider supprimer confirmer publier déployer créer fusionner " +
+    "rembourser rejeter commander " +
+    // es / pt / it
+    "enviar guardar pagar aprobar eliminar borrar confirmar publicar desplegar crear fusionar reembolsar rechazar " +
+    "actualizar salvar aprovar excluir implantar inviare salvare pagare approvare eliminare confermare pubblicare " +
+    // ru
+    "отправить сохранить оплатить утвердить согласовать удалить подтвердить опубликовать провести создать " +
+    "развернуть обновить отклонить оформить перевести вернуть").split(" "));
+  const STEMS = ["submit", "approv", "delet", "remov", "deploy", "confirm", "publish", "refund", "releas", "execut",
+    "archiv", "purchas", "revok", "absend", "speicher", "bezahl", "genehmig", "freigeb", "lösch", "bestätig",
+    "einreich", "übermittel", "veröffentlich", "erstell", "überweis", "erstatt", "ablehn", "aktualisier",
+    "enregistr", "approuv", "supprim", "déploy", "rembours", "aprob", "elimin", "despleg", "reembols", "rechaz",
+    "actualiz", "conferm", "pubblic", "отправ", "сохран", "оплат", "утверд", "согласов", "удал", "подтверд",
+    "опублик", "провед", "провест", "развер", "обнов", "отклон", "оформ"];
+  const PHRASES = ["place order", "sign off", "mettre à jour", "make payment"];
+  // "Cancel" / "Close" alone dismiss; with an object ("Cancel order", "Close ticket") they commit
+  const DISMISS = new Set(["cancel", "close", "abbrechen", "schließen", "annuler", "fermer", "cancelar", "cerrar",
+    "fechar", "annulla", "chiudi", "отмена", "отменить", "закрыть"]);
+  // a name starting with one of these navigates or reads, whatever follows ("Next: review and submit")
+  const BENIGN = new Set(["next", "back", "previous", "prev", "preview", "search", "filter", "find", "view", "show",
+    "open", "edit", "login", "weiter", "zurück", "vorschau", "suchen", "suivant", "précédent", "aperçu",
+    "rechercher", "siguiente", "anterior", "buscar", "avanti", "indietro", "далее", "назад", "поиск", "найти"]);
+  // in a dialog, the affirmative answer is the commit ("Deploy to production?" → "OK")
+  const YES = new Set(["ok", "yes", "ja", "oui", "sí", "si", "sim", "да", "continue", "proceed"]);
+
+  let kinds = {}; // Claros tool kinds for this app: {button name: "read" | "write"} (expert/LLM classified)
+
+  function commitName(name, inDialog) {
+    const k = kinds[norm(name)];
+    if (k === "write") return true;
+    if (k === "read") return false;
+    const w = words(name);
+    if (!w.length || BENIGN.has(w[0]) || (w[0] === "sign" && (w[1] === "in" || w[1] === "up")) ||
+        (w[0] === "log" && w[1] === "in")) return false;
+    if (DISMISS.has(w[0])) return w.length > 1 && !w.slice(1).every((x) => DISMISS.has(x));
+    if (inDialog && YES.has(w[0])) return true;
+    const joined = w.join(" ");
+    return w.some((x) => WORDS.has(x) || STEMS.some((s) => x.startsWith(s))) || PHRASES.some((p) => joined.includes(p));
+  }
+
+  // ---------- DOM helpers (open shadow roots included) ----------
+  function all(root, sel) {
+    const out = [...root.querySelectorAll(sel)];
+    for (const el of root.querySelectorAll("*")) if (el.shadowRoot) out.push(...all(el.shadowRoot, sel));
+    return out;
+  }
+  const textOf = (el) => norm(el ? (el.innerText ?? el.textContent) : "");
+  function byIds(el, attr) {
+    const ids = (el.getAttribute(attr) || "").split(/\s+/).filter(Boolean);
+    const root = el.getRootNode();
+    return norm(ids.map((id) => textOf((root.getElementById ? root : document).getElementById(id))).join(" "));
+  }
+  const ACTIONABLE = "button, a[href], input[type=submit], input[type=button], input[type=image], [role=button], " +
+    "[role=link], [role=menuitem], summary";
+
+  function nameOf(el) {
+    return byIds(el, "aria-labelledby") || norm(el.getAttribute("aria-label")) ||
+      (el.tagName === "INPUT" ? norm(el.value || el.alt || (el.type === "submit" ? "Submit" : "")) : "") ||
+      textOf(el) || norm(el.getAttribute("title"));
+  }
+  const inDialog = (el) => !!el.closest("dialog, [role=dialog], [role=alertdialog]");
+  const disabled = (el) => el.disabled || el.getAttribute("aria-disabled") === "true";
+
+  /** The element a click lands on, if it's a consequential action: {el, name} or null. */
+  function classify(target) {
+    const el = target?.closest?.(ACTIONABLE);
+    if (!el || disabled(el)) return null;
+    const name = nameOf(el);
+    const form = el.form || null;
+    const submits = form && (el.type === "submit" || el.type === "image" ||
+      (el.tagName === "BUTTON" && !el.getAttribute("type")));
+    const post = submits && (el.getAttribute("formmethod") || form.getAttribute("method") || "get").toLowerCase() !== "get";
+    if (post) return { el, name: name || "Submit" };
+    // a row's own button inside a form ("Remove line") edits the form; the form's submit is the commit
+    if (!submits && el.closest("form") && el.closest("tr, [role=row], li")) return null;
+    if (commitName(name, inDialog(el))) return { el, name };
+    return null;
+  }
+
+  // ---------- reading the record ----------
+  const CONTROLS = "input, select, textarea, [contenteditable=''], [contenteditable=true], [role=textbox], " +
+    "[role=combobox], [role=checkbox], [role=switch], [role=radio], [role=spinbutton], [role=slider], " +
+    "[role=listbox], output";
+  const SKIP = new Set(["password", "submit", "button", "reset", "image", "file"]);
+
+  function clean(s) {
+    return norm(s).replace(/\s*[:：*]+\s*$/, "").replace(/^\*\s*/, "");
+  }
+
+  function labelOf(c) {
+    const l = byIds(c, "aria-labelledby") || norm(c.getAttribute("aria-label"));
+    if (l) return clean(l);
+    const host = c.parentElement?.closest("[role=combobox]"); // an input inside a custom combobox
+    if (host) {
+      const h = byIds(host, "aria-labelledby") || norm(host.getAttribute("aria-label"));
+      if (h) return clean(h);
+    }
+    for (const lab of c.labels || []) {
+      const x = lab.cloneNode(true);
+      x.querySelectorAll(CONTROLS + ", option").forEach((n) => n.remove());
+      if (norm(x.textContent)) return clean(x.textContent);
+    }
+    const ph = c.getAttribute("placeholder") || c.getAttribute("aria-placeholder") || c.getAttribute("title");
+    if (ph) return clean(ph);
+    // nearby text: the closest text before the control, within a few ancestors that hold no other control
+    let n = c;
+    for (let depth = 0; n && depth < 3; depth++, n = n.parentElement) {
+      for (let s = n.previousElementSibling; s; s = s.previousElementSibling) {
+        if (s.matches(CONTROLS) || s.querySelector(CONTROLS)) break;
+        const t = textOf(s);
+        if (t && t.length <= 60) return clean(t);
+      }
+      if (n.parentElement && all(n.parentElement, CONTROLS).length > 1) break;
+    }
+    return clean(c.getAttribute("name") || c.id || "");
+  }
+
+  function valueOf(c) {
+    const role = c.getAttribute("role");
+    if (c.tagName === "SELECT") {
+      const sel = [...c.selectedOptions].map((o) => norm(o.label || o.text));
+      return c.multiple ? sel.join(", ") : (sel[0] ?? "");
+    }
+    if (c.tagName === "INPUT" && (c.type === "checkbox" || c.type === "radio")) return c.checked ? 1 : 0;
+    if (role === "checkbox" || role === "switch" || role === "radio") return c.getAttribute("aria-checked") === "true" ? 1 : 0;
+    if (c.tagName === "INPUT" || c.tagName === "TEXTAREA") return c.value;
+    if (role === "spinbutton" || role === "slider") return c.getAttribute("aria-valuetext") ?? c.getAttribute("aria-valuenow") ?? textOf(c);
+    if (role === "listbox") return all(c, "[aria-selected=true]").map(textOf).join(", ");
+    if (role === "combobox") {
+      const inner = c.querySelector("input");
+      return inner ? inner.value : (c.getAttribute("aria-valuetext") ?? textOf(c));
+    }
+    return textOf(c);
+  }
+
+  const optionLabel = (r) => (r.labels?.[0] ? clean(r.labels[0].textContent) : "") || norm(r.getAttribute("aria-label")) ||
+    textOf(r) || r.value;
+
+  function groupLabel(r) {
+    const g = r.closest("[role=radiogroup], fieldset, [role=group]");
+    if (g) {
+      const l = byIds(g, "aria-labelledby") || norm(g.getAttribute("aria-label")) || textOf(g.querySelector("legend"));
+      if (l) return clean(l);
+    }
+    return clean(r.getAttribute("name") || "");
+  }
+
+  /** Each table / grid in the scope → rows of {column header: cell value}; a two-column table with row headers is
+   *  key-value pairs instead. Returns the cells' controls so they aren't read again as fields. */
+  function tables(scope, state) {
+    const rows = [], used = new Set();
+    for (const t of all(scope, "table, [role=table], [role=grid]")) {
+      if (t.parentElement?.closest("table, [role=table], [role=grid]")) continue; // nested: the outer one reads it
+      const native = t.tagName === "TABLE";
+      const trs = native ? [...t.rows] : all(t, "[role=row]");
+      const cellsOf = (tr) => native ? [...tr.cells] : [...tr.querySelectorAll("[role=cell], [role=gridcell], [role=columnheader], [role=rowheader]")];
+      const head = trs.find((tr) => cellsOf(tr).length && cellsOf(tr).every((c) => c.tagName === "TH" || /header/.test(c.getAttribute("role") || "")));
+      const body = trs.filter((tr) => tr !== head && cellsOf(tr).length);
+      if (!head) { // row headers: <tr><th>Label</th><td>value</td></tr>
+        for (const tr of body) {
+          const c = cellsOf(tr);
+          if (c.length === 2 && (c[0].tagName === "TH" || c[0].getAttribute("role") === "rowheader")) {
+            state[clean(textOf(c[0]))] ??= cellValue(c[1], used);
+          }
+        }
+        continue;
+      }
+      const cols = cellsOf(head).map((c) => clean(textOf(c)));
+      for (const tr of body) {
+        const row = {};
+        cellsOf(tr).forEach((cell, i) => {
+          const v = cellValue(cell, used);
+          if (cols[i] && v !== "" && v != null) row[cols[i]] = v;
+        });
+        if (Object.keys(row).length) rows.push(row);
+      }
+    }
+    return { rows, used };
+  }
+
+  function cellValue(cell, used) {
+    const cs = all(cell, CONTROLS).filter(field);
+    cs.forEach((c) => used.add(c));
+    if (!cs.length) return textOf(cell);
+    const vals = cs.map(valueOf).filter((v) => v !== "");
+    return vals.length === 1 ? vals[0] : vals.join(" ");
+  }
+
+  function field(c) {
+    if (c.tagName === "INPUT" && SKIP.has(c.type)) return false;
+    if (/^(BUTTON|FIELDSET|OBJECT)$/.test(c.tagName) && !c.getAttribute("role")) return false; // form.elements has these
+    if (c.closest("[aria-hidden=true]")) return false;
+    // a wrapper role (combobox around an input) is read through its input
+    if (!/^(INPUT|SELECT|TEXTAREA)$/.test(c.tagName) && c.querySelector("input, select, textarea")) return false;
+    // an option inside a listbox, a textbox inside a combobox: the outer control is the field
+    if (c.parentElement?.closest("[role=listbox], select")) return false;
+    return true;
+  }
+
+  const holdsRecord = (n) => all(n, CONTROLS).some((c) => field(c) && c.type !== "hidden") || all(n, "dl, table").length > 0;
+
+  /** Where the record lives: the button's form if it holds fields, else the nearest ancestor that does (a dialog with
+   *  fields; a bottom action bar or a field-less confirm dialog → the screen around it), else the whole page. */
+  function scopeOf(el) {
+    const f = el.form || el.closest("form, [role=form]");
+    if (f && holdsRecord(f)) return f;
+    // ponytail: nearest ancestor with any field; a search box beside the button would win over the record further up
+    for (let n = el.parentElement; n && n !== document.documentElement; n = n.parentElement) {
+      if (holdsRecord(n)) return n;
+    }
+    return document.body;
+  }
+
+  /** The record the page shows around `el`: {state: {label: value}, rows: [{column: value}]}. */
+  function record(el) {
+    const scope = scopeOf(el);
+    const state = {};
+    const { rows, used } = tables(scope, state);
+    const fields = [];
+    const radios = new Map();
+    const ctrls = new Set(all(scope, CONTROLS));
+    if (scope.elements) for (const c of scope.elements) ctrls.add(c); // form="…" controls outside the form
+    const isForm = scope.tagName === "FORM"; // a form submits its hidden steps too; elsewhere unrendered = not shown
+    for (const c of ctrls) {
+      if (used.has(c) || !field(c) || (!isForm && c.type !== "hidden" && !c.getClientRects().length)) continue;
+      if ((c.tagName === "INPUT" && c.type === "radio") || c.getAttribute("role") === "radio") {
+        const g = groupLabel(c);
+        if (!radios.has(g)) radios.set(g, "");
+        if (valueOf(c)) radios.set(g, optionLabel(c));
+        continue;
+      }
+      if (c.tagName === "INPUT" && c.type === "hidden") continue; // read below, by name, last
+      const label = labelOf(c);
+      if (label) fields.push([label, valueOf(c)]);
+    }
+    for (const [g, v] of radios) if (g) fields.push([g, v]);
+    // line items without a table: the n-th repeat of a label belongs to row n
+    const count = {};
+    for (const [l] of fields) count[l] = (count[l] || 0) + 1;
+    const seen = {}, extra = [];
+    for (const [l, v] of fields) {
+      if (count[l] > 1) {
+        const i = (seen[l] = (seen[l] ?? -1) + 1);
+        (extra[i] ??= {})[l] = v;
+      } else state[l] = v;
+    }
+    rows.push(...extra.filter((r) => r && Object.keys(r).length));
+    // read-only summaries (a wizard's review step): <dl>
+    for (const dl of all(scope, "dl")) {
+      for (const dt of dl.querySelectorAll("dt")) {
+        const dd = dt.nextElementSibling;
+        if (dd?.tagName === "DD") state[clean(textOf(dt))] ??= textOf(dd);
+      }
+    }
+    if (scope.elements) {
+      for (const c of scope.elements) if (c.type === "hidden" && c.name) state[c.name] ??= c.value;
+    }
+    delete state[""];
+    return { state, rows };
+  }
+
+  // ---------- holding and replaying ----------
+  const held = new Map();
+  let seq = 0, pass = false;
+
+  function hold(e, item, replay) {
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    const id = ++seq;
+    let rec;
+    try { rec = record(item.el); } catch (err) { rec = { state: {}, rows: [], error: String(err) }; }
+    held.set(id, { replay, info: { id, kind: item.kind, action: item.name, app: location.origin, url: location.href,
+      title: document.title, frame: window !== window.top, ...rec } });
+    try { window.__clarosNotify?.(); } catch { /* no binding: the harness drains after its action */ }
+  }
+
+  function withPass(fn) {
+    pass = true;
+    try { fn(); } finally { pass = false; }
+  }
+
+  window.addEventListener("click", (e) => {
+    if (pass) return;
+    const c = classify(e.composedPath()[0] || e.target);
+    if (c) hold(e, { ...c, kind: "click" }, () => withPass(() => c.el.click()));
+  }, true);
+
+  window.addEventListener("submit", (e) => {
+    if (pass) return;
+    const form = e.target, sub = e.submitter;
+    const method = ((sub && sub.getAttribute("formmethod")) || form.getAttribute("method") || "get").toLowerCase();
+    const name = sub ? nameOf(sub) : (norm(form.getAttribute("aria-label")) || "Submit");
+    if (method === "get" && !commitName(name, false)) return; // a search form
+    hold(e, { el: sub || form, name, kind: "submit" },
+      () => withPass(() => (sub && sub.form === form ? form.requestSubmit(sub) : form.requestSubmit())));
+  }, true);
+
+  // Enter / Space on a custom (non-native) button: apps act on keydown there, no click follows
+  window.addEventListener("keydown", (e) => {
+    if (pass || (e.key !== "Enter" && e.key !== " ")) return;
+    const t = e.composedPath()[0] || e.target;
+    if (!t?.closest || t.closest("button, a[href], input, textarea, select")) return; // native: a click follows
+    const c = classify(t);
+    if (c) hold(e, { ...c, kind: "key" }, () => withPass(() => t.dispatchEvent(new KeyboardEvent("keydown",
+      { key: e.key, code: e.code, bubbles: true, cancelable: true, composed: true }))));
+  }, true);
+
+  window.__claros = {
+    take: () => [...held.values()].filter((h) => !h.taken && (h.taken = true)).map((h) => h.info),
+    release: (id) => { const h = held.get(id); held.delete(id); if (h) h.replay(); return !!h; },
+    drop: (id) => held.delete(id),
+    setKinds: (k) => { kinds = k || {}; },
+    // for tests and the e2e report
+    classify: (el) => { const c = classify(el); return c && c.name; },
+    record: (el) => record(el),
+    commitName,
+  };
+})();

claros_browser-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+claros_browser/__init__.py,sha256=T-rQk5YEqZjEehw41QBcb9EsFGWA-0-ow6fy9Hr_jv0,13174
+claros_browser/page.js,sha256=XIMlviezI2WSkSSKd8NMuMg7XHmidafEsAc44YezdRA,18281
+claros_browser-0.1.0.dist-info/METADATA,sha256=kQoQdIMdHPG4NqXv3wM70w6xwr9gZbwq3XeaHol8jRU,1010
+claros_browser-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+claros_browser-0.1.0.dist-info/licenses/LICENSE,sha256=Buv88Tdsa2GqRMkcoCi3yfBy9x8z22K7IwIS2M9lEa0,1072
+claros_browser-0.1.0.dist-info/RECORD,,

claros_browser-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

claros_browser-0.1.0.dist-info/licenses/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.