meltygui 0.1.0__py3-none-any.whl

meltygui/core/definition_hotswap.py

@@ -0,0 +1,231 @@
+"""Keep live definitions canonical when their source moves between modules."""
+import inspect
+import gc
+import sys
+import types
+
+from meltygui.core.melty import Melty
+
+
+def _patch_nested_functions(previous, replacement, namespace):
+    """Update existing factory-created callbacks without recreating closures."""
+    def nested_codes(code):
+        result = {}
+        for child in code.co_consts:
+            if isinstance(child, types.CodeType):
+                if not child.co_name.startswith("<"):
+                    result[child.co_qualname] = child
+                result.update(nested_codes(child))
+        return result
+
+    fresh = nested_codes(replacement)
+    if not fresh:
+        return lambda: None
+    edits = []
+    # Earlier factory-only swaps can leave callbacks more than one code
+    # generation behind. Match their defining namespace, source and qualified
+    # local name rather than only referrers of the immediately previous code.
+    for function in gc.get_objects():
+        if type(function) is not types.FunctionType or function.__globals__ is not namespace:
+            continue
+        old_code = function.__code__
+        new_code = fresh.get(old_code.co_qualname)
+        if (new_code is None or new_code is old_code
+                or old_code.co_filename != previous.co_filename):
+            continue
+        if old_code.co_freevars != new_code.co_freevars:
+            raise ValueError(f"cannot preserve live closure for {old_code.co_qualname}: free variables changed")
+        edits.append((function, old_code, new_code))
+    for function, _old_code, new_code in edits:
+        function.__code__ = new_code
+
+    def restore():
+        for function, old_code, _new_code in edits:
+            function.__code__ = old_code
+    return restore
+
+
+def patch_function(live, replacement, *, force=False):
+    """Patch in place, retaining the defining namespace after a source move.
+
+    Python cannot reassign a function's __globals__. For a relocated function,
+    its original identity becomes a small forwarding entry point; __wrapped__
+    exposes the actual source implementation to inspection and later edits.
+    Normal edits still patch code directly and pay no forwarding cost.
+    """
+    previous = (live.__code__, live.__defaults__, live.__kwdefaults__,
+                dict(live.__annotations__), live.__doc__, live.__module__,
+                live.__qualname__, dict(live.__dict__))
+    previous_target = Melty.relocated_functions.get(id(live))
+    target = inspect.unwrap(live) if live.__dict__.get('__melty_relocated__') else live
+    target_previous = (target.__code__, target.__defaults__, target.__kwdefaults__,
+                       dict(target.__annotations__), target.__doc__, target.__module__,
+                       target.__qualname__)
+
+    if force and replacement.__globals__ is live.__globals__:
+        target = live
+        live.__dict__.pop('__wrapped__', None)
+        live.__dict__.pop('__melty_relocated__', None)
+        Melty.relocated_functions.pop(id(live), None)
+
+    restore_nested = None
+    if target.__globals__ is replacement.__globals__:
+        restore_nested = _patch_nested_functions(target.__code__, replacement.__code__, target.__globals__)
+        target.__code__ = replacement.__code__
+        target.__defaults__ = replacement.__defaults__
+        target.__kwdefaults__ = replacement.__kwdefaults__
+        target.__annotations__ = replacement.__annotations__
+        target.__doc__ = replacement.__doc__
+        target.__module__ = replacement.__module__
+        target.__qualname__ = replacement.__qualname__
+    else:
+        # Keep existing lexical state when the free-variable contract survives.
+        implementation = replacement
+        if target.__code__.co_freevars and target.__code__.co_freevars == replacement.__code__.co_freevars:
+            implementation = types.FunctionType(
+                replacement.__code__, replacement.__globals__, replacement.__name__,
+                replacement.__defaults__, target.__closure__)
+            implementation.__kwdefaults__ = replacement.__kwdefaults__
+            implementation.__annotations__ = replacement.__annotations__
+            implementation.__doc__ = replacement.__doc__
+            implementation.__qualname__ = replacement.__qualname__
+        Melty.relocated_functions[id(live)] = implementation
+        captures = [f'capture_{index}' for index in range(len(live.__closure__ or ()))]
+        capture_line = f'        ({", ".join(captures)},)\n' if captures else ''
+        source = (
+            f'def make_entry({", ".join(captures)}):\n'
+            '    def entry(*args, **kwargs):\n'
+            + capture_line
+            + '        from meltygui.core.melty import Melty\n'
+            + f'        return Melty.relocated_functions[{id(live)}](*args, **kwargs)\n'
+            + '    return entry\n')
+        namespace = {}
+        exec(compile(source, '<melty definition relocation>', 'exec'), namespace)
+        entry = namespace['make_entry'](*([None] * len(captures)))
+        live.__code__ = entry.__code__
+        live.__defaults__ = None
+        live.__kwdefaults__ = None
+        live.__wrapped__ = implementation
+        live.__melty_relocated__ = True
+        live.__annotations__ = replacement.__annotations__
+        live.__doc__ = replacement.__doc__
+    live.__module__ = replacement.__module__
+    live.__qualname__ = replacement.__qualname__
+
+    def restore():
+        if restore_nested is not None:
+            restore_nested()
+        (live.__code__, live.__defaults__, live.__kwdefaults__, annotations,
+         live.__doc__, live.__module__, live.__qualname__, attributes) = previous
+        live.__annotations__ = annotations
+        live.__dict__.clear()
+        live.__dict__.update(attributes)
+        if target is not live:
+            (target.__code__, target.__defaults__, target.__kwdefaults__, annotations,
+             target.__doc__, target.__module__, target.__qualname__) = target_previous
+            target.__annotations__ = annotations
+        if previous_target is None:
+            Melty.relocated_functions.pop(id(live), None)
+        else:
+            Melty.relocated_functions[id(live)] = previous_target
+    return restore
+
+
+def canonicalize_definitions(replacements):
+    """Rebind exports and type-bearing function metadata to the live objects.
+
+    Only exact object identities are replaced, never names shared by unrelated
+    modules. Runtime instances and arbitrary application object graphs are not
+    traversed. Closure metadata matters for render_func's injection plans and
+    for zero-argument super() in relocated methods.
+    """
+    # Keep the original alive too: replaced tuples/signatures can otherwise
+    # be freed mid-walk and their ids reused by later function metadata.
+    seen = {}
+
+    def replace(value):
+        pair = replacements.get(id(value))
+        if pair is not None and pair[0] is value:
+            return pair[1]
+        identity = id(value)
+        if identity in seen:
+            return seen[identity][1]
+        seen[identity] = (value, value)
+        if isinstance(value, dict):
+            for key, item in list(value.items()):
+                new_key, new_item = replace(key), replace(item)
+                if new_key is not key:
+                    del value[key]
+                if new_key is not key or new_item is not item:
+                    value[new_key] = new_item
+        elif isinstance(value, list):
+            for index, item in enumerate(value):
+                value[index] = replace(item)
+        elif isinstance(value, tuple):
+            result = tuple(replace(item) for item in value)
+            if any(a is not b for a, b in zip(result, value)):
+                seen[identity] = (value, result)
+                return result
+        elif isinstance(value, inspect.Parameter):
+            result = value.replace(annotation=replace(value.annotation), default=replace(value.default))
+            seen[identity] = (value, result)
+            return result
+        elif isinstance(value, inspect.Signature):
+            result = value.replace(parameters=[replace(p) for p in value.parameters.values()],
+                                   return_annotation=replace(value.return_annotation))
+            seen[identity] = (value, result)
+            return result
+        return value
+
+    visited_functions = set()
+
+    def function_metadata(function):
+        if id(function) in visited_functions:
+            return
+        visited_functions.add(id(function))
+        function.__annotations__ = replace(function.__annotations__)
+        function.__defaults__ = replace(function.__defaults__)
+        function.__kwdefaults__ = replace(function.__kwdefaults__)
+        for cell in function.__closure__ or ():
+            try:
+                value = cell.cell_contents
+            except ValueError:
+                continue
+            replacement = replace(value)
+            if replacement is not value:
+                cell.cell_contents = replacement
+            if isinstance(replacement, types.FunctionType):
+                function_metadata(replacement)
+        wrapped = function.__dict__.get('__wrapped__')
+        if isinstance(wrapped, types.FunctionType):
+            function_metadata(wrapped)
+
+    def definition_metadata(value):
+        if isinstance(value, types.FunctionType):
+            function_metadata(value)
+        elif isinstance(value, type):
+            for member in vars(value).values():
+                if isinstance(member, types.FunctionType):
+                    function_metadata(member)
+                elif isinstance(member, (staticmethod, classmethod)):
+                    function_metadata(member.__func__)
+                elif isinstance(member, property):
+                    for function in (member.fget, member.fset, member.fdel):
+                        if function is not None:
+                            function_metadata(function)
+
+    for fresh, live in replacements.values():
+        definition_metadata(fresh)
+        definition_metadata(live)
+    for module in tuple(sys.modules.values()):
+        if not isinstance(module, types.ModuleType):
+            continue
+        touched = False
+        for name, value in tuple(vars(module).items()):
+            pair = replacements.get(id(value))
+            if pair is not None and pair[0] is value:
+                vars(module)[name] = pair[1]
+                touched = True
+        if touched:
+            for value in tuple(vars(module).values()):
+                definition_metadata(value)

