diff --git a/README.md b/README.md index e5a57f2..9cd1646 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ agent loop ──(MCP: stdio/http)──> lyra-browser server ──> Playwright | Downloads | `list_downloads` | | Forms | `read_form`, `select_option`, `set_editor`, `upload_file`, `read_draft`, `save_draft`, `publish` | | Reading | `get_url`, `read_page`, `screenshot`, `read_image` | +| Tasks | `drag`, `evaluate_readonly`, `read_download`, `save_deliverable`, `set_emulation` | | DevTools | `console_messages`, `network_requests`, `network_request`, `page_performance`, `storage`, `export_har`, `evaluate` | | Collaboration | `highlight_element`, `ask_user_to_do`, `request_takeover`, `resume_after_takeover` | @@ -398,6 +399,34 @@ no listener does: alerts and `beforeunload` are accepted, `confirm` is dismissed - Nothing here judges the answer: accepting a `confirm` that goes on to post a form is still stopped where the request leaves unless it was declared (`submits=true`). +### Task tools: drag, a read-only look, downloads, deliverables, place and language + +What a task needs beyond reading and clicking (`src/lyra_browser/tools/tasks.py`): + +- `drag(source, target)` — presses the pointer on `source`, moves it onto `target` in + steps and releases it, after checking both ends as `click` checks its target. Asks to + interact, like `hover`. For sliders, sortable lists and boards that follow the pointer. +- `evaluate_readonly(expression)` — a JavaScript expression that only reads. Chrome + evaluates it with `throwOnSideEffect`, so an assignment, a DOM change or a request is + refused by the engine before it runs (`refused_side_effect`), not by a pattern match; + that is why it needs no approval, unlike `evaluate`. Expressions that name cookies or + web storage are refused (`refused_storage`): `storage` reads those and asks before it + reveals values. +- `read_download(filename)` — the content of a file this session saved (text up to + 50000 characters, or size, SHA-256 and the first bytes of a binary). Nothing else on + disk can be named. +- `save_deliverable(name, content)` — writes a result (an extract, a table) under a + plain file name to the session's deliverables directory (`/deliverables`, a + UAT run's own directory in `lyra-uat`), never over an existing file unless + `overwrite=true`, up to 1 MB. +- `set_emulation(latitude, longitude, accuracy, locale, timezone, clear)` — what pages + are told about place and language: `navigator.geolocation` (and the permission it + needs), `Intl`/`navigator.language`, the time zone. For this tab and every tab opened + after it. `Accept-Language` and the IP address do not change. + +Reading cookies and web storage is `storage` (DevTools, below); there is no second tool +for it. `scripts/verify_task_tools_e2e.py` is the real-browser gate. + ### DevTools: console, network, performance, storage, `evaluate` What Chrome's DevTools panels show, as tools. What they return was produced by the page diff --git a/docs/UAT.md b/docs/UAT.md index 569c63e..ac09134 100644 --- a/docs/UAT.md +++ b/docs/UAT.md @@ -257,6 +257,15 @@ This is POSIX code (process groups, signals). It was run on Linux only: where th `/proc` (macOS) it falls back to `killpg` alone for the liveness check, which has not been run, and Windows is not supported. +### Task tools in a run + +The task tools (`drag`, `evaluate_readonly`, `read_download`, `save_deliverable`, +`set_emulation`, and `storage` for cookies and web storage) are not offered by default: +name them in `tools.allow` for a persona whose task needs them. `save_deliverable` +writes into the run directory (`/deliverables/`), so what a persona produced stays +with its report. They go through the same consent policy as the rest (`closed` or +`autonomous`); none of them can send a form or publish. + ## Hooks `hooks.before` and `hooks.after` are shell commands. A failing `before` (non-zero) diff --git a/scripts/verify_task_tools_e2e.py b/scripts/verify_task_tools_e2e.py new file mode 100644 index 0000000..28eca6e --- /dev/null +++ b/scripts/verify_task_tools_e2e.py @@ -0,0 +1,216 @@ +#!/usr/bin/env python3 +"""Real-browser gate for the task tools: drag, evaluate_readonly, read_download, +save_deliverable and set_emulation. + +Runs the server's own tools over a real session (``build_tools``) against a loopback +site, on the driver ``LYRA_BROWSER_DRIVER`` names (native by default): + +- drag: a slider that follows ``pointermove`` reaches the end; an HTML5 drag-and-drop + target is measured (a NOTE, not a failure: raw pointer input does not start an HTML5 + drag on every driver) +- evaluate_readonly: reads answer; ``document.title = ...``, a DOM append and ``fetch`` + are refused by Chrome itself, and the title is unchanged afterwards; storage names are + refused before Chrome is asked +- read_download: a CSV saved by ``click(download=true)`` is read back +- save_deliverable: the file is where the reply says, and not written twice +- set_emulation: locale, time zone and position reach the page, survive a navigation + and reach a tab opened afterwards + + python scripts/verify_task_tools_e2e.py + LYRA_BROWSER_DRIVER=playwright python scripts/verify_task_tools_e2e.py +""" + +from __future__ import annotations + +import asyncio +import json +import os +import sys +import tempfile +import threading +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path + +SCRIPTS = Path(__file__).resolve().parent +REPO = SCRIPTS.parent +sys.path.insert(0, str(REPO / "src")) +sys.path.insert(0, str(SCRIPTS)) + +from verify_browser_e2e import build_tools, expect, free_port # noqa: E402 + +SLIDER = """slider + +

