browserwright 0.8.2__tar.gz → 0.9.1__tar.gz

{browserwright-0.8.2/src/browserwright.egg-info → browserwright-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.8.2
+Version: 0.9.1
 Summary: Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends).
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.11
@@ -10,6 +10,7 @@ Requires-Dist: pillow==12.2.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: playwright>=1.60.0
 Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: html-to-markdown<4,>=3.10.6
 Provides-Extra: ux
 Requires-Dist: rich>=13; extra == "ux"
 Dynamic: license-file

{browserwright-0.8.2 → browserwright-0.9.1}/pyproject.toml

@@ -15,7 +15,7 @@ name = "browserwright"
 # stamping regex is `^(version\s*=\s*)["'][^"']+["']\s*$` and CI aborts unless
 # it matches exactly once. `tests/skill/test_release_versioning.py` enforces all
 # of that before a tag is ever pushed. See RELEASING.md.
-version = "0.8.2"
+version = "0.9.1"
 description = "Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends)."
 requires-python = ">=3.11"
 license = "AGPL-3.0-only"
@@ -30,6 +30,26 @@ dependencies = [
     # daemon-resolved Chrome and does not need Playwright's bundled browser.
     "playwright>=1.60.0",
     "pyyaml>=6.0.3",
+    # HTML -> Markdown for the `read_markdown()` content view (ADR-0006/0007).
+    # Rust core + PyO3, and it pulls in NOTHING transitively — which is why it
+    # beat `markdownify` (bs4 + soupsieve) and `trafilatura` (lxml + a 32 MB
+    # babel locale tree) here. It is also the only converter measured that
+    # carries `class="language-*"` into a fenced ```lang block and keeps
+    # `rowspan` cells, both of which matter on the documentation pages this
+    # view exists to read.
+    #
+    # We deliberately track upstream rather than freeze: the project is running
+    # a systematic markdown-fidelity campaign (its own "Phase Z..HH" feat
+    # series) that keeps improving exactly what we depend on. The safety net for
+    # that is `tests/skill/test_markdown_golden.py` — golden files turn an
+    # upstream byte-level output change into a CI failure instead of a silent
+    # shift in what every agent reads. ADR-0007 makes those tests a precondition
+    # of this `>=`, not an optional extra.
+    #
+    # The `<4` cap is not conservatism about features: 3.0.0 removed the v1
+    # `convert_to_markdown()` entry point outright, so a major bump can break us
+    # at import time. Raise it deliberately, with the golden files as the diff.
+    "html-to-markdown>=3.10.6,<4",
 ]
 
 [project.optional-dependencies]
@@ -58,6 +78,11 @@ browserwright = [
     "site_skills_starter/**/*.md",
     "site_skills_starter/**/*.py",
     "skill_runtime.md",
+    # Vendored Mozilla Readability, injected as SOURCE TEXT via page.evaluate
+    # (add_script_tag is blocked by page CSP; page.evaluate is not). It has to
+    # ship as a real file for that reason — see repl/vendor/README.md.
+    "repl/vendor/*.js",
+    "repl/vendor/*.md",
 ]
 
 [tool.setuptools.exclude-package-data]
@@ -69,6 +94,7 @@ asyncio_mode = "auto"
 testpaths = ["tests"]
 markers = [
     "real_chrome: end-to-end test that launches a real Chrome + extension (skipped unless explicitly selected)",
+    "launchd: loads throwaway LaunchAgents to measure real launchd behaviour; macOS-only, skipped unless explicitly selected (issue #57)",
 ]
 
 # Lint config. `select` is explicit on purpose: ruff's *default* rule set grew

{browserwright-0.8.2 → browserwright-0.9.1}/src/browserwright/__init__.py