meltygui/core/diagnostics/__init__.py

@@ -0,0 +1 @@
+"""Shared framework diagnostics machinery."""

meltygui/core/diagnostics/attribute_churn.py

@@ -0,0 +1,38 @@
+from typing import Dict, Set, Tuple
+
+from meltygui.core.rendering.window_decoration import window
+
+
+@window
+class AttributeChurnMonitor:
+    """Per-frame counter of @live attribute writes.
+
+    Reset at frame end; pair with Toggles.attrib_churn_log to dump
+    a top-N summary each frame the counter is non-empty.
+    """
+
+
+    attributes_changed: Set[Tuple[str, str]] = set()
+    attribute_change_count: Dict[Tuple[str, str], int] = {}
+
+    @classmethod
+    def record(cls, cls_name: str, attr_name: str) -> None:
+        key = (cls_name, attr_name)
+        cls.attributes_changed.add(key)
+        cls.attribute_change_count[key] = cls.attribute_change_count.get(key, 0) + 1
+
+    @classmethod
+    def on_frame_end(cls) -> None:
+        if not cls.attribute_change_count:
+            return
+
+        from meltygui.core.runtime.toggles import Toggles
+        if Toggles.attrib_churn_log:
+            from meltygui.core.melty import Melty
+            top = sorted(cls.attribute_change_count.items(), key=lambda kv: -kv[1])[:10]
+            line = ", ".join(f"{c}.{a}={n}" for (c, a), n in top)
+            print(f"[churn f{Melty.frame_count}] {line}")
+
+
+        cls.attributes_changed.clear()
+        cls.attribute_change_count.clear()

