lyra-browser 0.1.2__py3-none-any.whl

lyra_browser/__init__.py

@@ -0,0 +1,10 @@
+"""lyra-browser — a headful, collaborative browser MCP server for VEGA."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .config import Config
+from .server import build_server
+
+__all__ = ["Config", "build_server", "__version__"]

lyra_browser/__main__.py

@@ -0,0 +1,85 @@
+"""CLI entry point: ``lyra-browser`` launches the MCP server over stdio.
+
+VEGA (mcp.json) and Hermes (config.yaml ``mcp_servers``) spawn this as a stdio
+MCP server. Pass ``--http`` to instead serve over Streamable HTTP for
+remote/dev use.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .config import CLIENTS, Config
+from .server import build_server
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="lyra-browser", description=__doc__)
+    parser.add_argument("--http", action="store_true", help="Serve over HTTP instead of stdio.")
+    parser.add_argument("--host", default="127.0.0.1", help="HTTP host (with --http).")
+    parser.add_argument("--port", type=int, default=8765, help="HTTP port (with --http).")
+    parser.add_argument(
+        "--headless",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help=(
+            "Run without a visible window. Nobody can watch or take over, so the "
+            "collaboration tools refuse with 'unattended'. Omit to follow "
+            "LYRA_BROWSER_HEADLESS, else the client's default (headless for "
+            "hermes, and on Linux with no display)."
+        ),
+    )
+    parser.add_argument(
+        "--client",
+        choices=sorted(CLIENTS),
+        default=None,
+        help=(
+            "The agent harness spawning this server. Picks where the profile and "
+            "captures live and whether a window is expected. Omit to follow "
+            "LYRA_BROWSER_CLIENT, else detect (VEGA_DATA_DIR -> vega, "
+            "HERMES_HOME -> hermes)."
+        ),
+    )
+    parser.add_argument(
+        "--uat-run",
+        type=Path,
+        default=None,
+        metavar="RUN_JSON",
+        help=(
+            "Serve one UAT persona run over stdio: the run.json that `lyra-uat run` "
+            "wrote. Configuration comes from that file, not from the environment or "
+            "the other flags. Used by harness brains (Claude Code, Codex)."
+        ),
+    )
+    return parser
+
+
+def config_from_args(args: argparse.Namespace) -> Config:
+    """Build the runtime config: environment first, explicit flags on top.
+
+    A flag beats the environment so a developer can force either mode without
+    editing the VEGA install's mcp.json env block.
+    """
+    cfg = Config.from_env(client=args.client)
+    if args.headless is not None:
+        cfg.headless = args.headless
+    return cfg
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    if args.uat_run is not None:
+        from .uat.server import serve_stdio
+
+        serve_stdio(args.uat_run)
+        return
+    mcp = build_server(config_from_args(args))
+    if args.http:
+        mcp.run(transport="http", host=args.host, port=args.port)
+    else:
+        mcp.run()
+
+
+if __name__ == "__main__":
+    main()

lyra_browser/approval.py

