procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/web/tests/test_api.py

@@ -0,0 +1,330 @@
+"""The public Python API other tools import: open_session, run_steps, get_text,
+screenshot, save_session - all with an injected FakeDriver (no real browser)."""
+from __future__ import annotations
+
+import pytest
+
+from tools.web import api, sessions
+from tools.web.errors import SessionError, UsageError
+
+
+def _seed(name="linkedin"):
+    sessions.write_state(name, {"cookies": [{"name": "sid", "value": "v"}], "origins": []})
+
+
+def test_render_pdf_sessionless_writes_pdf(tmp_path, driver_factory):
+    out = tmp_path / "invoice.pdf"
+    res = api.render_pdf("<h1>hi</h1>", str(out), fmt="Letter",
+                         driver_factory=driver_factory)
+    d = driver_factory.built[0]
+    # session-less: no storageState, no user_data_dir, headless
+    assert d.init["storage_state"] is None and d.init["user_data_dir"] is None
+    assert d.init["headless"] is True
+    call = [kw for m, kw in d.calls if m == "render_pdf"][0]
+    assert call["html"] == "<h1>hi</h1>" and call["fmt"] == "Letter"
+    assert d.closed is True                      # browser always torn down
+    assert res["out"] == str(out) and res["bytes"] > 0
+    assert out.read_bytes().startswith(b"%PDF")
+
+
+def test_render_pdf_custom_sheet_passes_size_and_margin(tmp_path, driver_factory):
+    # A roll-up / poster needs an exact sheet, not a paper name.
+    out = tmp_path / "rollup.pdf"
+    api.render_pdf("<div>x</div>", str(out), width="1000mm", height="2000mm", margin="0",
+                   driver_factory=driver_factory)
+    call = [kw for m, kw in driver_factory.built[0].calls if m == "render_pdf"][0]
+    assert (call["width"], call["height"], call["margin"]) == ("1000mm", "2000mm", "0")
+
+
+def test_render_pdf_defaults_keep_paper_format(tmp_path, driver_factory):
+    out = tmp_path / "doc.pdf"
+    api.render_pdf("<p>x</p>", str(out), driver_factory=driver_factory)
+    call = [kw for m, kw in driver_factory.built[0].calls if m == "render_pdf"][0]
+    assert call["fmt"] == "A4" and call["width"] is None and call["margin"] is None
+
+
+def test_open_session_loads_state_and_starts(isolated_sessions, driver_factory):
+    _seed()
+    d = api.open_session("linkedin", url="https://x.test", driver_factory=driver_factory)
+    assert d.started is True
+    # storageState from the saved file was handed to the factory
+    assert d.init["storage_state"]["cookies"][0]["value"] == "v"
+    # url -> a goto happened
+    assert ("goto", {"url": "https://x.test", "timeout": None}) in d.calls
+
+
+def test_open_session_missing_raises(isolated_sessions, driver_factory):
+    with pytest.raises(SessionError):
+        api.open_session("nope", driver_factory=driver_factory)
+
+
+def test_open_session_auto_detects_persistent_profile(isolated_sessions, driver_factory):
+    # A `<name>.profile` dir (saved via --persistent) is used WITHOUT any
+    # storageState — and without the caller passing user_data_dir.
+    prof = sessions.profile_dir("gprof")
+    prof.mkdir()
+    (prof / "Default").write_text("x", encoding="utf-8")  # non-empty
+    d = api.open_session("gprof", driver_factory=driver_factory)
+    assert d.started is True
+    assert d.init["user_data_dir"] == str(prof)
+    assert d.init["storage_state"] is None
+
+
+def test_run_steps_end_to_end_and_closes(isolated_sessions, driver_factory):
+    _seed()
+    out = api.run_steps(
+        "linkedin",
+        [{"do": "extract_text", "selector": "h1", "name": "title"}],
+        url="https://x.test",
+        driver_factory=driver_factory,
+    )
+    assert out["session"] == "linkedin"
+    assert "title" in out["results"]
+    d = driver_factory.built[0]
+    assert d.closed is True  # always torn down
+
+
+def test_run_steps_headed_flag_threads_through(isolated_sessions, driver_factory):
+    _seed()
+    api.run_steps("linkedin", [], headless=False, driver_factory=driver_factory)
+    assert driver_factory.built[0].init["headless"] is False
+
+
+def test_get_text_with_wait_and_selector(isolated_sessions, driver_factory):
+    _seed()
+    out = api.get_text("linkedin", "https://x.test", selector="main",
+                       wait="#ready", driver_factory=driver_factory)
+    assert out["session"] == "linkedin"
+    assert out["selector"] == "main"
+    d = driver_factory.built[0]
+    methods = d.methods()
+    assert "wait_for" in methods and "extract_text" in methods
+    assert d.closed is True
+
+
+def test_screenshot_full_page_default(isolated_sessions, driver_factory):
+    _seed()
+    out = api.screenshot("linkedin", "https://x.test", "shot.png",
+                         driver_factory=driver_factory)
+    assert out["path"] == "shot.png"
+    shot = [kw for m, kw in driver_factory.built[0].calls if m == "screenshot"][0]
+    assert shot["full_page"] is True
+
+
+def test_save_session_writes_state_after_signal(isolated_sessions, driver_factory):
+    signalled = {"v": False}
+
+    def wait_for_signal():
+        signalled["v"] = True
+
+    out = api.save_session("newsite", "https://login.test",
+                           wait_for_signal=wait_for_signal,
+                           driver_factory=driver_factory)
+    assert signalled["v"] is True            # human signal was awaited
+    assert out["session"] == "newsite"
+    # storageState captured from the (headed) driver and persisted
+    assert sessions.exists("newsite")
+    saved = sessions.load_state("newsite")
+    assert saved["cookies"][0]["name"] == "sid"
+    # headed browser was requested
+    assert driver_factory.built[0].init["headless"] is False
+    assert driver_factory.built[0].closed is True
+
+
+def test_save_session_persistent_captures_cookie_sidecar(isolated_sessions, driver_factory):
+    """A persistent save snapshots live cookies (incl. session-scoped) to a
+    sidecar, because the on-disk profile won't persist them itself."""
+    out = api.save_session("ryv", "https://example.ryver.com",
+                           wait_for_signal=lambda: None, persistent=True,
+                           driver_factory=driver_factory)
+    assert out["persistent"] is True
+    assert out["cookies_saved"] == 1                 # FakeDriver returns one cookie
+    assert sessions.cookies_exist("ryv")
+    saved = sessions.load_cookies("ryv")
+    assert saved[0]["name"] == "sid" and saved[0]["expires"] == -1
+    # cookies captured AFTER the human signal and BEFORE close
+    methods = driver_factory.built[0].methods()
+    assert methods.index("get_cookies") < methods.index("close")
+
+
+def test_open_session_persistent_reinjects_cookies_before_navigation(isolated_sessions, driver_factory):
+    """Opening a persistent profile that has a cookie sidecar must re-inject the
+    cookies into the fresh context BEFORE navigating, so the first request is
+    authenticated."""
+    prof = sessions.profile_dir("ryv")
+    prof.mkdir()
+    (prof / "Default").write_text("x", encoding="utf-8")
+    sessions.write_cookies("ryv", [{"name": "sid", "value": "z",
+                                    "domain": ".ringhel.ryver.com", "path": "/",
+                                    "expires": -1}])
+    d = api.open_session("ryv", url="https://example.ryver.com",
+                         driver_factory=driver_factory)
+    assert d.injected_cookies and d.injected_cookies[0]["value"] == "z"
+    methods = d.methods()
+    assert methods.index("add_cookies") < methods.index("goto")  # inject, THEN navigate
+
+
+def test_open_session_persistent_without_sidecar_skips_injection(isolated_sessions, driver_factory):
+    """No sidecar -> no add_cookies call (back-compat for IndexedDB-auth
+    profiles like WhatsApp that never had one)."""
+    prof = sessions.profile_dir("wa")
+    prof.mkdir()
+    (prof / "Default").write_text("x", encoding="utf-8")
+    d = api.open_session("wa", url="https://web.whatsapp.com",
+                         driver_factory=driver_factory)
+    assert "add_cookies" not in d.methods()
+    assert d.injected_cookies == []
+
+
+def test_save_session_signal_order(isolated_sessions, driver_factory):
+    """storage_state must be captured AFTER the human signal, not before."""
+    order = []
+
+    def wait_for_signal():
+        order.append("signal")
+
+    # wrap the factory to record when storage_state is read
+    base = driver_factory
+
+    def factory(**kw):
+        d = base(**kw)
+        orig = d.storage_state
+
+        def traced():
+            order.append("capture")
+            return orig()
+        d.storage_state = traced
+        return d
+
+    api.save_session("ordered", "https://login.test",
+                     wait_for_signal=wait_for_signal, driver_factory=factory)
+    assert order == ["signal", "capture"]
+
+
+# --- non-stdin login wait (agent-driven save-session) -----------------------
+
+def test_save_session_wait_seconds_detects_login(isolated_sessions, driver_factory,
+                                                 monkeypatch):
+    """With --wait-seconds the browser is held open WITHOUT touching stdin, and
+    the wait ends as soon as the address bar leaves the login host."""
+    monkeypatch.setattr(api, "_POLL_SECONDS", 0)
+    monkeypatch.setattr(api, "_SETTLE_SECONDS", 0)
+
+    def boom():                       # stdin must never be consulted
+        raise AssertionError("save_session must not block on stdin")
+    monkeypatch.setattr(api, "_block_on_enter", boom)
+
+    out = api.save_session("goog", "https://drive.google.com/drive/my-drive",
+                           persistent=True, wait_seconds=30,
+                           wait_until_url_excludes="accounts.google.com",
+                           driver_factory=driver_factory)
+    assert out["waited_for"] == "url"
+    assert out["login_detected"] is True          # FakeDriver url is off the login host
+    assert out["final_url"] == "https://example.com/after"   # FakeDriver post-nav url
+
+
+def test_save_session_wait_seconds_reports_timeout(isolated_sessions, monkeypatch):
+    """Still on the login host when time runs out -> login_detected False, so a
+    half-authenticated save is never mistaken for success. This is the exact
+    case that silently produced a broken `google` session (see
+    WEB-AUTOMATION-NOTES.md)."""
+    from tools.web.tests.conftest import FakeDriver
+
+    monkeypatch.setattr(api, "_POLL_SECONDS", 0)
+    monkeypatch.setattr(api, "_SETTLE_SECONDS", 0)
+
+    def stuck_factory(**kwargs):
+        # never leaves the login host, however long we wait
+        return FakeDriver(url="https://accounts.google.com/signin", **kwargs)
+
+    out = api.save_session("goog2", "https://accounts.google.com/signin",
+                           persistent=True, wait_seconds=1,
+                           wait_until_url_excludes="accounts.google.com",
+                           driver_factory=stuck_factory)
+    assert out["login_detected"] is False
+    assert "final_url" not in out
+
+
+def test_save_session_rejects_nonpositive_wait(isolated_sessions, driver_factory):
+    with pytest.raises(UsageError):
+        api.save_session("goog3", "https://example.test", wait_seconds=0,
+                         driver_factory=driver_factory)
+
+
+# --- human-handoff hold (agent stages, human commits) ----------------------
+
+def _steps():
+    return [{"do": "fill", "selector": "#name", "text": "x"}]
+
+
+def test_run_hold_ends_early_when_selector_appears(isolated_sessions, driver_factory,
+                                                   monkeypatch):
+    """The hold exists so a human can click Submit. FakeDriver.wait_for always
+    resolves, i.e. the confirmation element is already there -> reason
+    'selector', completed True."""
+    monkeypatch.setattr(api, "_POLL_SECONDS", 0)
+
+    _seed()
+    out = api.run_steps("linkedin", _steps(), headless=False, hold_seconds=30,
+                        hold_until_selector="text=Thank",
+                        driver_factory=driver_factory)
+    assert out["hold"]["completed"] is True
+    assert out["hold"]["reason"] == "selector"
+
+
+def test_run_hold_ends_early_when_url_leaves_host(isolated_sessions, driver_factory,
+                                                  monkeypatch):
+    monkeypatch.setattr(api, "_POLL_SECONDS", 0)
+
+    _seed()
+    out = api.run_steps("linkedin", _steps(), headless=False, hold_seconds=30,
+                        hold_until_url_excludes="form.example.test",
+                        driver_factory=driver_factory)
+    assert out["hold"]["completed"] is True
+    assert out["hold"]["reason"] == "url"
+
+
+def test_run_hold_timeout_is_success_not_failure(isolated_sessions, monkeypatch):
+    """The regression this feature exists for: an idle human must NOT turn a
+    successful fill into a failed run. No raise, steps' results intact."""
+    from tools.web.tests.conftest import FakeDriver
+
+    monkeypatch.setattr(api, "_POLL_SECONDS", 0)
+
+    class NeverDriver(FakeDriver):
+        def wait_for(self, selector, *, timeout=None):
+            raise RuntimeError("selector never appears")
+
+    _seed()
+    out = api.run_steps("linkedin", _steps(), headless=False, hold_seconds=1,
+                        hold_until_selector="text=Thank",
+                        driver_factory=lambda **kw: NeverDriver(**kw))
+    assert out["hold"]["completed"] is False
+    assert out["hold"]["reason"] == "timeout"
+    assert out["hold"]["held_seconds"] >= 0
+    assert "results" in out          # the steps still ran
+
+
+def test_run_hold_requires_headed(isolated_sessions, driver_factory):
+    with pytest.raises(UsageError):
+        api.run_steps("linkedin", _steps(), headless=True, hold_seconds=30,
+                      driver_factory=driver_factory)
+
+
+def test_run_hold_rejects_nonpositive(isolated_sessions, driver_factory):
+    with pytest.raises(UsageError):
+        api.run_steps("linkedin", _steps(), headless=False, hold_seconds=0,
+                      driver_factory=driver_factory)
+
+
+def test_run_hold_conditions_require_hold_seconds(isolated_sessions, driver_factory):
+    with pytest.raises(UsageError):
+        api.run_steps("linkedin", _steps(), headless=False,
+                      hold_until_selector="text=Thank",
+                      driver_factory=driver_factory)
+
+
+def test_run_without_hold_has_no_hold_block(isolated_sessions, driver_factory):
+    _seed()
+    out = api.run_steps("linkedin", _steps(), driver_factory=driver_factory)
+    assert "hold" not in out