meltygui/core/diagnostics/fps_counter.py

@@ -0,0 +1,39 @@
+"""Per-OS-window frame rate for the Toggles.show_fps titlebar readout.
+
+Frames render on request, so an idle window presents nothing: the rate is
+measured over the recent burst of consecutive frames only. A gap longer than
+IDLE_GAP_S starts a new burst instead of averaging the idle time in; the
+previous burst's rate stays on display until the new one has two frames.
+"""
+import time
+
+# Frames the rate is averaged over. Raise for a steadier, slower readout.
+WINDOW_FRAMES = 60
+# A pause this long between frames counts as idle, not as a slow frame.
+IDLE_GAP_S = 0.25
+
+
+class FpsCounter:
+    def __init__(self):
+        self.frame_starts = []
+        self.rate = None
+        self.frame_ms = 0.0
+
+    def frame_started(self):
+        now = time.perf_counter()
+        if self.frame_starts and now - self.frame_starts[-1] > IDLE_GAP_S:
+            self.frame_starts.clear()
+        self.frame_starts.append(now)
+        del self.frame_starts[:-WINDOW_FRAMES]
+        if len(self.frame_starts) >= 2:
+            self.rate = (len(self.frame_starts) - 1) / (now - self.frame_starts[0])
+        return now
+
+    def frame_finished(self, started):
+        self.frame_ms = (time.perf_counter() - started) * 1000.0
+
+    def label(self):
+        """'118 fps  7.9 ms': the latest burst's rate and the previous frame's
+        render-thread time. A lone frame after idle keeps the last burst's rate."""
+        rate = "--" if self.rate is None else f"{self.rate:.0f}"
+        return f"{rate} fps  {self.frame_ms:.1f} ms"

meltygui/core/diagnostics/gpu_frame_timer.py

