feat: add Browser Use run hooks

Author: aaronlab

CHANGELOG.md

@@ -9,6 +9,10 @@ to keep the first contribution small and reviewable.
 
 ## Unreleased
 
+## 0.1.15 - 2026-05-10
+
+- Added `create_run_hooks` for Browser Use apps that pass `on_step_start` and
+  `on_step_end` directly to `agent.run(...)`.
 - Improved Skyvern metadata extraction so nested task/workflow run IDs and
   statuses are promoted into step metadata.
 

LAUNCH.md

@@ -1,7 +1,7 @@
 # BrowserTrace Launch Control Room
 
 Canonical repo: https://github.com/aaronlab/browsertrace
-Current release: `v0.1.14`
+Current release: `v0.1.15`
 Owner account: `aaronlab`
 
 ## Current State
@@ -14,10 +14,10 @@ Owner account: `aaronlab`
 - If posting before PyPI is live, use the tested no-install `uvx` fallback:
 
 ```bash
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace doctor
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace demo
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace list
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace doctor
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace demo
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace list
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace
 ```
 
 - Current audited star count should be checked before every public push:
@@ -30,8 +30,8 @@ gh repo view aaronlab/browsertrace --json stargazerCount,url,homepageUrl,owner
 - README animation: `docs/demo.gif`
 - Static poster: `docs/demo-poster.png`
 - Live zero-install demo: https://aaronlab.github.io/browsertrace/
-- Downloadable demo trace: `browsertrace-demo.html` attached to release `v0.1.14`
-- Public-safe demo trace: `browsertrace-demo-public.html` attached to release `v0.1.14`
+- Downloadable demo trace: `browsertrace-demo.html` attached to release `v0.1.15`
+- Public-safe demo trace: `browsertrace-demo-public.html` attached to release `v0.1.15`
 - Launch discussion: https://github.com/aaronlab/browsertrace/discussions/6
 
 ## Day 0 Asset Checklist

README.md

@@ -42,10 +42,10 @@ Use this before PyPI publishing is enabled. The quickest path is `uvx` from the
 GitHub release tag:
 
 ```bash
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace doctor
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace demo
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace list
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace doctor
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace demo
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace list
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace
 ```
 
 If you see `uvx: command not found`, install `uv` from the
@@ -73,10 +73,10 @@ Requires Python 3.11+.
 
 ```bash
 # SDK only
-pip install "browsertrace @ git+https://github.com/aaronlab/browsertrace@v0.1.14"
+pip install "browsertrace @ git+https://github.com/aaronlab/browsertrace@v0.1.15"
 
 # SDK + local web UI
-pip install "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14"
+pip install "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15"
 browsertrace doctor
 browsertrace demo
 browsertrace
@@ -109,9 +109,9 @@ For compact AI/coding-agent troubleshooting context, use
 project links and prompts.
 
 - The first-run troubleshooting checklist walks through `browsertrace doctor`, `browsertrace demo`, `browsertrace list`, `browsertrace show`, and public-safe export; see the [checklist](examples/#first-run-troubleshooting-checklist).
-- The live static demo and public-safe demo export let you inspect a trace before installing anything; open the [live static demo](https://aaronlab.github.io/browsertrace/) or download [`browsertrace-demo-public.html`](https://github.com/aaronlab/browsertrace/releases/download/v0.1.14/browsertrace-demo-public.html).
+- The live static demo and public-safe demo export let you inspect a trace before installing anything; open the [live static demo](https://aaronlab.github.io/browsertrace/) or download [`browsertrace-demo-public.html`](https://github.com/aaronlab/browsertrace/releases/download/v0.1.15/browsertrace-demo-public.html).
 - The command cheat sheet summarizes `browsertrace doctor`, `browsertrace demo`, `browsertrace list`, `browsertrace show`, and public-safe export commands; see the [cheat sheet](examples/#browsertrace-command-cheat-sheet).
-- The v0.1.14 release notes summarize what changed in the pinned GitHub tag; read the [v0.1.14 release notes](https://github.com/aaronlab/browsertrace/releases/tag/v0.1.14).
+- The v0.1.15 release notes summarize what changed in the pinned GitHub tag; read the [v0.1.15 release notes](https://github.com/aaronlab/browsertrace/releases/tag/v0.1.15).
 - The PyPI tracking issue is the source for publishing status while install commands stay pinned to the GitHub tag; follow the [PyPI tracking issue](https://github.com/aaronlab/browsertrace/issues/5).
 - `uvx` is the no-install trial path, and pinned GitHub-tag `pip install` is the persistent install path.
 - `[ui]` is needed for the local web UI, while SDK-only install is enough for trace capture integrations.
@@ -147,13 +147,13 @@ If install or demo startup fails, use the
 [first-run troubleshooting checklist](examples/#first-run-troubleshooting-checklist).
 
 For changes in this pinned tag, read the
-[v0.1.14 release notes](https://github.com/aaronlab/browsertrace/releases/tag/v0.1.14).
+[v0.1.15 release notes](https://github.com/aaronlab/browsertrace/releases/tag/v0.1.15).
 
 Want to inspect an exported trace before installing anything? Open the
 [live static demo](https://aaronlab.github.io/browsertrace/) or download
-[`browsertrace-demo.html`](https://github.com/aaronlab/browsertrace/releases/download/v0.1.14/browsertrace-demo.html)
+[`browsertrace-demo.html`](https://github.com/aaronlab/browsertrace/releases/download/v0.1.15/browsertrace-demo.html)
 or the public-safe
-[`browsertrace-demo-public.html`](https://github.com/aaronlab/browsertrace/releases/download/v0.1.14/browsertrace-demo-public.html)
+[`browsertrace-demo-public.html`](https://github.com/aaronlab/browsertrace/releases/download/v0.1.15/browsertrace-demo-public.html)
 from the latest release.
 
 For a walkthrough, read
@@ -302,7 +302,7 @@ is recorded against the last step.
 ```python
 from browser_use import Agent
 from browsertrace import Tracer
