davinci-resolve-mcp 2.67.0 → 2.68.0

package/scripts/install_resolve_bridge.py

@@ -0,0 +1,260 @@
+"""Install the bridge (or just the host-model probe) into Resolve's Scripts folder.
+
+    python scripts/install_resolve_bridge.py --probe-only    # settle the host model first
+    python scripts/install_resolve_bridge.py                 # probe + bridge launcher
+
+Deploys to every applicable macOS/Linux location, including the sandboxed App
+Store container used by the free edition — which is why the free edition can be
+installed alongside a direct-download Studio without either disturbing the other.
+
+Nothing is started here. Resolve must be restarted after installing so it
+re-scans the Scripts folders, and the script is then run from
+**Workspace ▸ Scripts**.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import secrets
+import shutil
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+CONFIG_DIR = Path.home() / ".config/davinci-resolve-mcp"
+CONFIG_PATH = CONFIG_DIR / "bridge.json"
+DEFAULT_PORT = 49632
+
+_SCRIPTS_SUFFIX = "Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility"
+
+#: A sandboxed (App Store) build sees its container as HOME, so Resolve's
+#: documented per-user path virtualizes to `<container>/Data/` + the SAME suffix.
+#: The vendor segment is kept.
+#:
+#: Two traps, both hit on a real install:
+#:
+#: 1. `<container>/Data/Library/Application Support/Fusion/Scripts/Utility`
+#:    exists and is pre-scaffolded with Color/Comp/Deliver/Edit/Tool/Utility —
+#:    but that is **Fusion's standalone tree**, not Resolve's, and Resolve does
+#:    not scan it. Keying on "which directory already exists" picks the decoy.
+#: 2. Resolve does not create its own `Fusion/Scripts` tree until a script is
+#:    installed, so requiring the target to pre-exist skips the free edition
+#:    entirely — the one build the bridge exists for.
+#:
+#: So: a container that exists means the edition is installed, and the tree is
+#: *created*. Blackmagic's README is the authority on the suffix, not the
+#: filesystem.
+_SANDBOX_MARKER = "com.blackmagic-design."
+#: Containers that are not Resolve (RAW Player, Speed Test, the IO XPC helper).
+_NON_RESOLVE_CONTAINERS = ("BlackmagicRaw", "IOXPC")
+
+
+def _is_resolve_container(path: Path) -> bool:
+    if not path.name.startswith(_SANDBOX_MARKER):
+        return False
+    return not any(marker in path.name for marker in _NON_RESOLVE_CONTAINERS)
+
+
+def script_targets() -> list[Path]:
+    """Every Scripts/Utility folder Resolve will scan on this machine.
+
+    Sandboxed containers are included because the App Store build cannot see the
+    normal per-user path — that isolation is exactly what lets the free edition
+    coexist with a direct-download Studio install.
+    """
+    home = Path.home()
+    candidates = [
+        home / _SCRIPTS_SUFFIX,
+        Path("/") / _SCRIPTS_SUFFIX,
+        home / ".local/share/DaVinciResolve/Fusion/Scripts/Utility",
+    ]
+    containers = home / "Library/Containers"
+    sandboxed: list[Path] = []
+    if containers.is_dir():
+        for entry in sorted(containers.iterdir()):
+            if _is_resolve_container(entry) and (entry / "Data").is_dir():
+                sandboxed.append(entry / "Data" / _SCRIPTS_SUFFIX)
+
+    usable: list[Path] = []
+    for path in candidates:
+        # Non-sandboxed: the install created the tree, so require it.
+        if path.is_dir() or (path.parent.is_dir() and os.access(path.parent, os.W_OK)):
+            usable.append(path)
+    # Sandboxed: the container's existence is the signal; the tree gets created.
+    usable.extend(sandboxed)
+    return list(dict.fromkeys(usable))
+
+
+#: Resolve enumerates `.py` scripts in Workspace > Scripts only when it finds a
+#: **framework** Python. Homebrew/pyenv/conda interpreters are not detected, and
+#: the failure is completely silent: the script sits in the right folder with the
+#: right permissions and simply never appears. Lua is embedded, so `.lua` always
+#: lists — which is why a Lua canary is installed alongside the probe.
+_FRAMEWORK_PYTHON_ROOTS = (
+    Path("/Library/Frameworks/Python.framework/Versions"),
+    Path("/System/Library/Frameworks/Python.framework/Versions"),
+)
+
+_LUA_CANARY = """-- Installed by davinci-resolve-mcp as an enumeration canary.
+-- If THIS appears under Workspace > Scripts but resolve_bridge_probe does not,
+-- Resolve is listing Lua and silently skipping Python: it cannot find a
+-- framework Python install. Install one from python.org and restart Resolve.
+print("Resolve is enumerating scripts. If the Python probe is missing, install a")
+print("framework Python from python.org (Homebrew/pyenv are NOT detected).")
+"""
+
+
+def framework_pythons() -> list[str]:
+    """Framework Python versions Resolve can actually see."""
+    found: list[str] = []
+    for root in _FRAMEWORK_PYTHON_ROOTS:
+        if not root.is_dir():
+            continue
+        for entry in sorted(root.iterdir()):
+            # `Versions/Current` is a symlink to a real version — counting it
+            # would report two installs where there is one.
+            if entry.is_symlink():
+                continue
+            if (entry / "bin" / "python3").exists() or (entry / "Python").exists():
+                found.append(f"{root}/{entry.name}")
+    return found
+
+
+def python_preflight() -> dict:
+    """Will Resolve list the Python probe we are about to install?"""
+    frameworks = framework_pythons()
+    return {
+        "framework_pythons": frameworks,
+        "resolve_will_list_python_scripts": bool(frameworks),
+        "advice": None if frameworks else (
+            "No framework Python found. Resolve will silently ignore every .py "
+            "script in its Scripts folders — they will simply not appear in "
+            "Workspace > Scripts, with no error. Homebrew, pyenv and conda "
+            "interpreters are NOT detected. Install a framework build from "
+            "python.org (any recent 3.x), restart Resolve, and re-check. The "
+            "Lua canary installed alongside will list either way, so you can "
+            "tell 'Python not detected' apart from 'wrong folder'."
+        ),
+    }
+
+
+def ensure_config(port: int, rotate: bool) -> dict:
+    existing: dict = {}
+    if CONFIG_PATH.exists():
+        try:
+            existing = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            existing = {}
+    token = existing.get("token")
+    if rotate or not isinstance(token, str) or len(token) < 43:
+        token = secrets.token_urlsafe(32)
+    # ResolveOperations requires roots; without them the bridge refuses to start.
+    # Conservative default: the user's home. Widen deliberately, not by accident.
+    existing_media = [r for r in (existing.get("allowed_media_roots") or []) if isinstance(r, str)]
+    existing_output = [r for r in (existing.get("allowed_output_roots") or []) if isinstance(r, str)]
+    config = {
+        "host": "127.0.0.1",
+        "port": port,
+        "token": token,
+        "auth_clock_skew_seconds": 60,
+        "allowed_media_roots": existing_media or [str(Path.home())],
+        "allowed_output_roots": existing_output or [str(Path.home() / "Movies")],
+    }
+    CONFIG_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+    tmp = CONFIG_PATH.with_suffix(".tmp")
+    tmp.write_text(json.dumps(config, indent=2, sort_keys=True), encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    tmp.replace(CONFIG_PATH)
+    os.chmod(CONFIG_PATH, 0o600)
+    return config
+
+
+def install(*, probe_only: bool, port: int, rotate: bool) -> dict:
+    # Write the config first: the launcher embeds its path, and a launcher
+    # pointing at a file that does not exist yet is a confusing first run.
+    if not probe_only:
+        ensure_config(port, rotate)
+    targets = script_targets()
+    if not targets:
+        raise SystemExit(
+            "No writable DaVinci Resolve Scripts/Utility folder found. Is Resolve installed?"
+        )
+    installed: list[str] = []
+    for target in targets:
+        target.mkdir(mode=0o700, parents=True, exist_ok=True)
+        for probe in ("resolve_bridge_probe.py", "resolve_capability_probe.py"):
+            shutil.copy2(REPO / "scripts" / probe, target / probe)
+            installed.append(str(target / probe))
+        # Lua always enumerates; Python only with a framework install. The canary
+        # makes "Python not detected" distinguishable from "wrong folder".
+        canary = target / "resolve_bridge_canary.lua"
+        canary.write_text(_LUA_CANARY, encoding="utf-8")
+        installed.append(str(canary))
+        if not probe_only:
+            runtime = target.parents[1] / ".davinci_mcp_runtime"
+            runtime.mkdir(mode=0o700, parents=True, exist_ok=True)
+            for module in ("resolve_bridge.py", "resolve_bridge_ops.py"):
+                shutil.copy2(REPO / "src/utils" / module, runtime / module)
+                installed.append(str(runtime / module))
+            # A sandboxed (App Store) build cannot read ~/.config at all — inside
+            # the container `~` IS the container, so an absolute real-home path is
+            # unreachable by construction (measured: "Operation not permitted").
+            # The runtime dir is already inside the container, so the config goes
+            # beside the modules. Same token, so the out-of-sandbox client still
+            # authenticates against ~/.config.
+            runtime_config = runtime / "bridge.json"
+            shutil.copy2(CONFIG_PATH, runtime_config)
+            os.chmod(runtime_config, 0o600)
+            installed.append(str(runtime_config))
+            # The launcher IS the menu entry. Without it the modules sit in the
+            # runtime dir with nothing able to start them.
+            launcher_source = (REPO / "scripts/resolve_bridge_launcher.py").read_text(encoding="utf-8")
+            launcher = launcher_source.replace(
+                "@@RUNTIME_ROOT_B64@@",
+                base64.urlsafe_b64encode(str(runtime).encode("utf-8")).decode("ascii"),
+            ).replace(
+                "@@CONFIG_PATH_B64@@",
+                base64.urlsafe_b64encode(str(CONFIG_PATH).encode("utf-8")).decode("ascii"),
+            )
+            launcher_path = target / "resolve_bridge.py"
+            launcher_path.write_text(launcher, encoding="utf-8")
+            installed.append(str(launcher_path))
+    result = {"installed": installed, "probe_only": probe_only, "python": python_preflight()}
+    if not probe_only:
+        loaded = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+        result["config"] = {"path": str(CONFIG_PATH),
+                            **{k: v for k, v in loaded.items() if k != "token"}}
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--probe-only", action="store_true",
+                        help="install only the host-model probe (run this first)")
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT)
+    parser.add_argument("--rotate-token", action="store_true")
+    args = parser.parse_args()
+    if not 1024 <= args.port <= 65535:
+        raise SystemExit("--port must be 1024..65535")
+
+    result = install(probe_only=args.probe_only, port=args.port, rotate=args.rotate_token)
+    print(json.dumps(result, indent=2, sort_keys=True))
+    print()
+    if not result["python"]["resolve_will_list_python_scripts"]:
+        print("!" * 72)
+        print("WARNING: " + result["python"]["advice"])
+        print("!" * 72)
+        print()
+    print("Next:")
+    print("  1. Restart DaVinci Resolve so it re-scans the Scripts folders.")
+    print("  2. Open a saved project (the Scripts menu is empty in Project Manager).")
+    print("  3. Workspace > Scripts > resolve_bridge_probe  — run it TWICE.")
+    print("  4. Read ~/.config/davinci-resolve-mcp/host-model-probe.json")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/resolve_bridge_launcher.py

@@ -0,0 +1,202 @@
+"""Workspace ▸ Scripts ▸ resolve_bridge — starts the in-app bridge.
+
+Installed by ``python scripts/install_resolve_bridge.py``. Run it once per
+Resolve session; it holds the loopback listener open until Resolve exits or a
+client asks it to stop.
+
+**This blocks, on purpose.** A Scripts-menu script is a child process of Resolve
+(measured on Studio 19.1.3.7 and free 21.0.3.7), so a background thread dies the
+instant this function returns. `serve()` detects the host model and blocks or
+returns accordingly — see `src/utils/resolve_bridge.py`. While it is running this
+script will appear "busy" in Resolve; that is the listener staying alive, not a
+hang, and Resolve's UI is unaffected because this is a separate process.
+
+The runtime directory is written in by the installer, because Resolve's Scripts
+folder has no relation to the repository and nothing can be imported from it.
+
+## The supervisor loop
+
+Blocking has a cost: this script cannot be re-run while it is alive, so a stale
+runtime used to mean quitting Resolve. `serve()` now reports *why* it returned,
+and a `reload` sends us back around this loop with the runtime re-imported from
+disk — new code live, no UI interaction.
+
+Re-importing is done into a **throwaway module object** rather than with
+`importlib.reload`, so a module that fails halfway cannot leave the running one
+half-overwritten. The old modules keep serving and the failure is reported.
+"""
+
+import base64
+import importlib.util
+import os
+import sys
+import traceback
+
+RUNTIME_ROOT = base64.urlsafe_b64decode("@@RUNTIME_ROOT_B64@@".encode("ascii")).decode("utf-8")
+_HOME_CONFIG = base64.urlsafe_b64decode("@@CONFIG_PATH_B64@@".encode("ascii")).decode("utf-8")
+
+if RUNTIME_ROOT not in sys.path:
+    sys.path.insert(0, RUNTIME_ROOT)
+
+
+def resolve_config_path():
+    """Runtime-local config first — the only one a sandboxed build can read.
+
+    Inside the App Store sandbox, `~` is the container, so the absolute
+    real-home path baked in at install time raises "Operation not permitted".
+    The runtime directory sits inside the container next to the modules, so a
+    copy there is always reachable. Both copies carry the same token, so the
+    out-of-sandbox MCP client still authenticates from ~/.config.
+    """
+    local = os.path.join(RUNTIME_ROOT, "bridge.json")
+    if os.path.isfile(local):
+        return local
+    return _HOME_CONFIG
+
+
+CONFIG_PATH = resolve_config_path()
+
+
+def acquire_resolve():
+    candidate = globals().get("resolve")
+    if candidate is not None:
+        return candidate
+    bmd = globals().get("bmd")
+    if bmd is not None:
+        try:
+            return bmd.scriptapp("Resolve")
+        except Exception:
+            return None
+    try:
+        import DaVinciResolveScript as script_module
+        return script_module.scriptapp("Resolve")
+    except Exception:
+        return None
+
+
+def load_runtime():
+    """Import the two runtime modules fresh, into new module objects.
+
+    Returns ``(resolve_bridge, resolve_bridge_ops)`` or raises. Nothing already
+    imported is mutated, so a failed reload leaves the running bridge intact.
+    """
+    loaded = []
+    for name in ("resolve_bridge", "resolve_bridge_ops"):
+        path = os.path.join(RUNTIME_ROOT, name + ".py")
+        spec = importlib.util.spec_from_file_location(name, path)
+        if spec is None or spec.loader is None:
+            raise ImportError("cannot load %s from %s" % (name, path))
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        # Registered only once both have executed, so a half-loaded pair is
+        # never visible to anything that imports by name.
+        loaded.append((name, module))
+    for name, module in loaded:
+        sys.modules[name] = module
+    return loaded[0][1], loaded[1][1]
+
+
+def main():
+    print("=" * 70)
+    print("DaVinci Resolve MCP - in-app bridge")
+    print("=" * 70)
+
+    resolve_object = acquire_resolve()
+    if resolve_object is None:
+        print("  ERROR: no 'resolve' object. Run this from Workspace > Scripts.")
+        return
+
+    try:
+        resolve_bridge, resolve_bridge_ops = load_runtime()
+    except Exception:
+        print("  ERROR: could not import the bridge runtime from:")
+        print("    %s" % RUNTIME_ROOT)
+        print("  Re-run: python scripts/install_resolve_bridge.py")
+        traceback.print_exc()
+        return
+
+    try:
+        product = resolve_object.GetProductName()
+        version = resolve_object.GetVersionString()
+    except Exception:
+        product, version = "DaVinci Resolve", "?"
+
+    generation = 0
+    while True:
+        try:
+            config = resolve_bridge.load_config(CONFIG_PATH)
+        except Exception as exc:
+            print("  ERROR: bridge config unusable: %s" % exc)
+            print("    tried: %s" % CONFIG_PATH)
+            if CONFIG_PATH != _HOME_CONFIG:
+                print("    (runtime-local copy; the ~/.config one is unreachable from a sandbox)")
+            print("  Re-run: python scripts/install_resolve_bridge.py")
+            return
+
+        bridge_holder = {}
+
+        def lifecycle(mode, _ops=resolve_bridge_ops, _rb=resolve_bridge, _holder=bridge_holder):
+            """Vet the request, then flag the serve loop. Never stops in place."""
+            if mode == "reload":
+                problems = _rb.validate_runtime_sources(RUNTIME_ROOT)
+                if problems:
+                    # Refused by a bridge that is still serving, which is the
+                    # whole point of checking before stopping.
+                    raise _ops.OperationError(
+                        "reload_rejected",
+                        "the installed runtime will not compile: " + "; ".join(problems),
+                    )
+            _holder["bridge"].request_stop(mode)
+            return {"generation": generation}
+
+        operations = resolve_bridge_ops.ResolveOperations(
+            resolve_object,
+            media_roots=list(config.get("allowed_media_roots") or [os.path.expanduser("~")]),
+            output_roots=list(config.get("allowed_output_roots") or [os.path.expanduser("~")]),
+            lifecycle=lifecycle,
+        )
+        bridge = resolve_bridge.Bridge(
+            resolve_object, config, resolve_bridge_ops.make_dispatch(operations)
+        )
+        bridge_holder["bridge"] = bridge
+
+        model = resolve_bridge._host_model()
+        print("  product     : %s %s" % (product, version))
+        print("  listening   : 127.0.0.1:%s" % config["port"])
+        print("  config      : %s" % CONFIG_PATH)
+        print("  host model  : %s (blocking=%s)" % (model["model"], model["blocking_required"]))
+        print("  operations  : %d" % len(resolve_bridge_ops.ResolveOperations.OPERATIONS))
+        print("  generation  : %d" % generation)
+        print()
+        print("  The MCP server connects with DAVINCI_RESOLVE_BRIDGE=1.")
+        if model["blocking_required"]:
+            print("  This script now HOLDS the listener open and will look busy until")
+            print("  Resolve exits. That is expected — closing it stops the bridge.")
+        print("=" * 70)
+
+        try:
+            outcome = bridge.serve(host_model=model)
+        except KeyboardInterrupt:
+            bridge.stop()
+            print("  bridge stopped (interrupted).")
+            return
+        finally:
+            bridge.stop()
+
+        reason = (outcome or {}).get("stop_reason")
+        if reason != "reload":
+            print("  bridge stopped (%s)." % (reason or "returned"))
+            return
+
+        print("  reload requested — re-importing the runtime from disk...")
+        try:
+            resolve_bridge, resolve_bridge_ops = load_runtime()
+        except Exception:
+            # The old module objects are untouched, so serving again with them
+            # is a real fallback rather than a hope.
+            print("  RELOAD FAILED — continuing on the previously loaded runtime:")
+            traceback.print_exc()
+        generation += 1
+
+
+main()

package/scripts/resolve_bridge_probe.py

@@ -0,0 +1,162 @@
+"""Resolve Scripts-menu probe: does a menu script run in-process or as a child?
+
+Run from **Workspace ▸ Scripts ▸ resolve_bridge_probe** (install with
+``python scripts/install_resolve_bridge.py --probe-only``).
+
+The answer decides how the bridge's listener must behave, and the two options
+are fatal in opposite directions — a daemon thread dies instantly in a child
+process, and a blocking loop wedges Resolve in-process. This settles it with
+evidence instead of a guess.
+
+Edition-independent: Workspace ▸ Scripts behaves the same on Studio and free, so
+this can be run on whatever is already installed.
+
+**Deliberately self-contained.** This file is copied into Resolve's Scripts
+folder, where the repository is not on the path and nothing can be imported from
+it. The ~20 lines of detection are duplicated here rather than imported, and
+`tests/test_resolve_bridge.py` asserts the two copies agree. An import would
+raise in Resolve's console and tell you nothing.
+
+Writes findings to ``~/.config/davinci-resolve-mcp/host-model-probe.json`` and
+prints them. Starts no listener and touches no project.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import time
+
+REPORT_PATH = os.path.expanduser("~/.config/davinci-resolve-mcp/host-model-probe.json")
+
+# Kept in sync with src/utils/resolve_bridge.py — see the module docstring.
+PARENT_MARKERS = ("resolve", "fuscript", "fusion")
+
+
+def process_name(pid):
+    """Best-effort process name; empty string when it cannot be read."""
+    try:  # Linux
+        with open("/proc/%d/comm" % pid) as handle:
+            return handle.read().strip()
+    except (OSError, IOError):
+        pass
+    try:  # macOS
+        out = subprocess.Popen(
+            ["ps", "-p", str(pid), "-o", "comm="],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+        ).communicate()[0]
+        if isinstance(out, bytes):
+            out = out.decode("utf-8", "replace")
+        return out.strip()
+    except Exception:
+        return ""
+
+
+def host_model():
+    """Ask about THIS process, not the parent.
+
+    The sandboxed App Store build blocks `ps` on another process, so the parent
+    name comes back empty even though the script IS a child of Resolve
+    (measured: pid 97667, parent 97258, name unreadable). Reading sys.executable
+    needs no permission, so it is the decision; the parent name is corroboration.
+    """
+    parent_pid = os.getppid()
+    parent_name = process_name(parent_pid) or ""
+    executable = sys.executable or ""
+    self_is_host = bool(executable) and executable.rstrip("/").endswith("/Resolve")
+    return {
+        "model": "in_process" if self_is_host else "child_process",
+        "parent_pid": parent_pid,
+        "parent_name": parent_name,
+        "self_executable": executable,
+        "self_is_resolve": self_is_host,
+        "parent_corroborates": any(m in parent_name.lower() for m in PARENT_MARKERS),
+        "blocking_required": not self_is_host,
+        "pid": os.getpid(),
+    }
+
+
+def acquire_resolve():
+    """The live object, if Resolve handed us one."""
+    candidate = globals().get("resolve")
+    if candidate is not None:
+        return candidate
+    bmd = globals().get("bmd")
+    if bmd is not None:
+        try:
+            return bmd.scriptapp("Resolve")
+        except Exception:
+            return None
+    try:
+        import DaVinciResolveScript as script_module
+        return script_module.scriptapp("Resolve")
+    except Exception:
+        return None
+
+
+def main():
+    probe = host_model()
+
+    # Does the interpreter survive the script returning? A child process exits
+    # here; Resolve's own interpreter keeps this module alive. So a SECOND run
+    # sees the marker only in the in-process case — independent corroboration of
+    # the parent-name detection above.
+    module = sys.modules[__name__]
+    previous = getattr(module, "_PREVIOUS_RUN_AT", None)
+    probe["previous_run_in_this_interpreter"] = previous
+    probe["interpreter_persisted"] = previous is not None
+    module._PREVIOUS_RUN_AT = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+    resolve_object = acquire_resolve()
+    probe["resolve_object_available"] = resolve_object is not None
+    if resolve_object is not None:
+        try:
+            product = resolve_object.GetProductName()
+            probe["product"] = product
+            probe["version"] = resolve_object.GetVersionString()
+            probe["edition"] = "studio" if "studio" in str(product).lower() else "free"
+        except Exception as exc:
+            probe["product_probe_error"] = type(exc).__name__
+
+    try:
+        directory = os.path.dirname(REPORT_PATH)
+        if not os.path.isdir(directory):
+            os.makedirs(directory)
+        with open(REPORT_PATH, "w") as handle:
+            json.dump(probe, handle, indent=2, sort_keys=True)
+        written = REPORT_PATH
+    except (OSError, IOError) as exc:
+        # A sandboxed build may not reach ~/.config. The console output is the
+        # real result; the file is a convenience.
+        written = "could not write (%s) — read the console output above" % type(exc).__name__
+
+    print("=" * 68)
+    print("DaVinci Resolve MCP - Scripts-menu host-model probe")
+    print("=" * 68)
+    print("  host model      : %s" % probe["model"])
+    print("  parent process  : %s (pid %s)" % (probe["parent_name"] or "<unreadable — sandbox>", probe["parent_pid"]))
+    print("  this interpreter: %s" % (probe["self_executable"] or "<unknown>"))
+    print("  this pid        : %s" % probe["pid"])
+    print("  blocking needed : %s" % probe["blocking_required"])
+    print("  resolve object  : %s" % probe["resolve_object_available"])
+    if probe.get("product"):
+        print("  product         : %s %s (%s)" % (probe["product"], probe.get("version", "?"), probe.get("edition")))
+    print("  interpreter kept: %s" % probe["interpreter_persisted"])
+    print()
+    if probe["blocking_required"]:
+        print("  -> CHILD PROCESS. The listener must BLOCK; a daemon thread would")
+        print("     die the moment this script returns.")
+    else:
+        print("  -> IN-PROCESS (or launched outside Resolve). The listener must")
+        print("     NOT block, or Resolve's script execution wedges.")
+    print()
+    print("  Run this a SECOND time. If 'interpreter kept' flips to True, the")
+    print("  script runs inside Resolve's own interpreter. If it stays False,")
+    print("  each run is a fresh child process.")
+    print()
+    print("  report: %s" % written)
+    print("=" * 68)
+    return probe
+
+
+main()