@@ -0,0 +1,103 @@
+"""GPU frame-segment timing via GL_TIMESTAMP query objects.
+
+CPU timers around post_frame's segments show where the RENDER THREAD blocks,
+but a present stall is GPU backpressure: the CPU submits everything quickly
+and swap_buffers waits for the queue to drain — the CPU split blames "swap"
+while the actual cost sits in whichever segment's draw calls flooded the GPU
+(UI draw data, the tile-capture pass, the filter/shadow passes, ...).
+Timestamp queries mark when the GPU *executes* each boundary, so a completed
+frame yields per-segment GPU milliseconds.
+
+Non-blocking by design: results are polled a few frames late (ring of DEPTH
+slots) and a slot whose result isn't ready yet is simply dropped when its
+turn to be reused comes. Inert unless the perf-trace toggle is on, and it
+permanently disables itself on the first GL error (headless contexts, old
+drivers, missing GL 3.3 timer support)."""
+
+import time
+
+
+class GpuFrameTimer:
+    DEPTH = 4          # frames in flight before a result is read
+    MAX_STAMPS = 8     # boundaries per frame
+
+    def __init__(self):
+        self._gl = None
+        self._rings = None      # DEPTH x MAX_STAMPS query IDs
+        self._labels = None     # DEPTH x MAX_STAMPS stamp labels
+        self._counts = [0] * self.DEPTH
+        self._frames = [None] * self.DEPTH   # app frame number per slot
+        self._slot = 0
+        self._dead = False
+        self._active = False    # stamping enabled for the current frame
+
+    def begin(self, enabled, frame_no):
+        """Arm the current slot for this frame. GL context must be current."""
+        if self._dead or not enabled:
+            self._active = False
+            return
+        try:
+            if self._rings is None:
+                from OpenGL import GL as gl
+                self._gl = gl
+                self._rings = [[int(q) for q in gl.glGenQueries(self.MAX_STAMPS)]
+                               for _ in range(self.DEPTH)]
+                self._labels = [[None] * self.MAX_STAMPS
+                                for _ in range(self.DEPTH)]
+            self._counts[self._slot] = 0
+            self._frames[self._slot] = frame_no
+            self._active = True
+        except Exception:
+            self._dead = True
+            self._active = False
+
+    def stamp(self, label):
+        if not self._active:
+            return
+        try:
+            i = self._counts[self._slot]
+            if i >= self.MAX_STAMPS:
+                return
+            self._gl.glQueryCounter(self._rings[self._slot][i],
+                                    self._gl.GL_TIMESTAMP)
+            self._labels[self._slot][i] = label
+            self._counts[self._slot] = i + 1
+        except Exception:
+            self._dead = True
+            self._active = False
+
+    def end(self):
+        """Advance the ring; poll the OLDEST slot. Returns (frame_no,
+        {label: gpu_ms}) for a completed frame, else None. Never blocks: an
+        unavailable result stays queued until its slot is about to be reused,
+        then drops."""
+        if not self._active:
+            return None
+        out = None
+        try:
+            gl = self._gl
+            nxt = (self._slot + 1) % self.DEPTH
+            n = self._counts[nxt]
+            if n >= 2 and self._frames[nxt] is not None:
+                avail = gl.glGetQueryObjectiv(self._rings[nxt][n - 1],
+                                              gl.GL_QUERY_RESULT_AVAILABLE)
+                if avail:
+                    ts = [int(gl.glGetQueryObjectui64v(self._rings[nxt][i],
+                                                       gl.GL_QUERY_RESULT))
+                          for i in range(n)]
+                    segs = {}
+                    for i in range(1, n):
+                        segs[self._labels[nxt][i]] = (ts[i] - ts[i - 1]) / 1e6
+                    out = (self._frames[nxt], segs)
+                    self._frames[nxt] = None
+                    self._counts[nxt] = 0
+            self._slot = nxt
+        except Exception:
+            self._dead = True
+            self._active = False
+            return None
+        return out
+
+
+# Module singleton; survives hotswap (re-exec reuses existing context).
+GPU_TIMER = globals().get("GPU_TIMER") or GpuFrameTimer()

meltygui/core/diagnostics/inspection_core.py