-from browsertrace.integrations.browser_use import attach_tracer
+from browsertrace.integrations.browser_use import attach_tracer, create_run_hooks
 
 tracer = Tracer()
 agent = Agent(task="...", llm=ChatOpenAI(model="gpt-4o"))
@@ -314,9 +314,18 @@ with attach_tracer(agent, tracer, name="my run"):
 The adapter records the step URL, screenshot when exposed by Browser Use,
 action summary, model thought/actions, and compact browser-state context such
 as step count, title, tabs, and whether a screenshot was captured.
+For Browser Use apps that pass lifecycle hooks directly to `agent.run(...)`,
+use the run-hook helper instead:
+
+```python
+hooks = create_run_hooks(tracer, name="my run")
+with hooks:
+    await agent.run(on_step_start=hooks.on_step_start, on_step_end=hooks.on_step_end)
+```
+
 For Browser Use callback compatibility, see
 [Debug Browser Use failures with BrowserTrace](https://aaronlab.github.io/browsertrace/browser-use-debugging.html),
-including `register_new_step_callback` notes.
+including `register_new_step_callback` and `create_run_hooks` notes.
 
 ### Stagehand integration
 
@@ -429,7 +438,7 @@ For AI summaries before PyPI publishing is enabled, install the `ai` extra from
 the release tag you are using:
 
 ```bash
-pip install "browsertrace[ui,ai] @ git+https://github.com/aaronlab/browsertrace@v0.1.14"
+pip install "browsertrace[ui,ai] @ git+https://github.com/aaronlab/browsertrace@v0.1.15"
 ```
 
 ```bash

ROADMAP.md

@@ -6,7 +6,7 @@ LLM, and computer-use runs easier to inspect, export, and discuss.
 
 ## Current Release
 
-`v0.1.14` is the current launch release.
+`v0.1.15` is the current launch release.
 
 Shipped:
 
@@ -43,9 +43,9 @@ Completed launch prep:
 
 - [#13 GitHub profile README](https://github.com/aaronlab/browsertrace/issues/13)
   now points the `aaronlab` profile at BrowserTrace.
-- GitHub Release `v0.1.14` includes the wheel, sdist, full demo export,
+- GitHub Release `v0.1.15` includes the wheel, sdist, full demo export,
   public-safe demo export, demo video, poster, and GIF.
-- `v0.1.14` also includes the `browsertrace doctor` onboarding fix for
+- `v0.1.15` also includes the `browsertrace doctor` onboarding fix for
   pre-PyPI UI dependency guidance.
 - IndexNow submission is prepared and submitted for the main GitHub Pages
   launch URLs.

browsertrace/__init__.py

@@ -2,5 +2,5 @@
 
 from .tracer import Run, Tracer, trace
 
-__version__ = "0.1.14"
+__version__ = "0.1.15"
 __all__ = ["Tracer", "Run", "trace"]

browsertrace/integrations/browser_use.py

@@ -3,23 +3,34 @@
 Usage:
     from browser_use import Agent
     from browsertrace import Tracer
-    from browsertrace.integrations.browser_use import attach_tracer
+    from browsertrace.integrations.browser_use import attach_tracer, create_run_hooks
 
     tracer = Tracer()
     agent = Agent(task="...", llm=ChatOpenAI(model="gpt-4o"))
     run = attach_tracer(agent, tracer, name="my browser-use run")
     history = await agent.run()
     run.close()    # or use the returned object as a context manager
 
+    # For Browser Use apps that pass run hooks directly:
+    hooks = create_run_hooks(tracer, name="my browser-use run")
+    with hooks:
+        history = await agent.run(
+            on_step_start=hooks.on_step_start,
+            on_step_end=hooks.on_step_end,
+        )
+
 The adapter hooks `Agent.register_new_step_callback` and saves a step in the
 trace for each agent step, including the page URL, action(s) the model decided
-on, the model's stated thought, and a screenshot of the page state.
+on, the model's stated thought, and a screenshot of the page state. The
+run-hook helper covers Browser Use versions that expose `on_step_start` and
+`on_step_end` through `agent.run(...)`.
 """
 
 from __future__ import annotations
 
 import base64
 import contextlib
+import inspect
 from typing import Any, Optional
 
 from ..tracer import Run, Tracer
@@ -52,6 +63,70 @@ def __exit__(self, exc_type, exc, tb) -> None:
         self.close(error=f"{exc_type.__name__}: {exc}" if exc_type else None)
 
 
+class BrowserUseRunHooks(BrowserUseRun):
+    """Run-hook callbacks for Browser Use versions that pass hooks to run()."""
+
+    def __init__(self, tracer: Tracer, run: Run):
+        super().__init__(tracer, run)
+        self._started = False
+        self._latest_start_context: Optional[dict] = None
+
+    async def on_step_start(self, agent: Any) -> None:
+        self._ensure_started()
+        state = await _browser_state_from_agent(agent)
+        self._latest_start_context = _serialize_agent_context(
+            agent,
+            browser_state=state,
+            has_screenshot=_extract_screenshot(state) is not None,
+        )
+
+    async def on_step_end(self, agent: Any) -> None:
+        self._ensure_started()
+        state = await _browser_state_from_agent(agent)
+        screenshot = _extract_screenshot(state)
+        model_input = self._latest_start_context or _serialize_agent_context(
+            agent,
+            browser_state=state,
+            has_screenshot=screenshot is not None,
+        )
+        history = _serialize_history(agent)
+        self.run.step(
+            action=_format_action_items(_normalize_actions(history.get("actions")))
+            or "(no action)",
+            url=_safe_attr(state, "url", default=""),
+            screenshot=screenshot,
+            model_input=model_input,
+            model_output=history,
+            hook="browser_use_run_hooks",
+        )
+        self._latest_start_context = None
+
+    def close(self, error: Optional[str] = None) -> None:
+        self._ensure_started()
+        super().close(error=error)
+
+    def _ensure_started(self) -> None:
+        if self._started:
+            return
+        self.run._start()
+        self._started = True
+
+
+def create_run_hooks(
+    tracer: Tracer,
+    name: str = "browser-use run",
+) -> BrowserUseRunHooks:
+    """Create callbacks for `agent.run(on_step_start=..., on_step_end=...)`.
+
+    This covers Browser Use apps that expose run-time lifecycle hooks instead
+    of an attachable agent callback. Keep the returned object open for the
+    duration of `agent.run(...)`, then call `.close()` or use it as a context
+    manager.
+    """
+    run = Run(tracer, run_id=__import__("uuid").uuid4().hex, name=name)
+    return BrowserUseRunHooks(tracer, run)
+
+
 def attach_tracer(
     agent: Any,
     tracer: Tracer,
@@ -135,6 +210,59 @@ def _serialize_browser_state(
     return {"step_count": step_count, "browser_state": browser_state}
 
 
+async def _browser_state_from_agent(agent: Any) -> Any:
+    browser_session = _safe_attr(agent, "browser_session", default=None)
+    getter = _safe_attr(browser_session, "get_browser_state_summary", default=None)
+    if not callable(getter):
+        return None
+    with contextlib.suppress(Exception):
+        state = getter()
+        if inspect.isawaitable(state):
+            state = await state
+        return state
+    return None
+
+
+def _serialize_agent_context(
+    agent: Any,
+    *,
+    browser_state: Any,
+    has_screenshot: bool,
+) -> dict:
+    context = {
+        "task": _safe_attr(agent, "task", default=None),
+        "browser_state": {"has_screenshot": has_screenshot},
+    }
+    for name in ("url", "title", "tabs"):
+        value = _safe_attr(browser_state, name, default=None)
+        if value is not None:
+            context["browser_state"][name] = _json_safe(value)
+    return context
+
+
+def _serialize_history(agent: Any) -> dict:
+    history = _safe_attr(agent, "history", default=None)
+    return {
+        "thought": _latest_history_value(history, "model_thoughts"),
+        "output": _latest_history_value(history, "model_outputs"),
+        "actions": _latest_history_value(history, "model_actions") or [],
+        "extracted_content": _latest_history_value(history, "extracted_content"),
+        "url": _latest_history_value(history, "urls"),
+    }
+
+
+def _latest_history_value(history: Any, method_name: str) -> Any:
+    method = _safe_attr(history, method_name, default=None)
+    if not callable(method):
+        return None
+    with contextlib.suppress(Exception):
+        values = method()
+        if isinstance(values, (list, tuple)) and values:
+            return _json_safe(values[-1])
+        return _json_safe(values)
+    return None
+
+
 def _json_safe(value: Any) -> Any:
     if value is None or isinstance(value, (str, int, float, bool)):
         return value
@@ -172,6 +300,10 @@ def _extract_screenshot(state: Any) -> Optional[bytes]:
 
 def _format_actions(output: Any) -> str:
     actions = _serialize_actions(output)
+    return _format_action_items(actions)
+
+
+def _format_action_items(actions: list) -> str:
     if not actions:
         return ""
     parts = []
@@ -188,6 +320,14 @@ def _format_actions(output: Any) -> str:
     return " | ".join(parts)
 
 
+def _normalize_actions(actions: Any) -> list:
+    if actions is None:
+        return []
+    if isinstance(actions, list):
+        return actions
+    return [actions]
+
+
 def _serialize_actions(output: Any) -> list:
     actions = _safe_attr(output, "action", default=None)
     if actions is None:

docs/browser-use-debugging.html

@@ -261,9 +261,9 @@ <h2>Why this exists</h2>
       <h2>Try it before wiring Browser Use</h2>
       <div class="command-block">
         <button class="copy-button" type="button" data-copy-target="quickstart-command">Copy</button>
-        <pre><code id="quickstart-command">uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace doctor
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace demo
-uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.14" browsertrace</code></pre>
+        <pre><code id="quickstart-command">uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace doctor
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace demo
+uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace</code></pre>
       </div>
       <p>Open <code>http://127.0.0.1:3000</code>, then inspect <code>demo: checkout agent fails on disabled button</code>. From a source checkout, <code>python examples/browser_use_callback_demo.py</code> records Browser Use-shaped callback steps without installing Browser Use.</p>
     </section>
@@ -286,7 +286,16 @@ <h2>Attach it to a Browser Use agent</h2>
     <section>
       <h2>Callback compatibility</h2>
       <p><code>attach_tracer</code> supports Browser Use agents that expose <code>register_new_step_callback</code>, plus older or forked agents with <code>on_step_start</code>, <code>on_step</code>, or <code>_new_step_callback</code> attributes.</p>
-      <p>Current Browser Use examples may also pass <code>on_step_start</code> or <code>on_step_end</code> directly to <code>agent.run(...)</code>. If your app is run-hook-only and does not expose an attachable agent callback, keep using <code>run.snapshot(...)</code> manually for now and comment on issue #11 with the Browser Use version and hook shape you need.</p>
+      <p>Current Browser Use examples may also pass <code>on_step_start</code> or <code>on_step_end</code> directly to <code>agent.run(...)</code>. For that run-hook-only path, use <code>create_run_hooks</code>:</p>
+      <pre><code>from browsertrace import Tracer
+from browsertrace.integrations.browser_use import create_run_hooks
+
+tracer = Tracer()
+hooks = create_run_hooks(tracer, name="browser-use checkout run")
+
+with hooks:
+    await agent.run(on_step_start=hooks.on_step_start, on_step_end=hooks.on_step_end)</code></pre>
+      <p>The run-hook helper reads Browser Use history and browser-session summaries when they are available, then records the latest thought, action, extracted content, URL, title, tabs, and screenshot flag into the same local timeline. If your Browser Use version exposes a different hook shape, comment on issue #11 with the version and callback surface.</p>
     </section>
 
     <section>