@capagents/forgeqe 0.0.0-stage → 1.0.0

package/py/forgeqe_engine/service.py

@@ -0,0 +1,1335 @@
+"""
+Engine integration: autonomous browser tasks via LLM + Chromium (CDP).
+
+Requires Python 3.11+ and the engine library. The Agent gets the whole goal as its task; ForgeQE adds
+error-recovery instructions, a first-navigation hint, a repeated-control loop breaker, and
+workflow/spec export on top.
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Set, Tuple
+
+from . import brand
+from .diagnostics import Diagnostics, box_for
+from .logins import load_sessions, parse_logins, prompt_block, save_sessions, use_logins
+from .memory import READ_ONLY_ACTIONS, MemoryStore, compact_step, flow_step, page_id
+from .prompts import text as prompt_text, use_prompts
+from .report import CASE_REPORT_INSTRUCTION, CaseReport, build_timeline, case_report_from_history
+from .replay import ReplayOutcome, handoff_task, replay_flow
+from .settings import (
+    _truthy_env,
+    _browser_use_agent_tuning_kwargs,
+    resolve_browser_headless,
+    build_default_browser_login_system_extension,
+)
+from .urls import (
+    _parse_allowed_domains,
+    _allowed_hosts_violation_for_url,
+    _validate_goal_urls_against_allowlist,
+    normalize_http_base_url,
+)
+from .llm import (
+    _build_llm,
+    _time_llm_calls,
+    _usage_from_history,
+    _agent_usage,
+)
+from .browser import (
+    local_browser_launch_kwargs,
+    settle_page,
+    _shutdown_browser_instance,
+    _stop_agent_instance,
+    browser_profile,
+)
+from .loops import (
+    STEP_EXTENSIONS,
+    PROGRESS_WINDOW,
+    agent_steps,
+    step_outcomes,
+    making_progress,
+    resume_point,
+    resume_steps,
+    _resolve_browser_control_loop_max_retries,
+    _resolve_browser_control_loop_window,
+    _loop_start,
+    _loop_nudge_message,
+    _control_loop_exceeded,
+    _control_loop_break_message,
+    _install_nudges,
+)
+from .summary import (
+    _primary_summary,
+    _failure_trace_markdown,
+    _failure_screenshot_asset,
+    build_browser_result_markdown,
+    judge_from_history,
+)
+from .workflow_yaml import (
+    _locator_from_interacted,
+    _selector_candidates_from_semantic,
+    _semantic_locators_from_locator,
+    save_browser_use_run_yaml,
+)
+
+logger = logging.getLogger(__name__)
+
+
+Emit = Callable[[Dict[str, Any]], None]
+
+
+@dataclass
+class RunRequest:
+    goal: str
+    out_dir: str
+    llm: Dict[str, Any]
+    start_url: Optional[str] = None
+    headed: Optional[bool] = None
+    max_steps: Optional[int] = None
+    allowed_hosts: List[str] = field(default_factory=list)
+    session_id: Optional[str] = None
+    extend_system_message: Optional[str] = None
+    # {"dir": path, "replay": "verify" | "trust" | "off"}; no dir means no memory.
+    memory: Dict[str, Any] = field(default_factory=dict)
+    # [{name, domains, username_env, password_env, totp_env, session_file}]
+    logins: List[Dict[str, Any]] = field(default_factory=list)
+    # Number of steps in the test case this goal came from; the agent then reports a verdict for each.
+    case_steps: int = 0
+    # Step screenshots for the report: "all", "failures", or "off".
+    screenshots: str = "all"
+    # Accessibility checks on each page visited, for the report.
+    accessibility: bool = True
+    # The browser agent's prompts from prompts/browser-*.md (name -> text); missing names keep the engine's own.
+    prompts: Dict[str, str] = field(default_factory=dict)
+    # The application's API calls (network.json), for API and contract tests.
+    network: bool = True
+    # axe-core for the accessibility checks: {"script": path to axe.min.js, "tags": [...]}; empty: the built-in checks.
+    axe: Dict[str, Any] = field(default_factory=dict)
+    # Core Web Vitals and load timings of each page (performance.json).
+    vitals: bool = True
+    # Screenshots of each page for visual comparison: {"mask": [...], "pages": {...}, "full_page": bool}; None: off.
+    visual: Optional[Dict[str, Any]] = None
+    # ForgeQE overlay in a visible browser: edge glow, a bar with the current step, the person's input locked.
+    overlay: bool = True
+    # A failed run's resume.json ({steps, reason, failed_at, run_id}): replay those steps, then the agent carries on.
+    resume: Dict[str, Any] = field(default_factory=dict)
+    # Browser skills [{name, description, body}]: "given" adds them all, "choose" lets the model pick the ones the goal needs.
+    skills: List[Dict[str, Any]] = field(default_factory=list)
+    skills_pick: str = "given"
+    skills_max_chars: int = 6000
+    # Set during the run: the skills added to the agent's prompt, and the tokens choosing them took.
+    skills_used: List[str] = field(default_factory=list)
+    skills_usage: Dict[str, int] = field(default_factory=dict)
+    skills_decided: bool = False
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "RunRequest":
+        return cls(
+            logins=[x for x in (d.get("logins") or []) if isinstance(x, dict)],
+            case_steps=int(d["case_steps"]) if str(d.get("case_steps") or "").isdigit() else 0,
+            screenshots=str(d.get("screenshots") or "all").lower(),
+            accessibility=d.get("accessibility") is not False,
+            overlay=d.get("overlay") is not False,
+            network=d.get("network") is not False,
+            prompts={str(k): str(v) for k, v in (d.get("prompts") or {}).items()} if isinstance(d.get("prompts"), dict) else {},
+            axe=dict(d["axe"]) if isinstance(d.get("axe"), dict) else {},
+            vitals=d.get("vitals") is not False,
+            visual=dict(d["visual"]) if isinstance(d.get("visual"), dict) else None,
+            goal=str(d.get("goal") or ""),
+            out_dir=str(d.get("out_dir") or "out"),
+            llm=dict(d.get("llm") or {}),
+            start_url=(str(d["start_url"]) if d.get("start_url") else None),
+            headed=d.get("headed") if isinstance(d.get("headed"), bool) else None,
+            max_steps=int(d["max_steps"]) if str(d.get("max_steps") or "").isdigit() else None,
+            allowed_hosts=[str(h) for h in (d.get("allowed_hosts") or []) if str(h).strip()],
+            session_id=(str(d["session_id"]) if d.get("session_id") else None),
+            extend_system_message=(str(d["extend_system_message"]) if d.get("extend_system_message") else None),
+            memory=dict(d.get("memory") or {}),
+            resume=dict(d["resume"]) if isinstance(d.get("resume"), dict) else {},
+            skills=[x for x in (d.get("skills") or []) if isinstance(x, dict)],
+            skills_pick="choose" if str(d.get("skills_pick") or "") == "choose" else "given",
+            skills_max_chars=int(d["skills_max_chars"]) if str(d.get("skills_max_chars") or "").isdigit() else 6000,
+        )
+
+
+def _build_initial_navigate_actions(url: str) -> List[Dict[str, Any]]:
+    """The library's registry action for deterministic first navigation."""
+    return [{"navigate": {"url": url, "new_tab": False}}]
+
+
+def _agent_initial_actions_construction_error(exc: BaseException) -> bool:
+    """True when Agent(**kw) failed because of initial_actions shape/support."""
+    if isinstance(exc, (KeyError, TypeError)):
+        return True
+    try:
+        from pydantic import ValidationError
+
+        if isinstance(exc, ValidationError):
+            return True
+    except ImportError:
+        pass
+    msg = str(exc).lower()
+    return any(token in msg for token in ("initial_actions", "go_to_url", "navigate", "goto"))
+
+
+# Appended to the library's Agent system prompt so the model does not blindly proceed past UI failures.
+_BROWSER_ERROR_RECOVERY_SYSTEM_MESSAGE = """
+## Error detection and recovery (required)
+After each meaningful action, and before you treat a sub-step as done or advance the scenario:
+
+1. **Read the live page** (including modals and corners) for failure signals: `alert()` dialogs, toast/snackbar errors, banner alerts, form validation (red borders, field-level error text), empty required fields, **HTTP error pages** (4xx/5xx), generic “Something went wrong” / “Error” / “Failed” copy, access denied, rate limits, or an unexpected **login / session expired** wall when you expected to be authenticated.
+
+2. **If any error or blocking state is visible**, do **not** continue the happy path. **Recover first**: note what failed, dismiss only when safe, fix invalid inputs, choose a different control, navigate back to a good state, or complete sign-in / MFA if required—then **re-attempt** the failed step with the corrected approach.
+
+3. **Proceed** to the next scenario action only when the UI consistently shows a non-error state for the current goal (success confirmation, expected next screen, etc.).
+
+4. If you cannot recover after **3–4** attempts on the **same** control (search box, autocomplete, outlet picker, dropdown), **stop immediately** and state clearly what blocked you so the user can fix data, environment, or credentials. Do **not** keep retrying the same search/select pattern indefinitely.
+""".strip()
+
+# A run that passes becomes a test, so "done" must mean the goal holds on the page, not an approximation of it.
+_GOAL_VERIFICATION_SYSTEM_MESSAGE = """
+## Finishing (required)
+Call done with success=true only when every part of the goal holds on the page right now:
+- Each field shows exactly what the goal asked for. Sites pre-fill fields (a default origin, dates, passengers) or keep earlier choices, and fields that take several values add yours to them: remove every value the goal did not ask for.
+- Every setting the goal names (sort order, filters, dates, options) is applied through the page's own controls and the page shows it (the sort control reads the chosen order, the summary or URL shows the dates). Scanning unsorted results by eye does not replace applying the sort or filter.
+- Whatever the goal asks you to find or check, you read from the page, and your final answer says what you saw.
+- Items the page already lists (result cards, rows, prices, scores) are read from that list in one step; open an item only when the goal needs something the list does not show.
+- A tab that looks blank right after it opened is still loading: wait for it once, and do not conclude it is empty.
+If a part is not met and you cannot make it so, call done with success=false and name that part.
+""".strip()
+
+_BLUEPRINT_STEP_EFFICIENCY = """
+## Efficiency (automation blueprint)
+Advance through the scenario with one clear action per step. If the page shows an error, toast, validation failure, or blocking modal, recover briefly and retry—do not re-audit the entire page after every click.
+""".strip()
+
+
+def _compose_agent_extend_system_message(extra: Optional[str], *, include_error_recovery: bool = True) -> Optional[str]:
+    """Merge default recovery instructions with optional caller-provided system extension."""
+    goal_check = prompt_text("browser-goal-verification", _GOAL_VERIFICATION_SYSTEM_MESSAGE)
+    if _truthy_env("BROWSER_USE_SKIP_ERROR_RECOVERY_PROMPT"):
+        return "\n\n".join(p for p in (goal_check, (extra or "").strip()) if p)
+    recovery = prompt_text("browser-error-recovery", _BROWSER_ERROR_RECOVERY_SYSTEM_MESSAGE) if include_error_recovery else prompt_text("browser-efficiency", _BLUEPRINT_STEP_EFFICIENCY)
+    parts = [p for p in (recovery, goal_check, (extra or "").strip()) if p]
+    if not parts:
+        return None
+    return "\n\n".join(parts)
+
+
+def _serialize_agent_actions(agent_output: Any) -> List[Dict[str, Any]]:
+    out: List[Dict[str, Any]] = []
+    for act in getattr(agent_output, "action", []) or []:
+        try:
+            out.append(act.model_dump(exclude_none=True, mode="json"))
+        except Exception:
+            out.append({"raw": str(act)[:400]})
+    return out
+
+
+def _selector_hint_strings_from_interacted(ie: Any) -> List[str]:
+    """Turn the library's interacted_element into UI-friendly locator strings."""
+    loc = _locator_from_interacted(ie)
+    if not loc:
+        return []
+    sem = _semantic_locators_from_locator(loc)
+    hints: List[str] = []
+    for cand in _selector_candidates_from_semantic(sem):
+        ctype = str(cand.get("type") or "")
+        if ctype == "css" and cand.get("value"):
+            hints.append(str(cand["value"]))
+        elif ctype == "test_id" and cand.get("value"):
+            hints.append(f'[data-testid="{cand["value"]}"]')
+        elif ctype == "role" and cand.get("role"):
+            name = cand.get("name")
+            hints.append(f'role={cand["role"]} name="{name}"' if name else f'role={cand["role"]}')
+        elif ctype in ("label", "text") and cand.get("value"):
+            hints.append(f'{ctype}="{cand["value"]}"')
+    return hints
+
+
+def _element_label(browser_state: Any, index: Any) -> str:
+    """Accessible name or visible text of the element at a selector-map index, for the transcript."""
+    try:
+        node = browser_state.dom_state.selector_map.get(int(index))
+    except Exception:
+        return ""
+    if node is None:
+        return ""
+    for getter in (
+        lambda n: getattr(getattr(n, "ax_node", None), "name", None),
+        lambda n: (getattr(n, "attributes", None) or {}).get("aria-label"),
+        lambda n: (getattr(n, "attributes", None) or {}).get("placeholder"),
+        lambda n: n.get_all_children_text() if hasattr(n, "get_all_children_text") else None,
+        lambda n: (getattr(n, "attributes", None) or {}).get("value"),
+    ):
+        try:
+            text = getter(node)
+        except Exception:
+            text = None
+        if text and str(text).strip():
+            return re.sub(r"\s+", " ", str(text)).strip()[:80]
+    return str(getattr(node, "tag_name", "") or "")
+
+
+def describe_action(action: Dict[str, Any], browser_state: Any = None) -> str:
+    """One transcript line per library action, e.g. `click "Accept"` or `input "Mumbai" → "Where are you going?"`."""
+    for name, params in action.items():
+        if name in ("interacted_element", "result"):
+            continue
+        p = params if isinstance(params, dict) else {}
+        label = _element_label(browser_state, p.get("index")) if p.get("index") is not None else ""
+        target = f' "{label}"' if label else (f" #{p.get('index')}" if p.get("index") is not None else "")
+        if name in ("navigate", "go_to_url"):
+            return f"navigate {p.get('url') or ''}".strip()
+        if name == "search":
+            return f'search "{p.get("query") or ""}"'
+        if name in ("input", "input_text"):
+            return f'input "{p.get("text") or ""}" →{target}'
+        if name == "click":
+            return f"click{target}"
+        if name == "done":
+            return "done"
+        if name == "record_check":
+            return f'check "{p.get("expected") or ""}" → "{p.get("text") or ""}"'
+        if name == "send_keys":
+            return f"keys {p.get('keys') or ''}".strip()
+        if name == "scroll":
+            return f"scroll {'down' if p.get('down', True) else 'up'}"
+        if name == "select_dropdown":
+            return f'select "{p.get("text") or ""}" →{target}'
+        main = next((p[k] for k in ("query", "pattern", "selector", "text", "file_name", "path", "seconds") if p.get(k) not in (None, "")), None)
+        return f'{name}{target}{f" {json.dumps(str(main))}" if main is not None else ""}'[:160]
+    return "action"
+
+
+def describe_action_plainly(action: Dict[str, Any], browser_state: Any = None) -> str:
+    """The same action in plain words for the browser's bar, e.g. `Clicking “Accept”`."""
+    for name, params in action.items():
+        if name in ("interacted_element", "result"):
+            continue
+        p = params if isinstance(params, dict) else {}
+        label = _element_label(browser_state, p.get("index")) if p.get("index") is not None else ""
+        return brand.plain_action(name, p, label)
+    return ""
+
+
+def _action_box(action: Dict[str, Any], browser_state: Any) -> Optional[Dict[str, float]]:
+    for name, params in action.items():
+        if name not in ("interacted_element", "result") and isinstance(params, dict) and params.get("index") is not None:
+            return box_for(browser_state, params["index"])
+    return None
+
+
+def serialize_browser_step_payload(browser_state: Any, agent_output: Any, n_steps: int) -> Dict[str, Any]:
+    """One LLM step: URL, goals, and action/locator hints for the transcript."""
+    url = getattr(browser_state, "url", None) or ""
+    title = getattr(browser_state, "title", None) or ""
+    next_goal = getattr(agent_output, "next_goal", None) or ""
+    memory = getattr(agent_output, "memory", None) or ""
+    eval_prev = getattr(agent_output, "evaluation_previous_goal", None) or ""
+    actions = _serialize_agent_actions(agent_output)
+    locator_hints: List[str] = []
+    for a in actions:
+        for key, val in a.items():
+            if key == "interacted_element":
+                locator_hints.extend(_selector_hint_strings_from_interacted(val))
+                continue
+            if isinstance(val, dict):
+                if val.get("index") is not None:
+                    continue
+                if val.get("url"):
+                    locator_hints.append(f"navigate → {str(val.get('url'))[:100]}")
+    status_line = f"Step {n_steps}"
+    if next_goal:
+        status_line += f": {next_goal[:200]}"
+    elif memory:
+        status_line += f": {memory[:200]}"
+    elif eval_prev:
+        status_line += f": {eval_prev[:200]}"
+    if url:
+        status_line += f" — {url[:100]}"
+    return {
+        "step_number": n_steps,
+        "decided_at": time.time(),
+        "boxes": [_action_box(a, browser_state) for a in actions],
+        "url": url,
+        "title": title,
+        "next_goal": next_goal,
+        "memory": memory,
+        "evaluation_previous_goal": eval_prev,
+        "actions": actions,
+        "action_lines": [describe_action(a, browser_state) for a in actions],
+        "plain_actions": [describe_action_plainly(a, browser_state) for a in actions],
+        "locator_hints": locator_hints[:24],
+        "status_line": status_line[:600],
+    }
+
+
+REPLAY_MODES = ("verify", "trust", "off")
+
+
+@dataclass
+class MemoryRun:
+    """Page and flow memory for one run: what was replayed, what the agent did, and the store to save it in."""
+
+    store: MemoryStore
+    mode: str
+    goal: str
+    start_url: Optional[str]
+    steps: List[Dict[str, Any]] = field(default_factory=list)
+    # The agent step each entry of `steps` came from; 0 for replayed steps and the opening navigate.
+    step_of: List[int] = field(default_factory=list)
+    replay: Optional[ReplayOutcome] = None
+    llm_steps: int = 0
+    finished: bool = False
+    # After a failed run: {steps, reason, failed_at, run_id}, the steps worth replaying on a retry.
+    resume: Optional[Dict[str, Any]] = None
+    run_id: str = ""
+    # The run whose checkpoint this run picked up, so finishing clears it.
+    used_checkpoint: str = ""
+    # Actions that worked without changing the page (dead clicks, read-only scripts): not part of the flow.
+    no_effect: List[str] = field(default_factory=list)
+
+    def checkpoint(self) -> Optional[Dict[str, Any]]:
+        """Save the steps that worked so far and the page memory learned so far, so a run cut off here can be picked up."""
+        if self.mode == "off" or self.finished:
+            return None
+        steps = resume_steps(self.steps, self.step_of, 10**9)
+        if not steps:
+            return None
+        data = {"steps": steps, "reason": "", "failed_at": self.llm_steps + 1, "run_id": self.run_id, "interrupted": True}
+        self.store.save_checkpoint(self.goal, self.start_url, data)
+        self.store.flush()
+        return data
+
+    def add(self, step: Dict[str, Any], agent_step: int = 0) -> None:
+        self.steps.append(step)
+        self.step_of.append(agent_step)
+
+    @classmethod
+    def from_request(cls, req: RunRequest, start_url: Optional[str]) -> Optional["MemoryRun"]:
+        folder = str((req.memory or {}).get("dir") or "").strip()
+        if not folder:
+            return None
+        mode = str((req.memory or {}).get("replay") or "verify").lower()
+        return cls(MemoryStore(folder), mode if mode in REPLAY_MODES else "verify", req.goal, start_url)
+
+    def finish(self, out: Dict[str, Any]) -> Dict[str, Any]:
+        self.finished = True
+        status = "complete" if out.get("success") else "stopped" if out.get("cancelled") else "fail"
+        # A stopped run keeps its checkpoint, like one cut off by a crash; a finished one leaves its own result.
+        if status != "stopped":
+            try:
+                self.store.clear_checkpoint(self.goal, self.start_url, (self.run_id, self.used_checkpoint))
+            except Exception as ex:
+                logger.warning("memory: could not clear the checkpoint: %s", ex)
+        flow = None
+        try:
+            flow = self.store.save_flow_result(
+                self.goal,
+                self.start_url,
+                status=status,
+                steps=self.steps,
+                summary=str(out.get("summary") or ""),
+                final_url=str(out.get("final_url") or ""),
+                replayed=len(self.replay.done) if self.replay else 0,
+                llm_steps=self.llm_steps,
+                resume=self.resume if status == "fail" else None,
+            )
+        except Exception as ex:
+            logger.warning("memory: could not save the flow: %s", ex)
+        try:
+            self.store.flush()
+        except Exception as ex:
+            logger.warning("memory: could not write page memory: %s", ex)
+        info: Dict[str, Any] = {
+            "dir": str(self.store.root),
+            "mode": self.mode,
+            "replayed": len(self.replay.done) if self.replay else 0,
+            "replay_total": self.replay.total if self.replay else 0,
+            "llm_steps": self.llm_steps,
+            "flow": flow,
+            **self.store.stats(),
+        }
+        if self.no_effect:
+            info["left_out"] = list(self.no_effect)
+        if self.replay and not self.replay.complete:
+            info["replay_stopped"] = self.replay.reason
+            if status == "complete":
+                info["repaired"] = {"step": self.replay.stopped_at, "reason": self.replay.reason, "agent_steps": self.llm_steps}
+        if self.replay and self.replay.heals:
+            info["heals"] = self.replay.heals
+        if self.resume and status == "fail":
+            info["resume"] = {
+                "steps": len(self.resume["steps"]),
+                "failed_at": self.resume.get("failed_at"),
+                "reason": self.resume.get("reason") or "",
+                "lines": [str(st.get("line") or st.get("action")) for st in self.resume["steps"]],
+            }
+        return info
+
+
+def _plan_memory_actions(
+    mem: MemoryRun,
+    browser_state: Any,
+    payload: Dict[str, Any],
+    pending: List[Tuple[str, Dict[str, Any], Optional[Dict[str, Any]], str]],
+) -> None:
+    """Record the page the LLM just saw and remember which element each planned action targets."""
+    pending.clear()
+    try:
+        dom = getattr(browser_state, "dom_state", None)
+        snap = mem.store.observe(
+            str(getattr(browser_state, "url", "") or ""),
+            str(getattr(browser_state, "title", "") or ""),
+            getattr(dom, "selector_map", None) or {},
+        )
+    except Exception as ex:
+        logger.debug("memory: observe failed: %s", ex)
+        snap = {}
+    for action, line in zip(payload.get("actions") or [], payload.get("action_lines") or []):
+        name = next((k for k in action if k not in ("interacted_element", "result")), None)
+        if not name:
+            continue
+        params = action[name] if isinstance(action[name], dict) else {}
+        target = None
+        if params.get("index") is not None:
+            try:
+                target = snap.get(int(params["index"]))
+            except (TypeError, ValueError):
+                target = None
+        pending.append((name, params, target, line))
+
+
+async def _point_at_controls(
+    browser: Any, browser_state: Any, pending: List[Tuple[str, Dict[str, Any], Optional[Dict[str, Any]], str]]
+) -> None:
+    """Before the step's actions run: point each element action at the control a user acts on, its locators checked on the page."""
+    from .capture import flow_target
+
+    selector_map = getattr(getattr(browser_state, "dom_state", None), "selector_map", None) or {}
+    for i, (name, params, target, line) in enumerate(pending):
+        if target is None or name not in ("click", "input", "select_dropdown") or params.get("index") is None:
+            continue
+        try:
+            node = selector_map.get(int(params["index"]))
+            pending[i] = (name, params, await flow_target(browser, node, target), line)
+        except Exception as ex:
+            logger.debug("capture: could not check the target of %s: %s", name, ex)
+
+
+def agent_note(output: Any) -> str:
+    """The browser agent's own words for one step: what it made of the page and what it set out to do."""
+    parts: List[str] = []
+    for name in ("evaluation_previous_goal", "memory", "next_goal"):
+        text = " ".join(str(getattr(output, name, "") or "").split())
+        if text and text not in parts:
+            parts.append(text)
+    return " ".join(parts)[:800]
+
+
+def _record_memory_results(
+    mem: MemoryRun,
+    pending: List[Tuple[str, Dict[str, Any], Optional[Dict[str, Any]], str]],
+    results: List[Any],
+    agent_step: int = 0,
+    note: str = "",
+    *,
+    effects: Optional[List[Dict[str, Any]]] = None,
+    page_url: str = "",
+) -> None:
+    """
+    Score each acted-on element and add the actions that worked to this run's flow, with the agent's note for the step.
+    A click, key press, or script that changed nothing on the page is left out of the flow: the path a test follows is
+    what changed the page, not every attempt. A script that did change the page stays, marked scripted.
+    """
+    effects = effects or []
+    for i, ((name, params, target, line), r) in enumerate(zip(pending, results)):
+        ok = not str(getattr(r, "error", None) or "").strip()
+        eff = effects[i] if i < len(effects) and effects[i].get("action") == name else {}
+        if target:
+            mem.store.record_outcome(target["page"], target["key"], ok)
+        if not ok:
+            continue
+        if eff.get("effect") is False and name in ("click", "send_keys", "evaluate", "click_selector"):
+            mem.no_effect.append(line)
+            continue
+        if name == "click_selector":
+            captured = eff.get("target")
+            if not captured:
+                continue
+            facts = captured["facts"]
+            control = {
+                "page": page_id(page_url) or "",
+                "key": "",
+                "facts": facts,
+                "locators": captured["locators"],
+                "current": {(l["type"], l["value"]): l.get("matches", 1) for l in captured["locators"] if l.get("verified")},
+            }
+            step = flow_step("click", {}, control, line)
+        elif name in READ_ONLY_ACTIONS:
+            continue
+        else:
+            step = flow_step(name, params, target, line)
+        if eff.get("effect") is not None:
+            step["effect"] = bool(eff["effect"])
+        if name == "click" and target and target.get("overlay"):
+            step["overlay"] = target["overlay"]
+        if name == "evaluate" and eff.get("effect") is True:
+            step["scripted"] = True
+        if note:
+            step["note"] = note
+        mem.add(step, agent_step)
+    pending.clear()
+
+
+def _write_artifacts(
+    out_dir: Path,
+    *,
+    req: RunRequest,
+    out: Dict[str, Any],
+    history: Any,
+    collected_steps: List[Dict[str, Any]],
+    live_trace_source: str,
+    start_url: Optional[str],
+    shot: Optional[Tuple[str, bytes]] = None,
+    mem: Optional[MemoryRun] = None,
+    timeline_history: Any = None,
+    diag: Optional[Diagnostics] = None,
+    llm_calls: Optional[List[Tuple[float, float]]] = None,
+) -> List[str]:
+    """workflow.yaml, trace.md, steps.json, run.json (and failure screenshot) in the run directory."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    files: List[str] = []
+    try:
+        timeline = build_timeline(
+            out_dir,
+            history=timeline_history if timeline_history is not None else history,
+            collected_steps=collected_steps,
+            replayed=list(mem.replay.done) if mem is not None and mem.replay else [],
+            screenshots=req.screenshots,
+            ok=bool(out.get("success")),
+            replay_times=list(mem.replay.times) if mem is not None and mem.replay else [],
+            llm_calls=llm_calls or [],
+            events=diag.events if diag is not None else [],
+        )
+        if timeline:
+            files.append(timeline)
+    except Exception as ex:
+        logger.warning("steps.json not written: %s", ex)
+    if diag is not None:
+        out["diagnostics"] = diag.summary()
+        try:
+            checks = diag.write(out_dir)
+            if checks:
+                files.append(checks)
+        except Exception as ex:
+            logger.warning("accessibility.json not written: %s", ex)
+        try:
+            perf = diag.write_perf(out_dir)
+            if perf:
+                files.append(perf)
+        except Exception as ex:
+            logger.warning("performance.json not written: %s", ex)
+        try:
+            shots = diag.write_visual(out_dir)
+            if shots:
+                files.append(shots)
+        except Exception as ex:
+            logger.warning("visual captures not written: %s", ex)
+        if diag.network is not None:
+            try:
+                calls = diag.network.write(out_dir)
+                if calls:
+                    files.append(calls)
+            except Exception as ex:
+                logger.warning("network.json not written: %s", ex)
+    memory_steps: Optional[List[Dict[str, Any]]] = None
+    if mem is not None:
+        out["memory"] = mem.finish(out)
+        memory_steps = [compact_step(s) for s in mem.steps] or None
+        resume_path = out_dir / "resume.json"
+        if (out["memory"] or {}).get("resume") and mem.resume:
+            resume_path.write_text(
+                json.dumps({"goal": req.goal, "start_url": start_url or "", **mem.resume}, indent=2), encoding="utf-8"
+            )
+            files.append(str(resume_path.resolve()))
+            out["memory"]["resume"]["file"] = str(resume_path.resolve())
+        elif not out.get("cancelled"):
+            resume_path.unlink(missing_ok=True)
+    yaml_path, _ = save_browser_use_run_yaml(
+        out_dir,
+        req.goal,
+        success=bool(out.get("success")),
+        summary=str(out.get("summary") or out.get("error") or ""),
+        session_id=req.session_id,
+        history=history,
+        collected_steps=collected_steps,
+        live_trace_source=live_trace_source,
+        compact_steps=memory_steps,
+        checks=out.get("checks") or [],
+    )
+    if yaml_path:
+        files.append(yaml_path)
+        out["yaml_path"] = yaml_path
+
+    if shot:
+        ext, data = shot
+        shot_path = out_dir / f"failure.{ext}"
+        shot_path.write_bytes(data)
+        files.append(str(shot_path.resolve()))
+        out["failure_screenshot"] = str(shot_path.resolve())
+
+    trace = out.get("result_markdown") or f"### Task\n\n{req.goal}\n\n---\n\n## Result\n\n{out.get('summary') or out.get('error') or ''}"
+    trace_path = out_dir / "trace.md"
+    trace_path.write_text(str(trace).rstrip() + "\n", encoding="utf-8")
+    files.append(str(trace_path.resolve()))
+
+    if req.skills_decided:
+        out["skills"] = list(req.skills_used)
+    if req.skills_usage and isinstance(out.get("usage"), dict):
+        for k in ("input", "output"):
+            out["usage"][k] = int(out["usage"].get(k) or 0) + int(req.skills_usage.get(k) or 0)
+    run_path = out_dir / "run.json"
+    slim = {k: v for k, v in out.items() if k != "result_markdown"}
+    slim["goal"] = req.goal
+    slim["start_url"] = start_url or ""
+    slim["driver"] = "engine"
+    slim["run_id"] = out_dir.name
+    run_path.write_text(json.dumps(slim, indent=2, ensure_ascii=False, default=str), encoding="utf-8")
+    files.insert(0, str(run_path.resolve()))
+    return files
+
+
+async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Event) -> Dict[str, Any]:
+    """
+    Run a single library Agent task and write artifacts into ``req.out_dir``.
+    ``emit`` receives transcript events; setting ``cancel_event`` stops the run.
+    """
+    goal = (req.goal or "").strip()
+    if not goal:
+        return {"success": False, "error": "Empty task goal.", "summary": ""}
+
+    allowed_domains = _parse_allowed_domains(req.allowed_hosts)
+    err = _validate_goal_urls_against_allowlist(goal, allowed_domains)
+    if err:
+        return {"success": False, "error": err, "summary": ""}
+
+    normalized_initial: Optional[str] = None
+    if (req.start_url or "").strip():
+        normalized_initial = normalize_http_base_url(req.start_url)
+        if not normalized_initial:
+            emit({"type": "log", "level": "warn", "text": f"Ignoring start URL (not http/https): {req.start_url}"})
+        else:
+            err_init = _allowed_hosts_violation_for_url(normalized_initial, allowed_domains)
+            if err_init:
+                return {"success": False, "error": err_init, "summary": ""}
+
+    from browser_use import Agent, Browser, Tools
+
+    from .capture import CAPTURE_SYSTEM_MESSAGE, install_effects, register_click_selector
+    from .checks import CHECKS_SYSTEM_MESSAGE, register_checks
+    from .skills import choose_skills, skills_block
+
+    recorded_checks: List[Dict[str, Any]] = []
+    brand.install()
+    headless = resolve_browser_headless(req.headed)
+    timeout_sec = float(os.getenv("BROWSER_USE_TIMEOUT_SECONDS", "600"))
+    step_timeout = int(os.getenv("BROWSER_USE_STEP_TIMEOUT", "180"))
+
+    try:
+        llm = _build_llm(req.llm)
+    except Exception as e:
+        return {"success": False, "error": str(e), "summary": ""}
+    llm_calls: List[Tuple[float, float]] = []
+    _time_llm_calls(llm, llm_calls)
+    use_prompts(req.prompts)
+    diag = Diagnostics(accessibility=req.accessibility, network=req.network, axe=req.axe or None, vitals=req.vitals, visual=req.visual)
+
+    browser_kw = local_browser_launch_kwargs(headless=headless)
+    if allowed_domains is not None:
+        browser_kw["allowed_domains"] = allowed_domains
+    logins = parse_logins(req.logins)
+    sensitive, missing = use_logins(logins)
+    for env in missing:
+        emit({"type": "log", "level": "warn", "text": f"Saved login: {env} is not set, so that value is not available to the agent"})
+    stored = load_sessions(logins)
+    if stored:
+        browser_kw["storage_state"] = stored
+        names = [l.name for l in logins if l.session_file and Path(l.session_file).is_file()]
+        emit({"type": "log", "level": "info", "text": f"Signed-in session restored for {', '.join(names)}"})
+    emit(
+        {
+            "type": "log",
+            "level": "info",
+            "text": f"ForgeQE engine · {browser_kw.get('channel')} · {'headless' if headless else 'visible'}"
+            + (f" · opening {normalized_initial}" if normalized_initial else " · agent picks the site"),
+        }
+    )
+
+    out_dir = Path(req.out_dir)
+    browser = Browser(**browser_kw)
+    overlay = brand.Overlay(browser) if req.overlay and not headless else None
+    agent = None
+    mem = MemoryRun.from_request(req, normalized_initial)
+    if mem is not None:
+        mem.run_id = out_dir.name
+    sessions_written: Dict[str, str] = {}
+    announced: Set[str] = set()
+
+    async def _save_logins() -> None:
+        saved = [n for n in await save_sessions(browser, logins, sessions_written) if n not in announced]
+        if saved:
+            announced.update(saved)
+            emit({"type": "log", "level": "info", "text": f"Signed-in session saved for {', '.join(saved)}"})
+
+    try:
+        collected_steps: List[Dict[str, Any]] = []
+
+        def _save(out: Dict[str, Any], source: str, *, history: Any = None, shot: Optional[Tuple[str, bytes]] = None) -> Dict[str, Any]:
+            """Write the run's artifacts for any way the run ended (`source` names it in the trace) and return `out`."""
+            out["files"] = _write_artifacts(
+                out_dir, req=req, out=out, history=history, collected_steps=collected_steps, live_trace_source=source,
+                start_url=normalized_initial, diag=diag, llm_calls=llm_calls, shot=shot, mem=mem,
+                # Without a finished history, the steps so far come from the agent itself.
+                timeline_history=getattr(agent, "history", None) if history is None else None,
+            )
+            return out
+
+        launch_profile: Dict[str, Any] = {}
+        loop_break_state: Dict[str, Any] = {}
+        loop_max_retries = _resolve_browser_control_loop_max_retries()
+        loop_window = _resolve_browser_control_loop_window()
+        loop_breaker_enabled = not _truthy_env("BROWSER_USE_SKIP_CONTROL_LOOP_BREAKER")
+
+        nudges: List[str] = []
+
+        def _evaluate_control_loop() -> bool:
+            """The first loop gets a nudge to change approach; a loop after the nudge stops the run."""
+            if not loop_breaker_enabled or loop_break_state.get("triggered"):
+                return loop_break_state.get("triggered", False)
+            since = int(loop_break_state.get("since") or 0)
+            recent = collected_steps[since:]
+            exceeded, fp, count = _control_loop_exceeded(recent, max_retries=loop_max_retries, window=loop_window)
+            if not exceeded or not fp:
+                return False
+            first, line = _loop_start(recent, fp, loop_window)
+            loop_break_state.setdefault("from", since + first)
+            if not loop_break_state.get("nudged") and loop_break_state.get("can_nudge"):
+                loop_break_state.update({"nudged": True, "since": len(collected_steps)})
+                nudges.append(_loop_nudge_message(line=line, count=count, window=loop_window))
+                emit({"type": "log", "level": "warn", "text": f"Repeated {line or 'the same action'} {count} times: told the agent to try a different approach"})
+                return False
+            loop_break_state.update(
+                {
+                    "triggered": True,
+                    "fingerprint": fp,
+                    "count": count,
+                    "max_retries": loop_max_retries,
+                    "message": _control_loop_break_message(
+                        count=count, max_retries=loop_max_retries, fingerprint=fp, nudged=bool(loop_break_state.get("nudged"))
+                    ),
+                }
+            )
+            cancel_event.set()
+            return True
+
+        pending_actions: List[Tuple[str, Dict[str, Any], Optional[Dict[str, Any]], str]] = []
+        # What each action of the current step changed on the page, in call order (capture.install_effects).
+        action_effects: List[Dict[str, Any]] = []
+        captured: Dict[str, Any] = {}
+        step_url: Dict[str, str] = {"url": ""}
+        replay_offset = 0
+
+        async def _on_new_step(browser_state: Any, agent_output: Any, n_steps: int) -> None:
+            payload = serialize_browser_step_payload(browser_state, agent_output, n_steps + replay_offset)
+            collected_steps.append(payload)
+            _evaluate_control_loop()
+            emit({"type": "step", **{k: v for k, v in payload.items() if k not in ("actions", "boxes")}})
+            action_effects.clear()
+            step_url["url"] = str(payload.get("url") or "")
+            if mem is not None:
+                _plan_memory_actions(mem, browser_state, payload, pending_actions)
+                await _point_at_controls(browser, browser_state, pending_actions)
+            await diag.sample(browser)
+            if overlay is not None:
+                await overlay.acting(brand.step_text(payload))
+
+        handoff: Optional[str] = None
+        flow: Optional[Dict[str, Any]] = None
+        kind = ""
+        if mem is not None and mem.mode != "off":
+            saved = mem.store.load_flow(goal, normalized_initial)
+            checkpoint = mem.store.load_checkpoint(goal, normalized_initial)
+            if req.resume.get("steps"):
+                flow, kind = req.resume, "interrupted" if req.resume.get("interrupted") else "resume"
+            elif saved and saved.get("successes") and saved.get("steps"):
+                flow, kind = saved, "exact"
+            elif checkpoint:
+                flow, kind = checkpoint, "interrupted"
+                mem.used_checkpoint = str(checkpoint.get("run_id") or "")
+            elif saved and isinstance(saved.get("resume"), dict) and saved["resume"].get("steps"):
+                flow, kind = saved["resume"], "resume"
+        if flow and kind and flow.get("steps"):
+            if kind == "interrupted":
+                replay_text = (
+                    f"Replaying {len(flow['steps'])} steps an earlier run of this task got through before it was cut off"
+                    + (f" ({flow['run_id']})" if flow.get("run_id") else "")
+                )
+            elif kind == "resume":
+                replay_text = (
+                    f"Replaying {len(flow['steps'])} steps that worked in an earlier run of this task"
+                    + (f" ({flow['run_id']})" if flow.get("run_id") else "")
+                    + (f", which went wrong at step {flow['failed_at']}" if flow.get("failed_at") else "")
+                )
+            else:
+                replay_text = (
+                    f"Replaying {len(flow['steps'])} recorded steps from memory "
+                    f"(last passed {str(flow.get('last_success') or '')[:10]} · {flow.get('successes')} of {flow.get('runs')} runs passed)"
+                )
+            emit({"type": "memory", "text": replay_text})
+            await browser.start()
+            await diag.start(browser)
+            replay = await replay_flow(
+                flow, browser=browser, store=mem.store, emit=emit, cancel_event=cancel_event, on_step=lambda: diag.sample(browser), overlay=overlay
+            )
+            mem.replay = replay
+            for done_step in replay.done:
+                mem.add(done_step)
+            replay_offset = replay.emitted
+            if replay.complete and kind == "exact":
+                emit({"type": "memory", "text": f"Replayed all {len(replay.done)} steps without the LLM"})
+            elif replay.complete:
+                emit({"type": "memory", "text": f"Replayed {len(replay.done)} remembered steps without the LLM; the agent continues from here"})
+            else:
+                emit({"type": "memory", "text": f"Replayed {len(replay.done)} of {replay.total} steps; {replay.reason}"})
+            if cancel_event.is_set():
+                err = "Browser task stopped by user"
+                out = {"success": False, "error": err, "summary": err, "step_events": collected_steps, "cancelled": True}
+                _save(out, "cancelled")
+                return out
+            if replay.complete and mem.mode == "trust" and kind == "exact":
+                summary = f"Replayed all {len(replay.done)} recorded steps from memory without calling the LLM."
+                if flow.get("summary"):
+                    summary += f"\n\nResult of the run that recorded them: {flow['summary']}"
+                out = {
+                    "success": True,
+                    "summary": summary,
+                    "result_markdown": f"### Task\n\n{goal}\n\n---\n\n## Result\n\n{summary}",
+                    "session_id": req.session_id,
+                    "final_url": replay.url,
+                    "usage": {"input": 0, "output": 0},
+                    "steps": replay.emitted,
+                    "step_events": collected_steps,
+                    "browser": await browser_profile(browser, browser_kw),
+                }
+                _save(out, "memory_replay")
+                return out
+            if replay.done:
+                handoff = handoff_task(goal, flow, replay, kind=kind)
+                emit({"type": "memory", "text": "The agent checks the result" if replay.complete and kind == "exact" else "The agent takes over from here"})
+
+        extra_parts: List[str] = [prompt_text("browser-checks", CHECKS_SYSTEM_MESSAGE), prompt_text("browser-capture", CAPTURE_SYSTEM_MESSAGE)]
+        login_block = build_default_browser_login_system_extension()
+        if login_block:
+            extra_parts.append(login_block)
+        saved_logins = prompt_block(logins)
+        if saved_logins:
+            extra_parts.append(saved_logins)
+        if req.case_steps > 0:
+            extra_parts.append(prompt_text("browser-case-report", CASE_REPORT_INSTRUCTION).replace("{n}", str(req.case_steps)))
+        if (req.extend_system_message or "").strip():
+            extra_parts.append((req.extend_system_message or "").strip())
+        if req.skills:
+            if req.skills_pick == "choose":
+                chosen, req.skills_usage = await choose_skills(llm, goal, req.skills)
+            else:
+                chosen = [str(s.get("name") or "") for s in req.skills]
+            block, req.skills_used, dropped = skills_block(chosen, req.skills, req.skills_max_chars)
+            req.skills_decided = True
+            if block:
+                extra_parts.append(block)
+                emit({"type": "log", "level": "info", "text": f"Skills for this run: {', '.join(req.skills_used)}"})
+            if dropped:
+                emit({"type": "log", "level": "warn", "text": f"Skills left out (over skills.browser_max_chars): {', '.join(dropped)}"})
+        if mem is not None:
+            hints = mem.store.prompt_hints(normalized_initial, goal)
+            if hints:
+                extra_parts.append(hints)
+        extend_msg = _compose_agent_extend_system_message("\n\n".join(extra_parts) if extra_parts else None)
+
+        agent_kw: Dict[str, Any] = dict(
+            task=handoff or goal,
+            llm=llm,
+            browser=browser,
+            step_timeout=step_timeout,
+            register_new_step_callback=_on_new_step,
+            enable_signal_handler=False,
+        )
+        agent_tools = Tools()
+        register_checks(agent_tools, recorded_checks)
+        register_click_selector(agent_tools, captured)
+        install_effects(agent_tools, action_effects, captured)
+        agent_kw["tools"] = agent_tools
+        agent_kw.update(_browser_use_agent_tuning_kwargs())
+        if extend_msg:
+            agent_kw["extend_system_message"] = extend_msg
+        if sensitive:
+            agent_kw["sensitive_data"] = sensitive
+        if req.case_steps > 0:
+            agent_kw["output_model_schema"] = CaseReport
+        # Only a pinned start page is opened for the agent; the library's own URL guessing from the task stays off.
+        agent_kw["directly_open_url"] = False
+        if normalized_initial and not handoff:
+            agent_kw["initial_actions"] = _build_initial_navigate_actions(normalized_initial)
+            if mem is not None:
+                mem.add(flow_step("navigate", {"url": normalized_initial, "new_tab": False}, None, f"navigate {normalized_initial}"))
+
+        async def _should_stop_callback() -> bool:
+            if cancel_event.is_set():
+                return True
+            return _evaluate_control_loop()
+
+        agent_kw["register_should_stop_callback"] = _should_stop_callback
+        task_with_url_preamble = False
+        for _ in range(10):
+            try:
+                agent = Agent(**agent_kw)
+                break
+            except Exception as exc:
+                err_txt = str(exc)
+                err_l = err_txt.lower()
+                if "enable_signal_handler" in agent_kw and "enable_signal_handler" in err_l:
+                    agent_kw.pop("enable_signal_handler", None)
+                    continue
+                if "initial_actions" in agent_kw and normalized_initial and _agent_initial_actions_construction_error(exc):
+                    agent_kw.pop("initial_actions", None)
+                    if not task_with_url_preamble:
+                        task_with_url_preamble = True
+                        agent_kw["task"] = (
+                            f"Navigate to {normalized_initial} first (open this exact URL in the browser), "
+                            f"wait for the page to finish loading, then complete the task below:\n\n{goal}"
+                        )
+                    continue
+                if "extend_system_message" in agent_kw and "extend_system_message" in err_txt:
+                    agent_kw.pop("extend_system_message", None)
+                    continue
+                if "directly_open_url" in agent_kw and "directly_open_url" in err_txt:
+                    agent_kw.pop("directly_open_url", None)
+                    continue
+                if "output_model_schema" in agent_kw and "output_model_schema" in err_txt:
+                    agent_kw.pop("output_model_schema", None)
+                    continue
+                if "register_should_stop_callback" in agent_kw and "register_should_stop" in err_l:
+                    agent_kw.pop("register_should_stop_callback", None)
+                    continue
+                tuning_keys = (
+                    "enable_planning",
+                    "use_thinking",
+                    "use_judge",
+                    "flash_mode",
+                    "loop_detection_enabled",
+                    "loop_detection_window",
+                    "vision_detail_level",
+                    "max_actions_per_step",
+                    "llm_timeout",
+                    "max_failures",
+                    "max_history_items",
+                    "message_compaction",
+                )
+                popped = False
+                for tk in tuning_keys:
+                    if tk in agent_kw and tk in err_txt:
+                        agent_kw.pop(tk, None)
+                        popped = True
+                if popped:
+                    continue
+                raise
+        if agent is None:
+            raise RuntimeError("engine library Agent: failed to construct after parameter fallbacks")
+        loop_break_state["can_nudge"] = _install_nudges(agent, nudges)
+
+        max_steps = req.max_steps or 0
+        env_steps = (os.getenv("BROWSER_USE_MAX_STEPS") or "").strip()
+        if not max_steps and env_steps.isdigit() and int(env_steps) > 0:
+            max_steps = int(env_steps)
+        step_cap = max_steps * (1 + STEP_EXTENSIONS) if max_steps > 0 else 0
+        budget_state: Dict[str, Any] = {}
+
+        def _plan_resume(reason: str) -> None:
+            """Keep the steps that worked before this failed run went wrong, for the next run or a retry to replay."""
+            if mem is None or mem.mode == "off":
+                return
+            items = list(getattr(getattr(agent, "history", None), "history", None) or [])
+            at = resume_point(step_outcomes(items), loop_from=loop_break_state.get("from"), stalled=bool(budget_state.get("message")))
+            steps = resume_steps(mem.steps, mem.step_of, at)
+            if not steps:
+                return
+            first_line = (str(reason or "").strip().splitlines() or [""])[0]
+            mem.resume = {"steps": steps, "reason": first_line[:400], "failed_at": at, "run_id": out_dir.name}
+            emit({"type": "memory", "text": f"Kept the {len(steps)} steps that worked before step {at}; the next run of this task replays them and picks up there"})
+
+        async def _on_step_end(agent_ref: Any) -> None:
+            try:
+                last = agent_ref.history.history[-1]
+            except Exception:
+                return
+            results = getattr(last, "result", None) or []
+            if mem is not None:
+                mem.llm_steps = len(agent_steps(agent_ref.history.history))
+                _record_memory_results(
+                    mem, pending_actions, results, mem.llm_steps, agent_note(getattr(last, "model_output", None)),
+                    effects=list(action_effects), page_url=step_url["url"],
+                )
+                try:
+                    point = mem.checkpoint()
+                    if point:
+                        (out_dir / "resume.json").write_text(
+                            json.dumps({"goal": req.goal, "start_url": normalized_initial or "", **point}, indent=2), encoding="utf-8"
+                        )
+                except Exception as ex:
+                    logger.warning("memory: could not save the checkpoint: %s", ex)
+            items = []
+            for r in results:
+                err = str(getattr(r, "error", None) or "").strip()
+                text = err or str(getattr(r, "extracted_content", None) or "").strip()
+                items.append(
+                    {
+                        "ok": not err,
+                        "done": bool(getattr(r, "is_done", False)),
+                        "text": (text.splitlines() or [""])[0][:240],
+                    }
+                )
+            emit({"type": "result", "step": len(agent_ref.history.history) + replay_offset, "items": items})
+            n = len(agent_ref.history.history)
+            if max_steps > 0 and n < step_cap and n % max_steps == 0 and not any(i["done"] for i in items):
+                if making_progress(step_outcomes(agent_ref.history.history)):
+                    emit({"type": "log", "level": "info", "text": f"Reached {n} steps and still making progress: carrying on, up to {step_cap}"})
+                else:
+                    budget_state["message"] = f"Stopped at {n} steps: the last {PROGRESS_WINDOW} steps made no progress."
+                    emit({"type": "log", "level": "warn", "text": budget_state["message"]})
+                    agent_ref.stop()
+            if not launch_profile:
+                launch_profile.update(await browser_profile(browser, browser_kw))
+            await diag.sample(browser)
+            with contextlib.suppress(Exception):
+                await _save_logins()
+            try:
+                u = await agent_ref.token_cost_service.get_usage_summary()
+                emit({"type": "usage", "input": int(u.total_prompt_tokens or 0), "output": int(u.total_completion_tokens or 0), "cached": int(getattr(u, "total_prompt_cached_tokens", 0) or 0)})
+            except Exception:
+                pass
+            if overlay is not None:
+                await overlay.thinking()
+
+        async def _on_step_start(agent_ref: Any) -> None:
+            if not collected_steps:
+                await diag.start(browser)
+            if overlay is not None and not collected_steps:
+                await overlay.thinking("Reading the page")
+            if collected_steps:
+                waited = await settle_page(browser)
+                if waited >= 1:
+                    emit({"type": "log", "level": "debug", "text": f"Waited {waited:.1f}s for the page to finish loading"})
+
+        async def _run_agent():
+            if max_steps > 0:
+                return await agent.run(max_steps=step_cap, on_step_start=_on_step_start, on_step_end=_on_step_end)
+            return await agent.run(on_step_start=_on_step_start, on_step_end=_on_step_end)
+
+        run_task = asyncio.create_task(_run_agent())
+        cancel_wait = asyncio.create_task(cancel_event.wait())
+        done, _pending = await asyncio.wait({run_task, cancel_wait}, return_when=asyncio.FIRST_COMPLETED, timeout=timeout_sec)
+
+        if not done:
+            cancel_wait.cancel()
+            await _stop_agent_instance(agent)
+            run_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await run_task
+            err = f"Browser task timed out after {timeout_sec:.0f}s"
+            out = {"success": False, "error": err, "summary": err, "step_events": collected_steps, "usage": await _agent_usage(agent)}
+            _plan_resume(err)
+            _save(out, "timeout")
+            return out
+
+        if cancel_wait in done and not run_task.done():
+            await _stop_agent_instance(agent)
+            run_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await run_task
+            triggered = bool(loop_break_state.get("triggered"))
+            err = loop_break_state.get("message") if triggered else "Browser task stopped by user"
+            out = {
+                "success": False,
+                "error": err,
+                "summary": err,
+                "step_events": collected_steps,
+                "cancelled": not triggered,
+                "loop_breaker": triggered,
+                "usage": await _agent_usage(agent),
+            }
+            if triggered:
+                _plan_resume(str(err))
+            _save(out, "cancelled")
+            return out
+
+        cancel_wait.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await cancel_wait
+
+        try:
+            history = run_task.result()
+        except Exception as e:
+            triggered = bool(loop_break_state.get("triggered"))
+            if cancel_event.is_set():
+                err = loop_break_state.get("message") if triggered else "Browser task stopped by user"
+                out = {
+                    "success": False,
+                    "error": err,
+                    "summary": err,
+                    "step_events": collected_steps,
+                    "cancelled": not triggered,
+                    "loop_breaker": triggered,
+                }
+            else:
+                logger.exception("engine library Agent.run failed")
+                out = {"success": False, "error": str(e), "summary": str(e), "step_events": collected_steps}
+            out["usage"] = await _agent_usage(agent)
+            if not out.get("cancelled"):
+                _plan_resume(str(out["error"]))
+            _save(out, "agent_run_exception")
+            return out
+
+        case_report = case_report_from_history(history) if req.case_steps > 0 else None
+        primary = str(case_report.get("summary") or "").strip() if case_report else ""
+        primary = primary or _primary_summary(history)
+        success_flag = history.is_successful()
+        if success_flag is None:
+            success_flag = not history.has_errors() and bool(primary)
+        ok = bool(success_flag)
+        if loop_break_state.get("triggered"):
+            ok = False
+        judge = judge_from_history(history)
+        judge_rejected = ok and judge is not None and judge["verdict"] is False
+        if judge_rejected:
+            ok = False
+        # The agent can call done(success=true) after recording an expected result that does not hold, or after its own
+        # case report fails a step. Its evidence wins over its verdict: the test case failed.
+        contradicted = ok and evidence_fails(recorded_checks, case_report)
+        if contradicted:
+            ok = False
+        errs_list = [e for e in history.errors() if e]
+        if not ok:
+            if loop_break_state.get("triggered"):
+                summary = str(loop_break_state.get("message") or "Stopped after repeated search/select attempts.")
+            elif budget_state.get("message"):
+                summary = str(budget_state["message"]) + (f"\n\n{primary}" if primary else "")
+            elif judge_rejected:
+                why = judge.get("failure_reason") or judge.get("reasoning") or "the trace does not show the goal met"
+                summary = f"The agent reported success, but the judge found the goal not met: {why}"
+                if primary:
+                    summary += f"\n\nThe agent's report: {primary}"
+            else:
+                summary = primary or (errs_list[-1] if errs_list else "Browser task finished without a clear result.")
+        else:
+            summary = primary or ""
+
+        try:
+            result_md = build_browser_result_markdown(history, recorded_checks if ok else None)
+        except Exception as ex:
+            logger.warning("build_browser_result_markdown failed: %s", ex)
+            result_md = str(summary)
+        result_md = f"### Task\n\n{goal}\n\n---\n\n{result_md}"
+
+        shot: Optional[Tuple[str, bytes]] = None
+        trace_md = ""
+        if not ok:
+            trace_md = _failure_trace_markdown(history)
+            shot = _failure_screenshot_asset(history)
+            fail_parts: List[str] = ["## Failure details", "", trace_md, ""]
+            if shot:
+                fail_parts.extend(["### Screenshot (last state)", "", f"![failure](failure.{shot[0]})", ""])
+            result_md = result_md.rstrip() + "\n\n" + "\n".join(fail_parts).strip()
+
+        try:
+            urls = [u for u in (history.urls() or []) if u]
+        except Exception:
+            urls = []
+        out: Dict[str, Any] = {
+            "success": ok,
+            "summary": str(summary),
+            "result_markdown": result_md,
+            "session_id": req.session_id,
+            "final_url": urls[-1] if urls else "",
+            "usage": _usage_from_history(history),
+            "steps": len(history.history or []) + replay_offset,
+            "step_events": collected_steps,
+            "browser": dict(launch_profile) if launch_profile else await browser_profile(browser, browser_kw),
+        }
+        if judge is not None:
+            out["judge"] = judge
+        if loop_break_state.get("triggered"):
+            out["loop_breaker"] = True
+        if case_report:
+            out["case_report"] = case_report
+        failed_checks = [c for c in recorded_checks if c.get("holds") is False]
+        # The steps were done and an expected result did not hold: the test failed, the run did not.
+        assertion_failed = contradicted or (
+            not ok and bool(failed_checks) and not loop_break_state.get("triggered") and not budget_state.get("message") and not judge_rejected
+        )
+        out["outcome"] = "passed" if ok else "assertion_failed" if assertion_failed else "error"
+        if recorded_checks and (ok or assertion_failed):
+            out["checks"] = list(recorded_checks)
+        if not ok:
+            out["error"] = str(summary)
+            if trace_md:
+                out["failure_trace"] = trace_md
+            if not assertion_failed:
+                _plan_resume(str(summary))
+        _save(out, "history", history=history, shot=shot)
+        return out
+    finally:
+        if mem is not None and not mem.finished:
+            with contextlib.suppress(Exception):
+                mem.store.flush()
+        with contextlib.suppress(Exception):
+            await _save_logins()
+        if overlay is not None:
+            overlay.close()
+        await _shutdown_browser_instance(browser)
+
+
+def evidence_fails(checks: List[Dict[str, Any]], case_report: Optional[Dict[str, Any]]) -> bool:
+    """Whether the agent's own evidence fails the test: a recorded check that does not hold, or a failed case step."""
+    if any(c.get("holds") is False for c in checks or []):
+        return True
+    return any(str(step.get("status")) == "failed" for step in ((case_report or {}).get("steps") or []))
+
+
+async def run_with_events(req: RunRequest, emit: Emit, cancel_event: asyncio.Event) -> Dict[str, Any]:
+    """Run and always finish with a `done` event, even when setup fails before the Agent starts."""
+    try:
+        out = await run_browser_task(req, emit, cancel_event)
+    except Exception as e:
+        logger.exception("run failed")
+        out = {"success": False, "error": str(e), "summary": str(e)}
+    if "files" not in out:
+        try:
+            out["files"] = _write_artifacts(
+                Path(req.out_dir), req=req, out=out, history=None, collected_steps=out.get("step_events") or [],
+                live_trace_source="setup", start_url=req.start_url,
+            )
+        except Exception as ex:
+            logger.warning("artifact write failed: %s", ex)
+            out["files"] = []
+    emit({"type": "done", "result": {k: v for k, v in out.items() if k != "step_events"}})
+    return out