@capagents/forgeqe 0.0.0-stage → 1.0.1

package/py/forgeqe_engine/workflow_yaml.py

@@ -0,0 +1,689 @@
+"""
+Persist engine runs as compact YAML (format ``forgeqe-v2-compact``).
+
+Walks AgentHistory (or the live per-step trace when history is missing) into replayable
+steps with semantic locators, and records execution metadata that explains partial runs.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import logging
+import os
+import re
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+FORMAT_V2_COMPACT = "forgeqe-v2-compact"
+
+
+def _sanitize_jsonish(obj: Any) -> Any:
+    """Recursively coerce values to YAML/JSON-safe primitives."""
+    if obj is None or isinstance(obj, (bool, int, float, str)):
+        return obj
+    if isinstance(obj, dict):
+        return {str(k): _sanitize_jsonish(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_sanitize_jsonish(x) for x in obj]
+    if isinstance(obj, (datetime,)):
+        return obj.isoformat()
+    try:
+        return json.loads(json.dumps(obj, default=str))
+    except (TypeError, ValueError):
+        return str(obj)
+
+
+def _truthy_include_full_history() -> bool:
+    raw = os.getenv("BROWSER_USE_YAML_INCLUDE_FULL_HISTORY")
+    if raw is None:
+        return False
+    return str(raw).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _to_action_dict(act: Any) -> Optional[Dict[str, Any]]:
+    if act is None:
+        return None
+    if isinstance(act, dict):
+        return act
+    try:
+        if hasattr(act, "model_dump"):
+            return act.model_dump(mode="json")
+    except Exception:
+        pass
+    return None
+
+
+def _to_dict_model(obj: Any) -> Optional[Dict[str, Any]]:
+    if obj is None:
+        return None
+    if isinstance(obj, dict):
+        return obj
+    try:
+        if hasattr(obj, "model_dump"):
+            return obj.model_dump(mode="json")
+        # DOMInteractedElement is a dataclass whose to_dict() omits ax_name.
+        if hasattr(obj, "to_dict"):
+            d = dict(obj.to_dict())
+            if getattr(obj, "ax_name", None) is not None:
+                d.setdefault("ax_name", obj.ax_name)
+            return d
+        if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+            return dataclasses.asdict(obj)
+    except Exception:
+        pass
+    return None
+
+
+def _locator_from_interacted(ie: Any) -> Dict[str, Any]:
+    """Pick stable fields from the library's interacted_element for replay / test specs."""
+    d = _to_dict_model(ie)
+    if not d:
+        return {}
+    attrs = d.get("attributes") if isinstance(d.get("attributes"), dict) else {}
+    out: Dict[str, Any] = {}
+    if attrs.get("id"):
+        out["id"] = str(attrs["id"])
+    for key in ("data-test-id", "data-testid"):
+        if attrs.get(key):
+            out["test_id"] = str(attrs[key])
+            break
+    if attrs.get("name"):
+        out["name_attr"] = str(attrs["name"])
+    if attrs.get("href"):
+        out["href"] = str(attrs["href"])
+    if attrs.get("role"):
+        out["role"] = str(attrs["role"])
+    if attrs.get("type"):
+        out["input_type"] = str(attrs["type"])
+    an = d.get("ax_name")
+    if an is not None and str(an).strip():
+        out["name"] = str(an).strip()
+    nn = d.get("node_name")
+    if nn:
+        out["tag"] = str(nn).strip()
+    return out
+
+
+def _locator_from_extracted_text(text: str) -> Dict[str, Any]:
+    """
+    Parse compact locator hints from the library's extracted_content lines.
+    Examples:
+      Clicked button "Accept cookies" id=onetrust-accept-btn-handler
+      Clicked input type=button role=combobox id=:R1bmt6:-form-item name=Title
+      Clicked li role=option "Mr" id=listbox-xxxx-option-0
+    """
+    t = (text or "").strip()
+    if not t:
+        return {}
+    out: Dict[str, Any] = {}
+
+    m_testid = re.search(r"\b(?:data-test-id|data-testid)=([^\s]+)", t)
+    if m_testid:
+        out["test_id"] = m_testid.group(1).strip().strip('"').strip("'")
+    m_id = re.search(r"\bid=([^\s]+)", t)
+    if m_id:
+        out["id"] = m_id.group(1).strip().strip('"').strip("'")
+    m_role = re.search(r"\brole=([^\s]+)", t)
+    if m_role:
+        out["role"] = m_role.group(1).strip().strip('"').strip("'")
+    m_type = re.search(r"\btype=([^\s]+)", t)
+    if m_type:
+        out["input_type"] = m_type.group(1).strip().strip('"').strip("'")
+    m_name_attr = re.search(r"\bname=([^\s]+)", t)
+    if m_name_attr:
+        out["name_attr"] = m_name_attr.group(1).strip().strip('"').strip("'")
+
+    m_label = re.search(r'\"([^\"]+)\"', t)
+    if m_label:
+        lbl = m_label.group(1).strip()
+        if lbl:
+            out["name"] = lbl
+
+    lower = t.lower()
+    if "clicked button" in lower:
+        out.setdefault("tag", "BUTTON")
+    elif "clicked input" in lower or "typed '" in lower:
+        out.setdefault("tag", "INPUT")
+    elif "clicked li" in lower:
+        out.setdefault("tag", "LI")
+    elif "clicked a " in lower or "clicked link" in lower:
+        out.setdefault("tag", "A")
+
+    return out
+
+
+def _merge_locator(primary: Dict[str, Any], fallback: Dict[str, Any]) -> Dict[str, Any]:
+    if not primary:
+        return dict(fallback or {})
+    if not fallback:
+        return dict(primary or {})
+    out = dict(primary)
+    for k, v in fallback.items():
+        if k not in out or out.get(k) in (None, ""):
+            out[k] = v
+    return out
+
+
+def _normalize_locator_for_replay(locator: Dict[str, Any], extracted_text: str) -> Dict[str, Any]:
+    """Canonicalize flaky locators so capture and replay use the same stable intent."""
+    loc = dict(locator or {})
+    text = (extracted_text or "").strip().lower()
+    name = str(loc.get("name") or "").strip().lower()
+    eid = str(loc.get("id") or "").strip()
+    tag = str(loc.get("tag") or "").strip().upper()
+
+    # Cookie banners often expose a dialog/container id while the actionable control is a button.
+    cookie_accept = (
+        "allow all cookies" in name
+        or "accept all" in name
+        or ("cookie" in text and ("allow" in text or "accept" in text))
+    )
+    weak_cookie_container_id = eid in {"CybotCookiebotDialog", "CybotCookiebotDialogBodyUnderlay"}
+    if cookie_accept and weak_cookie_container_id:
+        loc.pop("id", None)
+        if not str(loc.get("tag") or "").strip():
+            loc["tag"] = "BUTTON"
+        elif tag in {"DIV", "SPAN"}:
+            loc["tag"] = "BUTTON"
+
+    return loc
+
+
+def _semantic_locators_from_locator(locator: Dict[str, Any]) -> Dict[str, Any]:
+    """Explicit semantic locator variants for deterministic replay, Playwright-friendly."""
+    loc = locator or {}
+    sem: Dict[str, Any] = {}
+
+    test_id = str(loc.get("test_id") or "").strip()
+    elem_id = str(loc.get("id") or "").strip()
+    role = str(loc.get("role") or "").strip()
+    name = str(loc.get("name") or "").strip()
+    name_attr = str(loc.get("name_attr") or "").strip()
+    href = str(loc.get("href") or "").strip()
+    tag = str(loc.get("tag") or "").strip().upper()
+
+    if test_id:
+        sem["by_test_id"] = test_id
+    if elem_id:
+        sem["by_id"] = elem_id
+    if name_attr:
+        sem["by_name_attr"] = name_attr
+    if href:
+        sem["by_href"] = href
+    if role:
+        sem["by_role"] = {"role": role, "name": name} if name else {"role": role}
+    if name:
+        sem["by_text"] = name
+        sem["by_label"] = name
+    if tag:
+        sem["element_tag"] = tag
+
+    return sem
+
+
+def _selector_candidates_from_semantic(semantic: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Ordered selector attempts used by replay. Earlier entries are preferred."""
+    s = semantic or {}
+    out: List[Dict[str, Any]] = []
+    if s.get("by_test_id"):
+        out.append({"type": "test_id", "value": s["by_test_id"]})
+    if s.get("by_id"):
+        out.append({"type": "css", "value": f"#{s['by_id']}"})
+    if s.get("by_name_attr"):
+        out.append({"type": "css", "value": f"[name='{s['by_name_attr']}']"})
+    if s.get("by_href"):
+        out.append({"type": "css", "value": f"a[href='{s['by_href']}']"})
+    by_role = s.get("by_role")
+    if isinstance(by_role, dict) and by_role.get("role"):
+        cand = {"type": "role", "role": str(by_role["role"])}
+        if by_role.get("name"):
+            cand["name"] = str(by_role["name"])
+        out.append(cand)
+    if s.get("by_label"):
+        out.append({"type": "label", "value": s["by_label"]})
+    if s.get("by_text"):
+        out.append({"type": "text", "value": s["by_text"]})
+    return out
+
+
+def _is_actionable_locator(locator: Dict[str, Any]) -> bool:
+    if not isinstance(locator, dict) or not locator:
+        return False
+    keys = ("test_id", "id", "name_attr", "href", "name", "role")
+    return any(str(locator.get(k) or "").strip() for k in keys)
+
+
+def build_compact_steps_from_history(history: Any) -> List[Dict[str, Any]]:
+    """
+    Walk the library's AgentHistory and emit minimal steps for deterministic replay and readable YAML.
+
+    Each step: op, optional url/title/page_url, locator (semantic), index fallback for audit.
+    """
+    out: List[Dict[str, Any]] = []
+    entries = getattr(history, "history", None)
+    if not isinstance(entries, list):
+        return out
+
+    for entry in entries:
+        mo = getattr(entry, "model_output", None)
+        if mo is None:
+            continue
+        actions = getattr(mo, "action", None) or []
+        if not isinstance(actions, list):
+            continue
+        results = getattr(entry, "result", None) or []
+        if not isinstance(results, list):
+            results = []
+        st = getattr(entry, "state", None)
+        url = ""
+        title = ""
+        if st is not None:
+            url = getattr(st, "url", None) or ""
+            title = getattr(st, "title", None) or ""
+        interacted = getattr(st, "interacted_element", None) if st is not None else None
+        if not isinstance(interacted, list):
+            interacted = [interacted] if interacted is not None else []
+        ie_list: List[Optional[Dict[str, Any]]] = []
+        for ie in interacted:
+            ie_list.append(_to_dict_model(ie))
+
+        # The library keeps interacted_element and result aligned with the actions, one slot per action.
+        for ie_idx, act in enumerate(actions):
+            ad = _to_action_dict(act)
+            if not ad:
+                continue
+            if "done" in ad:
+                continue
+            if "navigate" in ad and isinstance(ad["navigate"], dict):
+                nav = ad["navigate"]
+                out.append({"op": "navigate", "url": nav.get("url") or "", "page_url": url, "title": title})
+                continue
+            if "go_to_url" in ad and isinstance(ad["go_to_url"], dict):
+                gu = ad["go_to_url"]
+                out.append({"op": "navigate", "url": gu.get("url") or "", "page_url": url, "title": title})
+                continue
+            if "click" in ad and isinstance(ad["click"], dict):
+                ck = ad["click"]
+                idx = ck.get("index")
+                ie = ie_list[ie_idx] if ie_idx < len(ie_list) else None
+                loc = _locator_from_interacted(ie)
+                res_txt = ""
+                if ie_idx < len(results):
+                    rr = _to_dict_model(results[ie_idx]) or {}
+                    res_txt = str(rr.get("extracted_content") or "")
+                loc = _merge_locator(loc, _locator_from_extracted_text(res_txt))
+                loc = _normalize_locator_for_replay(loc, res_txt)
+                sem = _semantic_locators_from_locator(loc)
+                cands = _selector_candidates_from_semantic(sem)
+                if _is_actionable_locator(loc) or len(cands) > 0:
+                    out.append(
+                        {
+                            "op": "click",
+                            "page_url": url,
+                            "title": title,
+                            "index": idx,
+                            "locator": loc,
+                            "semantic_locators": sem,
+                            "selector_candidates": cands,
+                        }
+                    )
+                continue
+            inp_dict: Optional[Dict[str, Any]] = None
+            if "input" in ad and isinstance(ad["input"], dict):
+                inp_dict = ad["input"]
+            elif "input_text" in ad and isinstance(ad["input_text"], dict):
+                it0 = ad["input_text"]
+                inp_dict = {
+                    "text": it0.get("text") if it0.get("text") is not None else it0.get("value") or "",
+                    "clear": bool(it0.get("clear", True)),
+                    "index": it0.get("index"),
+                }
+            if inp_dict is not None:
+                inp = inp_dict
+                ie = ie_list[ie_idx] if ie_idx < len(ie_list) else None
+                loc = _locator_from_interacted(ie)
+                res_txt = ""
+                if ie_idx < len(results):
+                    rr = _to_dict_model(results[ie_idx]) or {}
+                    res_txt = str(rr.get("extracted_content") or "")
+                loc = _merge_locator(loc, _locator_from_extracted_text(res_txt))
+                loc = _normalize_locator_for_replay(loc, res_txt)
+                sem = _semantic_locators_from_locator(loc)
+                cands = _selector_candidates_from_semantic(sem)
+                if _is_actionable_locator(loc) or len(cands) > 0:
+                    out.append(
+                        {
+                            "op": "input",
+                            "page_url": url,
+                            "title": title,
+                            "text": inp.get("text", ""),
+                            "clear": bool(inp.get("clear", False)),
+                            "index": inp.get("index"),
+                            "locator": loc,
+                            "semantic_locators": sem,
+                            "selector_candidates": cands,
+                        }
+                    )
+                continue
+            if "wait" in ad and isinstance(ad["wait"], dict):
+                w = ad["wait"]
+                try:
+                    sec = float(w.get("seconds") or 0)
+                except (TypeError, ValueError):
+                    sec = 0.0
+                out.append({"op": "wait", "seconds": sec, "page_url": url})
+                continue
+            keys = [k for k in ad.keys() if k not in ("done",)]
+            if keys:
+                out.append({"op": "unknown", "action_keys": keys, "page_url": url, "raw": ad})
+
+    return out
+
+
+def _first_navigate_step_from_live_trace(collected_steps: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """When full action parsing yields nothing, emit a single navigate so replay can at least open the app."""
+    if not isinstance(collected_steps, list):
+        return None
+    for st in collected_steps:
+        if not isinstance(st, dict):
+            continue
+        page_url = str(st.get("url") or "").strip()
+        title = str(st.get("title") or "").strip()
+        for act in st.get("actions") or []:
+            if not isinstance(act, dict):
+                continue
+            nav = act.get("navigate")
+            if isinstance(nav, dict):
+                u = str(nav.get("url") or "").strip()
+                if u:
+                    return {"op": "navigate", "url": u, "page_url": page_url or u, "title": title}
+            gu = act.get("go_to_url")
+            if isinstance(gu, dict):
+                u = str(gu.get("url") or "").strip()
+                if u:
+                    return {"op": "navigate", "url": u, "page_url": page_url or u, "title": title}
+        if page_url.startswith("http"):
+            return {"op": "navigate", "url": page_url, "page_url": page_url, "title": title}
+    return None
+
+
+def build_compact_steps_from_live_trace(collected_steps: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Rebuild compact replay steps from per-step callback payloads when AgentHistory is unavailable."""
+    out: List[Dict[str, Any]] = []
+    if not isinstance(collected_steps, list):
+        return out
+    for st in collected_steps:
+        if not isinstance(st, dict):
+            continue
+        url = str(st.get("url") or "")
+        title = str(st.get("title") or "")
+        for act in st.get("actions") or []:
+            if not isinstance(act, dict):
+                continue
+            if "navigate" in act and isinstance(act["navigate"], dict):
+                nu = str(act["navigate"].get("url") or "").strip()
+                if nu:
+                    out.append({"op": "navigate", "url": nu, "page_url": url, "title": title})
+                continue
+            if "go_to_url" in act and isinstance(act["go_to_url"], dict):
+                nu = str(act["go_to_url"].get("url") or "").strip()
+                if nu:
+                    out.append({"op": "navigate", "url": nu, "page_url": url, "title": title})
+                continue
+            if "click" in act and isinstance(act["click"], dict):
+                idx = act["click"].get("index")
+                ie = act.get("interacted_element")
+                loc = _locator_from_interacted(ie) if ie is not None else {}
+                sem = _semantic_locators_from_locator(loc)
+                cands = _selector_candidates_from_semantic(sem)
+                if _is_actionable_locator(loc) or cands:
+                    out.append(
+                        {
+                            "op": "click",
+                            "page_url": url,
+                            "title": title,
+                            "index": idx,
+                            "locator": loc,
+                            "semantic_locators": sem,
+                            "selector_candidates": cands,
+                        }
+                    )
+                continue
+            inp_live: Optional[Dict[str, Any]] = None
+            if "input" in act and isinstance(act["input"], dict):
+                inp_live = act["input"]
+            elif "input_text" in act and isinstance(act["input_text"], dict):
+                it1 = act["input_text"]
+                inp_live = {
+                    "text": it1.get("text") if it1.get("text") is not None else it1.get("value") or "",
+                    "clear": bool(it1.get("clear", True)),
+                    "index": it1.get("index"),
+                }
+            if inp_live is not None:
+                ie = act.get("interacted_element")
+                loc = _locator_from_interacted(ie) if ie is not None else {}
+                sem = _semantic_locators_from_locator(loc)
+                cands = _selector_candidates_from_semantic(sem)
+                if _is_actionable_locator(loc) or cands:
+                    out.append(
+                        {
+                            "op": "input",
+                            "page_url": url,
+                            "title": title,
+                            "text": str(inp_live.get("text") or ""),
+                            "clear": bool(inp_live.get("clear", False)),
+                            "index": inp_live.get("index"),
+                            "locator": loc,
+                            "semantic_locators": sem,
+                            "selector_candidates": cands,
+                        }
+                    )
+                continue
+            if "wait" in act and isinstance(act["wait"], dict):
+                try:
+                    sec = float(act["wait"].get("seconds") or 0)
+                except (TypeError, ValueError):
+                    sec = 0.0
+                out.append({"op": "wait", "seconds": sec, "page_url": url})
+                continue
+            keys = [k for k in act.keys() if k not in ("done", "interacted_element")]
+            if keys:
+                out.append({"op": "unknown", "action_keys": keys, "page_url": url, "raw": act})
+    return out
+
+
+def build_execution_context_for_live_trace(
+    *,
+    success: bool,
+    summary: str,
+    compact_steps: List[Dict[str, Any]],
+    source: str = "live_trace",
+) -> Dict[str, Any]:
+    """Execution metadata when AgentHistory is not available."""
+    nav_n = sum(1 for s in compact_steps if s.get("op") == "navigate")
+    interact_n = sum(1 for s in compact_steps if s.get("op") in ("click", "input"))
+    wait_n = sum(1 for s in compact_steps if s.get("op") == "wait")
+    unknown_n = sum(1 for s in compact_steps if s.get("op") == "unknown")
+    notes = [
+        "This workflow was saved from the live step trace (per-step callback), "
+        f"because the run ended with `{source}` or history could not be serialized. "
+        "Replay may be partial; run the goal again after fixes for a full history-based file."
+    ]
+    return _sanitize_jsonish(
+        {
+            "run_successful": success,
+            "recorded_counts": {"navigate": nav_n, "click_input": interact_n, "wait": wait_n, "unknown": unknown_n},
+            "summary_excerpt": (summary or "")[:2500],
+            "replay_notes": notes,
+        }
+    )
+
+
+def build_execution_context_for_yaml(
+    history: Any,
+    *,
+    success: bool,
+    summary: str,
+    compact_steps: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    """Metadata that explains why replay may be partial (e.g. LLM connection errors after the first navigate)."""
+    nav_n = sum(1 for s in compact_steps if s.get("op") == "navigate")
+    interact_n = sum(1 for s in compact_steps if s.get("op") in ("click", "input"))
+    wait_n = sum(1 for s in compact_steps if s.get("op") == "wait")
+    unknown_n = sum(1 for s in compact_steps if s.get("op") == "unknown")
+
+    ctx: Dict[str, Any] = {
+        "run_successful": success,
+        "recorded_counts": {"navigate": nav_n, "click_input": interact_n, "wait": wait_n, "unknown": unknown_n},
+        "summary_excerpt": (summary or "")[:2500],
+    }
+
+    try:
+        urls = [u for u in (history.urls() or []) if u]
+        ctx["urls_visited"] = urls[-20:]
+        ctx["last_url"] = urls[-1] if urls else ""
+    except Exception:
+        ctx["urls_visited"] = []
+        ctx["last_url"] = ""
+
+    try:
+        raw_errs = [str(e).strip() for e in history.errors() if e and str(e).strip()]
+        ctx["errors"] = [{"message": m, "count": c} for m, c in Counter(raw_errs).most_common(12)]
+        ctx["error_total"] = len(raw_errs)
+    except Exception:
+        ctx["errors"] = []
+        ctx["error_total"] = 0
+
+    joined = " ".join(str(e.get("message", "")) for e in ctx.get("errors", [])).lower()
+    replay_lines: List[str] = []
+    blank_input_steps = sum(
+        1 for s in compact_steps if isinstance(s, dict) and s.get("op") == "input" and not str(s.get("text") or "").strip()
+    )
+    if blank_input_steps:
+        replay_lines.append(
+            f"{blank_input_steps} recorded input step(s) have empty text (common when passwords are redacted). "
+            "Set FORGEQE_ENGINE_DEFAULT_LOGIN_USERNAME / FORGEQE_ENGINE_DEFAULT_LOGIN_PASSWORD to fill them."
+        )
+    if not success:
+        if "connection" in joined or "connect" in joined:
+            replay_lines.append(
+                "ForgeQE lost contact with the LLM API after the steps listed above. "
+                "Check the profile's endpoint, key, VPN/firewall, and quotas, then run again."
+            )
+        if interact_n == 0:
+            replay_lines.append(
+                "No click or input was recorded; steps may only contain navigate. "
+                "Replay can open the start URL but cannot complete the goal until a successful run records UI actions."
+            )
+        elif interact_n > 0:
+            replay_lines.append(
+                f"Partial recording: {interact_n} click/input step(s) saved. "
+                "Replay runs those actions in order; it fails if the DOM or locators changed."
+            )
+
+    ctx["replay_notes"] = replay_lines
+    return _sanitize_jsonish(ctx)
+
+
+def serialize_browser_use_history(history: Any) -> Any:
+    """Best-effort serialization of the library's AgentHistory (or similar)."""
+    if history is None:
+        return None
+    try:
+        if hasattr(history, "model_dump"):
+            return _sanitize_jsonish(history.model_dump(mode="json"))
+    except Exception:
+        logger.debug("model_dump(mode=json) failed, falling back", exc_info=True)
+    try:
+        if hasattr(history, "model_dump"):
+            return _sanitize_jsonish(history.model_dump())
+    except Exception:
+        logger.debug("model_dump failed", exc_info=True)
+    if isinstance(history, (dict, list)):
+        return _sanitize_jsonish(history)
+    return {"_note": "unserialized_history", "repr": repr(history)}
+
+
+def build_compact_steps(history: Any, collected_steps: Optional[List[Dict[str, Any]]]) -> List[Dict[str, Any]]:
+    """History first, then the live trace, then a single navigate — the same fallback order as the save path."""
+    compact_steps: List[Dict[str, Any]] = []
+    if history is not None:
+        try:
+            compact_steps = build_compact_steps_from_history(history)
+        except Exception as e:
+            logger.warning("build_compact_steps_from_history failed, will try live trace: %s", e)
+            compact_steps = []
+    if not compact_steps and collected_steps:
+        compact_steps = build_compact_steps_from_live_trace(collected_steps)
+    if not compact_steps and collected_steps:
+        nav_only = _first_navigate_step_from_live_trace(collected_steps)
+        if nav_only:
+            compact_steps = [nav_only]
+    return compact_steps
+
+
+def save_browser_use_run_yaml(
+    out_dir: Path,
+    goal: str,
+    *,
+    success: bool,
+    summary: str,
+    session_id: Optional[str],
+    history: Any = None,
+    collected_steps: Optional[List[Dict[str, Any]]] = None,
+    live_trace_source: str = "history",
+    compact_steps: Optional[List[Dict[str, Any]]] = None,
+    checks: Optional[List[Dict[str, Any]]] = None,
+) -> tuple[Optional[str], List[Dict[str, Any]]]:
+    """Write ``workflow.yaml`` into the run directory. Returns (path or None, compact steps)."""
+    goal = (goal or "").strip()
+    if not goal:
+        return None, []
+    out_dir.mkdir(parents=True, exist_ok=True)
+    now = datetime.now(timezone.utc)
+    path = out_dir / "workflow.yaml"
+    if not compact_steps:
+        compact_steps = build_compact_steps(history, collected_steps)
+    summary_s = summary if isinstance(summary, str) else str(summary)
+    if history is not None:
+        try:
+            execution = build_execution_context_for_yaml(
+                history, success=success, summary=summary_s, compact_steps=compact_steps
+            )
+        except Exception as e:
+            logger.warning("build_execution_context_for_yaml failed: %s", e)
+            execution = build_execution_context_for_live_trace(
+                success=success, summary=summary_s, compact_steps=compact_steps, source=live_trace_source
+            )
+    else:
+        execution = build_execution_context_for_live_trace(
+            success=success, summary=summary_s, compact_steps=compact_steps, source=live_trace_source
+        )
+    doc: Dict[str, Any] = {
+        "format": FORMAT_V2_COMPACT,
+        "goal": goal,
+        "created_at": now.isoformat().replace("+00:00", "Z"),
+        "success": success,
+        "summary": summary_s,
+        "session_id": session_id,
+        "steps_count": len(compact_steps),
+        "steps": _sanitize_jsonish(compact_steps),
+        "execution": execution,
+    }
+    if checks:
+        doc["checks"] = _sanitize_jsonish(checks)
+    if history is not None and _truthy_include_full_history():
+        doc["history"] = serialize_browser_use_history(history)
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(doc, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+        return str(path.resolve()), compact_steps
+    except Exception as e:
+        logger.warning("Could not save the workflow YAML: %s", e)
+        return None, compact_steps