@capagents/forgeqe 0.0.0-stage → 1.0.0

package/py/forgeqe_engine/llm.py

@@ -0,0 +1,195 @@
+"""The browser agent's model: built from a ForgeQE llms.json profile, timed, and its token usage."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger("forgeqe_engine.service")
+
+
+AZURE_API_VERSION_DEFAULT = "2024-05-01-preview"
+
+# Microsoft Entra ID scope for Azure OpenAI and Azure AI Foundry; a gateway such as API Management sets its own.
+ENTRA_SCOPE_DEFAULT = "https://cognitiveservices.azure.com/.default"
+
+
+_AZURE_ENDPOINT_PATH_SUFFIXES = (
+    "/openai/v1/chat/completions",
+    "/openai/deployments",
+    "/chat/completions",
+    "/openai/v1",
+    "/models/chat/completions",
+    "/models",
+)
+
+
+def normalize_azure_endpoint(endpoint: Optional[str]) -> str:
+    """Strip API path segments so AzureOpenAI gets a base resource URL only."""
+    url = (endpoint or "").strip()
+    if not url:
+        return ""
+    if "?" in url:
+        url = url.split("?", 1)[0].strip()
+    url = url.rstrip("/")
+    lower = url.lower()
+    for suffix in _AZURE_ENDPOINT_PATH_SUFFIXES:
+        if lower.endswith(suffix):
+            url = url[: -len(suffix)].rstrip("/")
+            lower = url.lower()
+    return url
+
+
+def _resolve_api_key(cfg: Dict[str, Any]) -> str:
+    key = str(cfg.get("api_key") or cfg.get("apiKey") or "").strip()
+    if key:
+        return key
+    env_name = str(cfg.get("api_key_env") or "").strip()
+    if env_name and os.getenv(env_name):
+        return str(os.getenv(env_name))
+    return ""
+
+
+def uses_entra(cfg: Dict[str, Any]) -> bool:
+    return str(cfg.get("auth") or "key").strip().lower() == "entra"
+
+
+def entra_scope(cfg: Dict[str, Any]) -> str:
+    return str(cfg.get("token_scope") or cfg.get("tokenScope") or ENTRA_SCOPE_DEFAULT).strip()
+
+
+def entra_credential(cfg: Dict[str, Any]):
+    """
+    Microsoft Entra ID credential for an `auth: entra` profile: managed identity (user-assigned when the profile names
+    its client id), workload identity, a service principal in AZURE_* variables, or the Azure CLI's sign-in, whichever
+    this machine has. No key is read or stored.
+    """
+    try:
+        from azure.identity import DefaultAzureCredential
+    except ImportError as e:
+        raise ValueError(
+            "auth: entra needs the azure-identity package in the engine's Python. Run forgeqe setup, "
+            "or pip install azure-identity into FORGEQE_PYTHON."
+        ) from e
+    client_id = str(cfg.get("managed_identity_client_id") or cfg.get("managedIdentityClientId") or "").strip()
+    return DefaultAzureCredential(managed_identity_client_id=client_id) if client_id else DefaultAzureCredential()
+
+
+def entra_token_provider(cfg: Dict[str, Any]):
+    """A callable returning a current bearer token; azure-identity caches it and renews it before it expires."""
+    from azure.identity import get_bearer_token_provider
+
+    return get_bearer_token_provider(entra_credential(cfg), entra_scope(cfg))
+
+
+def _bearer_client(token: Any):
+    """An HTTP client that puts a current Entra ID token in each request's Authorization header."""
+    import httpx
+
+    class _Bearer(httpx.Auth):
+        def auth_flow(self, request: httpx.Request):
+            request.headers["Authorization"] = f"Bearer {token()}"
+            yield request
+
+    return httpx.AsyncClient(auth=_Bearer(), limits=httpx.Limits(max_connections=20, max_keepalive_connections=6))
+
+
+def _build_llm(llm_config: Optional[Dict[str, Any]]):
+    """Construct a browser_use chat model from a ForgeQE llms.json profile."""
+    cfg: Dict[str, Any] = dict(llm_config) if llm_config else {}
+    provider = (cfg.get("provider") or "azure").lower()
+    entra = uses_entra(cfg)
+    if entra and provider not in ("azure", "openai_compatible"):
+        raise ValueError(f"auth: entra works with the azure and openai_compatible providers, not {provider}.")
+    api_key = "" if entra else _resolve_api_key(cfg)
+
+    if provider == "ollama":
+        from browser_use.llm.ollama.chat import ChatOllama
+
+        host = (cfg.get("endpoint") or cfg.get("apiEndpoint") or "http://localhost:11434").rstrip("/")
+        # llms.json often holds the OpenAI-compatible /v1 URL; the native Ollama client wants the bare host.
+        host = re.sub(r"/v1$", "", host)
+        return ChatOllama(model=str(cfg.get("model") or "llama3.2"), host=host)
+
+    if provider == "azure":
+        from browser_use.llm.azure.chat import ChatAzureOpenAI
+
+        endpoint = normalize_azure_endpoint(cfg.get("endpoint") or cfg.get("apiEndpoint") or "")
+        deployment = cfg.get("deployment") or cfg.get("deploymentName") or cfg.get("model")
+        api_version = cfg.get("api_version") or cfg.get("apiVersion") or AZURE_API_VERSION_DEFAULT
+        if not endpoint or not deployment:
+            raise ValueError("Azure OpenAI needs an endpoint and a deployment: check them in llms.json.")
+        dep = str(deployment)
+        common: Dict[str, Any] = {"model": dep, "azure_deployment": dep, "azure_endpoint": endpoint, "api_version": str(api_version)}
+        if entra:
+            return ChatAzureOpenAI(**common, azure_ad_token_provider=entra_token_provider(cfg))
+        if not api_key:
+            raise ValueError(
+                "Azure OpenAI needs an API key: set the profile's api_key_env variable (see llms.json), "
+                "or set auth: entra to sign in with Microsoft Entra ID instead."
+            )
+        return ChatAzureOpenAI(**common, api_key=api_key)
+
+    if provider in ("openai", "openai_compatible"):
+        from browser_use.llm.openai.chat import ChatOpenAI
+
+        kw: Dict[str, Any] = {"model": str(cfg.get("model") or "gpt-4o")}
+        if provider == "openai_compatible":
+            base = str(cfg.get("endpoint") or "").strip()
+            if not base:
+                raise ValueError("openai_compatible profiles need an endpoint (base URL).")
+            kw["base_url"] = base
+            if entra:
+                # The gateway takes an Entra ID bearer token; the client asks for a fresh one on every request.
+                kw["api_key"] = "entra"
+                kw["http_client"] = _bearer_client(entra_token_provider(cfg))
+                return ChatOpenAI(**kw)
+            kw["api_key"] = api_key or "local"
+        else:
+            if not api_key:
+                raise ValueError("OpenAI needs an API key: set OPENAI_API_KEY or the profile's api_key_env.")
+            kw["api_key"] = api_key
+        return ChatOpenAI(**kw)
+
+    raise ValueError(f"Unsupported LLM provider for the engine: {provider}")
+
+
+def _time_llm_calls(llm: Any, calls: List[Tuple[float, float]]) -> None:
+    """Record when each model call started and ended, so the report can split step time into model and browser."""
+    inner = getattr(llm, "ainvoke", None)
+    if inner is None:
+        return
+
+    async def timed(*args: Any, **kwargs: Any) -> Any:
+        started = time.time()
+        try:
+            return await inner(*args, **kwargs)
+        finally:
+            calls.append((started, time.time()))
+
+    try:
+        object.__setattr__(llm, "ainvoke", timed)
+    except Exception:
+        logger.debug("model call timing not available for %s", type(llm).__name__)
+
+
+def _usage_from_history(history: Any) -> Dict[str, int]:
+    try:
+        u = getattr(history, "usage", None)
+        if u is not None:
+            return {"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
+    return {"input": 0, "output": 0}
+
+
+async def _agent_usage(agent: Any) -> Dict[str, int]:
+    """Tokens used so far; history.usage is only filled in when run() finishes, not when the run is stopped or times out."""
+    try:
+        u = await agent.token_cost_service.get_usage_summary()
+        return {"input": int(u.total_prompt_tokens or 0), "output": int(u.total_completion_tokens or 0), "cached": int(u.total_prompt_cached_tokens or 0)}
+    except Exception:
+        return _usage_from_history(getattr(agent, "history", None))

package/py/forgeqe_engine/logins.py

@@ -0,0 +1,251 @@
+"""
+Saved logins for the browser agent.
+
+Credentials never reach the model: each login becomes the library's ``sensitive_data`` scoped to its site, so the
+agent only sees placeholders such as ``<secret>shop_password</secret>`` and the library types the real value.
+A placeholder ending in ``bu_2fa_code`` holds an authenticator (TOTP) secret; the library types a fresh code.
+Cookies and local storage for each login's site are kept in a session file between runs.
+Values come from the environment by name, or from the request's ``values`` for logins ForgeQE remembered for its session
+(credentials the user gave in a message or test case); those arrive over stdin and are never logged.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from dataclasses import dataclass, field as dc_field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+FIELDS = (("username", "username_env", "text"), ("password", "password_env", "text"), ("bu_2fa_code", "totp_env", "totp"))
+_TAG = re.compile(r"^\s*<secret>\s*([A-Za-z0-9_]+)\s*</secret>\s*$")
+
+# placeholder -> ("text" | "totp", env var); set for the current run by use_logins().
+_PLACEHOLDERS: Dict[str, Tuple[str, str]] = {}
+
+
+@dataclass
+class Login:
+    name: str
+    domains: List[str]
+    username_env: Optional[str] = None
+    password_env: Optional[str] = None
+    totp_env: Optional[str] = None
+    session_file: Optional[str] = None
+    values: Dict[str, str] = dc_field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Login":
+        name = re.sub(r"[^A-Za-z0-9_]", "_", str(d.get("name") or "login"))
+        domains = [str(x).strip() for x in (d.get("domains") or []) if str(x).strip()]
+        env = lambda k: (str(d[k]).strip() or None) if d.get(k) else None  # noqa: E731
+        raw = d.get("values") if isinstance(d.get("values"), dict) else {}
+        values = {k: str(v) for k, v in raw.items() if k in ("username", "password", "totp") and isinstance(v, str) and v}
+        return cls(name, domains, env("username_env"), env("password_env"), env("totp_env"), env("session_file"), values)
+
+    def placeholder(self, field: str) -> str:
+        return f"{self.name}_{field}"
+
+    def hosts(self) -> List[str]:
+        out = []
+        for pattern in self.domains:
+            host = pattern.split("://", 1)[-1].split("/", 1)[0].split(":", 1)[0].lower()
+            out.append(host[2:] if host.startswith("*.") else host.lstrip("*"))
+        return [h for h in out if h]
+
+
+def parse_logins(raw: Any) -> List[Login]:
+    return [Login.from_dict(d) for d in (raw or []) if isinstance(d, dict) and d.get("domains")]
+
+
+def use_logins(logins: List[Login]) -> Tuple[Dict[str, Dict[str, str]], List[str]]:
+    """The library's sensitive_data ({domain pattern: {placeholder: value}}) and the env vars that are not set."""
+    _PLACEHOLDERS.clear()
+    data: Dict[str, Dict[str, str]] = {}
+    missing: List[str] = []
+    for login in logins:
+        secrets: Dict[str, str] = {}
+        for field, attr, kind in FIELDS:
+            env = getattr(login, attr)
+            if not env:
+                continue
+            given = login.values.get("totp" if kind == "totp" else field)
+            value = given if given else (os.environ.get(env) or "").strip()
+            if not value:
+                missing.append(env)
+                continue
+            if given:
+                # This process runs one browser task; replayed sign-in steps read the value by env name.
+                os.environ[env] = given
+            key = login.placeholder(field)
+            secrets[key] = value.replace(" ", "") if kind == "totp" else value
+            _PLACEHOLDERS[key] = (kind, env)
+        if secrets:
+            for pattern in login.domains:
+                data.setdefault(pattern, {}).update(secrets)
+    return data, missing
+
+
+def secret_ref(text: Any) -> Optional[Tuple[str, str]]:
+    """("text" | "totp", env var) when an action's text is a login placeholder, tagged or bare."""
+    if not isinstance(text, str) or not _PLACEHOLDERS:
+        return None
+    m = _TAG.match(text)
+    key = m.group(1) if m else text.strip()
+    return _PLACEHOLDERS.get(key)
+
+
+def text_envs() -> List[str]:
+    return [env for kind, env in _PLACEHOLDERS.values() if kind == "text"]
+
+
+def totp_code(secret: str) -> str:
+    import pyotp
+
+    return pyotp.TOTP(secret.replace(" ", ""), digits=6).now()
+
+
+def prompt_block(logins: List[Login]) -> Optional[str]:
+    lines = []
+    for login in logins:
+        parts = [
+            f"{label} <secret>{login.placeholder(field)}</secret>"
+            for field, attr, label in (("username", "username_env", "username"), ("password", "password_env", "password"), ("bu_2fa_code", "totp_env", "one-time code"))
+            if getattr(login, attr) and login.placeholder(field) in _PLACEHOLDERS
+        ]
+        if parts:
+            lines.append(f"- {login.name} on {', '.join(login.domains)}: {', '.join(parts)}")
+    if not lines:
+        return None
+    return "\n".join(
+        [
+            "## Saved logins",
+            "Use these only when the site asks you to sign in (a login form, or a page asking for an authenticator / 2FA / one-time code) and the task did not give other credentials. "
+            "Type the placeholder exactly as written, including the <secret> tags; the real value is filled in for you. "
+            "The one-time code placeholder produces a fresh code each time you type it. If the page already shows you signed in, carry on without signing in again.",
+            *lines,
+        ]
+    )
+
+
+def _host_matches(host: str, login_hosts: List[str]) -> bool:
+    host = host.lstrip(".").lower()
+    return any(host == h or h.endswith("." + host) or host.endswith("." + h) for h in login_hosts)
+
+
+def load_sessions(logins: List[Login]) -> Optional[Dict[str, Any]]:
+    """Cookies and local storage saved by earlier runs, merged into one storage state; None when there are none."""
+    cookies: List[Dict[str, Any]] = []
+    origins: List[Dict[str, Any]] = []
+    for login in logins:
+        if not login.session_file:
+            continue
+        file = Path(login.session_file)
+        if not file.is_file():
+            continue
+        try:
+            state = json.loads(file.read_text(encoding="utf-8"))
+        except Exception as ex:
+            logger.warning("login %s: session file unreadable (%s); signing in again", login.name, ex)
+            continue
+        cookies.extend(c for c in state.get("cookies") or [] if isinstance(c, dict))
+        origins.extend(o for o in state.get("origins") or [] if isinstance(o, dict))
+    if not cookies and not origins:
+        return None
+    return {"cookies": cookies, "origins": origins}
+
+
+def split_sessions(state: Dict[str, Any], logins: List[Login]) -> Dict[str, Dict[str, Any]]:
+    """The part of a browser storage state that belongs to each login's site, by login name."""
+    out: Dict[str, Dict[str, Any]] = {}
+    for login in logins:
+        if not login.session_file:
+            continue
+        hosts = login.hosts()
+        cookies = [c for c in state.get("cookies") or [] if _host_matches(str(c.get("domain") or ""), hosts)]
+        origins = [o for o in state.get("origins") or [] if _host_matches(urlparse(str(o.get("origin") or "")).hostname or "", hosts)]
+        if cookies or origins:
+            out[login.name] = {"cookies": cookies, "origins": origins}
+    return out
+
+
+def write_session(file: str, state: Dict[str, Any]) -> None:
+    path = Path(file)
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    ignore = path.parent / ".gitignore"
+    if not ignore.exists():
+        ignore.write_text("# Saved browser sessions (cookies); never commit them.\n*\n", encoding="utf-8")
+    tmp = path.with_suffix(f".{os.getpid()}.tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        json.dump(state, fh, indent=2)
+    os.replace(tmp, path)
+
+
+async def interactive_login(payload: Dict[str, Any], emit: Any, finished: Any) -> Dict[str, Any]:
+    """
+    Open a visible browser on the login's page with any saved session, let a person sign in, and save the session
+    when `finished` is set by a "save" line on stdin.
+    """
+    from browser_use import Browser
+
+    from . import brand
+    from .service import _shutdown_browser_instance, local_browser_launch_kwargs
+
+    logins = parse_logins(payload.get("logins"))
+    url = str(payload.get("url") or "").strip()
+    if not logins or not url:
+        return {"success": False, "error": "A login with a url is required."}
+    brand.install()
+    kw = local_browser_launch_kwargs(headless=False)
+    stored = load_sessions(logins)
+    if stored:
+        kw["storage_state"] = stored
+    browser = Browser(**kw)
+    overlay = brand.Overlay(browser, lock=False) if payload.get("overlay") is not False else None
+    try:
+        await browser.start()
+        await browser._cdp_navigate(url)
+        if overlay is not None:
+            await overlay.waiting(f"Sign in to {logins[0].name} here, then press Enter in the terminal to save the session")
+        emit({"type": "log", "level": "info", "text": f"Browser open at {url}"})
+        await finished.wait()
+        if payload.get("cancelled"):
+            return {"success": False, "error": "cancelled"}
+        saved = await save_sessions(browser, logins, {})
+        if not saved:
+            return {"success": False, "error": f"No cookies or local storage for {', '.join(logins[0].domains)} were found; nothing was saved."}
+        return {"success": True, "saved": saved, "summary": f"Session saved for {', '.join(saved)}"}
+    finally:
+        await _shutdown_browser_instance(browser)
+
+
+async def save_sessions(browser: Any, logins: List[Login], written: Dict[str, str]) -> List[str]:
+    """
+    Write each login's cookies and local storage from the live browser when they changed since the last write
+    (`written` holds what was last written, by login). Returns the logins written this time.
+    """
+    if not any(l.session_file for l in logins):
+        return []
+    try:
+        state = await browser._cdp_get_storage_state()
+    except Exception as ex:
+        logger.debug("could not read the browser's cookies to save logins: %s", ex)
+        return []
+    saved = []
+    for name, part in split_sessions(dict(state or {}), logins).items():
+        body = json.dumps(part, sort_keys=True)
+        if written.get(name) == body:
+            continue
+        login = next(l for l in logins if l.name == name)
+        try:
+            write_session(str(login.session_file), part)
+            written[name] = body
+            saved.append(name)
+        except Exception as ex:
+            logger.warning("login %s: could not save the session: %s", name, ex)
+    return saved

package/py/forgeqe_engine/loops.py

@@ -0,0 +1,224 @@
+"""Progress checks, the repeated-control loop breaker and its nudges, and where a failed run resumes."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections import Counter
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# max_steps is a checkpoint: a run still making progress there goes on, up to (1 + STEP_EXTENSIONS) x max_steps.
+STEP_EXTENSIONS = 2
+
+
+PROGRESS_WINDOW = 10
+
+
+PROGRESS_NEEDED = 3
+
+
+def agent_steps(history_items: Any) -> List[Any]:
+    """The history items of the agent's own steps, numbered from 1; the library's opening navigation is step 0."""
+    return [h for h in (history_items or []) if getattr(getattr(h, "metadata", None), "step_number", None) != 0]
+
+
+def step_outcomes(history_items: Any) -> List[bool]:
+    """Per agent step: its actions ran without an error and the agent's own evaluation in the next step did not call it a failure."""
+    items = agent_steps(history_items)
+    out: List[bool] = []
+    for i, h in enumerate(items):
+        results = getattr(h, "result", None) or []
+        ok = bool(results) and not any(getattr(r, "error", None) for r in results)
+        if ok and i + 1 < len(items):
+            verdict = str(getattr(getattr(items[i + 1], "model_output", None), "evaluation_previous_goal", "") or "").lower()
+            if "fail" in verdict and "success" not in verdict:
+                ok = False
+        out.append(ok)
+    return out
+
+
+def making_progress(outcomes: List[bool], window: int = PROGRESS_WINDOW, needed: int = PROGRESS_NEEDED) -> bool:
+    recent = outcomes[-window:]
+    return bool(recent) and sum(recent) >= min(needed, len(recent))
+
+
+def resume_point(outcomes: List[bool], *, loop_from: Optional[int] = None, stalled: bool = False) -> int:
+    """
+    The agent step (1-based) where a failed run went wrong; the steps before it are the ones worth replaying.
+
+    A repeated-control loop went wrong where the repeats began, a stalled run where its last progress window began,
+    and any other failure at its trailing streak of failed steps, or at its last step when that streak is empty.
+    """
+    n = len(outcomes)
+    if loop_from:
+        return max(1, loop_from)
+    if stalled:
+        return max(1, n - PROGRESS_WINDOW + 1)
+    i = n
+    while i > 0 and not outcomes[i - 1]:
+        i -= 1
+    return i + 1 if i < n else max(1, n)
+
+
+def resume_steps(steps: List[Dict[str, Any]], step_of: List[int], failed_at: int) -> List[Dict[str, Any]]:
+    """Recorded steps from before `failed_at` (replayed ones count as step 0); empty when none of them does more than open or wait."""
+    kept = [s for s, n in zip(steps, step_of) if n < failed_at]
+    if not any(s.get("action") not in ("navigate", "wait", "scroll") for s in kept):
+        return []
+    return kept
+
+
+_LOOP_PRONE_ACTION_KEYS = frozenset({"input", "click", "search", "type", "select"})
+
+
+_CONTROL_LOOP_GOAL_KEYWORDS = ("search", "select", "outlet", "autocomplete", "combobox", "filter", "lookup", "pick", "choose")
+
+
+def _resolve_browser_control_loop_max_retries() -> int:
+    raw = (os.getenv("BROWSER_USE_CONTROL_LOOP_MAX_RETRIES") or "").strip()
+    if raw.isdigit():
+        return max(2, int(raw))
+    return 4
+
+
+def _resolve_browser_control_loop_window() -> int:
+    raw = (os.getenv("BROWSER_USE_CONTROL_LOOP_WINDOW") or "").strip()
+    if raw.isdigit():
+        return max(4, int(raw))
+    return 8
+
+
+def _normalize_snippet(s: str) -> str:
+    return re.sub(r"\s+", " ", (s or "").strip().lower())
+
+
+def _action_fingerprint(action_name: str, params: Any) -> Optional[str]:
+    if action_name not in _LOOP_PRONE_ACTION_KEYS:
+        return None
+    if not isinstance(params, dict):
+        params = {}
+    if action_name in ("input", "type"):
+        text = str(params.get("text", "")).strip().lower()
+        return f"input|{params.get('index')}|{text}"
+    if action_name == "click":
+        return f"click|{params.get('index')}"
+    if action_name == "search":
+        query = str(params.get("query", "")).strip().lower()
+        tokens = sorted(set(re.sub(r"[^\w\s]", " ", query).split()))
+        return f"search|{'|'.join(tokens)}"
+    text = str(params.get("text", params.get("label", ""))).strip().lower()
+    return f"select|{params.get('index')}|{text}"
+
+
+def _step_action_lines(step: Dict[str, Any]) -> List[Tuple[str, str]]:
+    """(fingerprint, action line) for the search/select/input actions of one browser step, plus its goal when it is one."""
+    out: List[Tuple[str, str]] = []
+    lines = list(step.get("action_lines") or [])
+    for i, action in enumerate(step.get("actions") or []):
+        if not isinstance(action, dict):
+            continue
+        for action_name, params in action.items():
+            if action_name in ("interacted_element", "result"):
+                continue
+            fp = _action_fingerprint(action_name, params)
+            if fp:
+                out.append((fp, str(lines[i]) if i < len(lines) else action_name))
+
+    goal = (step.get("next_goal") or step.get("memory") or "").strip().lower()
+    if goal and any(k in goal for k in _CONTROL_LOOP_GOAL_KEYWORDS):
+        out.append((f"goal|{_normalize_snippet(goal)[:120]}", (step.get("next_goal") or step.get("memory") or "").strip()))
+    return out
+
+
+def _step_action_fingerprints(step: Dict[str, Any]) -> List[str]:
+    """Fingerprints for search/select/input loops within a single browser step."""
+    return [fp for fp, _ in _step_action_lines(step)]
+
+
+def _loop_start(collected_steps: List[Dict[str, Any]], fingerprint: str, window: int) -> Tuple[int, str]:
+    """1-based index of the first step in the recent window that repeated `fingerprint`, and that action's line."""
+    start = max(0, len(collected_steps) - window)
+    first, line = len(collected_steps), ""
+    for i in range(start, len(collected_steps)):
+        for fp, text in _step_action_lines(collected_steps[i]):
+            if fp == fingerprint:
+                first = min(first, i + 1)
+                line = text
+    return first, line
+
+
+def _loop_nudge_message(*, line: str, count: int, window: int) -> str:
+    what = f"`{line}`" if line else "the same action"
+    return (
+        f"ForgeQE: you have done {what} {count} times in the last {window} steps and the page is still not where you want it. "
+        "Doing it again will not help. Before acting, look at the current page and work out why the earlier attempts did not stick: "
+        "clicking one control can reset another (for example, a trip-type toggle can clear a date you just picked), a picker may need "
+        "a confirm or close, the value may already be set, or the element you want may be a different one. Then take a different approach. "
+        "If there is no way forward, call done with success false and describe the blocker."
+    )
+
+
+def _control_loop_exceeded(
+    collected_steps: List[Dict[str, Any]], *, max_retries: int, window: int
+) -> Tuple[bool, Optional[str], int]:
+    """True when the same search/select action repeats too often in the recent step window."""
+    if not collected_steps or max_retries < 2:
+        return False, None, 0
+    counts: Counter[str] = Counter()
+    for step in collected_steps[-window:]:
+        for fp in _step_action_fingerprints(step):
+            counts[fp] += 1
+    if not counts:
+        return False, None, 0
+    fp, count = counts.most_common(1)[0]
+    if count >= max_retries:
+        return True, fp, count
+    return False, None, 0
+
+
+def _control_loop_break_message(*, count: int, max_retries: int, fingerprint: Optional[str], nudged: bool = False) -> str:
+    detail = ""
+    if fingerprint:
+        if fingerprint.startswith("input|"):
+            parts = fingerprint.split("|", 2)
+            detail = f" (repeated input '{parts[2]}')" if len(parts) >= 3 and parts[2] else " (repeated input on the same field)"
+        elif fingerprint.startswith("search|"):
+            detail = " (repeated search)"
+        elif fingerprint.startswith("select|"):
+            detail = " (repeated select)"
+        elif fingerprint.startswith("goal|"):
+            detail = " (repeated search/select goal)"
+    return (
+        f"Stopped after {count} repeated attempts on the same control (limit {max_retries}){detail}"
+        + (", after the agent had already been told to change approach. " if nudged else ". ")
+        + "Try a different selector, wait longer for results, or complete this step manually."
+    )
+
+
+def _install_nudges(agent: Any, queue: List[str]) -> bool:
+    """
+    Deliver ForgeQE's messages to the agent on its next step, next to the library's own loop nudge.
+
+    The library clears per-step context before each step, so the queue is drained from inside the step,
+    after that reset. False when this library version has no such hook; the caller then stops instead of nudging.
+    """
+    hook = getattr(agent, "_inject_loop_detection_nudge", None)
+    manager = getattr(agent, "_message_manager", None)
+    if not callable(hook) or manager is None or not hasattr(manager, "_add_context_message"):
+        return False
+    try:
+        from browser_use.llm.messages import UserMessage
+    except Exception:
+        return False
+
+    def inject() -> None:
+        hook()
+        while queue:
+            manager._add_context_message(UserMessage(content=queue.pop(0)))
+
+    try:
+        agent._inject_loop_detection_nudge = inject
+    except Exception:
+        return False
+    return True