@capagents/forgeqe 0.0.0-stage → 1.0.0

package/py/forgeqe_engine/memory.py

@@ -0,0 +1,1004 @@
+"""
+Page memory: what ForgeQE learned on earlier runs, used to act faster and call the LLM less.
+
+Layout under the memory directory:
+
+  pages/<host>/<page>.json   every interactive element seen on that page, each with ranked locators
+  flows/<goal>-<hash>.json   the actions of the last successful run of a goal, replayable without the LLM
+
+A locator's confidence (1-99 %) multiplies four factors: how stable its kind is (test id > id >
+role+name > ... > xpath), how unique it was on the page, how consistently it reappeared on later
+visits, and how often acting through it worked during replay.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from collections import Counter
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Set, Tuple
+from urllib.parse import urlparse
+
+from .logins import secret_ref, text_envs
+
+VERSION = 1
+MAX_ELEMENTS_PER_PAGE = 400
+MAX_LOCATORS_PER_ELEMENT = 10
+MAX_SAMPLE_URLS = 5
+MAX_FLOW_STEPS = 80
+FLOW_STEP_LOCATORS = 6
+
+ROLES = frozenset(
+    {
+        "button", "link", "textbox", "searchbox", "combobox", "checkbox", "radio", "switch", "option",
+        "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "listbox", "slider", "spinbutton",
+        "heading", "img", "gridcell", "cell", "row", "columnheader", "treeitem", "dialog",
+    }
+)
+TEST_ID_ATTRS = ("data-testid", "data-test-id", "data-test", "data-qa", "data-cy")
+KEPT_ATTRS = ("id", "name", "type", "placeholder", "aria-label", "title", "alt", "href", "role", *TEST_ID_ATTRS)
+FORM_TAGS = frozenset({"input", "textarea", "select"})
+TEXT_TAGS = frozenset({"a", "button", "label", "li", "span", "div", "td", "th", "summary", "option", "p"})
+
+# Stability of each locator kind before page evidence is applied.
+BASE = {
+    "test_id": 0.96,
+    "id": 0.90,
+    "role": 0.88,
+    "name": 0.86,
+    "label": 0.84,
+    "placeholder": 0.82,
+    "alt": 0.78,
+    "href": 0.74,
+    "title": 0.72,
+    "text": 0.70,
+    "css": 0.50,
+    "xpath": 0.30,
+}
+# Kinds precise enough to recognise the same element on a later visit; xpath is the last resort.
+STRONG = ("test_id", "id", "name", "role", "label", "placeholder", "href")
+INDEXED = (*STRONG, "xpath")
+GENERATED_FACTOR = 0.4
+
+_GENERATED = (
+    re.compile(r"\d{4,}"),
+    re.compile(r"(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{8,}", re.I),
+    re.compile(r":[rR][0-9a-zA-Z]*:"),
+    re.compile(r"^(ember|ext-gen|mui-|react-select-|headlessui-|radix-|yui_|j_id|__)", re.I),
+    # CSS-in-JS: emotion (css-1q2w3e), styled-components (Button-sc-1x2y3z-0, sc-aXZVg), jsx-123
+    re.compile(r"^(css|jsx|sc)-[a-z0-9]{5,}$", re.I),
+    re.compile(r"-sc-[a-z0-9]{5,}", re.I),
+)
+
+# Actions that only read the page; replay skips them and flows do not record them.
+READ_ONLY_ACTIONS = frozenset(
+    {"extract", "find_text", "search_page", "find_elements", "dropdown_options", "screenshot", "read_file", "write_file", "replace_file", "done", "record_check"}
+)
+ELEMENT_ACTIONS = frozenset({"click", "input", "select_dropdown", "scroll", "upload_file"})
+REPLAYABLE_ACTIONS = frozenset({"navigate", "search", "go_back", "wait", "click", "input", "select_dropdown", "scroll", "send_keys"})
+SECRET_ENV_VARS = ("BROWSER_USE_DEFAULT_LOGIN_PASSWORD", "BROWSER_USE_DEFAULT_LOGIN_USERNAME")
+
+LocKey = Tuple[str, str]
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _q(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _clean(text: Any, limit: int = 120) -> str:
+    return re.sub(r"\s+", " ", str(text or "")).strip()[:limit]
+
+
+def _sha(text: str, n: int) -> str:
+    return hashlib.sha1(text.encode("utf-8")).hexdigest()[:n]
+
+
+def looks_generated(value: str) -> bool:
+    """Framework-generated ids and hashes change between builds or page loads."""
+    return any(p.search(value or "") for p in _GENERATED)
+
+
+def _css_ident(value: str) -> bool:
+    return bool(re.fullmatch(r"[A-Za-z_][\w-]*", value or ""))
+
+
+# ---------------------------------------------------------------------------------------------
+# Pages
+# ---------------------------------------------------------------------------------------------
+
+
+def _template_segment(seg: str) -> str:
+    if seg.isdigit() or (looks_generated(seg) and not re.search(r"\.[a-z]{2,5}$", seg)):
+        return "*"
+    if len(seg) >= 24 and re.search(r"\d", seg):
+        return "*"
+    return seg
+
+
+def page_ref(url: str) -> Optional[Tuple[str, str]]:
+    """(host, path template) for a page URL. Ids in the path become `*`, the query string is dropped."""
+    try:
+        p = urlparse(url or "")
+    except Exception:
+        return None
+    if p.scheme not in ("http", "https") or not p.hostname:
+        return None
+    host = p.hostname.lower()
+    if p.port and p.port not in (80, 443):
+        host = f"{host}:{p.port}"
+    path = "/" + "/".join(_template_segment(s) for s in p.path.split("/") if s)
+    frag = p.fragment or ""
+    if frag.startswith("/") or frag.startswith("!/"):
+        path += "#" + "/".join(_template_segment(s) for s in frag.split("?")[0].split("/"))
+    return host, path
+
+
+def page_id(url: str) -> Optional[str]:
+    ref = page_ref(url)
+    return f"{ref[0]}{ref[1]}" if ref else None
+
+
+def _page_slug(path: str) -> str:
+    if path == "/":
+        return "index"
+    return f"{re.sub(r'[^A-Za-z0-9]+', '_', path).strip('_')[:60] or 'page'}-{_sha(path, 8)}"
+
+
+def _host_dir(host: str) -> str:
+    return re.sub(r"[^A-Za-z0-9.-]+", "_", host)
+
+
+# ---------------------------------------------------------------------------------------------
+# Elements and locators
+# ---------------------------------------------------------------------------------------------
+
+
+def element_facts(node: Any) -> Dict[str, Any]:
+    """Identity-relevant facts of a library DOM node (EnhancedDOMTreeNode)."""
+    raw_attrs = getattr(node, "attributes", None) or {}
+    attrs = {k: str(v) for k, v in raw_attrs.items() if k in KEPT_ATTRS and v not in (None, "")}
+    ax = getattr(node, "ax_node", None)
+    tag = str(getattr(node, "node_name", "") or "").lower()
+    role = _clean(attrs.get("role") or getattr(ax, "role", None) or "", 40)
+    name = _clean(getattr(ax, "name", None) or "")
+    text = ""
+    if not name and tag in TEXT_TAGS and hasattr(node, "get_all_children_text"):
+        try:
+            text = _clean(node.get_all_children_text(max_depth=4))
+        except Exception:
+            text = ""
+    try:
+        xpath = str(node.xpath or "")
+    except Exception:
+        xpath = ""
+    try:
+        stable_hash = node.compute_stable_hash()
+    except Exception:
+        stable_hash = None
+    classes: List[str] = []
+    cls = str(raw_attrs.get("class") or "")
+    if cls:
+        try:
+            from browser_use.dom.views import filter_dynamic_classes
+
+            cls = filter_dynamic_classes(cls)
+        except Exception:
+            pass
+        classes = [c for c in cls.split() if _css_ident(c) and not looks_generated(c)]
+    return {
+        "tag": tag,
+        "role": role,
+        "name": name,
+        "text": text,
+        "attributes": attrs,
+        "classes": classes[:4],
+        "xpath": xpath,
+        "stable_hash": stable_hash,
+    }
+
+
+def candidate_locators(f: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Every locator we can build for one element: semantic first, css and xpath last."""
+    out: List[Dict[str, Any]] = []
+    a: Dict[str, str] = f.get("attributes") or {}
+    tag = f.get("tag") or "*"
+    role, name = f.get("role") or "", f.get("name") or ""
+
+    def add(kind: str, value: str, playwright: str, **extra: Any) -> None:
+        if not value:
+            return
+        base = BASE[kind]
+        generated = kind in ("test_id", "id", "name", "href", "css") and looks_generated(value)
+        if generated:
+            base *= GENERATED_FACTOR
+        loc = {"type": kind, "value": value, "playwright": playwright, "base": round(base, 3), **extra}
+        if generated:
+            loc["generated"] = True
+        out.append(loc)
+
+    tid_attr = next((k for k in TEST_ID_ATTRS if a.get(k)), None)
+    if tid_attr:
+        v = a[tid_attr]
+        # An attribute selector, not getByTestId: a repository can point getByTestId at another attribute (data-test, data-qa).
+        css = f"[{tid_attr}={_q(v)}]"
+        add("test_id", v, f"page.locator({_q(css)})", attr=tid_attr, css=css)
+    if a.get("id"):
+        v = a["id"]
+        css = f"#{v}" if _css_ident(v) else f"[id={_q(v)}]"
+        add("id", v, f"page.locator({_q(css)})", css=css)
+    if role in ROLES and name and len(name) <= 80:
+        add("role", f"{role}|{name}", f"page.getByRole({_q(role)}, {{ name: {_q(name)}, exact: true }})", role=role, name=name)
+    if a.get("name"):
+        css = f"{tag}[name={_q(a['name'])}]"
+        add("name", a["name"], f"page.locator({_q(css)})", css=css)
+    if tag in FORM_TAGS:
+        label = a.get("aria-label") or (name if name and name not in (a.get("placeholder"), a.get("title")) else "")
+        if label and len(label) <= 80:
+            add("label", label, f"page.getByLabel({_q(label)}, {{ exact: true }})")
+        if a.get("placeholder"):
+            add("placeholder", a["placeholder"], f"page.getByPlaceholder({_q(a['placeholder'])}, {{ exact: true }})")
+    elif a.get("aria-label") and len(a["aria-label"]) <= 80 and not (role in ROLES and name == a["aria-label"]):
+        add("label", a["aria-label"], f"page.getByLabel({_q(a['aria-label'])}, {{ exact: true }})")
+    if a.get("alt"):
+        add("alt", a["alt"], f"page.getByAltText({_q(a['alt'])}, {{ exact: true }})")
+    if a.get("title"):
+        add("title", a["title"], f"page.getByTitle({_q(a['title'])}, {{ exact: true }})")
+    href = a.get("href") or ""
+    if tag == "a" and href and not href.startswith(("javascript:", "#")) and len(href) <= 200:
+        css = f"a[href={_q(href)}]"
+        add("href", href, f"page.locator({_q(css)})", css=css)
+    text = f.get("text") or (name if tag not in FORM_TAGS else "")
+    if text and len(text) <= 60 and tag not in FORM_TAGS:
+        add("text", text, f"page.getByText({_q(text)}, {{ exact: true }})")
+    classes = f.get("classes") or []
+    if classes:
+        css = tag + "".join(f".{c}" for c in classes[:2])
+        add("css", css, f"page.locator({_q(css)})", css=css)
+    if f.get("xpath"):
+        xp = "/" + str(f["xpath"]).lstrip("/")
+        add("xpath", xp, f"page.locator({_q('xpath=' + xp)})")
+    return out
+
+
+def confidence(loc: Dict[str, Any]) -> int:
+    """1-99: kind stability × uniqueness on the page × consistency across visits × replay success."""
+    matches = int(loc.get("matches") or 1)
+    unique = 1.0 if matches <= 1 else 0.5 / (matches - 1)
+    seen = max(1, int(loc.get("seen") or 1))
+    missed = int(loc.get("missed") or 0)
+    stability = (0.75 + 0.25 * min(seen, 4) / 4) * (seen / (seen + missed))
+    ok, bad = int(loc.get("success") or 0), int(loc.get("failure") or 0)
+    reliability = (ok + 1) / (ok + bad + 1)
+    return max(1, min(99, round(100 * float(loc.get("base") or 0.3) * unique * stability * reliability)))
+
+
+def rank(locs: Iterable[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    ranked = []
+    for loc in locs:
+        loc["confidence"] = confidence(loc)
+        ranked.append(loc)
+    ranked.sort(key=lambda l: (-l["confidence"], -BASE.get(l["type"], 0)))
+    return ranked[:MAX_LOCATORS_PER_ELEMENT]
+
+
+def _public_locator(loc: Dict[str, Any]) -> Dict[str, Any]:
+    keep = ("type", "value", "playwright", "confidence", "verified", "role", "name", "css", "attr")
+    return {k: loc[k] for k in keep if k in loc}
+
+
+def element_label(facts: Dict[str, Any]) -> str:
+    a = facts.get("attributes") or {}
+    return facts.get("name") or facts.get("text") or a.get("placeholder") or a.get("aria-label") or facts.get("tag") or ""
+
+
+# ---------------------------------------------------------------------------------------------
+# Store
+# ---------------------------------------------------------------------------------------------
+
+
+def goal_key(goal: str, start_url: Optional[str]) -> str:
+    norm = re.sub(r"\s+", " ", (goal or "").strip().lower()).rstrip(" .!")
+    return f"{norm}|{(start_url or '').strip().rstrip('/')}"
+
+
+class MemoryStore:
+    """Loads page files lazily, updates them in memory during a run, and writes them on flush()."""
+
+    def __init__(self, root: str | Path, run_id: Optional[str] = None) -> None:
+        self.root = Path(root).expanduser()
+        self.run_id = run_id or datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%f")
+        self._pages: Dict[str, Dict[str, Any]] = {}
+        self._files: Dict[str, Path] = {}
+        self._index: Dict[str, Dict[LocKey, str]] = {}
+        self._loaded: Dict[str, Any] = {}
+        self._base: Dict[str, Dict[str, Dict[str, Any]]] = {}
+        self._base_visits: Dict[str, int] = {}
+        self._dirty: Set[str] = set()
+        self.touched_pages: Set[str] = set()
+        self.touched_elements: Set[Tuple[str, str]] = set()
+        self.new_elements = 0
+
+    # -- pages ------------------------------------------------------------------------------
+
+    def _page(self, host: str, path: str) -> Tuple[str, Dict[str, Any]]:
+        pid = f"{host}{path}"
+        if pid in self._pages:
+            return pid, self._pages[pid]
+        file = self.root / "pages" / _host_dir(host) / f"{_page_slug(path)}.json"
+        page: Optional[Dict[str, Any]] = None
+        if file.is_file():
+            try:
+                page = json.loads(file.read_text(encoding="utf-8"))
+            except Exception:
+                page = None
+        if not isinstance(page, dict) or not isinstance(page.get("elements"), dict):
+            now = now_iso()
+            page = {
+                "version": VERSION, "host": host, "path": path, "title": "", "first_seen": now, "last_seen": now,
+                "visits": 0, "sample_urls": [], "elements": {},
+            }
+        self._pages[pid] = page
+        self._files[pid] = file
+        self._loaded[pid] = int(page.get("revision") or 0)
+        self._base[pid] = {key: _counts(entry) for key, entry in page["elements"].items()}
+        self._base_visits[pid] = int(page.get("visits") or 0)
+        index: Dict[LocKey, str] = {}
+        for key, entry in page["elements"].items():
+            for loc in entry.get("locators") or []:
+                if loc.get("type") in INDEXED:
+                    index.setdefault((loc["type"], loc["value"]), key)
+        self._index[pid] = index
+        return pid, page
+
+    def page_for_url(self, url: str) -> Optional[Dict[str, Any]]:
+        ref = page_ref(url)
+        return self._page(*ref)[1] if ref else None
+
+    def observe(self, url: str, title: str, selector_map: Dict[int, Any]) -> Dict[int, Dict[str, Any]]:
+        """Record every element in a library selector map. Returns index → {key, page, facts, locators, current}."""
+        ref = page_ref(url)
+        if not ref or not selector_map:
+            return {}
+        pid, page = self._page(*ref)
+        now = now_iso()
+        if page.get("last_run") != self.run_id:
+            page["visits"] = int(page.get("visits") or 0) + 1
+            page["last_run"] = self.run_id
+        page["last_seen"] = now
+        if title and title != ref[0] and not title.startswith(("http:", "https:")):
+            page["title"] = _clean(title, 200)
+        clean_url = (url or "").split("#")[0] if "#/" not in (url or "") else url
+        samples = [u for u in page.get("sample_urls") or [] if u != clean_url]
+        page["sample_urls"] = (samples + [clean_url])[-MAX_SAMPLE_URLS:]
+
+        snapshot: List[Tuple[int, Dict[str, Any], List[Dict[str, Any]]]] = []
+        for idx, node in selector_map.items():
+            try:
+                facts = element_facts(node)
+            except Exception:
+                continue
+            snapshot.append((int(idx), facts, candidate_locators(facts)))
+        counts = Counter((l["type"], l["value"]) for _, _, locs in snapshot for l in locs)
+
+        out: Dict[int, Dict[str, Any]] = {}
+        used: Set[str] = set()
+        for idx, facts, locs in snapshot:
+            for loc in locs:
+                loc["matches"] = counts[(loc["type"], loc["value"])]
+            key = self._identify(pid, page, facts, locs, used)
+            used.add(key)
+            entry = self._merge(pid, page, key, facts, locs, now)
+            out[idx] = {
+                "key": key,
+                "page": pid,
+                "facts": facts,
+                "locators": entry["locators"],
+                "current": {(l["type"], l["value"]): l["matches"] for l in locs},
+            }
+            self.touched_elements.add((pid, key))
+        self._prune(page)
+        self._dirty.add(pid)
+        self.touched_pages.add(pid)
+        return out
+
+    def _identify(self, pid: str, page: Dict[str, Any], facts: Dict[str, Any], locs: List[Dict[str, Any]], used: Set[str]) -> str:
+        elements = page["elements"]
+        strong = [l for l in locs if l["type"] in STRONG and l["matches"] == 1 and not l.get("generated")]
+        index = self._index[pid]
+        for loc in strong:
+            key = index.get((loc["type"], loc["value"]))
+            if key and key not in used and key in elements and elements[key].get("tag") == facts["tag"]:
+                return key
+        # Sites reuse the same popup container for different widgets, so a matching xpath only
+        # identifies the element when its role and accessible name or text agree too.
+        label = facts["name"] or facts["text"] or ""
+        for loc in (l for l in locs if l["type"] == "xpath"):
+            key = index.get((loc["type"], loc["value"]))
+            entry = elements.get(key) if key and key not in used else None
+            if (
+                entry
+                and entry.get("tag") == facts["tag"]
+                and (entry.get("role") or "") == (facts["role"] or "")
+                and (entry.get("name") or entry.get("text") or "") == label
+            ):
+                return key
+        if strong:
+            basis = f"{facts['tag']}|{strong[0]['type']}={strong[0]['value']}"
+        else:
+            basis = f"{facts['tag']}|xpath={facts['xpath']}|{facts['name'] or facts['text']}"
+        key = _sha(basis, 12)
+        if key in used:
+            key = _sha(f"{basis}|xpath={facts['xpath']}", 12)
+        return key
+
+    def _merge(self, pid: str, page: Dict[str, Any], key: str, facts: Dict[str, Any], locs: List[Dict[str, Any]], now: str) -> Dict[str, Any]:
+        elements = page["elements"]
+        entry = elements.get(key)
+        if entry is None:
+            entry = {"key": key, "first_seen": now, "visits": 0, "interactions": 0, "success": 0, "failure": 0, "locators": []}
+            elements[key] = entry
+            self.new_elements += 1
+        first_this_run = entry.get("last_run") != self.run_id
+        stored: Dict[LocKey, Dict[str, Any]] = {(l["type"], l["value"]): l for l in entry.get("locators") or []}
+        changed = False
+        current: Set[LocKey] = set()
+        for loc in locs:
+            k = (loc["type"], loc["value"])
+            current.add(k)
+            s = stored.get(k)
+            if s is None:
+                s = {kk: vv for kk, vv in loc.items()}
+                s.update(seen=1, missed=0, success=0, failure=0, first_seen=now)
+                stored[k] = s
+                changed = True
+            else:
+                if first_this_run:
+                    s["seen"] = int(s.get("seen") or 0) + 1
+                s.update(matches=loc["matches"], base=loc["base"], playwright=loc["playwright"])
+            s["last_seen"] = now
+        if first_this_run:
+            for k, s in stored.items():
+                if k not in current:
+                    s["missed"] = int(s.get("missed") or 0) + 1
+                    changed = True
+            entry["visits"] = int(entry.get("visits") or 0) + 1
+        entry.update(
+            tag=facts["tag"],
+            role=facts["role"] or None,
+            name=facts["name"] or None,
+            text=facts["text"] or None,
+            attributes=facts["attributes"],
+            xpath=facts["xpath"],
+            stable_hash=facts["stable_hash"],
+            last_seen=now,
+            last_run=self.run_id,
+        )
+        entry["locators"] = list(stored.values())
+        self._rerank(entry, now if changed or "last_updated" not in entry else None)
+        index = self._index[pid]
+        for loc in entry["locators"]:
+            if loc["type"] in INDEXED:
+                index.setdefault((loc["type"], loc["value"]), key)
+        return entry
+
+    @staticmethod
+    def _rerank(entry: Dict[str, Any], updated: Optional[str]) -> None:
+        entry["locators"] = rank(entry.get("locators") or [])
+        top = entry["locators"][0] if entry["locators"] else None
+        entry["best"] = top["playwright"] if top else None
+        entry["confidence"] = top["confidence"] if top else 0
+        if updated:
+            entry["last_updated"] = updated
+
+    @staticmethod
+    def _prune(page: Dict[str, Any]) -> None:
+        elements = page["elements"]
+        if len(elements) <= MAX_ELEMENTS_PER_PAGE:
+            return
+        order = sorted(elements.values(), key=lambda e: (e.get("interactions", 0) > 0, e.get("last_seen", "")))
+        for entry in order[: len(elements) - MAX_ELEMENTS_PER_PAGE]:
+            elements.pop(entry["key"], None)
+
+    def record_outcome(self, pid: str, key: str, ok: bool, locator: Optional[LocKey] = None, stale: Iterable[LocKey] = ()) -> None:
+        """An action on this element worked or failed; `locator` is the one replay resolved it with."""
+        page = self._pages.get(pid)
+        entry = (page or {}).get("elements", {}).get(key)
+        if not entry:
+            return
+        now = now_iso()
+        entry["interactions"] = int(entry.get("interactions") or 0) + 1
+        entry["success" if ok else "failure"] = int(entry.get("success" if ok else "failure") or 0) + 1
+        entry["last_used"] = now
+        self.touched_elements.add((pid, key))
+        by_key = {(l["type"], l["value"]): l for l in entry.get("locators") or []}
+        if locator and locator in by_key:
+            field = "success" if ok else "failure"
+            by_key[locator][field] = int(by_key[locator].get(field) or 0) + 1
+        for k in stale:
+            if k in by_key:
+                by_key[k]["failure"] = int(by_key[k].get("failure") or 0) + 1
+        self._rerank(entry, now)
+        self._dirty.add(pid)
+
+    def record_stale(self, pid: str, key: str, stale: Iterable[LocKey]) -> None:
+        """Replay found this recorded element's action on a different element; its locators in `stale` no longer find anything."""
+        entry = (self._pages.get(pid) or {}).get("elements", {}).get(key)
+        if not entry:
+            return
+        gone = set(stale)
+        changed = False
+        for loc in entry.get("locators") or []:
+            if (loc["type"], loc["value"]) in gone:
+                loc["failure"] = int(loc.get("failure") or 0) + 1
+                loc["missed"] = int(loc.get("missed") or 0) + 1
+                changed = True
+        if changed:
+            self.touched_elements.add((pid, key))
+            self._rerank(entry, now_iso())
+            self._dirty.add(pid)
+
+    def element(self, pid: str, key: str) -> Optional[Dict[str, Any]]:
+        if pid not in self._pages:
+            host_end = pid.find("/")
+            if host_end < 0:
+                return None
+            self._page(pid[:host_end], pid[host_end:])
+        return self._pages[pid]["elements"].get(key)
+
+    def flush(self) -> None:
+        """Write changed pages. When another run saved the same page since this one loaded it (parallel suites), the
+        saved copy is merged in first, so neither run's work is lost."""
+        if not self._dirty:
+            return
+        with _locked(self.root):
+            for pid in list(self._dirty):
+                page = self._pages[pid]
+                disk = _read_json(self._files[pid])
+                if disk and isinstance(disk.get("elements"), dict) and int(disk.get("revision") or 0) != self._loaded.get(pid):
+                    self._merge_saved(pid, page, disk)
+                page["element_count"] = len(page["elements"])
+                page["last_updated"] = now_iso()
+                page["revision"] = max(int(page.get("revision") or 0), int((disk or {}).get("revision") or 0)) + 1
+                _write_json(self._files[pid], page)
+                self._loaded[pid] = page["revision"]
+                self._base[pid] = {key: _counts(entry) for key, entry in page["elements"].items()}
+                self._base_visits[pid] = int(page.get("visits") or 0)
+        self._dirty.clear()
+
+    def _merge_saved(self, pid: str, page: Dict[str, Any], disk: Dict[str, Any]) -> None:
+        """Fold a copy saved by another run into this run's page: counters become saved + this run's increase."""
+        mine = {key for p, key in self.touched_elements if p == pid}
+        base = self._base.get(pid, {})
+        for key, saved in disk["elements"].items():
+            if key not in mine or key not in page["elements"]:
+                page["elements"][key] = saved
+                continue
+            entry = page["elements"][key]
+            start = base.get(key) or _counts({})
+            for f in _ELEMENT_COUNTS:
+                entry[f] = int(saved.get(f) or 0) + int(entry.get(f) or 0) - start["e"][f]
+            ours = {(l["type"], l["value"]): l for l in entry.get("locators") or []}
+            for sl in saved.get("locators") or []:
+                k = (sl["type"], sl["value"])
+                loc = ours.get(k)
+                if loc is None:
+                    ours[k] = sl
+                    continue
+                was = start["l"].get(k) or {}
+                for f in _LOCATOR_COUNTS:
+                    loc[f] = int(sl.get(f) or 0) + int(loc.get(f) or 0) - int(was.get(f) or 0)
+            entry["locators"] = list(ours.values())
+            self._rerank(entry, None)
+        page["visits"] = int(disk.get("visits") or 0) + int(page.get("visits") or 0) - self._base_visits.get(pid, 0)
+        self._prune(page)
+
+    def stats(self) -> Dict[str, int]:
+        return {"pages": len(self.touched_pages), "elements": len(self.touched_elements), "new_elements": self.new_elements}
+
+    # -- flows ------------------------------------------------------------------------------
+
+    def flow_file(self, goal: str, start_url: Optional[str]) -> Path:
+        key = goal_key(goal, start_url)
+        slug = re.sub(r"[^a-z0-9]+", "-", key.split("|", 1)[0])[:50].strip("-") or "goal"
+        return self.root / "flows" / f"{slug}-{_sha(key, 10)}.json"
+
+    def load_flow(self, goal: str, start_url: Optional[str]) -> Optional[Dict[str, Any]]:
+        file = self.flow_file(goal, start_url)
+        if not file.is_file():
+            return None
+        try:
+            flow = json.loads(file.read_text(encoding="utf-8"))
+        except Exception:
+            return None
+        return flow if isinstance(flow, dict) and isinstance(flow.get("steps"), list) else None
+
+    def checkpoint_file(self, goal: str, start_url: Optional[str]) -> Path:
+        return self.root / "checkpoints" / self.flow_file(goal, start_url).name
+
+    def save_checkpoint(self, goal: str, start_url: Optional[str], data: Dict[str, Any]) -> None:
+        """The steps that worked so far in a run still going, so a run cut off before it finished can be picked up."""
+        _write_json(self.checkpoint_file(goal, start_url), {"goal": goal, "start_url": start_url or "", **data, "at": now_iso()})
+
+    def load_checkpoint(self, goal: str, start_url: Optional[str]) -> Optional[Dict[str, Any]]:
+        data = _read_json(self.checkpoint_file(goal, start_url))
+        return data if data and isinstance(data.get("steps"), list) and data["steps"] else None
+
+    def clear_checkpoint(self, goal: str, start_url: Optional[str], run_ids: Iterable[str]) -> None:
+        """Remove the checkpoint when one of these runs wrote it: a run that finishes leaves its own result instead."""
+        file = self.checkpoint_file(goal, start_url)
+        data = _read_json(file)
+        if data is not None and str(data.get("run_id") or "") in {r for r in run_ids if r}:
+            file.unlink(missing_ok=True)
+
+    def save_flow_result(
+        self,
+        goal: str,
+        start_url: Optional[str],
+        *,
+        status: str,
+        steps: List[Dict[str, Any]],
+        summary: str = "",
+        final_url: str = "",
+        replayed: int = 0,
+        llm_steps: int = 0,
+        resume: Optional[Dict[str, Any]] = None,
+    ) -> Optional[str]:
+        """
+        Update the goal's flow after a run. Only successful runs replace its steps. Returns "saved" or "updated".
+
+        A failed run with `resume` (the steps that worked before it went wrong) keeps them under "resume", so the
+        next run of this task replays them and the agent picks up where the failed run went wrong.
+        """
+        if status == "stopped":
+            return None
+        with _locked(self.root):
+            return self._save_flow_result(goal, start_url, status=status, steps=steps, summary=summary,
+                                          final_url=final_url, replayed=replayed, llm_steps=llm_steps, resume=resume)
+
+    def _save_flow_result(self, goal: str, start_url: Optional[str], *, status: str, steps: List[Dict[str, Any]],
+                          summary: str, final_url: str, replayed: int, llm_steps: int,
+                          resume: Optional[Dict[str, Any]] = None) -> Optional[str]:
+        file = self.flow_file(goal, start_url)
+        flow = self.load_flow(goal, start_url)
+        created = flow is None
+        keep_resume = status == "fail" and bool(resume and resume.get("steps"))
+        if created and not keep_resume and (status != "complete" or not steps):
+            return None
+        now = now_iso()
+        if flow is None:
+            flow = {"version": VERSION, "goal": goal, "start_url": start_url or "", "created": now,
+                    "runs": 0, "successes": 0, "failures": 0, "replays": 0, "steps": []}
+        flow["runs"] = int(flow.get("runs") or 0) + 1
+        if replayed:
+            flow["replays"] = int(flow.get("replays") or 0) + 1
+        if status == "complete" and steps:
+            flow["successes"] = int(flow.get("successes") or 0) + 1
+            flow["steps"] = steps[:MAX_FLOW_STEPS]
+            flow["host"] = _flow_host(steps, start_url)
+            flow["last_success"] = now
+            flow["summary"] = (summary or "")[:2000]
+            flow["final_url"] = final_url or ""
+            flow["llm_steps"] = llm_steps
+            flow["replayed_steps"] = replayed
+            flow.pop("resume", None)
+        elif status != "complete":
+            flow["failures"] = int(flow.get("failures") or 0) + 1
+        if keep_resume and resume:
+            flow["resume"] = {**resume, "steps": list(resume["steps"])[:MAX_FLOW_STEPS], "at": now}
+            flow.setdefault("host", _flow_host(resume["steps"], start_url))
+        flow["last_status"] = status
+        flow["last_run"] = now
+        flow["updated"] = now
+        _write_json(file, flow)
+        if created and status != "complete":
+            return None
+        return "saved" if created else "updated"
+
+    def recent_flows(self, host: str, *, exclude: Optional[Path] = None, limit: int = 2) -> List[Dict[str, Any]]:
+        folder = self.root / "flows"
+        if not folder.is_dir():
+            return []
+        found = []
+        for file in folder.glob("*.json"):
+            if exclude is not None and file.resolve() == exclude.resolve():
+                continue
+            try:
+                flow = json.loads(file.read_text(encoding="utf-8"))
+            except Exception:
+                continue
+            if isinstance(flow, dict) and flow.get("host") == host and flow.get("successes") and flow.get("steps"):
+                found.append(flow)
+        found.sort(key=lambda f: str(f.get("last_success") or ""), reverse=True)
+        return found[:limit]
+
+    def pages_for_host(self, host: str) -> List[Dict[str, Any]]:
+        folder = self.root / "pages" / _host_dir(host)
+        pages = []
+        for file in folder.glob("*.json") if folder.is_dir() else []:
+            try:
+                page = json.loads(file.read_text(encoding="utf-8"))
+            except Exception:
+                continue
+            if isinstance(page, dict):
+                pages.append(page)
+        pages.sort(key=lambda p: -int(p.get("visits") or 0))
+        return pages
+
+    def prompt_hints(self, start_url: Optional[str], goal: str, *, max_chars: int = 2500) -> str:
+        """Short system-prompt section: earlier successful paths on this site and the pages seen there."""
+        ref = page_ref(start_url or "")
+        if not ref:
+            return ""
+        host = ref[0]
+        lines: List[str] = []
+        flows = self.recent_flows(host, exclude=self.flow_file(goal, start_url))
+        if flows:
+            lines.append("Earlier successful runs of other tasks on this site. Reuse the steps that also apply to this task (a banner, a sign-in, a search form), skip the rest; the live page wins when it differs:")
+            for flow in flows:
+                lines.append(f'- "{_clean(flow.get("goal"), 140)}"')
+                for step in flow["steps"][:15]:
+                    lines.append(f"    {_clean(step.get('line') or step.get('action'), 140)}")
+        pages = self.pages_for_host(host)[:6]
+        if pages:
+            lines.append("Pages seen on this site before, with the controls that already worked:")
+            for page in pages:
+                sample = (page.get("sample_urls") or [""])[-1]
+                lines.append(f"- {page.get('path')} — {_clean(page.get('title'), 60)} ({_clean(sample, 160)})")
+                controls = _worked_controls(page)
+                if controls:
+                    lines.append(f"    {controls}")
+        if not lines:
+            return ""
+        text = (
+            "## Site memory from earlier ForgeQE runs\n"
+            "Do these steps in one turn where the page already shows the controls. "
+            "Do not spend a turn exploring a page listed here.\n"
+            + "\n".join(lines)
+        )
+        return text if len(text) <= max_chars else text[: max_chars - 20] + "\n…(memory truncated)"
+
+
+def _worked_controls(page: Dict[str, Any], limit: int = 6) -> str:
+    """Controls a previous run actually used, so the model can act on them instead of searching the page."""
+    elements = [e for e in (page.get("elements") or {}).values() if isinstance(e, dict) and int(e.get("success") or 0) > 0]
+    elements.sort(key=lambda e: (-int(e.get("success") or 0), -int(e.get("confidence") or 0)))
+    bits = []
+    for entry in elements[:limit]:
+        attrs = entry.get("attributes") or {}
+        label = entry.get("name") or entry.get("text") or attrs.get("placeholder") or attrs.get("aria-label") or entry.get("tag")
+        loc = (entry.get("locators") or [{}])[0]
+        kind = loc.get("type") or "locator"
+        conf = loc.get("confidence") or entry.get("confidence") or 0
+        bits.append(f"{_clean(label, 40)} ({kind} {conf}%)")
+    return "use these, do not look for them: " + ", ".join(bits) if bits else ""
+
+
+def _flow_host(steps: List[Dict[str, Any]], start_url: Optional[str]) -> str:
+    ref = page_ref(start_url or "")
+    if ref:
+        return ref[0]
+    for step in steps:
+        url = (step.get("params") or {}).get("url") if step.get("action") == "navigate" else None
+        ref = page_ref(url or "") if url else None
+        if ref:
+            return ref[0]
+        if step.get("page"):
+            return str(step["page"]).split("/", 1)[0]
+    return ""
+
+
+_ELEMENT_COUNTS = ("visits", "interactions", "success", "failure")
+_LOCATOR_COUNTS = ("seen", "missed", "success", "failure")
+
+
+def _counts(entry: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "e": {f: int(entry.get(f) or 0) for f in _ELEMENT_COUNTS},
+        "l": {(l["type"], l["value"]): {f: int(l.get(f) or 0) for f in _LOCATOR_COUNTS} for l in entry.get("locators") or []},
+    }
+
+
+@contextmanager
+def _locked(root: Path) -> Iterator[None]:
+    """Exclusive lock on the memory folder for the read-merge-write at the end of a run."""
+    root.mkdir(parents=True, exist_ok=True)
+    with open(root / ".lock", "a+") as handle:
+        try:
+            import fcntl
+        except ImportError:
+            import msvcrt
+
+            handle.seek(0)
+            while True:
+                try:
+                    msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+                    break
+                except OSError:
+                    continue
+            try:
+                yield
+            finally:
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+            return
+        fcntl.flock(handle, fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(handle, fcntl.LOCK_UN)
+
+
+def _read_json(file: Path) -> Optional[Dict[str, Any]]:
+    if not file.is_file():
+        return None
+    try:
+        data = json.loads(file.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _write_json(file: Path, data: Dict[str, Any]) -> None:
+    file.parent.mkdir(parents=True, exist_ok=True)
+    tmp = file.with_suffix(f".{os.getpid()}.tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False, default=str), encoding="utf-8")
+    os.replace(tmp, file)
+
+
+# ---------------------------------------------------------------------------------------------
+# Flow steps
+# ---------------------------------------------------------------------------------------------
+
+
+def _secret_env(text: Any) -> Optional[str]:
+    if not text:
+        return None
+    for name in (*SECRET_ENV_VARS, *text_envs()):
+        if os.environ.get(name) and str(text) == os.environ[name]:
+            return name
+    return None
+
+
+def _present_first(target: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """The element's ranked locators, those that found it on the page just now ahead of ones only seen on earlier visits."""
+    current = target.get("current") or {}
+    locs = list(target.get("locators") or [])
+    return [l for l in locs if (l["type"], l["value"]) in current] + [l for l in locs if (l["type"], l["value"]) not in current]
+
+
+def flow_step(action: str, params: Dict[str, Any], target: Optional[Dict[str, Any]], line: str) -> Dict[str, Any]:
+    """One replayable action. Element actions keep the element's ranked locators and fingerprint, never its index."""
+    step: Dict[str, Any] = {"action": action, "params": {k: v for k, v in (params or {}).items() if k != "index"}, "line": line}
+    if action == "input" and not step["params"].get("totp_env"):
+        text = step["params"].get("text")
+        ref = secret_ref(text)
+        env = ref[1] if ref and ref[0] == "text" else _secret_env(text)
+        if ref and ref[0] == "totp":
+            step["params"]["text"] = None
+            step["params"]["totp_env"] = ref[1]
+        elif env:
+            step["params"]["text"] = None
+            step["params"]["text_env"] = env
+        elif target and (target["facts"].get("attributes") or {}).get("type") == "password":
+            step["params"]["text"] = None
+            step["secret"] = True
+        if (env or ref or step.get("secret")) and text:
+            step["line"] = line.replace(str(text), "***")
+    if target:
+        facts = target["facts"]
+        step.update(
+            page=target["page"],
+            element=target["key"],
+            label=element_label(facts),
+            locators=[_public_locator(l) for l in _present_first(target)[:FLOW_STEP_LOCATORS]],
+            fingerprint={
+                "tag": facts["tag"],
+                "role": facts["role"],
+                "name": facts["name"],
+                "stable_hash": facts["stable_hash"],
+                "xpath": facts["xpath"],
+            },
+        )
+    return step
+
+
+def resolve_step(
+    step: Dict[str, Any], snapshot: Dict[int, Dict[str, Any]], store: Optional[MemoryStore] = None
+) -> Tuple[Optional[int], Optional[LocKey], List[LocKey]]:
+    """
+    Find a recorded step's element in the current page snapshot (from MemoryStore.observe).
+    Tries locators from most to least confident; returns (index, locator used, locators that matched nothing).
+    """
+    locs = list(step.get("locators") or [])
+    if store and step.get("page") and step.get("element"):
+        entry = store.element(step["page"], step["element"])
+        if entry and entry.get("locators"):
+            fresh = {(l["type"], l["value"]) for l in entry["locators"]}
+            locs = entry["locators"] + [l for l in locs if (l["type"], l["value"]) not in fresh]
+    fp = step.get("fingerprint") or {}
+    stale: List[LocKey] = []
+    for loc in locs:
+        k = (loc["type"], loc["value"])
+        hits = [idx for idx, e in snapshot.items() if k in e["current"]]
+        if len(hits) == 1:
+            return hits[0], k, stale
+        if len(hits) > 1:
+            narrowed = [
+                i for i in hits
+                if snapshot[i]["facts"]["tag"] == fp.get("tag") and (not fp.get("name") or snapshot[i]["facts"]["name"] == fp.get("name"))
+            ]
+            if len(narrowed) == 1:
+                return narrowed[0], k, stale
+            continue
+        stale.append(k)
+    key = step.get("element")
+    hits = [idx for idx, e in snapshot.items() if key and e["key"] == key]
+    if len(hits) == 1:
+        return hits[0], None, stale
+    if fp.get("stable_hash") is not None:
+        hits = [idx for idx, e in snapshot.items() if e["facts"].get("stable_hash") == fp["stable_hash"]]
+        if len(hits) == 1:
+            return hits[0], None, stale
+    return None, None, stale
+
+
+def compact_step(step: Dict[str, Any]) -> Dict[str, Any]:
+    """Flow step → workflow.yaml step, carrying the best-ranked locator and the browser agent's note for the step."""
+    out = _compact_step(step)
+    if step.get("scripted"):
+        out["scripted"] = True
+    if step.get("overlay"):
+        out["overlay"] = step["overlay"]
+    if step.get("note"):
+        out["note"] = step["note"]
+    return out
+
+
+def _compact_step(step: Dict[str, Any]) -> Dict[str, Any]:
+    action = step.get("action") or ""
+    p = step.get("params") or {}
+    if action == "navigate":
+        return {"op": "navigate", "url": p.get("url") or ""}
+    if action in ("click", "input", "select_dropdown"):
+        locs = step.get("locators") or []
+        fp = step.get("fingerprint") or {}
+        out: Dict[str, Any] = {
+            "op": {"click": "click", "input": "input", "select_dropdown": "select"}[action],
+            "page": step.get("page") or "",
+            "label": step.get("label") or "",
+            "best_locator": locs[0]["playwright"] if locs else None,
+            "locators": [
+                {"type": l["type"], "value": l["value"], "confidence": l.get("confidence"), **{k: l[k] for k in ("css", "attr", "verified") if l.get(k)}}
+                for l in locs
+            ],
+            "locator": {k: v for k, v in {"tag": (fp.get("tag") or "").upper(), "role": fp.get("role"), "name": fp.get("name")}.items() if v},
+        }
+        if action == "input":
+            out["text"] = p.get("text") if p.get("text") is not None else ""
+            out["clear"] = bool(p.get("clear", False))
+            if p.get("text_env"):
+                out["text_env"] = p["text_env"]
+            if p.get("totp_env"):
+                out["totp_env"] = p["totp_env"]
+        if action == "select_dropdown":
+            out["text"] = p.get("text") or ""
+        return out
+    if action == "send_keys":
+        return {"op": "press", "keys": p.get("keys") or ""}
+    if action == "wait":
+        return {"op": "wait", "seconds": p.get("seconds") or 1}
+    if action == "scroll":
+        return {"op": "scroll", "down": p.get("down", True), "pages": p.get("pages") or 1}
+    if action == "go_back":
+        return {"op": "back"}
+    if action == "evaluate":
+        return {"op": "evaluate", "code": str(p.get("code") or "")[:2000]}
+    return {"op": "unknown", "action_keys": [action]}