@@ -0,0 +1,169 @@
+# fastinspect.py
+from __future__ import annotations
+import inspect
+import weakref
+from types import FunctionType, MethodType
+from typing import Mapping
+
+# Mapping of function -> (signature, code_object_id)
+# WeakKeyDictionary avoids memory leaks when functions go out of scope.
+_SIG_CACHE: "weakref.WeakKeyDictionary[object, tuple[inspect.Signature, int | None]]" = weakref.WeakKeyDictionary()
+
+
+def _unwrap_callable(obj):
+    """Normalize bound methods, functools.partial, and wrappers to a base callable."""
+    # Bound method -> underlying function (keep method object as key if you prefer)
+    if isinstance(obj, MethodType):
+        return obj.__func__
+    # functools.partial exposes .func
+    func = getattr(obj, "func", None)
+    if func is not None and callable(func):
+        return func
+    # Many wrappers set __wrapped__
+    return inspect.unwrap(obj)
+
+
+def _code_id(func) -> int | None:
+    """Stable identifier for the current implementation of a Python function."""
+    code = getattr(func, "__code__", None)
+    return id(code) if code is not None else None  # For builtins/extension funcs returns None
+
+
+def get_signature(callable_obj) -> inspect.Signature:
+    """
+    Fast, safe signature fetch with caching and auto-invalidating when the function's
+    code object changes (i.e., after hot-reload).
+    """
+    base = _unwrap_callable(callable_obj)
+    current_code_id = _code_id(base)
+
+    cached = _SIG_CACHE.get(base)
+    if cached is not None:
+        sig, cached_code_id = cached
+        if cached_code_id == current_code_id:
+            return sig  # up-to-date
+
+    # Compute once; this is the slow part we want to avoid doing repeatedly
+    sig = inspect.signature(base)
+
+    # Store in WeakKeyDictionary
+    _SIG_CACHE[base] = (sig, current_code_id)
+
+    # Bonus: stamp __signature__ so *future* inspect.signature(base) is O(1)
+    try:
+        setattr(base, "__signature__", sig)
+    except Exception:
+        # Not all callables allow setting attributes (e.g., many builtins)
+        pass
+
+    return sig
+
+
+import inspect
+from functools import partial
+from types import FunctionType, MethodType
+from typing import Mapping, Any
+
+
+def set_runtime_defaults_in_place(fn: Any, new_defaults: Mapping[str, Any]) -> bool:
+    """
+    Change the *runtime* defaults of a callable so that calling it uses the new values.
+    Supports:
+      - plain Python functions
+      - bound/unbound methods (updates the underlying function)
+      - classmethod/staticmethod (via bound method's __func__)
+      - functools.partial (you normally want to rebuild/patch the partial; see note)
+
+    Returns True if runtime defaults were updated; False if unsupported (e.g., builtins).
+    """
+    # 1) Find the underlying Python function object we can mutate.
+    base = fn
+    # bound method -> underlying function
+    if isinstance(base, MethodType):
+        base = base.__func__
+    # functools.partial (defaults live on the wrapped func; partial itself has args/keywords)
+    if isinstance(base, partial):
+        base = base.func
+    # unwrap decorator wrappers
+    base = inspect.unwrap(base)
+
+    # Only pure Python functions have writable __defaults__/__kwdefaults__
+    if not isinstance(base, FunctionType):
+        return False
+
+    sig = inspect.signature(base)
+
+    # Build a new parameter list with updated defaults by name
+    params = []
+    for p in sig.parameters.values():
+        if p.name in new_defaults and p.kind not in (p.VAR_POSITIONAL, p.VAR_KEYWORD) and not isinstance(p.default, inspect.Parameter):
+            p = p.replace(default=new_defaults[p.name])
+        params.append(p)
+
+    # Positional defaults must be a trailing contiguous block
+    pos = [p for p in params if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
+    flags = [p.default is not inspect._empty for p in pos]
+    try:
+        first = next(i for i, f in enumerate(flags) if f)
+        if not all(flags[i] for i in range(first, len(flags))):
+            # Invalid layout for runtime defaults; keep function usable, but don't set.
+            return False
+        pos_defaults = tuple(p.default if not isinstance(p.default, inspect.Parameter) else p.default for p in pos[first:]) if pos else None
+    except StopIteration:
+        pos_defaults = None
+
+    # Keyword-only defaults: free-form dict
+    kwonly = [p for p in params if p.kind is p.KEYWORD_ONLY]
+    kwdefaults = {p.name: p.default for p in kwonly if p.default is not inspect._empty} or None
+
+    # 2) Mutate the function object in place
+    try:
+        base.__defaults__ = pos_defaults
+    except Exception:
+        return False
+    try:
+        base.__kwdefaults__ = kwdefaults
+    except Exception:
+        # Some functions do not allow this; that's okay for functions without kw-only defaults
+        pass
+
+    return True
+
+def set_fn_defaults(fn, new_defaults: Mapping[str, Any]) -> bool:
+    ok = set_runtime_defaults_in_place(fn, new_defaults)
+    # Update the inspect signature to match (optional but nice)
+    # try:
+    #     sig = inspect.signature(fn)
+    #     new_params = [(p.replace(default=new_defaults[p.name])
+    #                    if p.name in new_defaults and p.kind not in (p.VAR_POSITIONAL, p.VAR_KEYWORD)
+    #                    else p)
+    #                   for p in sig.parameters.values()]
+    #     new_sig = inspect.Signature(new_params, return_annotation=sig.return_annotation)
+    #     # set on the exact object and the unwrapped base for robustness
+    #     setattr(fn, "__signature__", new_sig)
+    #     setattr(inspect.unwrap(fn), "__signature__", new_sig)
+    #
+    # except Exception:
+    #     pass
+    return ok
+
+
+def get_params(callable_obj) -> Mapping[str, inspect.Parameter]:
+    """Convenience: directly get the .parameters mapping (ordered)."""
+    return get_signature(callable_obj).parameters
+
+
+def invalidate(callable_obj=None):
+    """
+    Invalidate the cache for one callable (or all, if None).
+    Useful if you mutate __code__ in-place (rare); otherwise hot-reload creates
+    new function objects and the cache auto-updates by key.
+    """
+    if callable_obj is None:
+        _SIG_CACHE.clear()
+        return
+    base = _unwrap_callable(callable_obj)
+    try:
+        del _SIG_CACHE[base]
+    except KeyError:
+        pass

meltygui/core/diagnostics/monitor_core.py

@@ -0,0 +1,105 @@
+import subprocess
+import threading
+import time
+
+from meltygui.core.automation.mcp_server import _LOG_RESULT_CAP
+from meltygui.core.rendering.render_funcs import RenderFuncs
+from meltygui.core.rendering.window_decoration import window
+
+_SENTINEL = object()
+
+
+class _MonitorMeta(type):
+    _brightness = None
+    _pending = None
+    _event = threading.Event()
+    _thread = None
+    _lock = threading.Lock()
+
+    def __init__(cls, *args):
+        super().__init__(*args)
+
+        def _worker():
+            while True:
+                cls._event.wait()
+                cls._event.clear()
+                with cls._lock:
+                    value = cls._pending
+                if value is _SENTINEL:
+                    break
+                try:
+                    value = min(max(1, value), 100)
+                    subprocess.run(["ddcutil", "setvcp", "10", str(value)])
+                except Exception as e:
+                    print(f"Monitor error: {e}")
+
+        cls._thread = threading.Thread(target=_worker, daemon=True)
+        cls._thread.start()
+
+        def _fetch():
+            # result = subprocess.run(["ddcutil", "getvcp", "10"], capture_output=True, text=True)
+            # for part in result.stdout.split(","):
+            #     if "current value" in part:
+            #         cls._brightness = int(part.split("=")[1].strip())
+            #         return
+            cls._brightness = 30
+
+        threading.Thread(target=_fetch, daemon=True).start()
+
+    @property
+    def brightness(cls):
+        return cls._brightness
+
+    @brightness.setter
+    def brightness(cls, value):
+        cls._brightness = value
+        with cls._lock:
+            cls._pending = value
+        cls._event.set()
+
+    def shutdown(cls):
+        with cls._lock:
+            cls._pending = _SENTINEL
+        cls._event.set()
+        cls._thread.join()
+
+
+class Monitor(metaclass=_MonitorMeta):
+    pass
+
+
+@window(live=True, view_func=RenderFuncs.draw_type)
+class MCPServerLog:
+    """Append-only, in-memory record of MCP tool interactions for this launcher.
+
+    Every tool call (and its outcome) is appended to the ``logs`` class
+    attribute by the logging wrapper in ``start_launcher_mcp``. It's a class
+    attribute rather than an instance field so it's reachable from anywhere —
+    including ``eval_python`` — as just ``MCPServerLog.logs`` without threading
+    an instance around.
+
+    Each entry is a dict::
+
+        {"tool": str, "args": dict, "result": str|None,
+         "error": str|None, "timestamp": float}
+    """
+
+    logs = []
+    def __init__(self):
+        pass
+
+    @classmethod
+    def record(cls, tool, args, result=None, error=None):
+        def _cap(v):
+            if v is None:
+                return None
+            s = v if isinstance(v, str) else repr(v)
+            return s if len(s) <= _LOG_RESULT_CAP else s[:_LOG_RESULT_CAP] + "…"
+
+        cls.logs.append({
+            "tool": tool,
+            "args": dict(args),
+            "result": _cap(result),
+            "error": _cap(error),
+            "timestamp": time.time(),
+        })