froid-loop 0.11.1__py3-none-any.whl

froid_loop/data/plugins/unity/unity_cleanup.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Post-run scratch cleanup for the froid-loop Unity engine plugin.
+
+The IvanMurzak ``unity-mcp-cli`` downloads the Editor MCP server into Unity's
+per-project temp dir — on Linux ``/tmp/<companyName>/<productName>/`` — as a
+versioned ``unity-mcp-server-*.zip`` and never removes it, so a fresh zip
+accumulates every time the pinned server version changes. The Editor also writes
+an unbounded ``<project>/Temp/mcp-server/ai-editor-logs.txt``. Neither is needed
+once a run is over; this script reclaims both, best-effort, at ``post_run``.
+
+It runs once per run (both editor modes), after the loop has finished — so it
+never races an in-flight ``setup-mcp`` download. Gated by ``FROID_LOOP_CLEAN_TMP``
+(the engine maps [cleanup] clean_tmp onto it); a "0" disables it.
+
+Env (injected by the engine):
+  FROID_LOOP_WORKTREE     the Unity project path (the repo root in shared mode)
+  FROID_LOOP_REPO_ROOT    main repo root (fallback for the project path)
+  FROID_LOOP_CLEAN_TMP    "1" (default) enables; "0" disables
+  FROID_LOOP_UNITY_LOG_CAP_MB  truncate the mcp log once it exceeds this (default 5)
+
+Exit 0 always (best-effort): a cleanup failure must never fail a finished run.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+# companyName/productName are flat scalars in the otherwise-YAML asset.
+_COMPANY_RE = re.compile(r"^\s*companyName:\s*(.+?)\s*$", re.MULTILINE)
+_PRODUCT_RE = re.compile(r"^\s*productName:\s*(.+?)\s*$", re.MULTILINE)
+
+
+def _project() -> Path | None:
+    p = os.environ.get("FROID_LOOP_WORKTREE") or os.environ.get("FROID_LOOP_REPO_ROOT")
+    return Path(p) if p else None
+
+
+def read_project_identity(project: Path) -> tuple[str, str]:
+    """``(companyName, productName)`` from ProjectSettings/ProjectSettings.asset.
+    Falls back to ``("DefaultCompany", <dir name>)`` — Unity's own default
+    companyName — when the asset is missing or a field is unset."""
+    default = ("DefaultCompany", project.name)
+    asset = project / "ProjectSettings" / "ProjectSettings.asset"
+    try:
+        text = asset.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return default
+    company = _COMPANY_RE.search(text)
+    product = _PRODUCT_RE.search(text)
+    return (
+        company.group(1) if company and company.group(1) else default[0],
+        product.group(1) if product and product.group(1) else default[1],
+    )
+
+
+def _temp_cache_root() -> Path:
+    """Base of Unity's ``Application.temporaryCachePath`` (where unity-mcp-cli drops
+    the server zip), under which we look for ``<company>/<product>``.
+
+    On Linux this is exactly ``/tmp`` — keep it byte-for-byte (it *is* Unity's
+    documented temporaryCachePath base, not our scratch choice). On other platforms
+    (no /tmp) derive from ``tempfile.gettempdir()`` as a best-effort analogue.
+    NOTE: native Windows Unity uses a *different* cache root —
+    ``%USERPROFILE%\\AppData\\Local\\Temp\\<company>\\<product>`` — which
+    ``gettempdir()`` does not always resolve to; getting that exactly right is a
+    documented follow-up (no Windows backend ships this pass, so it isn't exercised)."""
+    if sys.platform.startswith("linux"):
+        return Path("/tmp")  # nosec B108 portability: Unity temporaryCachePath base (Linux)
+    return Path(tempfile.gettempdir())  # portability: non-Linux temp root (see note above)
+
+
+def _clean_tmp_zips(company: str, product: str) -> int:
+    """Remove the downloaded unity-mcp-server zips under the temp cache dir
+    ``<temp>/<company>/<product>``. Returns the number removed. Scoped to this
+    project's temp dir so a sibling project's downloads are never touched."""
+    # This is unity-mcp-cli's fixed download location, not our scratch choice.
+    tmp = _temp_cache_root() / company / product
+    if not tmp.is_dir():
+        return 0
+    removed = 0
+    for zip_path in tmp.glob("unity-mcp-server-*.zip"):
+        try:
+            zip_path.unlink()
+            removed += 1
+            print(f"unity_cleanup: removed {zip_path}", file=sys.stderr)
+        except OSError as exc:  # best effort
+            print(f"unity_cleanup: could not remove {zip_path}: {exc}", file=sys.stderr)
+    return removed
+
+
+def _truncate_mcp_log(project: Path) -> None:
+    """Reset the MCP editor log once it grows past the cap. Safe even while the
+    Editor/server holds it open — truncation just resets the size."""
+    try:
+        cap_mb = max(0, int(os.environ.get("FROID_LOOP_UNITY_LOG_CAP_MB", "5")))
+    except ValueError:
+        cap_mb = 5
+    log = project / "Temp" / "mcp-server" / "ai-editor-logs.txt"
+    try:
+        if log.is_file() and log.stat().st_size > cap_mb * 1_048_576:
+            log.write_bytes(b"")
+            print(f"unity_cleanup: truncated {log}", file=sys.stderr)
+    except OSError as exc:  # best effort
+        print(f"unity_cleanup: could not truncate {log}: {exc}", file=sys.stderr)
+
+
+def main() -> int:
+    if os.environ.get("FROID_LOOP_CLEAN_TMP", "1").strip() not in ("1", "true", "yes", "on", ""):
+        return 0
+    project = _project()
+    if project is None:
+        print("unity_cleanup: no project path (FROID_LOOP_WORKTREE/REPO_ROOT)", file=sys.stderr)
+        return 0
+    company, product = read_project_identity(project)
+    _clean_tmp_zips(company, product)
+    _truncate_mcp_log(project)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