@@ -0,0 +1,82 @@
+"""Risk gating and collaboration state for human-in-the-loop control.
+
+Two mechanisms live here:
+
+1. **Risk gate** — high-impact actions (navigating to a new origin, submitting a
+   form, clicking a destructive control) require an explicit ``confirm=True`` when
+   ``Config.require_approval`` is on. A gated call returns a structured
+   ``needs_approval`` envelope instead of acting, so VEGA can ask the user first.
+
+2. **Takeover state** — the user can grab the wheel. While a takeover is active,
+   agent-driven mutation tools refuse to act and tell the model to wait.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class ApprovalRequired(Exception):
+    """Raised by gated tools when the user has not yet confirmed the action."""
+
+    def __init__(self, action: str, reason: str, asked: bool = False) -> None:
+        super().__init__(reason)
+        self.action = action
+        self.reason = reason
+        self.asked = asked
+
+    def envelope(self) -> dict[str, str]:
+        if self.asked:
+            # The client put the question to a person and this is their answer.
+            # "Re-call with confirm=true" would only ask them again — on Hermes
+            # that is another approval prompt in their chat — so say so.
+            hint = (
+                "The user was asked and did not approve. Do not re-call to get "
+                "past this; tell them it was refused and retry only if they ask."
+            )
+        else:
+            hint = "Re-call with confirm=true to proceed once the user agrees."
+        return {
+            "status": "needs_approval",
+            "action": self.action,
+            "reason": self.reason,
+            "hint": hint,
+        }
+
+
+class TakeoverActive(Exception):
+    """Raised when the user holds the session and the agent tries to mutate it."""
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+    def envelope(self) -> dict[str, str]:
+        return {
+            "status": "takeover_active",
+            "reason": self.reason,
+            "hint": "The user is driving. Call resume_after_takeover when they hand back.",
+        }
+
+
+@dataclass(slots=True)
+class CollaborationState:
+    """Shared, in-process control state between the agent and the user."""
+
+    require_approval: bool = True
+    takeover: bool = False
+    takeover_reason: str = ""
+
+    def gate(self, action: str, reason: str, confirm: bool) -> None:
+        """Enforce the risk gate for a high-impact action.
+
+        Raises ApprovalRequired unless approval is disabled or confirm is True.
+        """
+        if not self.require_approval or confirm:
+            return
+        raise ApprovalRequired(action, reason)
+
+    def assert_agent_may_act(self) -> None:
+        """Block agent-driven mutations while the user holds a takeover."""
+        if self.takeover:
+            raise TakeoverActive(self.takeover_reason or "User has taken over the session.")

lyra_browser/audit.py

@@ -0,0 +1,80 @@
+"""Append-only audit trail.
+
+Every tool invocation is recorded as one JSON line so a user can review exactly
+what the agent did in their browser. This is a hard requirement for a tool that
+acts inside a session sharing the user's logins.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+
+class AuditLog:
+    def __init__(self, path: Path, *, mirror_stderr: bool = False) -> None:
+        self._path = path
+        # Each record is also written, unprefixed, as one JSON line on stderr —
+        # for hosts whose disk is ephemeral but whose stderr is collected.
+        self._mirror_stderr = mirror_stderr
+
+    def record(
+        self,
+        tool: str,
+        args: dict[str, Any] | None = None,
+        status: str = "ok",
+        detail: str | None = None,
+        origin: str | None = None,
+        initiator: str | None = None,
+    ) -> None:
+        """Append a single audit entry. Best-effort: never raises into a tool call.
+
+        ``origin`` is where the action points and ``initiator`` is where it came
+        from. Reconstructing an incident needs both: a request to a bank is
+        ordinary from the bank's own page and alarming from anywhere else.
+        """
+        entry: dict[str, Any] = {
+            "ts": datetime.now(UTC).isoformat(),
+            "tool": tool,
+            "args": _redact(args or {}),
+            "status": status,
+            "detail": detail,
+        }
+        # Only present when known, so existing entries keep their shape.
+        if origin is not None:
+            entry["origin"] = origin
+        if initiator is not None:
+            entry["initiator"] = initiator
+        line = json.dumps(entry, ensure_ascii=False)
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            with self._path.open("a", encoding="utf-8") as fh:
+                fh.write(line + "\n")
+        except OSError:
+            # Auditing must not break the agent loop; surfacing happens elsewhere.
+            pass
+        if self._mirror_stderr:
+            try:
+                print(line, file=sys.stderr, flush=True)
+            except (OSError, ValueError):
+                pass
+
+
+# Argument keys whose values should never hit the on-disk log verbatim.
+# ``post_data`` is here because the enforcement layer sees raw form bodies, and
+# that is exactly where a submitted password lives.
+_SENSITIVE_KEYS = {"password", "secret", "token", "value", "post_data"}
+
+
+def _redact(args: dict[str, Any]) -> dict[str, Any]:
+    """Redact values that may carry credentials typed into form fields."""
+    out: dict[str, Any] = {}
+    for key, val in args.items():
+        if key.lower() in _SENSITIVE_KEYS and isinstance(val, str):
+            out[key] = f"<redacted:{len(val)} chars>"
+        else:
+            out[key] = val
+    return out

lyra_browser/capture.py