@@ -42,6 +42,7 @@ from .errors import (  # noqa: F401
     NeedsUserConfirm,
     NetworkError,
     PageLoadFailed,
+    UnsupportedContentType,
 )
 from .primitives.discovery_api import (  # noqa: F401
     list_site_skills,
@@ -69,7 +70,7 @@ EXPORTS = [
     # errors
     "BrowserwrightError", "PageLoadFailed", "ElementNotFound", "AuthWall",
     "Captcha", "NetworkError", "DaemonUnavailable", "CDPError",
-    "NeedsUserConfirm",
+    "NeedsUserConfirm", "UnsupportedContentType",
 ]
 
 __all__ = EXPORTS

{browserwright-0.8.2 → browserwright-0.9.1}/src/browserwright/_executor/process.py

@@ -40,6 +40,7 @@ from collections.abc import Iterator
 from contextlib import contextmanager, redirect_stdout
 from typing import Any
 
+from .._text import spill_text, truncate_hard
 from ..errors import BrowserwrightError, serialize
 from .protocol import (
     MAX_TEXT_CHARS,
@@ -58,6 +59,92 @@ from .protocol import (
 _COLD_START_CONNECT_ATTEMPTS = 13
 _COLD_START_CONNECT_BACKOFF_S = 0.75
 
+# `_bw_warn` is callable from a loop, so the warnings LIST needs a bound as much
+# as each entry does. The overflow is folded into one final notice rather than
+# dropped silently.
+MAX_WARNINGS = 100
+
+
+def _cut_notice(what: str, path: str | None) -> str:
+    """The out-of-band line that makes a cut recoverable rather than lossy."""
+    if path:
+        return (
+            f"{what} truncated to {MAX_TEXT_CHARS} chars; the full text is at "
+            f"{path}"
+        )
+    return (
+        f"{what} truncated to {MAX_TEXT_CHARS} chars; the full text could not "
+        f"be written to disk, so re-run producing less output"
+    )
+
+
+def _cap_text(value: str, *, prefix: str) -> tuple[str, bool, str | None]:
+    """Bound one text channel. Returns (value, was_truncated, full_text_path).
+
+    Whole-line aware (``truncate_hard``): the transport must never be the layer
+    that severs a `[ref=eN]` a producer took care to keep intact, because the
+    severed token is not merely corrupt — `[ref=e2` cut from `[ref=e291]` is a
+    VALID ref for a different live element, so acting on it fails silently.
+
+    The bound is about what an agent can READ, so the untruncated value is
+    spilled to disk rather than dropped (ADR-0007 §5) and the path is reported
+    out-of-band by the caller. ``None`` means the spill itself failed, which
+    shortens the result but never fails the call.
+    """
+    if len(value) <= MAX_TEXT_CHARS:
+        return value, False, None
+    return truncate_hard(value, MAX_TEXT_CHARS), True, spill_text(
+        value, prefix=prefix
+    )
+
+
+def _cap_warnings(warnings: list[str]) -> tuple[list[str], bool]:
+    """Bound both the number of warnings and the length of each one.
+
+    Deliberately NOT via ``_cap_text``: warnings are the out-of-band METADATA
+    channel, not content, so they are truncated but never spilled. Routing them
+    through ``_cap_text`` writes one file per over-long warning — which buries
+    the very spill paths these lines exist to carry, and accumulates fast
+    because a warning loop produces up to MAX_WARNINGS of them per call.
+    """
+    capped = [
+        truncate_hard(str(w), MAX_TEXT_CHARS) for w in warnings[:MAX_WARNINGS]
+    ]
+    dropped = len(warnings) - len(capped)
+    if dropped > 0:
+        capped.append(f"… {dropped} further warning(s) suppressed")
+    return capped, dropped > 0
+
+
+def _cap_task_result_json(raw: str | None) -> tuple[str | None, bool]:
+    """Bound the task result JSON WITHOUT ever emitting invalid JSON.
+
+    Truncating a JSON document yields one that fails
+    ``ExecuteResponse.from_dict``'s own ``json.loads`` validation, which the
+    client reports as a malformed response and answers by REAPING the executor
+    — losing the session's persistent ``state`` over an oversized payload, a
+    strictly worse outcome than the payload itself. So an over-budget result is
+    replaced by a valid marker object carrying the path to the full JSON, which
+    a caller that actually wants it can read.
+    """
+    if raw is None or len(raw) <= MAX_TEXT_CHARS:
+        return raw, False
+    path = spill_text(raw, prefix="task-result")
+    marker: dict[str, Any] = {
+        "_browserwright_truncated": True,
+        "original_size": len(raw),
+        "full_result_path": path,
+    }
+    marker["reason"] = (
+        f"task result exceeded the {MAX_TEXT_CHARS}-char response bound; "
+        + (
+            f"the full JSON is at {path}"
+            if path
+            else "the full JSON could not be written to disk"
+        )
+    )
+    return json.dumps(marker), True
+
 
 @contextmanager
 def _request_environment(env: dict[str, str]) -> Iterator[None]:
@@ -83,11 +170,15 @@ def _request_environment(env: dict[str, str]) -> Iterator[None]:
 
 
 class _LivePageHolder:
-    """Adapts a live Playwright ``page`` to the ``.page`` attribute
-    ``snapshot.make_snapshot`` expects (it was written against the lazy
-    ``PlaywrightHandle``). We rebind ``.page`` whenever the worker re-binds the
-    session tab (cold-start / future ``reset()``), so ``snapshot()`` always
-    observes the executor's current live page."""
+    """Adapts a live Playwright ``page`` to the ``.page`` attribute the **view**
+    factories expect (``snapshot.make_snapshot`` / ``markdown.make_read_markdown``
+    were both written against the lazy ``PlaywrightHandle``). We rebind ``.page``
+    whenever the worker re-binds the session tab (cold-start / target change /
+    future ``reset()``), so every view observes the executor's current live page.
+
+    One holder serves ALL views on purpose: a second holder is a second thing to
+    remember to rebind, which is exactly how ``read_markdown`` shipped bound to a
+    handle nobody was updating (issue #59)."""
 
     def __init__(self) -> None:
         self.page: Any = None
@@ -138,7 +229,9 @@ class _Worker:
         self._facade_death_handler: Any = None
         # Persistent per-session state, injected by reference each call (Fork 5).
         self._state: dict[str, Any] = {}
-        self._snapshot_holder = _LivePageHolder()
+        # One live-page holder shared by every injected view (snapshot /
+        # read_markdown). Rebound wherever `self._page` is.
+        self._live_page_holder = _LivePageHolder()
         self._snapshot: Any = None
         # Per-call warnings/screenshots the running code can append to via the
         # injected `_bw_warn` / screenshot helpers. Reset at the start of each
@@ -351,8 +444,14 @@ class _Worker:
         self._context = ph.context_for_browser(self._browser)
         self._page = ph.bind_current_page(self._context, sess)
         self._page_target_id = sess.current_target_id
-        self._snapshot_holder.page = self._page
-        self._snapshot = make_snapshot(self._snapshot_holder)
+        self._live_page_holder.page = self._page
+        self._snapshot = make_snapshot(
+            self._live_page_holder,
+            # Late-bound on purpose: `_call_warnings` is REPLACED each
+            # call, so a bound `.append` captured here would append into
+            # the previous call's list and the notice would vanish.
+            warn=lambda m: self._call_warnings.append(m),
+        )
         self._arm_facade_death()
         # Issue #21: the live page must follow the session's current target
         # (``session_runtime.bind_target`` / ``open_session_tab`` /
@@ -408,8 +507,14 @@ class _Worker:
             return
         self._page = page
         self._page_target_id = sess.current_target_id
-        self._snapshot_holder.page = page
-        self._snapshot = make_snapshot(self._snapshot_holder)
+        self._live_page_holder.page = page
+        self._snapshot = make_snapshot(
+            self._live_page_holder,
+            # Late-bound on purpose: `_call_warnings` is REPLACED each
+            # call, so a bound `.append` captured here would append into
+            # the previous call's list and the notice would vanish.
+            warn=lambda m: self._call_warnings.append(m),
+        )
         # Same-call visibility: swap `page` inside the RUNNING heredoc's
         # globals so statements after switch_tab() see the new page.
         if self._active_globals is not None:
@@ -628,23 +733,52 @@ class _Worker:
         terminal_reason: str | None = None,
         task_result_json: str | None = None,
     ) -> ExecuteResponse:
-        """Assemble the response: cap the console at ``MAX_TEXT_CHARS`` and
-        attach the warnings/screenshots collected during the call."""
-        console = buf.getvalue()
-        truncated = False
-        if len(console) > MAX_TEXT_CHARS:
-            console = console[:MAX_TEXT_CHARS] + "\n… [truncated]"
-            truncated = True
+        """Assemble the response with EVERY text channel bounded, and attach the
+        warnings/screenshots collected during the call.
+
+        All four text channels are capped here, not just ``console``. An
+        expression-valued last statement is an entirely ordinary thing for an
+        agent to write, and an uncapped ``return_value`` big enough to exceed
+        ``protocol._MAX_FRAME`` does not merely ship megabytes: the client reads
+        it as a transport error and reaps this executor, taking the session's
+        live ``page`` and persistent ``state`` with it. Bounding the response by
+        construction is what makes that unreachable.
+        """
+        console, console_cut, console_path = _cap_text(
+            buf.getvalue(), prefix="console"
+        )
+        rv_cut, rv_path = False, None
+        if return_value is not None:
+            return_value, rv_cut, rv_path = _cap_text(
+                return_value, prefix="return-value"
+            )
+        task_result_json, task_cut = _cap_task_result_json(task_result_json)
+
+        raw_warnings = (
+            list(self._call_warnings) if warnings is None else list(warnings)
+        )
+        # The cut is reported out-of-band (ADR-0007 §5): stdout is content,
+        # warnings are metadata. Without this the agent sees a short payload and
+        # has no way to tell it was ever longer, nor where the rest went.
+        if console_cut:
+            raw_warnings.append(_cut_notice("output", console_path))
+        if rv_cut:
+            raw_warnings.append(_cut_notice("[return value]", rv_path))
+        if task_cut:
+            raw_warnings.append(
+                f"task result exceeded the {MAX_TEXT_CHARS}-char response bound "
+                f"and was replaced by a marker; use --output json to read it"
+            )
+        capped_warnings, warn_cut = _cap_warnings(raw_warnings)
+
         return ExecuteResponse(
             console=console,
             return_value=return_value,
             error=error,
             exit_code=exit_code,
-            warnings=(
-                list(self._call_warnings) if warnings is None else list(warnings)
-            ),
+            warnings=capped_warnings,
             screenshots=list(self._call_screenshots),
-            truncated=truncated,
+            truncated=console_cut or rv_cut or warn_cut or task_cut,
             terminal_reason=terminal_reason,
             task_result_json=task_result_json,
         )
@@ -680,25 +814,44 @@ class _Worker:
         )
 
     def _build_globals(self) -> dict[str, Any]:
-        """The exec namespace: the Phase C surface, but with ``page`` /
-        ``context`` replaced by the LIVE held objects, ``state`` injected by
-        reference (persists across calls — Fork 5), and ``snapshot`` rebound to
-        the live page.
+        """The exec namespace: the Phase C surface with every lazy name replaced
+        by this executor's live equivalent.
 
         We reuse ``_namespace.build_globals()`` so the agent helper layer +
-        EXPORTS stay identical to the heredoc, then OVERWRITE the lazy proxies
-        with live objects. The handle the lazy build injected
-        (``__bw_playwright_handle__``) is dropped — the executor owns teardown,
-        not the per-call namespace."""
+        EXPORTS stay identical to the heredoc, and hand it
+        :meth:`_bind_live_surface` as its live-surface hook so the swap lands
+        *before* the agent helper layer loads (issue #59)."""
         from ..repl import _namespace
 
-        g = _namespace.build_globals()
+        return _namespace.build_globals(self._bind_live_surface)
+
+    def _bind_live_surface(self, g: dict[str, Any]) -> None:
+        """Replace the lazily-bound namespace entries with the live ones.
+
+        Everything ``_namespace.build_globals`` binds to its lazy
+        ``PlaywrightHandle`` must be listed here. Resolving that handle on the
+        worker thread re-enters ``sync_playwright()`` inside the executor's
+        running asyncio loop and raises "Sync API inside the asyncio loop" —
+        which is what shipped for ``read_markdown`` (issue #59). The handle
+        itself is dropped: the executor owns teardown, not the per-call
+        namespace.
+
+        Called by ``build_globals`` BEFORE ``_load_agent_helpers``, so the
+        helper modules are seeded from the live surface too.
+        """
+        from ..repl.markdown import make_read_markdown
+
         g.pop("__bw_playwright_handle__", None)
         g["page"] = self._page
         g["context"] = self._context
         g["state"] = self._state  # same dict object each call → persistent
         if self._snapshot is not None:
             g["snapshot"] = self._snapshot
+        # The other view. Bound to the shared live-page holder (so it follows a
+        # mid-call target change exactly like `snapshot`), and handed THIS call's
+        # globals so its notes find the `_bw_warn` channel injected just below —
+        # `make_read_markdown` reads the namespace lazily for that reason.
+        g["read_markdown"] = make_read_markdown(self._live_page_holder, g)
         # Task invocations inside inline code borrow the same resident surface;
         # never let the public task runner allocate a second Playwright handle.
         g["run_task"] = self._run_task_on_live_surface
@@ -710,7 +863,6 @@ class _Worker:
         # `[WARNING]` line or a screenshot path back through the response.
         g["_bw_warn"] = self._call_warnings.append
         g["_bw_record_screenshot"] = self._record_screenshot
-        return g
 
     def _record_screenshot(self, path: str, **meta: Any) -> str:
         """Register a screenshot the heredoc captured so its path surfaces in

{browserwright-0.8.2 → browserwright-0.9.1}/src/browserwright/_executor/protocol.py

@@ -21,6 +21,8 @@ import struct
 from dataclasses import dataclass, field
 from typing import Any
 
+from .._text import MAX_TEXT_CHARS as _MAX_TEXT_CHARS
+
 # Default per-call timeout (ms). Playwriter defaults to 10000ms, but real page
 # ops (cold navigation + network settle) can legitimately take longer, so we
 # pick a more generous default. It is deliberately bounded WELL UNDER any
@@ -28,11 +30,14 @@ from typing import Any
 # so a slow-but-legitimate call never trips idle reclamation mid-flight.
 DEFAULT_TIMEOUT_MS = 90000
 
-# Cap on the rendered text block (console + return value), mirroring
-# playwriter's ~10000-char truncation. Whole-line aware truncation lives in
-# `snapshot._truncate_lines`; here we cap the console blob so a runaway print
-# loop can't ship megabytes back to the agent.
-MAX_TEXT_CHARS = 10000
+# Cap on EVERY text channel of the response — console, return value, warnings
+# and the task result JSON — so a runaway print loop, or an equally ordinary
+# expression-valued last statement, can't ship megabytes back to the agent.
+# Re-exported from `_text` because the producers (`repl/snapshot.py`,
+# `repl/markdown.py`) derive their own budgets from it and must not import the
+# transport to do so; `process._finish` applies it via `_text.truncate_hard`,
+# which prefers whole lines and marks the cut when it cannot keep one.
+MAX_TEXT_CHARS = _MAX_TEXT_CHARS
 TERMINAL_DEADLINE_EXCEEDED = "deadline_exceeded"
 TERMINAL_RESET_REQUESTED = "reset_requested"
 TERMINAL_REASONS = frozenset(
@@ -185,7 +190,9 @@ class ExecuteResponse:
       - ``screenshots``: list of ``{"path": str, ...}`` blocks for any image the
         heredoc captured — path-based (the executor and client share a
         filesystem), so the (possibly large) bytes never ride the wire.
-      - ``truncated``: True when the text block was capped at ``MAX_TEXT_CHARS``.
+      - ``truncated``: True when ANY text channel was capped at
+        ``MAX_TEXT_CHARS`` — console, return value, warnings or task result.
+        Which one it was is said in ``warnings``, the out-of-band channel.
       - ``error``: ``errors.serialize(exc)`` (or None on success), WITH a
         ``traceback`` key for generic exceptions so a shipped heredoc surfaces
         the same traceback the in-process path writes.

browserwright-0.9.1/src/browserwright/_text.py

@@ -0,0 +1,195 @@
+"""Text budgets and the two truncators that enforce them.
+
+Zero-dependency on purpose: both the executor transport (`_executor/protocol.py`,
+`_executor/process.py`) and the content producers (`repl/snapshot.py`,
+`repl/markdown.py`, `cli.py`) import from here, and the producers must not drag
+Playwright into the transport's import graph.
+
+Two truncators, because there are two genuinely different jobs
+--------------------------------------------------------------
+A producer promises **line integrity**: cutting an aria snapshot mid-line yields
+`[ref=e2` where the real token was `[ref=e291]` — a ref that is not merely
+corrupt but *well-formed for a different live element*, so acting on it fails
+silently. Same reason a Markdown cut mid-line yields a broken
+`[text](http://…` link. For a producer, overflowing a soft budget by one line is
+strictly better than emitting a partial ref, so `truncate_lines` keeps the first
+line whole even when it alone exceeds the budget.
+
+The transport promises a **bound**. Its whole reason to exist is that a runaway
+`print('x' * 5_000_000)` must not ship megabytes to the agent — and that payload
+is ONE line with no newlines, so the producer's "keep the first line whole"
+fallback would return 5,000,014 characters for a 10,000 budget. A soft
+truncator cannot serve as a hard cap. `truncate_hard` therefore drops whole
+lines wherever it can and cuts mid-line only when a single line still overflows,
+where it says so in the marker so a severed ref is at least VISIBLE rather than
+silent.
+
+The invariant this file exists to keep (ADR-0007 §5): no layer may truncate a
+payload at a raw offset once a layer above it has promised line integrity —
+except a hard bound, which must, and must announce it.
+
+And the other half of that same ADR heading — **truncation must come with the
+full text**. A bound exists because an agent cannot read 50,000 characters, not
+because those characters should stop existing. So every truncating layer here
+spills the untruncated payload to a file and reports the path out-of-band; what
+the agent sees is shortened, what it can still fetch is not.
+"""
+from __future__ import annotations
+
+import contextlib
+import itertools
+import os
+from pathlib import Path
+
+# The transport's hard bound on any single text channel of an executor response.
+# Mirrors playwriter's ~10000-char truncation. This is the ceiling every other
+# budget in the tree is derived from — see PRODUCER_BUDGET.
+MAX_TEXT_CHARS = 10000
+
+# What a single content producer (`snapshot()`, `read_markdown()`) may return by
+# default. Deliberately UNDER MAX_TEXT_CHARS rather than equal to it: a heredoc
+# normally prints other things alongside the payload, and the transport bound
+# applies to the WHOLE console blob, not to one producer's output. The headroom
+# is what keeps a producer's line-integrity promise from being re-cut downstream.
+PRODUCER_BUDGET = 8000
+
+TRUNC_MARKER = "… [truncated]"
+# A distinct marker for the last-resort mid-line cut, so a caller (and the agent
+# reading the output) can tell "you are missing whole lines" apart from "the last
+# line you can see is itself incomplete, do not trust a token at its end".
+MID_LINE_MARKER = "… [truncated mid-line]"
+
+
+# How many spills of one kind one process keeps before dropping its oldest.
+# The executor is long-lived and spills once per over-budget call, so unlike the
+# markdown/screenshot spills this path would otherwise grow without limit for
+# the life of the session. macOS does NOT prune /tmp — verified: files three
+# days old survive there — so nothing else is going to do this for us.
+SPILL_KEEP = 20
+
+# Where spills land. A module-level name rather than a literal so the test suite
+# can redirect it to a tmp dir — otherwise running the tests litters the
+# developer's real /tmp, which is how the accumulation this constant limits was
+# noticed in the first place. `/tmp` and not `tempfile.gettempdir()`: on macOS
+# the latter is the per-user `/var/folders/…` dir, whose value comes from the
+# TMPDIR of whichever session started the process, and the executor and the CLI
+# reading its spill paths are two processes that need not share one.
+SPILL_DIR = Path("/tmp")
+
+# Monotonic within the process, and deliberately NOT "lowest free index": with
+# pruning in play a recycled index would point an already-issued path at
+# different content, so an agent holding an older path would silently read the
+# wrong payload.
+_spill_seq = itertools.count()
+
+
+def _prune_spills(prefix: str) -> None:
+    """Drop this process's oldest ``prefix`` spills, keeping ``SPILL_KEEP``.
+
+    Scoped to our own pid on purpose: a session must never delete another
+    session's, another worktree's, or another user's files out from under them.
+    Entirely best-effort — a spill that cannot be pruned is not a failure.
+    """
+    mine: list[tuple[float, Path]] = []
+    with contextlib.suppress(OSError):
+        for p in SPILL_DIR.glob(f"browserwright-{prefix}-{os.getpid()}-*.txt"):
+            with contextlib.suppress(OSError):
+                mine.append((p.stat().st_mtime, p))
+    for _mtime, old in sorted(mine)[:-SPILL_KEEP]:
+        with contextlib.suppress(OSError):
+            old.unlink()
+
+
+def spill_text(text: str, *, prefix: str) -> str | None:
+    """Write the UNtruncated ``text`` to /tmp; return its path, or None.
+
+    The counterpart to the truncators: a bound shortens what the agent reads, it
+    must not destroy what the agent could still want. The path rides back
+    out-of-band (warnings / stderr) and the payload rides the disk rather than
+    the wire — the same reason `screenshots` in the executor protocol is
+    path-based, and the same mechanism `repl/markdown.py` already uses for the
+    content view.
+
+    Returns None on any OSError: failing to spill must never turn a merely long
+    result into a failed call. The caller says so in its notice instead.
+    """
+    while True:
+        cand = (
+            SPILL_DIR
+            / f"browserwright-{prefix}-{os.getpid()}-{next(_spill_seq)}.txt"
+        )
+        if not cand.exists():
+            break
+    try:
+        cand.write_text(text, encoding="utf-8")
+    except OSError:
+        return None
+    _prune_spills(prefix)
+    return str(cand)
+
+
+def _keep_whole_lines(text: str, budget: int) -> str | None:
+    """Longest whole-line prefix of ``text`` fitting ``budget``, else None.
+
+    None means not even the first line fits — the case the two callers below
+    resolve in opposite directions.
+    """
+    lines = text.splitlines()
+    kept: list[str] = []
+    used = 0
+    for ln in lines:
+        # +1 for the newline joining this line to the previous body.
+        add = len(ln) + (1 if kept else 0)
+        if used + add > budget:
+            break
+        kept.append(ln)
+        used += add
+    if not kept:
+        return None
+    return "\n".join(kept)
+
+
+def truncate_lines(text: str, max_chars: int) -> str:
+    """Cap ``text`` at ``max_chars`` on a LINE boundary, never mid-line.
+
+    SOFT: if even the first line overflows the budget it is still emitted whole,
+    because a partial `[ref=eN]` the agent might act on is worse than
+    overflowing a soft cap. Producers want this. The transport must not use it —
+    see :func:`truncate_hard`.
+
+    Callers apply this only when ``len(text) > max_chars``; the marker is
+    unconditional so a truncated payload always says so.
+    """
+    marker_cost = len(TRUNC_MARKER) + 1  # + the "\n" before the marker
+    body = _keep_whole_lines(text, max_chars - marker_cost)
+    if body is None:
+        # Budget too small for even one line + marker: surface line one whole.
+        lines = text.splitlines()
+        body = lines[0] if lines else text
+    return body + "\n" + TRUNC_MARKER
+
+
+def truncate_hard(text: str, budget: int) -> str:
+    """Cap ``text`` at ``budget`` characters — a bound that is never exceeded.
+
+    Prefers whole lines exactly like :func:`truncate_lines`, so a payload that
+    arrives with intact `[ref=eN]` tokens keeps them intact. Falls back to a
+    mid-line cut ONLY when a single line still overflows the budget, which is
+    the runaway-output case the bound exists for; that fallback is marked with
+    ``MID_LINE_MARKER`` so the incomplete tail is never mistaken for a whole one.
+
+    Guarantees ``len(result) <= budget`` for any ``budget >= 0``.
+    """
+    if len(text) <= budget:
+        return text
+    marker_cost = len(TRUNC_MARKER) + 1
+    if budget > marker_cost:
+        body = _keep_whole_lines(text, budget - marker_cost)
+        if body is not None:
+            return body + "\n" + TRUNC_MARKER
+    # A single line overflows the budget: cut it, and SAY that we cut it.
+    mid_cost = len(MID_LINE_MARKER) + 1
+    if budget > mid_cost:
+        return text[: budget - mid_cost] + "\n" + MID_LINE_MARKER
+    # Budget too small to even carry a marker — the bound still wins.
+    return text[:budget]