Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ ebay:
stealth: false # true if your eBay account signs in through Google (below)
domain: www.ebay.com # www.ebay.co.uk, www.ebay.de, …
amazon_domain: www.amazon.com
nav_timeout_s: 35 # per page load; a hung one is retried once in a fresh tab
cache_ttl_min: 360 # reuse a completed search this long (0 = off)
```

Then ask the agent to run `ebay_session_status`, and **sign in once** in the window that
Expand Down Expand Up @@ -95,6 +97,33 @@ or passkey login needs none of this.
| `compare_prices` | eBay sold + eBay active + Amazon active, side by side, each labelled with its basis. |
| `price_history` | Where today's price sits against what we've recorded before. |

**How the browser is driven.** On a protoAgent core whose `agent_browser` plugin offers the
`agent_browser.client` service, every command goes through core's hardened browser client. That
client has an output cap, a process-group kill on a timeout, CLI resolution (including core's
first-use download) and typed results, so a stuck browser reads as a timeout, never as a wall.
On an older core, or with `agent_browser` off, the plugin uses its own CLI wrapper
(`browser.py`). Either way it uses the same session, profile, launch options and labelled tab,
so switching never relaunches Chrome or loses the sign-in. Stealth behaviour is the same on
both paths.

**Failures say what to do next.** Every error carries an `error_kind`, plus a `next_step` the
agent follows:

- `timeout`: the browser didn't answer. That is a stuck tab or the site not responding, not
a wall. The plugin has already retried once in a fresh tab.
- `wall`: a sign-in wall or a human check. You act in the browser window.
- `page`: the page couldn't be read. That is a bug to report, never "nothing found".
- `unavailable`, `browser` and `bad_input` cover the rest.

Selector waits carry an explicit 10 s timeout. An un-timed wait that never succeeded used to
cost about 150 s, because the CLI re-sends it five times.

**Repeat searches are cached.** `ebay_price_check` and `ebay_price_and_profit` answer a repeat
of the same search (query, sold/active, condition) within `cache_ttl_min` from the last
completed check. The answer says `cached`, with its age. `fresh=true` forces a new reading.
The cache lives in the same local store as the price history (a `checks` table). A cache hit
is not counted as a new observation.

A bundled `ebay-pricing` skill teaches the agent how to narrow a query until the comps are
actually comparable, and how to report a price *with its basis*.

Expand Down Expand Up @@ -151,7 +180,7 @@ provided for sales taken *outside* eBay.

```bash
pip install -r requirements-dev.txt
pytest -q # 114 tests, no protoAgent host and no browser required
pytest -q # 209 tests, no protoAgent host and no browser required
ruff check . && ruff format --check .
```

Expand Down
103 changes: 88 additions & 15 deletions browser.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@
import contextlib
import json
import logging
import os
import shutil
import subprocess
import time
Expand All @@ -66,7 +67,30 @@


class BrowserError(RuntimeError):
"""A browser command failed, or the CLI isn't usable. Message is operator-facing."""
"""A browser command failed, or the CLI isn't usable. Message is operator-facing.

``kind`` says which failure it is, so a tool can tell the model what to do next instead of
handing it one undifferentiated string: ``"timeout"`` (the browser didn't answer — a stuck
tab or a site not responding, NOT a wall), ``"wall"`` (a bot check / sign-in wall answered),
``"unavailable"`` (no usable CLI), or ``"browser"`` (anything else the CLI reported)."""

kind = "browser"


class BrowserTimeout(BrowserError):
kind = "timeout"


class BrowserWall(BrowserError):
kind = "wall"

def __init__(self, message: str, wall_kind: str = ""):
super().__init__(message)
self.wall_kind = wall_kind


class BrowserUnavailable(BrowserError):
kind = "unavailable"


@dataclass
Expand All @@ -76,17 +100,33 @@ class Result:
stderr: str


def _run(args: list[str], *, timeout: float) -> Result:
"""Run the CLI once. The single seam every test stubs."""
#: The CLI gives up reading a reply after 30 s and RE-SENDS the command, up to five times
#: (agent-browser 0.27.1 ``connection.rs``). The daemon's default wait is also 30 s, so a wait
#: that never succeeds (a gate page with no results) cost ~150 s — measured: 152 s for one
#: un-timed ``wait``. Every wait here carries its own timeout, well under that.
_WAIT_TIMEOUT_S = 10.0
_TIMED_OUT = "timed out after"


def _run(args: list[str], *, timeout: float, env: dict | None = None) -> Result:
"""Run the CLI once. The single seam every test stubs. ``env`` is merged over this
process's environment for this one call (a wait's ``AGENT_BROWSER_DEFAULT_TIMEOUT``)."""
try:
p = subprocess.run(args, capture_output=True, text=True, timeout=timeout) # noqa: S603
p = subprocess.run( # noqa: S603
args, capture_output=True, text=True, timeout=timeout, env={**os.environ, **env} if env else None
)
except subprocess.TimeoutExpired:
return Result(False, "", f"timed out after {timeout:.0f}s")
return Result(False, "", f"{_TIMED_OUT} {timeout:.0f}s")
except FileNotFoundError:
return Result(False, "", f"{args[0]!r} not found on PATH")
return Result(p.returncode == 0, p.stdout or "", p.stderr or "")


def _timed_out(res: Result) -> bool:
text = (res.stderr or "") + (res.stdout or "")
return _TIMED_OUT in text or "daemon may be busy or unresponsive" in text


class Browser:
"""Drives one named ``agent-browser`` session.

Expand All @@ -106,6 +146,7 @@ def __init__(
stealth: bool = False,
timeout_s: float = 60.0,
min_interval_s: float = 1.5,
nav_timeout_s: float = 35.0,
):
self.binary = binary
self.session = session
Expand All @@ -114,6 +155,10 @@ def __init__(
self.stealth = stealth
self.timeout_s = timeout_s
self.min_interval_s = min_interval_s
# Shorter than the per-command timeout, and just past the CLI's 30 s read timeout: a
# navigation the daemon never answers (a wedged tab) is re-sent by the CLI up to five
# times, so waiting the full per-command timeout only buys more re-sends.
self.nav_timeout_s = min(nav_timeout_s, timeout_s)
self._last_nav = 0.0
self._session_ready = False
self.tab_label = _TAB_LABEL
Expand Down Expand Up @@ -163,11 +208,11 @@ def ensure_session(self) -> None:
if self._session_ready:
return
if reason := self.available():
raise BrowserError(reason)
raise BrowserUnavailable(reason)
try:
self.focus_own_tab()
except BrowserError as exc:
raise BrowserError(f"could not start the browser: {exc}") from None
raise type(exc)(f"could not start the browser: {exc}") from None
self._session_ready = True

def close(self) -> None:
Expand Down Expand Up @@ -234,9 +279,16 @@ def focus_own_tab(self) -> str:
log.warning("[ebay] the plugin's browser tab would not take focus — replaced it")
return "recreated"
if not res.ok:
raise BrowserError(self._last_line(res))
raise (BrowserTimeout if _timed_out(res) else BrowserError)(self._last_line(res))
return "created"

def reset_tab(self) -> None:
"""After a navigation that timed out: close Chrome's panels and replace OUR tab (the
only one carrying our label) with a fresh one. Never touches another tab."""
self.close_panels()
_run(self._tab_cmd("close", self.tab_label), timeout=self.timeout_s)
_run(self._tab_cmd("new", "--label", self.tab_label), timeout=self.timeout_s)

def refocus(self) -> str:
"""Another target answered instead of our tab: close Chrome's panels, take our tab back."""
self.close_panels()
Expand All @@ -249,17 +301,30 @@ def open(self, url: str) -> None:
try:
self.focus_own_tab()
except BrowserError as exc:
raise BrowserError(f"could not switch to the plugin's browser tab: {exc}") from None
raise type(exc)(f"could not switch to the plugin's browser tab: {exc}") from None
# Flags on every navigation: a daemon that died (an operator's `close`, a newer
# CLI's idle timeout) respawns with our profile instead of a blank one.
res = _run(self._open_cmd(url), timeout=self.timeout_s)
res = _run(self._open_cmd(url), timeout=self.nav_timeout_s)
if not res.ok and _BLOCKED_MARKER in (res.stderr + res.stdout):
# A target took the active slot between our switch and the navigation (the Gemini
# panel reopening). Take the tab back and try exactly once more.
self.refocus()
res = _run(self._open_cmd(url), timeout=self.timeout_s)
res = _run(self._open_cmd(url), timeout=self.nav_timeout_s)
if not res.ok and _timed_out(res):
# The one automatic recovery: a hung navigation usually means a wedged tab, so
# replace our tab and try once more before reporting a typed timeout.
log.warning("[ebay] opening %s timed out — replacing the plugin's tab and retrying once", url)
self.reset_tab()
with contextlib.suppress(BrowserError):
self.focus_own_tab()
res = _run(self._open_cmd(url), timeout=self.nav_timeout_s)
if not res.ok and _timed_out(res):
raise BrowserTimeout(
f"{url} did not load within {self.nav_timeout_s:.0f}s, twice (the second time in a fresh tab)"
)
if not res.ok:
raise BrowserError(f"could not open {url}: {(res.stderr or res.stdout).strip()}")
cls = BrowserTimeout if _timed_out(res) else BrowserError
raise cls(f"could not open {url}: {(res.stderr or res.stdout).strip()}")

def wait_for(self, selector: str, *, timeout_s: float | None = None) -> bool:
"""Block until ``selector`` appears. ``True`` if it did.
Expand All @@ -272,7 +337,15 @@ def wait_for(self, selector: str, *, timeout_s: float | None = None) -> bool:
and decides what it's looking at.
"""
self.ensure_session()
res = _run(self._cmd("wait", selector), timeout=timeout_s or self.timeout_s)
secs = min(timeout_s or _WAIT_TIMEOUT_S, 25.0)
# The CLI takes a selector wait's timeout from AGENT_BROWSER_DEFAULT_TIMEOUT (it injects it
# into the command). Without it the daemon waits 30 s — exactly the CLI's read timeout — and
# the CLI re-sends the wait up to five times (see _WAIT_TIMEOUT_S).
res = _run(
self._cmd("wait", selector),
timeout=secs + 10.0,
env={"AGENT_BROWSER_DEFAULT_TIMEOUT": str(int(secs * 1000))},
)
return res.ok

def eval_json(self, script: str):
Expand All @@ -291,9 +364,9 @@ def eval_json(self, script: str):
args, input=script, capture_output=True, text=True, timeout=self.timeout_s
)
except subprocess.TimeoutExpired:
raise BrowserError(f"page script timed out after {self.timeout_s:.0f}s") from None
raise BrowserTimeout(f"page script timed out after {self.timeout_s:.0f}s") from None
except FileNotFoundError:
raise BrowserError(f"{self.binary!r} not found on PATH") from None
raise BrowserUnavailable(f"{self.binary!r} not found on PATH") from None
if p.returncode != 0:
raise BrowserError(f"page script failed: {(p.stderr or p.stdout).strip()}")
return _parse_cli_json(p.stdout)
Expand Down
132 changes: 132 additions & 0 deletions coreclient.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
"""Drive the browser through protoAgent core's browser client when the host offers one.

Core's ``agent_browser`` plugin offers ``agent_browser.client`` (a plugin service, ADR 0116): its
own hardened path to the same ``agent-browser`` CLI. That path has an output cap, a process-group
kill on timeout, CLI resolution (including the pinned first-use download), the argv option guard,
a lock shared with the browser tools, and typed results that tell a stuck browser from a wall.
:class:`CoreBrowser` adapts it to the small surface the tools use (``open`` / ``wait_for`` /
``eval_json`` / ``refocus``), so ``tools.py`` doesn't care which path runs.

**The fallback stays.** Fleet members on a core older than the client, or with ``agent_browser``
disabled, get ``None`` from the lookup, and the tools use :class:`browser.Browser` exactly as
before. The lookup runs on every tool call, never at ``register()``: plugins load in no fixed
order, and a reload can add or remove the provider.

Same browser either way. The session keeps its configured name verbatim
(``instance_scoped=False``), so the daemon and the profile the operator signed in to are the ones
already running. It sends the same launch options (``--profile``, ``--headed``, and the one
``stealth`` Chrome flag when that's on), so switching paths never relaunches Chrome. It uses the
same labelled tab (``ebaytab``). Stealth and anti-detection behaviour are unchanged: the client
adds no launch options of its own.
"""

from __future__ import annotations

import logging

from .browser import _STEALTH_ARGS, _TAB_LABEL, BrowserError, BrowserTimeout, BrowserUnavailable, BrowserWall

log = logging.getLogger("protoagent.plugins.ebay")

#: A selector wait. Short on purpose: a results list that hasn't appeared in 10 s usually never
#: will (a gate page), and the tools' settle loop re-reads a slow page anyway.
WAIT_TIMEOUT_S = 10.0


def core_factory():
"""The host's ``agent_browser.client`` factory, or ``None``: no host (tests, CLI), a core
older than the client or the service seam, or ``agent_browser`` turned off."""
try:
from graph import sdk
except Exception: # noqa: BLE001 — host-free
return None
lookup = getattr(sdk, "service", None)
if not callable(lookup):
return None
try:
return lookup("agent_browser.client")
except Exception: # noqa: BLE001 — a lookup must never fail a tool call
log.exception("[ebay] looking up the core browser client failed")
return None


def _raise_for(result, what: str):
"""Map a failed core ``Result`` to this plugin's typed errors."""
kind = getattr(result, "kind", "cli_error")
error = getattr(result, "error", "") or kind
if kind == "timeout":
raise BrowserTimeout(f"{what}: {error}")
if kind == "wall":
wall = getattr(result, "wall", None)
raise BrowserWall(f"{what}: {error}", getattr(wall, "kind", ""))
if kind == "unavailable":
raise BrowserUnavailable(error)
raise BrowserError(f"{what}: {error}")


class CoreBrowser:
"""The tools' browser surface over core's client. ``factory`` is the
``agent_browser.client`` service; options mirror :class:`browser.Browser`'s."""

def __init__(
self,
factory,
*,
session: str,
profile: str,
headed: bool,
stealth: bool,
timeout_s: float,
nav_timeout_s: float,
min_interval_s: float,
):
self.stealth = stealth
self.session = session # tools._session_lock keys the read sequence by it
self.client = factory(
session=session,
instance_scoped=False,
profile=profile,
headed=headed,
browser_args=[_STEALTH_ARGS] if stealth else [],
own_tab=_TAB_LABEL,
timeout_s=timeout_s,
nav_timeout_s=min(nav_timeout_s, timeout_s),
min_interval_s=min_interval_s,
)

def open(self, url: str) -> None:
# check_walls=False: the tools' own settle-and-classify loop reads eBay's gate chain
# (search → /splashui/captcha → sign-in → back), which a probe right after the navigation
# would catch mid-chain and wrongly call a wall. The client still recovers a hung
# navigation once (a fresh tab) before reporting a typed timeout.
r = self.client.open(url, check_walls=False)
if not r.ok:
_raise_for(r, f"could not open {url}")

def wait_for(self, selector: str, *, timeout_s: float | None = None) -> bool:
# Best-effort, as in Browser.wait_for: a timeout is a legitimate answer (a gate page
# never shows results). A stuck browser shows up on the read that follows.
return self.client.wait(selector=selector, timeout_s=timeout_s or WAIT_TIMEOUT_S).ok

def eval_json(self, script: str):
r = self.client.eval_json(script)
if not r.ok:
_raise_for(r, "page script failed")
return r.value

def refocus(self) -> str:
self.client.close_panels()
r = self.client.focus_tab()
if not r.ok:
_raise_for(r, "could not switch to the plugin's browser tab")
return r.value

def check_wall(self, url: str):
"""A generic wall (Cloudflare, a 403/429, a vendor CAPTCHA) on the current page, as
core's wall label, or ``""``. Run only when the tools' own read found no results and no
eBay-specific reason, to name what the page actually is."""
r = self.client.check_wall(url)
return r.wall.label if getattr(r, "kind", "") == "wall" and r.wall is not None else ""

def close(self) -> None:
self.client.close()
Loading
Loading