@@ -0,0 +1,129 @@
+"""Captures: screenshots and element images written to disk for the model.
+
+A capture is handed over as a *file*, not as base64 inside the tool result.
+Measured on VEGA: the client concatenates the text blocks of a tool result and
+shows the model that string, so a base64 PNG arrives as tens of thousands of
+tokens of prose and no picture. VEGA does have an image path — a local file
+under its uploads root is attached to the next model turn as an image block —
+and the in-app browser runs on the same machine, so a file on disk is the one
+handoff both surfaces can use without a protocol in between.
+
+Files are named so they sort by time, written atomically so a reader never
+sees a partial PNG, and pruned oldest-first so a long session cannot fill the
+disk one screenshot per turn.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import struct
+import uuid
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .config import Config
+
+MIME_PNG = "image/png"
+_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+# Chrome answers Page.captureScreenshot with this while the renderer has not
+# presented a frame yet. Measured with Chrome 152 headless on a fresh context:
+# the first capture after a navigation to example.com fails, and the same call
+# ~1s later succeeds. It is a transient, not a broken page, so it is retried.
+_NO_FRAME_YET = "Unable to capture screenshot"
+_RETRY_DELAY_S = 0.15
+_RETRY_BUDGET_S = 3.0
+
+
+async def take(shoot: Callable[[], Awaitable[bytes]]) -> bytes:
+    """Run ``shoot`` and retry the no-frame-yet transient within a small budget.
+
+    Any other failure — element detached, page closed — is raised as it is;
+    only the one message Chrome uses for "nothing painted yet" is retried, and
+    even that gives up after ``_RETRY_BUDGET_S`` so a page that never paints
+    still errors instead of hanging the tool.
+    """
+    deadline = asyncio.get_running_loop().time() + _RETRY_BUDGET_S
+    while True:
+        try:
+            return await shoot()
+        except Exception as exc:  # noqa: BLE001 — filtered on the message below
+            if _NO_FRAME_YET not in str(exc) or asyncio.get_running_loop().time() >= deadline:
+                raise
+            await asyncio.sleep(_RETRY_DELAY_S)
+
+
+def png_size(png: bytes) -> tuple[int, int] | None:
+    """Width and height from the IHDR chunk, or None when this is not a PNG.
+
+    The IHDR chunk is mandatory and always first, so the dimensions sit at a
+    fixed offset: signature (8) + length (4) + type (4) = 16.
+    """
+    if len(png) < 24 or not png.startswith(_PNG_SIGNATURE) or png[12:16] != b"IHDR":
+        return None
+    width, height = struct.unpack(">II", png[16:24])
+    return width, height
+
+
+def save_capture(config: Config, png: bytes, kind: str) -> Path:
+    """Write ``png`` under the capture dir and return its path.
+
+    ``kind`` names what was captured (``page``, ``element``) and leads the file
+    name so a directory listing reads as a log. The write goes through a temp
+    file and ``os.replace`` so a concurrent reader — VEGA attaching the image
+    while we are still writing — cannot observe a truncated file.
+    """
+    directory = config.capture_dir
+    directory.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+    final = directory / f"{kind}-{stamp}-{uuid.uuid4().hex[:8]}.png"
+    tmp = final.with_suffix(".png.part")
+    with tmp.open("wb") as handle:
+        handle.write(png)
+    os.replace(tmp, final)
+    _prune(directory, keep=config.capture_keep)
+    return final
+
+
+def _prune(directory: Path, keep: int) -> None:
+    """Delete the oldest captures beyond ``keep``. ``keep <= 0`` keeps everything.
+
+    Ordered by name, not mtime: names carry a UTC timestamp, and mtime is what
+    a copy or a backup restore rewrites.
+    """
+    if keep <= 0:
+        return
+    files = sorted(p for p in directory.glob("*.png") if p.is_file())
+    for stale in files[: max(0, len(files) - keep)]:
+        try:
+            stale.unlink()
+        except OSError:
+            # Someone else's problem — a capture we cannot delete is not a
+            # reason to fail the one we just took.
+            pass
+
+
+def envelope(path: Path, png: bytes, *, url: str, inline: bool) -> dict:
+    """The tool result for a capture.
+
+    The path is the handoff. ``inline`` adds the base64 for a client with no
+    access to this filesystem — it is opt-in because on the client that does
+    (VEGA) the string would be shown to the model as text.
+    """
+    result: dict = {
+        "status": "ok",
+        "url": url,
+        "image_path": str(path),
+        "mime_type": MIME_PNG,
+        "bytes": len(png),
+    }
+    size = png_size(png)
+    if size is not None:
+        result["width"], result["height"] = size
+    if inline:
+        import base64
+
+        result["base64"] = base64.b64encode(png).decode("ascii")
+    return result