froid_loop/data/plugins/unity/unity_dialog_probe.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Detached, DETECT-ONLY Unity modal-dialog probe for the froid-loop Unity plugin.
+
+Unity on Linux is an X11 (or XWayland) client, so its run-freezing modal dialogs —
+"scene(s) have been modified" (reload / save-before-close), "conflicting scene
+changes" — are ordinary X windows. This probe polls xdotool for a *visible*
+Unity-owned window whose title matches one of those dialogs and, when it finds one,
+**reports it and nothing more**: it NEVER clicks, keys, activates, or closes any
+window. The scene-guard (auto-save) and the injected prompt facts are what *prevent*
+the modals; this is the last-resort observability net that tells a human one slipped
+through and is now freezing the MCP dispatch loop.
+
+Report on a fresh detection (deduped per window id, per probe lifetime):
+  1. a JSONL line to ``<run_dir>/unity-dialog-probe.jsonl`` — ``{ts, window, title}``;
+  2. a line to ``<run_dir>/ATTENTION`` in the same format as ``gates.notify``;
+  3. a best-effort ``notify-send`` desktop notification (guarded by ``shutil.which``,
+     gated by ``FROID_LOOP_UNITY_DIALOG_PROBE_NOTIFY``), mirroring ``gates.notify``.
+
+Lifecycle: launched detached by ``UnityPlugin`` (shared mode: at ``pre_run``;
+per_worktree: at ``pre_worktree_setup``) with the project/worktree path in argv, so
+``unity_teardown.py``'s ``/proc`` argv scan can find + reap it. It also writes its own
+``<run_dir>/unity-dialog-probe.pid`` (pid + start-time identity, via
+``runs.write_named_pid``) as the primary reap handle. Self-reaping backstop: it polls
+``<run_dir>/engine.pid`` liveness (``runs.engine_alive`` — the same identity-checked
+logic the CLI uses) and exits when the engine dies, so an un-reaped probe can never
+outlive its run.
+
+Stdlib only, plus froid-loop's own dep-free process/pid helpers (no third-party deps).
+No-op clean exit (0) when there is nothing to watch: ``DISPLAY`` unset, ``xdotool``
+absent, or ``FROID_LOOP_RUN_DIR`` unset (Windows/macOS fall out here — out of scope).
+
+Env (injected by the engine plugin):
+  FROID_LOOP_RUN_DIR                          run dir for outputs + engine.pid liveness
+  FROID_LOOP_UNITY_DIALOG_PROBE_INTERVAL_SEC  poll interval seconds     (default 5, min 1)
+  FROID_LOOP_UNITY_DIALOG_PROBE_NOTIFY        1/0 desktop notify        (default 1)
+  FROID_LOOP_UNITY_DIALOG_PROBE_CLASS         xdotool WM_CLASS regex    (default Unity)
+
+NOTE: the exact dialog titles + the "Unity" window class are UNVERIFIED against a live
+Linux Editor build — they are best-effort heuristics. Detection is advisory; a miss
+degrades to the pre-existing behavior (a human notices the frozen run), never worse.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+# froid-loop's own dep-free liveness/pid helpers (run under sys.executable, so the
+# package is importable — same contract unity_teardown.py relies on for process_host).
+from froid_loop.runs import engine_alive, write_named_pid
+
+PROBE_PID_FILE = "unity-dialog-probe.pid"
+PROBE_JSONL = "unity-dialog-probe.jsonl"
+ATTENTION_FILE = "ATTENTION"
+_TITLE = "Unity modal dialog detected"
+
+# Case-insensitive substrings identifying a run-freezing Unity modal dialog by its
+# window title. UNVERIFIED against a live Editor — kept broad + advisory on purpose.
+_DIALOG_PATTERNS = (
+    "changed on disk",
+    "save changes before",
+    "conflicting scene changes",
+    "scene(s) have been modified",
+    "reload the following",
+    "do you want to save",
+    "unapplied import settings",
+)
+
+# Set by the SIGTERM/SIGINT handler so a polite teardown ends the loop promptly.
+_stop = False
+
+
+def _truthy(value: str | None, default: bool) -> bool:
+    if value is None or value.strip() == "":
+        return default
+    return value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _install_signals() -> None:
+    """Break the poll loop on SIGTERM/SIGINT so the plugin's polite reap suffices."""
+
+    def _handler(_signum, _frame):
+        global _stop
+        _stop = True
+
+    for name in ("SIGTERM", "SIGINT"):
+        sig = getattr(signal, name, None)
+        if sig is not None:
+            try:
+                signal.signal(sig, _handler)
+            except (ValueError, OSError):  # pragma: no cover - not the main thread, etc.
+                pass
+
+
+def _interval() -> float:
+    try:
+        return max(1.0, float(os.environ.get("FROID_LOOP_UNITY_DIALOG_PROBE_INTERVAL_SEC", "5")))
+    except (TypeError, ValueError):
+        return 5.0
+
+
+def _run_xdotool(args: list[str], timeout: float = 10.0) -> subprocess.CompletedProcess:
+    return subprocess.run(["xdotool", *args], capture_output=True, text=True, timeout=timeout)
+
+
+def _unity_window_ids(run) -> list[str]:
+    """Ids of *visible* Unity-owned windows (xdotool search by WM_CLASS regex).
+    xdotool exits non-zero when nothing matches — that is the normal "no dialog"
+    case, not an error. Any launch failure degrades to an empty list."""
+    cls = os.environ.get("FROID_LOOP_UNITY_DIALOG_PROBE_CLASS", "Unity")
+    try:
+        proc = run(["search", "--onlyvisible", "--class", cls])
+    except (subprocess.SubprocessError, OSError):
+        return []
+    if proc.returncode != 0:
+        return []
+    return [line.strip() for line in proc.stdout.splitlines() if line.strip().isdigit()]
+
+
+def _window_name(run, wid: str) -> str:
+    try:
+        proc = run(["getwindowname", wid])
+    except (subprocess.SubprocessError, OSError):
+        return ""
+    return proc.stdout.strip() if proc.returncode == 0 else ""
+
+
+def _matches_dialog(name: str) -> bool:
+    low = name.lower()
+    return any(pattern in low for pattern in _DIALOG_PATTERNS)
+
+
+def _scan_for_dialogs(run) -> list[tuple[str, str]]:
+    """(window id, title) for every visible Unity window whose title matches a known
+    modal-dialog phrase. ``run`` is an injectable xdotool runner (for testing)."""
+    hits: list[tuple[str, str]] = []
+    for wid in _unity_window_ids(run):
+        name = _window_name(run, wid)
+        if name and _matches_dialog(name):
+            hits.append((wid, name))
+    return hits
+
+
+def _report(run_dir: Path, wid: str, name: str, *, notify: bool) -> None:
+    """Record one fresh detection: JSONL + ATTENTION + (best-effort) notify-send.
+    Every sink is independently guarded — a filesystem or notify failure never stops
+    the others, and never raises."""
+    ts = time.strftime("%Y-%m-%dT%H:%M:%S")
+    try:
+        with (run_dir / PROBE_JSONL).open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps({"ts": ts, "window": wid, "title": name}) + "\n")
+    except OSError:
+        pass
+    # ATTENTION line: identical shape to gates.notify's file sink.
+    stamp = time.strftime("%Y-%m-%d %H:%M:%S")
+    message = f"window {wid}: {name}"
+    try:
+        with (run_dir / ATTENTION_FILE).open("a", encoding="utf-8") as fh:
+            fh.write(f"[{stamp}] {_TITLE}: {message}\n")
+    except OSError:
+        pass
+    # portability: notify-send is Linux-only; the shutil.which guard makes this a
+    # no-op where it is absent (mirrors gates.notify).
+    if notify and shutil.which("notify-send"):
+        try:
+            subprocess.run(
+                ["notify-send", "--app-name=froid-loop", _TITLE, message],
+                timeout=10,
+                capture_output=True,
+            )
+        except (subprocess.SubprocessError, OSError):
+            pass  # desktop notification is best-effort
+
+
+def _scan_once(run, run_dir: Path, seen: set[str], *, notify: bool) -> int:
+    """One scan+report pass. Reports only window ids not already in ``seen`` (dedupe
+    repeat detections of the same dialog). Returns the count of NEW reports."""
+    reported = 0
+    for wid, name in _scan_for_dialogs(run):
+        if wid in seen:
+            continue
+        seen.add(wid)
+        _report(run_dir, wid, name, notify=notify)
+        reported += 1
+    return reported
+
+
+def _sleep_until_next_poll(interval: float, run_dir: Path) -> None:
+    """Sleep ``interval`` in ~1s slices so a SIGTERM or a dead engine is noticed
+    within about a second regardless of how long the poll interval is."""
+    slept = 0.0
+    while not _stop and slept < interval and engine_alive(run_dir):
+        time.sleep(min(1.0, interval - slept))
+        slept += 1.0
+
+
+def main() -> int:
+    if not os.environ.get("DISPLAY"):
+        print("unity_dialog_probe: DISPLAY unset; nothing to probe (exit 0)", file=sys.stderr)
+        return 0
+    if shutil.which("xdotool") is None:
+        print("unity_dialog_probe: xdotool not on PATH; nothing to probe (exit 0)", file=sys.stderr)
+        return 0
+    rd = (os.environ.get("FROID_LOOP_RUN_DIR") or "").strip()
+    if not rd:
+        # Without a run dir we have nowhere to report AND no engine pid to shadow —
+        # refuse rather than loop forever as an orphan.
+        print(
+            "unity_dialog_probe: FROID_LOOP_RUN_DIR unset; refusing to run with no "
+            "engine to shadow (exit 0)",
+            file=sys.stderr,
+        )
+        return 0
+
+    run_dir = Path(rd)
+    interval = _interval()
+    notify = _truthy(os.environ.get("FROID_LOOP_UNITY_DIALOG_PROBE_NOTIFY"), True)
+    _install_signals()
+    # primary reap handle: our own pid + start-time identity (mirrors runs.write_pid).
+    try:
+        write_named_pid(run_dir / PROBE_PID_FILE, os.getpid())
+    except OSError:
+        pass
+
+    seen: set[str] = set()
+    while not _stop and engine_alive(run_dir):
+        _scan_once(_run_xdotool, run_dir, seen, notify=notify)
+        _sleep_until_next_poll(interval, run_dir)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

froid_loop/data/plugins/unity/unity_facts.md

@@ -0,0 +1,17 @@
+## Unity scene-save discipline (froid-loop)
+
+You are driving a live Unity Editor over MCP. Unity-MCP scene-mutating tools mark
+scenes dirty but never save them, and a dirty or unsaved-on-quit scene raises modal
+Editor dialogs ("scene changed on disk", "save changes before closing") that freeze
+the Editor and every subsequent MCP call. Follow these rules:
+
+- After any scene-mutating MCP batch (`gameobject-*`, `*component*`, `tilemap-*`,
+  `cinemachine-*`, prefab instantiate), call `scene-save` for **each modified open
+  scene** BEFORE any of: running tests (`tests-run` aborts on dirty scenes), any
+  `git` command, entering play mode (`editor-application-set-state`), or ending the
+  session.
+- Never rewrite an open scene's `.unity`/`.prefab` on disk directly — prefer the MCP
+  tools. If a disk edit is unavoidable: `scene-save` first, make the edit, then
+  `assets-refresh`.
+- A `SceneAutoSaveGuard` auto-saves dirty scenes after ~5s idle, but do **not** rely
+  on it for ordering — call `scene-save` explicitly at the boundaries above.