0

+""" + +DND = """dnd +
card
+
bin
+""" + +READ = """read me + +prices""" + +GEO = """geo

waiting

+""" + +PAGES = {"/slider": SLIDER, "/dnd": DND, "/read": READ, "/geo": GEO, "/other": "o"} + + +class Handler(BaseHTTPRequestHandler): + def do_GET(self) -> None: # noqa: N802 + if self.path == "/files/prices.csv": + body = b"plan,price\nStudio,29\n" + self.send_response(200) + self.send_header("Content-Type", "text/csv") + self.send_header("Content-Disposition", 'attachment; filename="prices.csv"') + else: + body = PAGES.get(self.path, "404").encode() + self.send_response(200 if self.path in PAGES else 404) + self.send_header("Content-Type", "text/html; charset=utf-8") + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def log_message(self, *_args: object) -> None: + pass + + +async def title_of(tools, expected_prefix: str, seconds: float = 5.0) -> str: + deadline = asyncio.get_running_loop().time() + seconds + title = "" + while asyncio.get_running_loop().time() < deadline: + reply = await tools["evaluate_readonly"](expression="document.title") + title = json.loads(reply.get("result", '""')) if reply["status"] == "ok" else "" + if title.startswith(expected_prefix): + break + await asyncio.sleep(0.2) + return title + + +async def main() -> None: + from lyra_browser.origin import parse_origin + from lyra_browser.permission import Capability + + port = free_port() + server = ThreadingHTTPServer(("127.0.0.1", port), Handler) + threading.Thread(target=server.serve_forever, daemon=True).start() + base = f"http://127.0.0.1:{port}" + driver = os.environ.get("LYRA_BROWSER_DRIVER", "auto") + with tempfile.TemporaryDirectory(prefix="lyra-task-tools-") as tmp: + data_dir = Path(tmp) + ctx, tools = await build_tools(data_dir, headless=True) + site = parse_origin(base) + try: + opened = await tools["open_browser"]() + expect(opened.get("status") == "ok", f"browser opens ({driver})", opened) + ctx.perms.grant("default", site, Capability.NAVIGATE) + + # -- drag + await tools["navigate"](url=f"{base}/slider") + dragged = await tools["drag"](source="#knob", target="#end") + expect(dragged["status"] == "ok", "drag answers ok", dragged) + title = await title_of(tools, "slider:") + expect(title in ("slider:100", "slider:99"), "the slider followed to the end", title) + await tools["navigate"](url=f"{base}/dnd") + await tools["drag"](source="#card", target="#bin") + title = await title_of(tools, "dropped", seconds=2.0) + print(f"NOTE HTML5 drag-and-drop on {driver}: {'dropped' if title else 'no drop'}") + + # -- evaluate_readonly + await tools["navigate"](url=f"{base}/read") + ev = tools["evaluate_readonly"] + count = await ev(expression="document.querySelectorAll('li').length") + expect(count["status"] == "ok" and count["result"] == "3", "a read answers", count) + state = await ev(expression="window.appState") + expect(json.loads(state["result"]) == {"plan": "Studio", "price": 29}, "a global") + for write in ( + "document.title = 'changed'", + "document.body.appendChild(document.createElement('div'))", + "fetch('/other')", + ): + refused = await ev(expression=write) + expect( + refused["status"] == "refused_side_effect", + f"Chrome refuses a write: {write[:30]}", + refused, + ) + title = await ev(expression="document.title") + expect(json.loads(title["result"]) == "read me", "the title is unchanged", title) + refused = await ev(expression="document.cookie") + expect(refused["status"] == "refused_storage", "storage is left to `storage`") + + # -- read_download + ctx.perms.grant("default", site, Capability.DOWNLOAD) + saved = await tools["click"](selector="#csv", download=True, confirm=True) + expect(saved["status"] == "ok" and saved.get("download"), "the CSV is saved", saved) + read = await tools["read_download"](filename="prices.csv") + expect(read.get("text") == "plan,price\nStudio,29\n", "and read back", read) + + # -- save_deliverable + out = await tools["save_deliverable"](name="answer.txt", content="Studio costs 29") + expect(Path(out["path"]).read_text() == "Studio costs 29", "deliverable written", out) + again = await tools["save_deliverable"](name="answer.txt", content="x") + expect(again["status"] == "exists", "not written twice", again) + + # -- set_emulation + emulated = await tools["set_emulation"]( + latitude=52.52, longitude=13.40, locale="de-DE", timezone="Europe/Berlin" + ) + expect(emulated["status"] == "ok", "set_emulation answers ok", emulated) + await tools["navigate"](url=f"{base}/geo") + title = await title_of(tools, "geo") + expect(title == "geo:52.52,13.40", "the page gets the position", title) + loc = await ev(expression="Intl.DateTimeFormat().resolvedOptions().locale") + expect(json.loads(loc["result"]) == "de-DE", "locale survives a navigation", loc) + tz = await ev(expression="Intl.DateTimeFormat().resolvedOptions().timeZone") + expect(json.loads(tz["result"]) == "Europe/Berlin", "time zone too", tz) + page = await ctx.session.page() + before = list(ctx.session.open_pages()) + await page.evaluate("void window.open('/other', '_blank')") + popup = None + for _ in range(50): + fresh = [p for p in ctx.session.open_pages() if p not in before] + if fresh: + popup = fresh[0] + break + await asyncio.sleep(0.1) + expect(popup is not None, "the new tab opened") + await popup.wait_for_load_state() + await asyncio.sleep(0.5) + seen = await popup.evaluate("Intl.DateTimeFormat().resolvedOptions().locale") + expect(seen == "de-DE", "a tab opened afterwards gets the locale", seen) + finally: + await ctx.session.stop() + server.shutdown() + print("ALL PASS") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/src/lyra_browser/config.py b/src/lyra_browser/config.py index f6c7c53..d9656f4 100644 --- a/src/lyra_browser/config.py +++ b/src/lyra_browser/config.py @@ -434,6 +434,8 @@ class Config: audit_path: Path = field(init=False) # Where captures land — derived like profile_dir, see _default_capture_dir. capture_dir: Path = field(init=False) + # Where save_deliverable writes. None: ``/deliverables``. + deliverables_dir: Path | None = None # How many capture files to keep. Every screenshot is a new file, so an # agent that looks at the page on every turn would otherwise fill the disk # over a long session. Oldest go first; 0 disables pruning. diff --git a/src/lyra_browser/tools/__init__.py b/src/lyra_browser/tools/__init__.py index a31e8cd..ad1478d 100644 --- a/src/lyra_browser/tools/__init__.py +++ b/src/lyra_browser/tools/__init__.py @@ -19,6 +19,7 @@ navigation, reading, tabs, + tasks, waiting, ) @@ -34,3 +35,4 @@ def register_all(mcp: FastMCP, ctx: ServerContext) -> None: downloads.register(mcp, ctx) collaboration.register(mcp, ctx) devtools.register(mcp, ctx) + tasks.register(mcp, ctx) diff --git a/src/lyra_browser/tools/tasks.py b/src/lyra_browser/tools/tasks.py new file mode 100644 index 0000000..b51078f --- /dev/null +++ b/src/lyra_browser/tools/tasks.py @@ -0,0 +1,414 @@ +"""Tools a task needs beyond reading and clicking: dragging, a read-only look at the +page's script state, the content of a saved download, a written deliverable, and the +place and language the browser claims. + +Each goes through the same layers as the rest: a page from ``acquire_page``, the +interaction consent and the action guard where the page is acted on, and an audit row. +What a tool does *not* do is part of its contract: + +- ``evaluate_readonly`` runs with V8's side-effect check (``Runtime.evaluate`` with + ``throwOnSideEffect``): an expression that would write anything — the DOM, a global, a + request — is refused by the engine before it runs, not by a pattern match. It also + refuses expressions that name cookies or storage: ``storage`` reads those and asks + before it reveals values. +- ``read_download`` reads only files this session saved (``list_downloads``). +- ``save_deliverable`` writes only inside the session's deliverables directory, under a + plain file name, never over an existing file unless asked. +- ``set_emulation`` changes what pages are told (geolocation, locale, time zone) for this + tab and every tab opened after it; it grants the geolocation permission it implies. + +``storage`` (``tools/devtools.py``) is the read of cookies and web storage; there is no +second one here. +""" + +from __future__ import annotations + +import asyncio +import contextlib +import hashlib +import json +import re +import weakref +from pathlib import Path +from typing import Any + +from fastmcp import FastMCP + +from ..approval import TakeoverActive +from ..context import ServerContext, acquire_page, claim_session +from ..origin import loggable_url +from ..permission import Capability +from .actionable import DEFAULT_TIMEOUT_MS, check_target, clamp_timeout, guard_action +from .aftermath import Aftermath +from .scope import page_origin, require + +_EVAL_TIMEOUT_MS = 3000 +_MAX_RESULT_CHARS = 12000 +_MAX_DOWNLOAD_CHARS = 50000 +_MAX_DELIVERABLE_BYTES = 1_000_000 +_DELIVERABLE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$") +# What ``storage`` reads, and asks before it reveals: not through a side door. +_STORAGE_NAMES = re.compile( + r"\b(cookie|cookieStore|localStorage|sessionStorage|indexedDB|caches)\b" +) + + +def deliverables_dir(ctx: ServerContext) -> Path: + configured = getattr(ctx.config, "deliverables_dir", None) + return Path(configured or (ctx.config.data_dir / "deliverables")).expanduser() + + +async def cdp_send(page: Any, method: str, params: dict | None = None) -> dict: + """One DevTools command on the page's own target, on either driver.""" + session = await page.context.new_cdp_session(page) + try: + return await session.send(method, params or {}) + finally: + with contextlib.suppress(Exception): + await session.detach() + + +def _emulation_commands(state: dict[str, Any]) -> list[tuple[str, dict]]: + out: list[tuple[str, dict]] = [] + if "geolocation" in state: + geo = state["geolocation"] + out.append(("Emulation.setGeolocationOverride", geo or {})) + if "locale" in state: + out.append(("Emulation.setLocaleOverride", {"locale": state["locale"] or ""})) + if "timezone" in state: + out.append(("Emulation.setTimezoneOverride", {"timezoneId": state["timezone"] or ""})) + return out + + +# One DevTools session per tab for the overrides, kept open: Chrome drops an +# ``Emulation.*`` override when the session that set it detaches (measured with +# Playwright, whose ``new_cdp_session`` is a session of its own; the native driver's is +# the page's own and never detaches). Keyed weakly, so a closed tab takes its entry. +_EMULATION_SESSIONS: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary() + + +async def _emulation_session(page: Any) -> Any: + session = _EMULATION_SESSIONS.get(page) + if session is None: + session = await page.context.new_cdp_session(page) + _EMULATION_SESSIONS[page] = session + return session + + +async def apply_emulation(page: Any, state: dict[str, Any]) -> list[str]: + """Send the overrides to one tab; the commands that failed, as text.""" + failed = [] + for method, params in _emulation_commands(state): + try: + await (await _emulation_session(page)).send(method, params) + except Exception as exc: # noqa: BLE001 - reported, the rest still applies + failed.append(f"{method}: {type(exc).__name__}: {exc}"[:200]) + return failed + + +async def grant_geolocation(page: Any) -> str | None: + """The permission an overridden position needs, or why it could not be granted.""" + context = page.context + try: + if hasattr(context, "grant_permissions"): + await context.grant_permissions(["geolocation"]) + else: # the native driver: the browser-level command itself + await context._browser_send( + "Browser.grantPermissions", {"permissions": ["geolocation"]} + ) + except Exception as exc: # noqa: BLE001 + return f"{type(exc).__name__}: {exc}"[:200] + return None + + +def register(mcp: FastMCP, ctx: ServerContext) -> None: + emulation: dict[str, Any] = {} + tabs_seen: set[int] = set() + + def on_new_tab(page: Any) -> None: + # Every tab opened after set_emulation is told the same; a popup that loads at + # once may run a line of script before this lands, which the README says. + if emulation and id(page) not in tabs_seen: + tabs_seen.add(id(page)) + asyncio.ensure_future(apply_emulation(page, dict(emulation))) + + observers = getattr(ctx.session, "page_observers", None) + if isinstance(observers, list): + observers.append(on_new_tab) + + @mcp.tool + async def drag( + source: str, + target: str, + reason: str = "", + confirm: bool = False, + timeout_ms: int = DEFAULT_TIMEOUT_MS, + ) -> dict: + """Press the pointer on ``source``, move it onto ``target`` and release it. + + For sliders, sortable lists, kanban cards, file-drop areas fed from the page and + anything else moved with the mouse. Both are selectors (or aria-refs); each is + checked as ``click`` checks its target (``not_found``, ``hidden``, ``disabled``, + ``element_not_actionable``) before anyone is asked. Asks to interact with the + page, like ``hover``. The pointer moves in steps, so a page that tracks + ``pointermove`` sees a drag rather than a jump. + """ + page, err = await acquire_page(ctx) + if err: + return err + origin = page_origin(page) + try: + ctx.collab.assert_agent_may_act() + except TakeoverActive as exc: + return exc.envelope() + args = {"source": source, "target": target} + timeout = clamp_timeout(timeout_ms) + start, end = page.locator(source).first, page.locator(target).first + for selector, locator in ((source, start), (target, end)): + unusable = await check_target( + ctx, + tool="drag", + page=page, + origin=origin, + locator=locator, + selector=selector, + args=args, + ) + if unusable: + return unusable + denied, bought = await require( + ctx, + "drag", + target=origin, + capabilities=[Capability.INTERACT], + initiator=origin, + reason=reason, + confirm=confirm, + subject=getattr(page, "url", ""), + ) + if denied: + return denied + after = Aftermath(ctx, page) + async with guard_action( + ctx, + bought, + tool="drag", + selector=source, + page=page, + origin=origin, + args=args, + timeout_ms=timeout, + ) as done: + await start.hover(timeout=timeout) + await page.mouse.down() + try: + await end.hover(timeout=timeout) + # A last small move on the target: some pages only accept the drop after + # a pointermove that starts and ends inside it. + mouse = page.mouse + x, y = getattr(mouse, "x", None), getattr(mouse, "y", None) + if x is not None and y is not None: + await mouse.move(x + 1, y + 1, steps=2) + finally: + await page.mouse.up() + after.acted() + done.result = {"status": "ok", "url": page.url, "source": source, "target": target} + status = await after.fold(done.result, caused_by="drag") + ctx.audit.record("drag", args, status=status, origin=origin.describe()) + return done.result + + @mcp.tool + async def evaluate_readonly(expression: str) -> dict: + """Evaluate a JavaScript expression that only reads, in the current tab. + + For what the page knows but does not show: a value in a global, a computed + style, how many items a list holds, a data attribute. The engine itself refuses + anything with a side effect (assigning, calling a method that changes the DOM, + sending a request) and the answer is then ``refused_side_effect``; nothing ran. + Cookies and web storage are read with ``storage``, which asks before it reveals + values: an expression that names them is refused here. No approval is asked, + because nothing can change. Returns the value as JSON, or the exception. + """ + if not expression.strip(): + return {"status": "invalid_argument", "error": "expression is empty"} + if _STORAGE_NAMES.search(expression): + return { + "status": "refused_storage", + "hint": "Read cookies and web storage with the storage tool.", + } + page, err = await acquire_page(ctx) + if err: + return err + origin = page_origin(page).describe() + try: + reply = await cdp_send( + page, + "Runtime.evaluate", + { + "expression": expression, + "throwOnSideEffect": True, + "returnByValue": True, + "timeout": _EVAL_TIMEOUT_MS, + }, + ) + except Exception as exc: # noqa: BLE001 - the tab went away, the session failed + return {"status": "error", "error": f"{type(exc).__name__}: {exc}"[:300]} + details = reply.get("exceptionDetails") + if details: + text = str( + (details.get("exception") or {}).get("description") or details.get("text") or "" + ) + side_effect = "side-effect" in text.lower() or "side effect" in text.lower() + status = "refused_side_effect" if side_effect else "exception" + ctx.audit.record( + "evaluate_readonly", {"expression": expression}, status=status, origin=origin + ) + return {"status": status, "error": text[:2000], "url": loggable_url(page.url)} + result = reply.get("result") or {} + value = result.get("value", result.get("description")) + + try: + encoded = json.dumps(value, ensure_ascii=False, default=str) + except (TypeError, ValueError): + encoded = json.dumps(str(value), ensure_ascii=False) + ctx.audit.record("evaluate_readonly", {"expression": expression}, origin=origin) + return { + "status": "ok", + "result": encoded[:_MAX_RESULT_CHARS], + "truncated": len(encoded) > _MAX_RESULT_CHARS, + "type": result.get("type"), + "url": loggable_url(page.url), + } + + @mcp.tool + async def read_download(filename: str, max_chars: int = 20000) -> dict: + """Read a file this session downloaded (one ``list_downloads`` shows). + + ``filename`` is its ``filename`` or ``path``. Text (UTF-8) comes back as + ``text``, cut at ``max_chars`` (up to 50000); anything else is described + (``bytes``, ``sha256``, the first bytes in hex). Only saved downloads can be + read: any other path is ``not_found``. Reads only; asks nobody. + """ + conflict = await claim_session(ctx, claim=False) + if conflict is not None: + return conflict + saved = ctx.downloads.saved() + entry = next( + (d for d in reversed(saved) if filename in (d.get("filename"), d.get("path"))), + None, + ) + if entry is None: + return { + "status": "not_found", + "known": [d.get("filename") for d in saved], + } + path = Path(str(entry["path"])) + try: + data = path.read_bytes() + except OSError as exc: + return {"status": "error", "error": f"cannot read {path.name}: {exc.strerror}"} + limit = max(1, min(int(max_chars), _MAX_DOWNLOAD_CHARS)) + out: dict[str, Any] = { + "status": "ok", + "filename": entry.get("filename"), + "path": str(path), + "bytes": len(data), + "sha256": hashlib.sha256(data).hexdigest(), + } + try: + text = data.decode("utf-8") + except UnicodeDecodeError: + out["binary"] = True + out["head_hex"] = data[:64].hex() + else: + out["text"] = text[:limit] + out["truncated"] = len(text) > limit + ctx.audit.record("read_download", {"filename": entry.get("filename")}) + return out + + @mcp.tool + async def save_deliverable(name: str, content: str, overwrite: bool = False) -> dict: + """Write a result of the task to a file: an extract, a table, a summary. + + ``name`` is a plain file name (letters, digits, ``.``, ``_``, ``-``; no folders), + ``content`` the text (UTF-8, up to 1 MB). It lands in the session's deliverables + directory, whose path is returned. An existing file is kept unless + ``overwrite=true``. Writes only there; the page is not involved. + """ + if not _DELIVERABLE_NAME.match(name) or ".." in name: + return { + "status": "invalid_argument", + "error": "name must be a plain file name: letters, digits, '.', '_', '-'", + } + data = content.encode("utf-8") + if len(data) > _MAX_DELIVERABLE_BYTES: + return {"status": "invalid_argument", "error": "content is over 1 MB"} + directory = deliverables_dir(ctx) + directory.mkdir(parents=True, exist_ok=True) + path = directory / name + if path.exists() and not overwrite: + return {"status": "exists", "path": str(path), "hint": "pass overwrite=true"} + tmp = path.with_name(f".{name}.part") + tmp.write_bytes(data) + tmp.replace(path) + ctx.audit.record("save_deliverable", {"name": name, "bytes": len(data)}) + return {"status": "ok", "path": str(path), "bytes": len(data)} + + @mcp.tool + async def set_emulation( + latitude: float | None = None, + longitude: float | None = None, + accuracy: float = 50.0, + locale: str | None = None, + timezone: str | None = None, + clear: bool = False, + ) -> dict: + """Set where and in which language the browser says it is, for a task that + depends on it (local prices, a store finder, a date format). + + ``latitude``/``longitude`` (with ``accuracy`` in metres) override the position + ``navigator.geolocation`` reports, and the geolocation permission is granted. + ``locale`` (``de-DE``) changes what ``Intl`` and ``navigator.language`` say; + ``timezone`` (``Europe/Berlin``) the time zone. The request's + ``Accept-Language`` and the IP address do not change. Applies to this tab and + every tab opened after; ``clear=true`` removes them all. + """ + if (latitude is None) != (longitude is None): + return {"status": "invalid_argument", "error": "give latitude and longitude"} + if latitude is not None and not (-90 <= latitude <= 90 and -180 <= longitude <= 180): + return {"status": "invalid_argument", "error": "latitude/longitude out of range"} + page, err = await acquire_page(ctx) + if err: + return err + if clear: + state = {"geolocation": None, "locale": None, "timezone": None} + emulation.clear() + else: + state = {} + if latitude is not None: + state["geolocation"] = { + "latitude": latitude, + "longitude": longitude, + "accuracy": accuracy, + } + if locale is not None: + state["locale"] = locale + if timezone is not None: + state["timezone"] = timezone + if not state: + return {"status": "invalid_argument", "error": "nothing to set"} + emulation.update(state) + failed = [] + if state.get("geolocation"): + problem = await grant_geolocation(page) + if problem: + failed.append(f"Browser.grantPermissions: {problem}") + for tab in ctx.session.open_pages() if hasattr(ctx.session, "open_pages") else [page]: + tabs_seen.add(id(tab)) + failed += await apply_emulation(tab, state) + ctx.audit.record("set_emulation", {k: v for k, v in state.items()}) + return { + "status": "error" if failed else "ok", + "emulation": dict(emulation), + **({"failed": failed} if failed else {}), + } diff --git a/src/lyra_browser/uat/server.py b/src/lyra_browser/uat/server.py index 84a0c79..5c8c1a0 100644 --- a/src/lyra_browser/uat/server.py +++ b/src/lyra_browser/uat/server.py @@ -83,6 +83,8 @@ def build_config(spec: RunSpec, run_dir: Path) -> Config: capture_keep=0, ) cfg.capture_dir = run_dir / "captures" + # save_deliverable writes here: the run directory holds everything a run produced. + cfg.deliverables_dir = run_dir / "deliverables" return cfg diff --git a/tests/conftest.py b/tests/conftest.py index 983fe60..b3bf49e 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -202,6 +202,18 @@ async def press(self, key: str) -> None: class FakeMouse: def __init__(self, page: FakePage) -> None: self._page = page + self.x = 0.0 + self.y = 0.0 + + async def down(self, button: str = "left", click_count: int = 1) -> None: + self._page.calls.append(("mouse_down",)) + + async def up(self, button: str = "left", click_count: int = 1) -> None: + self._page.calls.append(("mouse_up",)) + + async def move(self, x: float, y: float, steps: int = 1) -> None: + self.x, self.y = x, y + self._page.calls.append(("mouse_move", x, y)) async def wheel(self, delta_x: float, delta_y: float) -> None: self._page.calls.append(("wheel", delta_x, delta_y)) @@ -214,6 +226,9 @@ class FakeBrowserContext: """What ``page.context`` offers the storage tool: the cookies a URL would send.""" def __init__(self) -> None: + self.cdp_calls: list[tuple[str, dict]] = [] + self.cdp_answers: dict[str, Any] = {} + self.granted: list[list[str]] = [] self.cookie_jar: list[dict] = [ { "name": "sid", @@ -230,6 +245,28 @@ def __init__(self) -> None: async def cookies(self, urls: Any = None) -> list[dict]: return list(self.cookie_jar) + async def new_cdp_session(self, page: Any) -> FakeCDPSession: + return FakeCDPSession(self) + + async def grant_permissions(self, permissions: list[str], origin: str | None = None) -> None: + self.granted.append(list(permissions)) + + +class FakeCDPSession: + """``context.new_cdp_session(page)``: every command is recorded on the context and + answered from ``cdp_answers`` (a dict, or a callable of the params), else ``{}``.""" + + def __init__(self, context: FakeBrowserContext) -> None: + self._context = context + + async def send(self, method: str, params: dict | None = None) -> dict: + self._context.cdp_calls.append((method, params or {})) + answer = self._context.cdp_answers.get(method, {}) + return answer(params or {}) if callable(answer) else answer + + async def detach(self) -> None: + pass + class FakeRequest: """A Playwright Request as the network listeners see it.""" @@ -693,6 +730,8 @@ def __init__(self, page: FakePage) -> None: """The open tabs, oldest first - what ``BrowserSession.open_pages`` reports.""" self.active_channel = "chrome" self.active_driver = "playwright" + # What BrowserSession calls for each tab it adopts (observers, set_emulation). + self.page_observers: list = [] self.started = True """A fake that hands out a page is, by definition, an open window.""" self.starting = False diff --git a/tests/test_task_tools.py b/tests/test_task_tools.py new file mode 100644 index 0000000..74c54db --- /dev/null +++ b/tests/test_task_tools.py @@ -0,0 +1,174 @@ +"""drag, evaluate_readonly, read_download, save_deliverable and set_emulation on fakes. + +The real-browser half (that Chrome refuses a write under ``throwOnSideEffect``, that an +override survives a navigation and reaches a new tab, that a drag moves a slider) is +``scripts/verify_task_tools_e2e.py``. +""" + +from __future__ import annotations + +import json + +import pytest + +from lyra_browser.tools import tasks + + +async def test_drag_presses_on_the_source_and_releases_on_the_target(make_ctx, tools_of, page): + ctx = make_ctx() + drag = (await tools_of(ctx))["drag"] + + result = await drag(source="#card", target="#done") + + assert result["status"] == "ok" + moves = [c for c in page.calls if c[0] in ("hover", "mouse_down", "mouse_up")] + assert moves == [("hover", "#card"), ("mouse_down",), ("hover", "#done"), ("mouse_up",)] + rows = [json.loads(line) for line in ctx.config.audit_path.read_text().splitlines()] + assert any(r["tool"] == "drag" and r["args"].get("target") == "#done" for r in rows) + + +async def test_drag_checks_both_ends_before_touching_the_page(make_ctx, tools_of, page): + page.present = {"#card"} # the target does not exist + drag = (await tools_of(make_ctx()))["drag"] + + result = await drag(source="#card", target="#nowhere") + + assert result["status"] == "not_found" + assert not [c for c in page.calls if c[0] in ("mouse_down", "mouse_up")] + + +async def test_drag_off_site_needs_approval_and_does_nothing(make_ctx, tools_of, page): + drag = (await tools_of(make_ctx(on_site=False)))["drag"] + + result = await drag(source="#a", target="#b") + + assert result["status"] == "needs_approval" + assert not [c for c in page.calls if c[0] in ("mouse_down", "mouse_up")] + + +async def test_evaluate_readonly_asks_the_engine_to_refuse_side_effects(make_ctx, tools_of, page): + page.context.cdp_answers["Runtime.evaluate"] = {"result": {"type": "number", "value": 3}} + ev = (await tools_of(make_ctx()))["evaluate_readonly"] + + result = await ev(expression="document.querySelectorAll('li').length") + + assert result == { + "status": "ok", + "result": "3", + "truncated": False, + "type": "number", + "url": page.url, + } + method, params = page.context.cdp_calls[-1] + assert method == "Runtime.evaluate" and params["throwOnSideEffect"] is True + + +async def test_evaluate_readonly_reports_a_refused_write(make_ctx, tools_of, page): + page.context.cdp_answers["Runtime.evaluate"] = { + "result": {"type": "object"}, + "exceptionDetails": { + "text": "Uncaught", + "exception": {"description": "EvalError: Possible side-effect in debug-evaluate"}, + }, + } + ev = (await tools_of(make_ctx()))["evaluate_readonly"] + + result = await ev(expression="document.title = 'x'") + + assert result["status"] == "refused_side_effect" + + +async def test_evaluate_readonly_does_not_read_storage(make_ctx, tools_of, page): + ev = (await tools_of(make_ctx()))["evaluate_readonly"] + + for expression in ("document.cookie", "localStorage.getItem('t')", "window.sessionStorage"): + assert (await ev(expression=expression))["status"] == "refused_storage" + assert page.context.cdp_calls == [] + + +async def test_read_download_reads_only_what_was_saved(make_ctx, tools_of, tmp_path): + ctx = make_ctx() + saved = tmp_path / "downloads" / "report.csv" + saved.parent.mkdir(parents=True) + saved.write_text("a,b\n1,2\n") + binary = saved.with_name("logo.png") + binary.write_bytes(b"\x89PNG\r\n\x1a\n\x00\xff") + ctx.downloads._saved[ctx.downloads._session_key()] = [ + {"filename": "report.csv", "path": str(saved), "bytes": 8, "url_origin": "x"}, + {"filename": "logo.png", "path": str(binary), "bytes": 10, "url_origin": "x"}, + ] + read = (await tools_of(ctx))["read_download"] + + text = await read(filename="report.csv") + assert text["status"] == "ok" and text["text"] == "a,b\n1,2\n" and not text["truncated"] + cut = await read(filename=str(saved), max_chars=3) + assert cut["text"] == "a,b" and cut["truncated"] + image = await read(filename="logo.png") + assert image["binary"] is True and image["head_hex"].startswith("89504e47") + assert (await read(filename="/etc/passwd"))["status"] == "not_found" + + +async def test_save_deliverable_writes_a_plain_name_once(make_ctx, tools_of, tmp_path): + ctx = make_ctx() + save = (await tools_of(ctx))["save_deliverable"] + + first = await save(name="prices.csv", content="plan,price\nStudio,29\n") + assert first["status"] == "ok" + assert (tmp_path / "deliverables" / "prices.csv").read_text() == "plan,price\nStudio,29\n" + assert (await save(name="prices.csv", content="x"))["status"] == "exists" + assert (await save(name="prices.csv", content="x", overwrite=True))["status"] == "ok" + for bad in ("../escape.txt", "a/b.txt", ".hidden", "", "x" * 200): + assert (await save(name=bad, content="x"))["status"] == "invalid_argument" + assert (await save(name="big.txt", content="x" * 1_000_001))["status"] == "invalid_argument" + rows = [json.loads(line) for line in ctx.config.audit_path.read_text().splitlines()] + assert all("content" not in r.get("args", {}) for r in rows if r["tool"] == "save_deliverable") + + +async def test_set_emulation_overrides_and_grants_geolocation(make_ctx, tools_of, page): + emulate = (await tools_of(make_ctx()))["set_emulation"] + + result = await emulate( + latitude=52.52, longitude=13.405, locale="de-DE", timezone="Europe/Berlin" + ) + + assert result["status"] == "ok" + sent = dict(page.context.cdp_calls) + assert sent["Emulation.setGeolocationOverride"]["latitude"] == 52.52 + assert sent["Emulation.setLocaleOverride"] == {"locale": "de-DE"} + assert sent["Emulation.setTimezoneOverride"] == {"timezoneId": "Europe/Berlin"} + assert page.context.granted == [["geolocation"]] + + page.context.cdp_calls.clear() + cleared = await emulate(clear=True) + assert cleared["status"] == "ok" and cleared["emulation"] == {} + assert dict(page.context.cdp_calls)["Emulation.setLocaleOverride"] == {"locale": ""} + + +async def test_set_emulation_reaches_a_tab_opened_afterwards(make_ctx, tools_of, page): + import asyncio + + from conftest import FakePage + + ctx = make_ctx() + emulate = (await tools_of(ctx))["set_emulation"] + await emulate(locale="ko-KR") + popup = FakePage("https://start.example/popup") + for observer in ctx.session.page_observers: + observer(popup) + await asyncio.sleep(0) + await asyncio.sleep(0) + assert ("Emulation.setLocaleOverride", {"locale": "ko-KR"}) in popup.context.cdp_calls + + +@pytest.mark.parametrize( + "kwargs", + [{"latitude": 1.0}, {"latitude": 91.0, "longitude": 0.0}, {}], +) +async def test_set_emulation_refuses_incomplete_requests(make_ctx, tools_of, kwargs): + emulate = (await tools_of(make_ctx()))["set_emulation"] + assert (await emulate(**kwargs))["status"] == "invalid_argument" + + +def test_the_storage_names_are_matched_as_words(): + assert tasks._STORAGE_NAMES.search("document.cookie") + assert not tasks._STORAGE_NAMES.search("cookies_accepted_banner_count")