procesio_cli/tools/web/tests/test_archive.py

@@ -0,0 +1,190 @@
+"""Tests for `web archive-document`.
+
+The capture is evidence, so the properties that matter are not "did it write a
+file" but: the original is byte-identical to what the publisher served, the hash
+in the header is the hash of THAT file, the extraction never silently loses the
+document's text, and a date the document states about itself is reported rather
+than reconciled. Each test below pins one of those.
+
+No network: the fetch path is exercised through --file, and the stylesheet
+inliner is driven with a stubbed requests module.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+FRAMEWORK_ROOT = Path(__file__).resolve().parents[3]
+if str(FRAMEWORK_ROOT) not in sys.path:
+    sys.path.insert(0, str(FRAMEWORK_ROOT))
+
+from tools.web.handlers import archive  # noqa: E402
+from tools.web.errors import UsageError  # noqa: E402
+
+
+class _Args:
+    """Minimal stand-in for the parsed argparse namespace."""
+
+    def __init__(self, **kw):
+        defaults = dict(url=None, file=None, source_url=None, out_dir=None,
+                        name=None, title=None, timeout=5, no_self_contained=True)
+        defaults.update(kw)
+        for k, v in defaults.items():
+            setattr(self, k, v)
+
+
+HTML = b"""<html><head><title>Terms & Conditions | ACME</title>
+<link rel="stylesheet" href="/s.css"></head>
+<body><h1>Terms</h1><p>Last updated: 10 August 2021</p>
+<p>Client must not resell the Technology.</p>
+<script>var x=1;</script></body></html>"""
+
+
+def _run(tmp_path, **kw):
+    src = tmp_path / "in.html"
+    src.write_bytes(kw.pop("body", HTML))
+    return archive.archive_document(
+        _Args(file=str(src), out_dir=str(tmp_path / "out"), name="terms", **kw))
+
+
+def test_original_is_byte_identical_and_hash_matches_it(tmp_path):
+    """The stored original must equal the input byte for byte, and the reported
+    sha256 must be the hash of that file - not of the extraction, and not of a
+    re-serialised parse tree. This is the whole basis for comparing a later
+    fetch against this one."""
+    res = _run(tmp_path)
+    original = Path(res["files"]["original"])
+    assert original.read_bytes() == HTML
+    assert res["sha256"]["original"] == hashlib.sha256(HTML).hexdigest()
+
+
+def test_extraction_keeps_document_text_and_drops_only_script(tmp_path):
+    """Dropping a region to tidy the extraction risks dropping a clause that
+    happens to sit in it, so only script/style are removed."""
+    res = _run(tmp_path)
+    text = Path(res["files"]["extraction"]).read_text(encoding="utf-8")
+    assert "Client must not resell the Technology." in text
+    assert "var x=1" not in text
+
+
+def test_provenance_header_carries_source_and_hash(tmp_path):
+    """An extraction that travels without its source and fetch date becomes an
+    unattributable quote the first time someone pastes it into a brief."""
+    res = _run(tmp_path, source_url="https://example.com/terms")
+    header = Path(res["files"]["extraction"]).read_text(encoding="utf-8")[:1200]
+    assert "https://example.com/terms" in header
+    assert res["sha256"]["original"] in header
+    assert "Fetched at (UTC)" in header
+
+
+def test_title_read_from_the_document_unless_overridden(tmp_path):
+    assert _run(tmp_path)["title"] == "Terms & Conditions | ACME"
+    assert _run(tmp_path, title="Pinned")["title"] == "Pinned"
+
+
+def test_self_contained_copy_is_written_only_when_asked(tmp_path):
+    assert "self_contained" not in _run(tmp_path)["files"]
+
+
+def test_date_candidates_are_reported_not_reconciled(tmp_path):
+    """Two different dates on one document is a finding about the document. The
+    action must surface both rather than pick one."""
+    body = (b"<html><body><p>Last updated: 10 August 2021</p>"
+            b"<p>Effective 19/12/2023</p></body></html>")
+    res = _run(tmp_path, body=body)
+    dates = [d["date"] for d in res["document_date_candidates"]]
+    assert "10 August 2021" in dates
+    assert "19/12/2023" in dates
+
+
+def test_a_bare_date_with_no_version_context_is_not_claimed_as_the_date(tmp_path):
+    """A date mentioned in passing is not the document's own date. Only dates
+    near version wording are reported, so the caller is not handed a false
+    'this document is dated X'."""
+    body = b"<html><body><p>The contract began on 01/01/2020 in Bucharest.</p></body></html>"
+    assert _run(tmp_path, body=body)["document_date_candidates"] == []
+
+
+def test_pdf_is_detected_by_magic_bytes_not_extension(tmp_path):
+    """A PDF served without a .pdf path or content-type must still be stored as
+    a .pdf and text-extracted as one."""
+    src = tmp_path / "doc.bin"
+    src.write_bytes(b"%PDF-1.4\n% not a real pdf")
+    res = archive.archive_document(
+        _Args(file=str(src), out_dir=str(tmp_path / "out"), name="agreement"))
+    assert res["kind"] == "pdf"
+    assert Path(res["files"]["original"]).suffix == ".pdf"
+
+
+@pytest.mark.parametrize("kw", [
+    dict(),                                            # neither url nor file
+    dict(url="https://x/y", file="z.html"),            # both
+])
+def test_exactly_one_source_is_required(tmp_path, kw):
+    with pytest.raises(UsageError):
+        archive.archive_document(
+            _Args(out_dir=str(tmp_path), name="n", **kw))
+
+
+def test_name_must_not_escape_the_out_dir(tmp_path):
+    """--name becomes a folder; a path separator in it would write outside the
+    collection."""
+    for bad in ("../evil", "a/b", "a\\b", "  "):
+        with pytest.raises(UsageError):
+            archive.archive_document(
+                _Args(file=str(tmp_path), out_dir=str(tmp_path), name=bad))
+
+
+def test_stylesheets_are_inlined_with_urls_made_absolute(tmp_path, monkeypatch):
+    """The inlined copy has to render offline, and url() inside a stylesheet is
+    relative to the STYLESHEET, not the page - left alone it loses its fonts."""
+    class _Resp:
+        status_code = 200
+        text = "body{background:url('img/bg.png')}"
+
+    monkeypatch.setattr("requests.get", lambda *a, **k: _Resp())
+    soup = archive._soup(HTML)
+    assert archive._inline_stylesheets(soup, "https://example.com/terms", 5) == 1
+    out = str(soup)
+    assert "inlined from https://example.com/s.css" in out
+    assert "url('https://example.com/img/bg.png')" in out
+    assert "<link" not in out
+
+
+def test_a_failing_stylesheet_degrades_but_never_aborts_the_capture(tmp_path, monkeypatch):
+    """Losing a stylesheet must not cost us the document."""
+    def _boom(*a, **k):
+        raise RuntimeError("network down")
+
+    monkeypatch.setattr("requests.get", _boom)
+    soup = archive._soup(HTML)
+    assert archive._inline_stylesheets(soup, "https://example.com/t", 5) == 0
+
+
+def test_manifest_declares_every_runtime_action(tmp_path):
+    """Manifest is the source of truth (Hard rule 3): an action reachable at
+    runtime but absent from tool.yaml is a contract that drifted."""
+    import yaml
+    from tools.web import main as web_main
+    manifest = yaml.safe_load((FRAMEWORK_ROOT / "tools/web/tool.yaml").read_text(encoding="utf-8"))
+    declared = {a["name"] for a in manifest["actions"]}
+    assert "archive-document" in declared
+    assert set(web_main.ACTIONS) == declared
+
+
+def test_cli_emits_one_json_object_on_stdout(tmp_path):
+    """JSON in, JSON out (Hard rule 2)."""
+    src = tmp_path / "in.html"
+    src.write_bytes(HTML)
+    proc = subprocess.run(
+        [sys.executable, str(FRAMEWORK_ROOT / "scripts/run-tool.py"), "web",
+         "archive-document", "--file", str(src), "--out-dir",
+         str(tmp_path / "out"), "--name", "terms"],
+        capture_output=True, text=True, cwd=str(FRAMEWORK_ROOT))
+    assert proc.returncode == 0, proc.stderr
+    assert json.loads(proc.stdout)["name"] == "terms"

procesio_cli/tools/web/tests/test_brokered.py

@@ -0,0 +1,138 @@
+"""web-tool broker routing tests: generic run/get-text/screenshot against a
+broker-OWNED session are translated to a web-steps op on the owning broker;
+unowned sessions, --direct, --channel and injected factories stay in-process.
+save-session/delete-session stop the owning broker first. No real broker is
+ever spawned (conftest autouse sets all *_DIRECT; tests stub the lib client)."""
+from __future__ import annotations
+
+import pytest
+
+from tools._lib.webserialize import client as ws_client
+from tools.web import brokered
+from tools.web.main import dispatch
+
+
+def _unroute(monkeypatch):
+    for env in ("WHATSAPP_DIRECT", "RYVER_WEB_DIRECT",
+                "FGO_WEB_DIRECT", "MIRRO_DIRECT"):
+        monkeypatch.delenv(env, raising=False)
+
+
+@pytest.fixture
+def captured_web_steps(monkeypatch):
+    """Stub the lib's web_steps; records the submission and returns a canned
+    run_steps-shaped result tagged as served by the broker."""
+    seen = {}
+
+    def fake(cfg, session, steps, *, url=None, headless=True,
+             read_timeout=None, dispatch_direct=None):
+        seen.update(tool=cfg.tool, session=session, steps=steps,
+                    url=url, headless=headless)
+        return {"session": session,
+                "results": {"text": "PAGE TEXT"}, "screenshots": ["x.png"],
+                "final_url": "https://final/", "diagnostics": {},
+                "via": "service", "service_queue_wait_ms": 3}
+
+    monkeypatch.setattr(ws_client, "web_steps", fake)
+    return seen
+
+
+def test_run_routes_to_owning_broker(monkeypatch, captured_web_steps):
+    _unroute(monkeypatch)
+    out = dispatch("run", ["--session", "ryver", "--url", "https://r/",
+                           "--actions", '[{"do": "extract_text", "name": "t"}]'])
+    assert captured_web_steps["tool"] == "ryver-web"
+    assert captured_web_steps["session"] == "ryver"
+    assert captured_web_steps["steps"] == [{"do": "extract_text", "name": "t"}]
+    assert out["via"] == "service"
+
+
+def test_get_text_translation_and_reshape(monkeypatch, captured_web_steps):
+    _unroute(monkeypatch)
+    out = dispatch("get-text", ["--session", "whatsapp", "--url", "https://w/",
+                                "--selector", "#main", "--wait", "#pane-side"])
+    assert captured_web_steps["steps"] == [
+        {"do": "wait_for", "selector": "#pane-side"},
+        {"do": "extract_text", "name": "text", "selector": "#main"},
+    ]
+    assert out["text"] == "PAGE TEXT" and out["session"] == "whatsapp"
+    assert out["final_url"] == "https://final/" and out["via"] == "service"
+
+
+def test_screenshot_translation(monkeypatch, captured_web_steps, tmp_path):
+    _unroute(monkeypatch)
+    target = str(tmp_path / "shot.png")
+    out = dispatch("screenshot", ["--session", "fgo", "--url", "https://f/",
+                                  "--out", target, "--viewport-only"])
+    assert captured_web_steps["steps"] == [
+        {"do": "screenshot", "path": target, "full_page": False}]
+    assert out["path"] == target and out["via"] == "service"
+
+
+def test_unowned_session_stays_direct(monkeypatch, driver_factory, isolated_sessions):
+    _unroute(monkeypatch)
+    monkeypatch.setattr(ws_client, "web_steps",
+                        lambda *a, **k: pytest.fail("unowned must not route"))
+    (isolated_sessions / "google.json").write_text('{"cookies": [], "origins": []}',
+                                                   encoding="utf-8")
+    out = dispatch("get-text", ["--session", "google", "--url", "https://g/"],
+                   driver_factory=driver_factory)
+    assert "text" in out
+
+
+def test_direct_and_channel_and_env_stay_local(monkeypatch):
+    _unroute(monkeypatch)
+    from types import SimpleNamespace as NS
+    base = dict(direct=False, channel=None, session="whatsapp")
+    assert brokered.eligible(NS(**base), driver_factory=None,
+                             allow_service=True) is not None
+    assert brokered.eligible(NS(**{**base, "direct": True}),
+                             driver_factory=None, allow_service=True) is None
+    assert brokered.eligible(NS(**{**base, "channel": "chrome"}),
+                             driver_factory=None, allow_service=True) is None
+    assert brokered.eligible(NS(**base), driver_factory=object(),
+                             allow_service=True) is None
+    assert brokered.eligible(NS(**{**base, "session": "google"}),
+                             driver_factory=None, allow_service=True) is None
+    monkeypatch.setenv("WHATSAPP_DIRECT", "1")   # owning tool's kill switch
+    assert brokered.eligible(NS(**base), driver_factory=None,
+                             allow_service=True) is None
+    monkeypatch.delenv("WHATSAPP_DIRECT")
+    monkeypatch.setenv("WHATSAPP_SERVICE_WORKER", "1")  # inside the worker
+    assert brokered.eligible(NS(**base), driver_factory=None,
+                             allow_service=True) is None
+
+
+def test_fallback_result_is_not_reshaped(monkeypatch):
+    """When the broker can't start, web_steps falls back to the DIRECT handler
+    whose result is already final — route() must return it untouched."""
+    _unroute(monkeypatch)
+    monkeypatch.setattr(ws_client, "ensure_running", lambda cfg, **k: None)
+    from types import SimpleNamespace as NS
+    parsed = NS(session="ryver", url="https://r/", selector=None, wait=None,
+                headed=False, direct=False, channel=None)
+    cfg = brokered.eligible(parsed, driver_factory=None, allow_service=True)
+    result = brokered.route(cfg, "get-text", parsed,
+                            dispatch_direct=lambda: {"text": "DIRECT",
+                                                     "session": "ryver"})
+    assert result["text"] == "DIRECT" and result["via"] == "direct-fallback"
+
+
+def test_save_session_stops_owning_broker(monkeypatch, isolated_sessions):
+    from tools.web.handlers import sessmgmt
+    stopped = {}
+    monkeypatch.setattr(ws_client, "ping", lambda cfg, **k: {"pong": True})
+    monkeypatch.setattr(ws_client, "stop",
+                        lambda cfg, **k: stopped.setdefault("tool", cfg.tool) or True)
+    monkeypatch.setattr(sessmgmt.api, "save_session",
+                        lambda name, url, channel=None, persistent=False, **kw:
+                        {"session": name, "url": url, "persistent": persistent})
+    from types import SimpleNamespace as NS
+    out = sessmgmt.save_session(NS(name="whatsapp", url="https://w/",
+                                   channel=None, persistent=True))
+    assert stopped["tool"] == "whatsapp-personal"
+    assert out["broker_stopped"] == "whatsapp-personal"
+
+    out = sessmgmt.save_session(NS(name="google", url="https://g/",
+                                   channel=None, persistent=False))
+    assert "broker_stopped" not in out