leanback 0.1.3__tar.gz → 0.1.4__tar.gz

{leanback-0.1.3 → leanback-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: leanback
-Version: 0.1.3
+Version: 0.1.4
 Summary: MCP server for Lean 4 theorem proving — check, prove, goals, eval, search
 Author: Stefan Szeider
 License: Apache-2.0
@@ -92,6 +92,8 @@ check(project="/home/user/lean/myproject", file="MyProof.lean")
 check(project="/home/user/lean/myproject", expr="#check Nat.add", imports=["Mathlib.Tactic"])
 ```
 
+Repeated `check(file=...)` calls on the same file reuse a warm Lean server: the first check pays the import cost, subsequent checks after edits take seconds (as long as the file's import lines are unchanged). Idle servers shut down automatically after 10 minutes; set `LEANBACK_NO_WARM=1` to disable warm sessions entirely.
+
 ### prove
 
 Verify theorem proofs with tactics, or check proof files.
@@ -121,8 +123,11 @@ Execute Lean expressions and see results.
 eval(project="/home/user/lean/myproject", code="#eval 2 + 2")
 eval(project="/home/user/lean/myproject", code="#check List.map")
 eval(project="/home/user/lean/myproject", code="#eval Nat.gcd 12 18", mathlib=True)
+eval(project="/home/user/lean/myproject", code="#eval myFunc 3", imports=["MyProject.Definitions"], build=True)
 ```
 
+With `build=True`, imported modules of the project itself are compiled first (`lake build`), so they don't need to be built manually before use.
+
 ### search
 
 Find declarations in Mathlib by pattern.
@@ -135,7 +140,7 @@ search(project="/home/user/lean/myproject", batch="add_assoc,mul_assoc,add_comm"
 
 ## All Tools Are Read-Only
 
-LeanBack never modifies files. It only reads project structure and runs Lean to check/evaluate code. File creation and editing is left to your agent's own tools.
+LeanBack never modifies your source files. It only reads project structure and runs Lean to check/evaluate code. File creation and editing is left to your agent's own tools. The one exception: `eval` with `build=True` runs `lake build`, which writes build artifacts to the project's `.lake` directory.
 
 ## Response Format
 

{leanback-0.1.3 → leanback-0.1.4}/README.md

@@ -73,6 +73,8 @@ check(project="/home/user/lean/myproject", file="MyProof.lean")
 check(project="/home/user/lean/myproject", expr="#check Nat.add", imports=["Mathlib.Tactic"])
 ```
 
+Repeated `check(file=...)` calls on the same file reuse a warm Lean server: the first check pays the import cost, subsequent checks after edits take seconds (as long as the file's import lines are unchanged). Idle servers shut down automatically after 10 minutes; set `LEANBACK_NO_WARM=1` to disable warm sessions entirely.
+
 ### prove
 
 Verify theorem proofs with tactics, or check proof files.
@@ -102,8 +104,11 @@ Execute Lean expressions and see results.
 eval(project="/home/user/lean/myproject", code="#eval 2 + 2")
 eval(project="/home/user/lean/myproject", code="#check List.map")
 eval(project="/home/user/lean/myproject", code="#eval Nat.gcd 12 18", mathlib=True)
+eval(project="/home/user/lean/myproject", code="#eval myFunc 3", imports=["MyProject.Definitions"], build=True)
 ```
 
+With `build=True`, imported modules of the project itself are compiled first (`lake build`), so they don't need to be built manually before use.
+
 ### search
 
 Find declarations in Mathlib by pattern.
@@ -116,7 +121,7 @@ search(project="/home/user/lean/myproject", batch="add_assoc,mul_assoc,add_comm"
 
 ## All Tools Are Read-Only
 
-LeanBack never modifies files. It only reads project structure and runs Lean to check/evaluate code. File creation and editing is left to your agent's own tools.
+LeanBack never modifies your source files. It only reads project structure and runs Lean to check/evaluate code. File creation and editing is left to your agent's own tools. The one exception: `eval` with `build=True` runs `lake build`, which writes build artifacts to the project's `.lake` directory.
 
 ## Response Format
 

{leanback-0.1.3 → leanback-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "leanback"
-version = "0.1.3"
+version = "0.1.4"
 description = "MCP server for Lean 4 theorem proving — check, prove, goals, eval, search"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{leanback-0.1.3 → leanback-0.1.4}/src/leanback/README.md

@@ -12,8 +12,11 @@ MCP server exposing Lean 4 development tools via Model Context Protocol.
 - `mathlib_search_simple.py`: Regex-based Mathlib search backend
 - `mcp_test.py`: E2E test client
 - `common/`: Shared utilities
-  - `env.py`: Lean environment handling (LeanRunner)
-  - `errors.py`: Error parsing and formatting
+  - `env.py`: Lean environment handling (LeanRunner, lake build helpers)
+  - `errors.py`: Error parsing and formatting (CLI JSON and LSP diagnostics)
+  - `lsp_client.py`: Synchronous Lean LSP client for warm file checks
+  - `warm.py`: Warm worker registry (staleness, idle timeout, atexit cleanup)
+  - `watchdog.py`: Process wrapper that reaps workers if the server dies
   - `project_context.py`: Project validation and context
   - `path_manager.py`: Path resolution and management
   - `util.py`: Misc utilities (temp file creation)

{leanback-0.1.3 → leanback-0.1.4}/src/leanback/common/env.py

@@ -29,6 +29,47 @@ def _find_native_dynlibs(project_path: Path) -> list[Path]:
     return sorted(packages_dir.glob(f"*/.lake/build/lib/lib*.{ext}"))
 
 
+def find_local_modules(project_path: Path, modules: list[str]) -> list[str]:
+    """Filter module names to those with source files in the project.
+
+    A module like ``Foo.Bar`` is local if ``<project>/Foo/Bar.lean`` exists.
+    Dependency modules (e.g. Mathlib.*) and core modules are excluded — they
+    are already built or come from the cache.
+    """
+    local = []
+    for module in modules:
+        source = project_path / (module.replace(".", "/") + ".lean")
+        if source.is_file():
+            local.append(module)
+    return local
+
+
+def build_modules(
+    project_path: Path, modules: list[str], timeout: float = 600
+) -> tuple[bool, str]:
+    """Build the given modules with ``lake build`` in the project directory.
+
+    Returns:
+        Tuple of (success, output). On failure, output contains the
+        combined stdout/stderr from lake.
+    """
+    if not modules:
+        return True, ""
+    try:
+        result = subprocess.run(
+            ["lake", "build", *modules],
+            cwd=project_path,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        return False, f"lake build timed out after {timeout:.0f} seconds"
+    output = ((result.stdout or "") + "\n" + (result.stderr or "")).strip()
+    return result.returncode == 0, output
+
+
 class LeanRunner:
     """
     Utility for running Lean commands in the appropriate environment.

{leanback-0.1.3 → leanback-0.1.4}/src/leanback/common/errors.py

@@ -489,6 +489,34 @@ def _get_suggestion_for_message(message: str) -> str | None:
     return None
 
 
+def lsp_diagnostics_to_errors(diagnostics: list[dict], file_name: str) -> list:
+    """Convert LSP publishDiagnostics entries to LeanError objects.
+
+    LSP positions are 0-based for both line and character; Lean's CLI JSON
+    output (which LeanError follows) uses 1-based lines and 0-based columns,
+    so lines are shifted by one.
+    """
+    severity_names = {1: "error", 2: "warning", 3: "info", 4: "info"}
+    errors = []
+    for diag in diagnostics:
+        start = diag.get("range", {}).get("start", {})
+        end = diag.get("range", {}).get("end", {})
+        msg_text = diag.get("message", "Unknown error")
+        errors.append(
+            LeanError(
+                file_name=file_name,
+                line=start.get("line", 0) + 1,
+                column=start.get("character", 0),
+                end_line=end.get("line", 0) + 1 if end else None,
+                end_column=end.get("character") if end else None,
+                severity=severity_names.get(diag.get("severity", 1), "error"),
+                message=msg_text,
+                suggestion=_get_suggestion_for_message(msg_text),
+            )
+        )
+    return errors
+
+
 def parse_lean_output(output: str, json_format: bool = False) -> list:
     """
     Parse Lean's output into structured errors.

leanback-0.1.4/src/leanback/common/lsp_client.py

@@ -0,0 +1,412 @@
+"""
+Synchronous Lean LSP client for warm-environment re-checking.
+
+LeanBack keeps a warm ``lake serve`` process per Lean project so that
+re-checking an edited file skips the expensive Mathlib import: the imported
+environment stays resident across edits, so a body-only edit re-checks in a
+fraction of a second instead of tens of seconds.
+
+This module drives a single ``lake serve`` process over the Language Server
+Protocol (LSP). It is deliberately single-threaded: there is no background
+reader thread. Every read happens inside a blocking wait bounded by a deadline,
+using ``select.select`` on the server's stdout (POSIX only — the warm path is
+POSIX-only; other platforms fall back to the cold path elsewhere).
+
+Framing follows the LSP base protocol: ``Content-Length: N\\r\\n\\r\\n`` followed
+by an N-byte UTF-8 JSON body. The client tolerates all interleaved server noise
+(``$/lean/fileProgress`` notifications, intermediate ``publishDiagnostics``,
+and server-to-client ``workspace/*/refresh`` requests).
+"""
+
+import json
+import os
+import select
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+
+# Timeout (seconds) for the initialize handshake. The server answers
+# ``initialize`` quickly; this only guards against a server that never starts.
+_HANDSHAKE_TIMEOUT = 60.0
+
+# Whole-file replacement range for an Incremental (sync kind 2) didChange: a
+# single content-change event spanning the entire document. The end line is
+# deliberately huge so it covers any current file length.
+_WHOLE_FILE_RANGE = {
+    "start": {"line": 0, "character": 0},
+    "end": {"line": 10_000_000, "character": 0},
+}
+
+
+class LspTimeoutError(Exception):
+    """Raised when an LSP operation does not complete within its deadline."""
+
+
+class LspProtocolError(Exception):
+    """Raised on a protocol failure: dead process, malformed frame, or an
+    error response from the server."""
+
+
+class LeanLspWorker:
+    """Drive a single warm ``lake serve`` process over LSP.
+
+    The worker spawns the server, performs the LSP handshake, and lets callers
+    re-check the on-disk content of files. The first check of a path issues a
+    ``didOpen``; later checks of the same path issue a whole-file ``didChange``,
+    which reuses the warm imported environment.
+
+    The worker is single-threaded and not safe for concurrent use.
+    """
+
+    def __init__(
+        self,
+        project_path: Path,
+        server_command: list[str] | None = None,
+        use_watchdog: bool = True,
+    ) -> None:
+        """Spawn the server and perform the LSP handshake.
+
+        Args:
+            project_path: Absolute path to the Lean project. Used as the
+                server's working directory and as its ``rootUri``.
+            server_command: Full command to launch the server. Defaults to
+                ``["lake", "serve"]``. Tests override this with a fake server.
+            use_watchdog: On POSIX, wrap the command in
+                ``leanback.common.watchdog`` so the server is killed if this
+                process is SIGKILLed. Ignored on non-POSIX platforms.
+
+        Raises:
+            LspProtocolError: If the server dies or returns an error during the
+                handshake.
+            LspTimeoutError: If the handshake does not complete in time.
+        """
+        self._project_path = Path(project_path).resolve()
+        self._closed = False
+        self._id = 0
+        self._buf = b""
+        # uri -> latest publishDiagnostics payload {"version": int|None,
+        # "diagnostics": list[dict]}.
+        self._diagnostics: dict[str, dict] = {}
+        # uris that have received a didOpen, and their current version int.
+        self._versions: dict[str, int] = {}
+        self._last_used = time.monotonic()
+
+        command = list(server_command) if server_command else ["lake", "serve"]
+        if use_watchdog and os.name == "posix":
+            command = [
+                sys.executable,
+                "-m",
+                "leanback.common.watchdog",
+                str(os.getpid()),
+                "--",
+                *command,
+            ]
+
+        # stderr goes to DEVNULL: it must never be a pipe, which would fill and
+        # deadlock the server. stdout is unbuffered (bufsize=0) so a single
+        # read() returns whatever bytes are available without waiting to fill a
+        # buffer — this pairs cleanly with select() on the raw fd.
+        self._proc = subprocess.Popen(
+            command,
+            cwd=self._project_path,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            bufsize=0,
+        )
+
+        try:
+            self._handshake()
+        except BaseException:
+            self.shutdown()
+            raise
+
+    @property
+    def alive(self) -> bool:
+        """Whether the server process is still running and not shut down."""
+        return not self._closed and self._proc.poll() is None
+
+    @property
+    def last_used(self) -> float:
+        """``time.monotonic()`` timestamp of the most recent ``check_file``."""
+        return self._last_used
+
+    def check_file(self, file_path: Path, timeout: float = 600.0) -> list[dict]:
+        """Check the current on-disk content of ``file_path``.
+
+        The first call for a given path issues a ``didOpen``; later calls issue
+        a whole-file ``didChange``. The method then waits for the server to
+        finalize diagnostics for the new version and returns them.
+
+        Args:
+            file_path: Absolute path to a ``.lean`` file that exists on disk.
+            timeout: Maximum seconds to wait for diagnostics to finalize.
+
+        Returns:
+            The list of diagnostic entries (raw LSP dicts) from the
+            ``publishDiagnostics`` payload for the checked version. Empty if the
+            file is clean.
+
+        Raises:
+            LspProtocolError: If the server has exited or returns an error.
+            LspTimeoutError: If diagnostics do not finalize within ``timeout``.
+        """
+        self._ensure_alive()
+        self._last_used = time.monotonic()
+
+        path = Path(file_path).resolve()
+        uri = path.as_uri()
+        text = path.read_text(encoding="utf-8")
+
+        if uri not in self._versions:
+            version = 1
+            self._versions[uri] = version
+            self._notify(
+                "textDocument/didOpen",
+                {
+                    "textDocument": {
+                        "uri": uri,
+                        "languageId": "lean4",
+                        "version": version,
+                        "text": text,
+                    }
+                },
+            )
+        else:
+            version = self._versions[uri] + 1
+            self._versions[uri] = version
+            self._notify(
+                "textDocument/didChange",
+                {
+                    "textDocument": {"uri": uri, "version": version},
+                    "contentChanges": [{"range": _WHOLE_FILE_RANGE, "text": text}],
+                },
+            )
+
+        deadline = time.monotonic() + timeout
+        rid = self._request(
+            "textDocument/waitForDiagnostics", {"uri": uri, "version": version}
+        )
+        self._await_response(rid, deadline)
+
+        payload = self._diagnostics.get(uri)
+        if payload is None:
+            return []
+        return payload["diagnostics"]
+
+    def shutdown(self, timeout: float = 5.0) -> None:
+        """Shut the server down and terminate the process. Idempotent.
+
+        Sends a best-effort ``shutdown`` request and ``exit`` notification with
+        a short deadline, then terminates (and, if needed, kills) the process.
+
+        Args:
+            timeout: Maximum seconds to wait for the ``shutdown`` response.
+        """
+        if self._closed:
+            return
+        self._closed = True
+
+        if self._proc.poll() is None:
+            try:
+                rid = self._request("shutdown", None)
+                self._await_response(rid, time.monotonic() + timeout)
+            except (LspProtocolError, LspTimeoutError):
+                pass
+            try:
+                self._notify("exit", None)
+            except LspProtocolError:
+                pass
+
+        self._terminate()
+
+    # -- internals ---------------------------------------------------------
+
+    def _handshake(self) -> None:
+        """Perform the ``initialize`` / ``initialized`` LSP handshake."""
+        rid = self._request(
+            "initialize",
+            {
+                "processId": os.getpid(),
+                "rootUri": self._project_path.as_uri(),
+                "capabilities": {
+                    "textDocument": {
+                        "synchronization": {
+                            "didSave": True,
+                            "dynamicRegistration": False,
+                        },
+                        "publishDiagnostics": {"relatedInformation": True},
+                    }
+                },
+            },
+        )
+        self._await_response(rid, time.monotonic() + _HANDSHAKE_TIMEOUT)
+        self._notify("initialized", {})
+
+    def _terminate(self) -> None:
+        """Terminate the process: SIGTERM, then SIGKILL after a short grace."""
+        if self._proc.poll() is not None:
+            return
+        try:
+            self._proc.terminate()
+            self._proc.wait(timeout=5.0)
+        except subprocess.TimeoutExpired:
+            self._proc.kill()
+            try:
+                self._proc.wait(timeout=5.0)
+            except subprocess.TimeoutExpired:
+                pass
+        except ProcessLookupError:
+            pass
+
+    def _ensure_alive(self) -> None:
+        """Raise if the worker is closed or the process has exited."""
+        if self._closed:
+            raise LspProtocolError("worker has been shut down")
+        if self._proc.poll() is not None:
+            raise LspProtocolError("Lean server process has exited")
+
+    def _next_id(self) -> int:
+        self._id += 1
+        return self._id
+
+    def _send(self, obj: dict) -> None:
+        """Frame and write a JSON-RPC message to the server's stdin."""
+        if self._proc.poll() is not None:
+            raise LspProtocolError("Lean server process has exited")
+        data = json.dumps(obj).encode("utf-8")
+        header = f"Content-Length: {len(data)}\r\n\r\n".encode("ascii")
+        try:
+            self._proc.stdin.write(header + data)
+            self._proc.stdin.flush()
+        except (BrokenPipeError, OSError) as exc:
+            raise LspProtocolError(f"failed to write to Lean server: {exc}")
+
+    def _request(self, method: str, params: object) -> int:
+        """Send a JSON-RPC request and return its id."""
+        rid = self._next_id()
+        self._send({"jsonrpc": "2.0", "id": rid, "method": method, "params": params})
+        return rid
+
+    def _notify(self, method: str, params: object) -> None:
+        """Send a JSON-RPC notification (no id, no response expected)."""
+        self._send({"jsonrpc": "2.0", "method": method, "params": params})
+
+    def _respond_null(self, rid: object) -> None:
+        """Answer a server-to-client request with a null result (politeness)."""
+        self._send({"jsonrpc": "2.0", "id": rid, "result": None})
+
+    def _await_response(self, rid: int, deadline: float) -> object:
+        """Read and dispatch messages until the response for ``rid`` arrives.
+
+        Args:
+            rid: The request id to wait for.
+            deadline: ``time.monotonic()`` value past which to give up.
+
+        Returns:
+            The ``result`` field of the matching response.
+
+        Raises:
+            LspProtocolError: On a dead process, malformed frame, or error
+                response.
+            LspTimeoutError: If the response does not arrive by ``deadline``.
+        """
+        while True:
+            msg = self._read_message(deadline)
+            if "method" in msg:
+                if "id" in msg:
+                    # Server-to-client request (e.g. semanticTokens/refresh):
+                    # answer politely and keep waiting.
+                    self._respond_null(msg["id"])
+                else:
+                    self._handle_notification(msg)
+                continue
+            if msg.get("id") != rid:
+                # A response to some other (already abandoned) request.
+                continue
+            if "error" in msg:
+                raise LspProtocolError(f"LSP error response: {msg['error']}")
+            return msg.get("result")
+
+    def _handle_notification(self, msg: dict) -> None:
+        """Store publishDiagnostics payloads; ignore all other notifications."""
+        if msg.get("method") != "textDocument/publishDiagnostics":
+            return
+        params = msg.get("params", {})
+        uri = params.get("uri")
+        if uri is None:
+            return
+        version = params.get("version")
+        diagnostics = params.get("diagnostics", [])
+        existing = self._diagnostics.get(uri)
+        # Keep the latest payload for the uri: overwrite unless this one is
+        # tagged with a strictly older version.
+        if (
+            existing is None
+            or version is None
+            or existing["version"] is None
+            or version >= existing["version"]
+        ):
+            self._diagnostics[uri] = {
+                "version": version,
+                "diagnostics": diagnostics,
+            }
+
+    def _read_message(self, deadline: float) -> dict:
+        """Read one complete JSON-RPC message before ``deadline``.
+
+        Accumulates bytes from the server's stdout into an internal buffer and
+        parses framed messages out of it.
+
+        Raises:
+            LspProtocolError: If the process exits or a frame is malformed.
+            LspTimeoutError: If no complete message arrives by ``deadline``.
+        """
+        while True:
+            frame = self._try_parse_frame()
+            if frame is not None:
+                return frame
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise LspTimeoutError("timed out waiting for LSP message")
+
+            readable, _, _ = select.select([self._proc.stdout], [], [], remaining)
+            if not readable:
+                if self._proc.poll() is not None:
+                    raise LspProtocolError("Lean server process has exited")
+                continue
+
+            chunk = self._proc.stdout.read(65536)
+            if not chunk:
+                raise LspProtocolError("Lean server closed its output stream")
+            self._buf += chunk
+
+    def _try_parse_frame(self) -> dict | None:
+        """Parse one framed message from the buffer, or return None if partial.
+
+        Raises:
+            LspProtocolError: If the header lacks Content-Length or the body is
+                not valid JSON.
+        """
+        if b"\r\n\r\n" not in self._buf:
+            return None
+        head, _, rest = self._buf.partition(b"\r\n\r\n")
+
+        length = None
+        for line in head.split(b"\r\n"):
+            if line.lower().startswith(b"content-length:"):
+                length = int(line.split(b":", 1)[1].strip())
+        if length is None:
+            raise LspProtocolError(f"missing Content-Length in header: {head!r}")
+
+        if len(rest) < length:
+            return None
+        body = rest[:length]
+        self._buf = rest[length:]
+        try:
+            return json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise LspProtocolError(f"malformed LSP message body: {exc}")

leanback-0.1.4/src/leanback/common/warm.py

@@ -0,0 +1,171 @@
+"""
+Warm Lean LSP worker registry.
+
+Keeps one persistent ``lake serve`` worker per project so that re-checking an
+edited file reuses the in-memory import environment instead of re-loading all
+``.olean`` files in a fresh process (~0.2 s instead of 20-120 s for
+Mathlib-scale imports; the speedup applies when the file's import header is
+unchanged between calls).
+
+Lifecycle safeguards:
+    - Workers are spawned under the watchdog wrapper (see ``watchdog.py``), so
+      they die even if LeanBack is SIGKILLed.
+    - A worker is invalidated when the project configuration changes
+      (lean-toolchain, lakefile, lake-manifest mtimes).
+    - An idle worker is shut down after ``IDLE_TIMEOUT`` seconds (workers hold
+      the imported environment in RAM — several GB for full Mathlib).
+    - All workers are shut down atexit.
+
+The warm path is POSIX-only and can be disabled with LEANBACK_NO_WARM=1;
+callers must fall back to the cold ``lake env lean`` path whenever
+``check_file_warm`` returns None.
+"""
+
+import atexit
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+
+from leanback.common.lsp_client import (
+    LeanLspWorker,
+    LspProtocolError,
+    LspTimeoutError,
+)
+
+
+logger = logging.getLogger(__name__)
+
+# Seconds a worker may sit unused before the sweeper shuts it down.
+IDLE_TIMEOUT = 600.0
+
+# Seconds between sweeper runs.
+SWEEP_INTERVAL = 60.0
+
+# Project files whose modification invalidates a warm worker.
+_CONFIG_FILES = (
+    "lean-toolchain",
+    "lakefile.lean",
+    "lakefile.toml",
+    "lake-manifest.json",
+)
+
+
+def warm_enabled() -> bool:
+    """Whether the warm LSP path may be used on this platform/configuration."""
+    return os.name == "posix" and os.environ.get("LEANBACK_NO_WARM") != "1"
+
+
+def _config_snapshot(project_path: Path) -> tuple:
+    """Snapshot mtimes of the files that invalidate a warm worker."""
+    snapshot = []
+    for name in _CONFIG_FILES:
+        path = project_path / name
+        try:
+            snapshot.append((name, path.stat().st_mtime_ns))
+        except OSError:
+            snapshot.append((name, None))
+    return tuple(snapshot)
+
+
+class _WorkerRegistry:
+    """Registry of warm workers, keyed by resolved project path."""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._workers: dict[Path, tuple[LeanLspWorker, tuple]] = {}
+        self._project_locks: dict[Path, threading.Lock] = {}
+        self._sweeper: threading.Thread | None = None
+
+    def project_lock(self, project_path: Path) -> threading.Lock:
+        """Per-project lock serializing warm checks (the worker is single-threaded)."""
+        with self._lock:
+            return self._project_locks.setdefault(project_path, threading.Lock())
+
+    def get(self, project_path: Path) -> LeanLspWorker:
+        """Return a live, non-stale worker for the project, spawning if needed."""
+        snapshot = _config_snapshot(project_path)
+        with self._lock:
+            entry = self._workers.get(project_path)
+            if entry is not None:
+                worker, spawn_snapshot = entry
+                if worker.alive and spawn_snapshot == snapshot:
+                    return worker
+                del self._workers[project_path]
+            else:
+                worker = None
+        # Shut down the stale/dead worker outside the registry lock.
+        if worker is not None:
+            worker.shutdown()
+            logger.info("Respawning warm worker for %s (stale or dead)", project_path)
+        new_worker = LeanLspWorker(project_path)
+        with self._lock:
+            self._workers[project_path] = (new_worker, snapshot)
+            self._ensure_sweeper()
+        return new_worker
+
+    def discard(self, project_path: Path) -> None:
+        """Shut down and forget the project's worker (if any)."""
+        with self._lock:
+            entry = self._workers.pop(project_path, None)
+        if entry is not None:
+            entry[0].shutdown()
+
+    def shutdown_all(self) -> None:
+        """Shut down every worker. Registered atexit."""
+        with self._lock:
+            entries = list(self._workers.values())
+            self._workers.clear()
+        for worker, _ in entries:
+            worker.shutdown()
+
+    def _ensure_sweeper(self) -> None:
+        # Caller holds self._lock.
+        if self._sweeper is None or not self._sweeper.is_alive():
+            self._sweeper = threading.Thread(
+                target=self._sweep_loop, name="leanback-warm-sweeper", daemon=True
+            )
+            self._sweeper.start()
+
+    def _sweep_loop(self) -> None:
+        while True:
+            time.sleep(SWEEP_INTERVAL)
+            now = time.monotonic()
+            with self._lock:
+                idle = [
+                    path
+                    for path, (worker, _) in self._workers.items()
+                    if now - worker.last_used > IDLE_TIMEOUT
+                ]
+                entries = [self._workers.pop(path) for path in idle]
+            for worker, _ in entries:
+                logger.info("Shutting down idle warm worker")
+                worker.shutdown()
+
+
+_registry = _WorkerRegistry()
+atexit.register(_registry.shutdown_all)
+
+
+def check_file_warm(
+    project_path: Path, file_path: Path, timeout: float = 600.0
+) -> list[dict] | None:
+    """Check a file via the warm LSP worker.
+
+    Returns the LSP diagnostics list on success, or None when the warm path
+    is unavailable or failed — the caller must then fall back to the cold
+    path. On failure the project's worker is discarded, so the next call
+    starts fresh.
+    """
+    if not warm_enabled():
+        return None
+    project_path = project_path.resolve()
+    with _registry.project_lock(project_path):
+        try:
+            worker = _registry.get(project_path)
+            return worker.check_file(file_path, timeout=timeout)
+        except (LspTimeoutError, LspProtocolError, OSError) as exc:
+            logger.warning("Warm check failed (%s); falling back to cold path", exc)
+            _registry.discard(project_path)
+            return None

leanback-0.1.4/src/leanback/common/watchdog.py

@@ -0,0 +1,182 @@
+"""
+Watchdog wrapper that kills a child process when its grandparent dies.
+
+LeanBack spawns long-lived ``lake serve`` workers. If LeanBack itself is
+SIGKILLed, those workers would be orphaned and keep multiple GB of RAM
+resident. To defend against this, LeanBack does not spawn the worker
+directly; it spawns this watchdog instead::
+
+    python -m leanback.common.watchdog <parent_pid> -- <cmd> [args...]
+
+The watchdog execs the command as its own child, passing its stdin, stdout,
+and stderr straight through (so the grandparent's LSP pipes reach the worker
+unchanged). It then polls ``<parent_pid>`` and, when that process disappears,
+terminates the child (SIGTERM, then SIGKILL after a grace period).
+
+POSIX-only. Stdlib-only, no third-party imports.
+
+Interface notes:
+    - The watchdog NEVER writes to stdout — that stream belongs to the child's
+      LSP protocol and any extra byte would corrupt it. All diagnostics go to
+      stderr.
+    - At startup the watchdog prints ``watchdog: child pid <N>`` to stderr.
+      This is a stable, documented interface: callers (and tests) may parse it
+      to learn the child's PID.
+"""
+
+import os
+import signal
+import subprocess
+import sys
+import time
+
+
+# How often (in seconds) to poll the parent PID. Overridable via
+# --poll-interval so tests can run quickly.
+DEFAULT_POLL_INTERVAL = 2.0
+
+# How long (in seconds) to wait for the child to exit after SIGTERM before
+# escalating to SIGKILL.
+TERM_GRACE = 5.0
+
+
+def _terminate_child(proc: subprocess.Popen, grace: float = TERM_GRACE) -> None:
+    """Terminate the child: SIGTERM, wait up to ``grace`` seconds, then SIGKILL.
+
+    Safe to call when the child has already exited.
+    """
+    if proc.poll() is not None:
+        return
+    try:
+        proc.terminate()
+    except ProcessLookupError:
+        return
+    try:
+        proc.wait(timeout=grace)
+        return
+    except subprocess.TimeoutExpired:
+        pass
+    try:
+        proc.kill()
+    except ProcessLookupError:
+        return
+    try:
+        proc.wait(timeout=grace)
+    except subprocess.TimeoutExpired:
+        pass
+
+
+def _parse_args(argv: list[str]) -> tuple[int, float, list[str]]:
+    """Parse ``<parent_pid> [--poll-interval S] -- <cmd> [args...]``.
+
+    Returns:
+        Tuple of (parent_pid, poll_interval, command).
+
+    Raises:
+        ValueError: If the arguments are malformed.
+    """
+    poll_interval = DEFAULT_POLL_INTERVAL
+    parent_pid: int | None = None
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--":
+            i += 1
+            break
+        elif arg == "--poll-interval":
+            if i + 1 >= len(argv):
+                raise ValueError("--poll-interval requires a value")
+            poll_interval = float(argv[i + 1])
+            i += 2
+        elif arg.startswith("--poll-interval="):
+            poll_interval = float(arg.split("=", 1)[1])
+            i += 1
+        elif parent_pid is None:
+            parent_pid = int(arg)
+            i += 1
+        else:
+            raise ValueError(f"unexpected argument before '--': {arg!r}")
+
+    command = argv[i:]
+    if parent_pid is None:
+        raise ValueError("missing parent_pid")
+    if not command:
+        raise ValueError("missing command after '--'")
+    return parent_pid, poll_interval, command
+
+
+def main(argv: list[str]) -> int:
+    """Run the watchdog.
+
+    Args:
+        argv: Arguments after the program name, i.e.
+            ``[<parent_pid>, [--poll-interval, S,] '--', <cmd>, args...]``.
+
+    Returns:
+        The child's return code if it exits on its own or via a forwarded
+        signal; ``1`` if the parent died first.
+    """
+    try:
+        parent_pid, poll_interval, command = _parse_args(argv)
+    except ValueError as exc:
+        print(f"watchdog: {exc}", file=sys.stderr)
+        print(
+            "watchdog: usage: python -m leanback.common.watchdog "
+            "<parent_pid> [--poll-interval S] -- <cmd> [args...]",
+            file=sys.stderr,
+        )
+        return 2
+
+    # Spawn the child, inheriting our stdin/stdout/stderr. We deliberately do
+    # NOT create pipes: the grandparent's LSP pipes must pass straight through.
+    proc = subprocess.Popen(command)
+    print(f"watchdog: child pid {proc.pid}", file=sys.stderr, flush=True)
+
+    # Forward SIGTERM/SIGINT that we receive to the child, then exit with its
+    # return code. A small flag records that we were signalled.
+    signalled = False
+
+    def _forward(signum: int, _frame: object) -> None:
+        nonlocal signalled
+        signalled = True
+
+    signal.signal(signal.SIGTERM, _forward)
+    signal.signal(signal.SIGINT, _forward)
+
+    try:
+        while True:
+            # Did the child exit on its own?
+            rc = proc.poll()
+            if rc is not None:
+                return rc
+
+            # Were we asked to shut down?
+            if signalled:
+                _terminate_child(proc)
+                rc = proc.poll()
+                return rc if rc is not None else 1
+
+            # Is the parent still alive?
+            try:
+                os.kill(parent_pid, 0)
+            except ProcessLookupError:
+                print(
+                    f"watchdog: parent {parent_pid} gone, killing child {proc.pid}",
+                    file=sys.stderr,
+                    flush=True,
+                )
+                _terminate_child(proc)
+                return 1
+            except PermissionError:
+                # Parent exists but is owned by another user — still alive.
+                pass
+
+            time.sleep(poll_interval)
+    finally:
+        # Belt and suspenders: never leave the child running if we unwind.
+        if proc.poll() is None:
+            _terminate_child(proc)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

{leanback-0.1.3 → leanback-0.1.4}/src/leanback/mcp_server.py

@@ -55,8 +55,10 @@ logger = logging.getLogger(__name__)
 mcp = FastMCP(
     "LeanBack",
     instructions="""\
-LeanBack provides tools for Lean 4 theorem proving. All tools are read-only — they never \
-modify files. Use your own file tools to create/edit .lean files, then use LeanBack to verify them.
+LeanBack provides tools for Lean 4 theorem proving. All tools are read-only for source files — \
+they never modify your .lean files. Use your own file tools to create/edit .lean files, then use \
+LeanBack to verify them. (Exception: eval with build=true compiles project modules, writing build \
+artifacts to .lake/.)
 
 ## Getting Started
 1. Call project_info(project="/path/to/project") to check if a project is ready
@@ -84,7 +86,9 @@ modify files. Use your own file tools to create/edit .lean files, then use LeanB
 - All tools require 'project' as an absolute path (e.g., "/home/user/lean/myproject")
 - check has NO mathlib flag — use imports=["Mathlib.Tactic"] instead
 - goals, prove, and eval with mathlib=True all import Mathlib.Tactic (simp, ring, omega, linarith, norm_num, decide, aesop)
+- eval can import modules of the project itself (imports=["MyProject.Definitions"]); pass build=true so they are compiled first
 - Tool calls typically take 5-30 seconds. The first call may be slower (Lean server startup).
+- Iterating on a file? check(file=...) is the fast loop: repeated checks of the same file reuse a warm Lean server (seconds instead of a fresh import each time). Keep the import lines unchanged between edits to stay warm.
 """,
 )
 
@@ -446,7 +450,7 @@ def check(
 
     Parameters:
     - project: Absolute path to the Lean project directory (e.g., "/home/user/lean/myproject")
-    - file: Path to a .lean file within the project (e.g., "Basic.lean", "src/Logic.lean")
+    - file: Path to a .lean file within the project (e.g., "Basic.lean", "src/Logic.lean"). Repeated checks of the same file reuse a warm Lean server: the first check pays the import cost (~20-30s with Mathlib), subsequent checks after edits take seconds as long as the file's import lines are unchanged.
     - check_all: Check each file individually for detailed error reporting (slower but more thorough)
     - expr: A Lean expression or command to check (e.g., "2 + 2 = 4", "Nat.add", "#eval 1 + 1"). Bare expressions are auto-wrapped in #check.
     - imports: List of modules to import when checking expressions (e.g., ["Mathlib.Tactic"]). First Mathlib import takes ~20-30s.
@@ -574,25 +578,39 @@ def check(
                 }
                 return _json(result)
 
-            success, errors = check_file(
-                file_path=file_path,
-                project_path=project_path,
-                console=console,
-            )
-
-            error_count = sum(1 for e in errors if e.severity == "error")
-            warning_count = sum(1 for e in errors if e.severity == "warning")
-            info_count = sum(1 for e in errors if e.severity == "info")
-
             try:
                 display_path = file_path.relative_to(project_path)
             except ValueError:
                 display_path = file
 
+            # Warm path: a persistent per-project Lean LSP worker makes
+            # repeated checks of the same file fast (the import environment
+            # stays in memory). Falls back to the cold path on any failure.
+            from leanback.common.errors import lsp_diagnostics_to_errors
+            from leanback.common.warm import check_file_warm
+
+            engine = "cold"
+            warm_diags = check_file_warm(project_path, file_path)
+            if warm_diags is not None:
+                errors = lsp_diagnostics_to_errors(warm_diags, str(display_path))
+                success = not any(e.severity == "error" for e in errors)
+                engine = "warm"
+            else:
+                success, errors = check_file(
+                    file_path=file_path,
+                    project_path=project_path,
+                    console=console,
+                )
+
+            error_count = sum(1 for e in errors if e.severity == "error")
+            warning_count = sum(1 for e in errors if e.severity == "warning")
+            info_count = sum(1 for e in errors if e.severity == "info")
+
             result = {
                 "success": success,
                 "type": "file_check",
                 "file_path": str(display_path),
+                "engine": engine,
                 "messages": _serialize_errors(errors),
                 "statistics": {
                     "total_errors": error_count,
@@ -918,6 +936,7 @@ def eval(
     file: str | None = None,
     imports: list[str] | None = None,
     mathlib: bool = False,
+    build: bool = False,
 ) -> str:
     """Execute Lean expressions and see their results.
 
@@ -930,6 +949,7 @@ def eval(
     - file: Path to a .lean file to execute instead of inline code
     - imports: Additional modules to import (e.g., ["Mathlib.Data.Finset.Basic"])
     - mathlib: Import Mathlib.Tactic for all standard tactics (simp, ring, omega, linarith, norm_num, decide, aesop, etc.). First call takes ~8-11s for import.
+    - build: Compile imported project modules first (runs `lake build` on them). Use when importing a module of THIS project (e.g., imports=["MyProject.Definitions"]) that may not be compiled yet — otherwise the import fails with "object file does not exist". Adds build time on first use; near-instant when already up to date. Note: this writes build artifacts to the project's .lake directory.
 
     Use either 'code' OR 'file', not both. The tool can handle multi-line code.
 
@@ -1016,6 +1036,30 @@ def eval(
             if "Mathlib.Tactic" not in resolved_imports:
                 resolved_imports.insert(0, "Mathlib.Tactic")
 
+        built_modules: list[str] = []
+        if build:
+            from leanback.common.env import build_modules, find_local_modules
+
+            # Consider both the imports parameter and import lines inside
+            # the code itself (relevant when executing a file).
+            candidates = list(resolved_imports)
+            candidates += re.findall(
+                r"^import\s+([\w.]+)", code_to_execute, re.MULTILINE
+            )
+            local_modules = find_local_modules(project_path, candidates)
+            build_ok, build_output = build_modules(project_path, local_modules)
+            if not build_ok:
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "BUILD_FAILED",
+                        "message": f"lake build failed for modules {local_modules}. "
+                        "Fix the errors in those modules first.",
+                        "build_output": build_output[:2000],
+                    }
+                )
+            built_modules = local_modules
+
         success, errors = check_lean_expr(
             expr=code_to_execute,
             imports=resolved_imports,
@@ -1023,17 +1067,25 @@ def eval(
             console=console,
         )
 
-        return _json(
-            {
-                "success": success,
-                "type": "code_execution",
-                "code": code_to_execute,
-                "imports": resolved_imports,
-                "messages": _serialize_errors(
-                    errors, sanitize_paths=True, source_file=file
-                ),
-            }
-        )
+        result = {
+            "success": success,
+            "type": "code_execution",
+            "code": code_to_execute,
+            "imports": resolved_imports,
+            "messages": _serialize_errors(
+                errors, sanitize_paths=True, source_file=file
+            ),
+        }
+        if built_modules:
+            result["built"] = built_modules
+        if not build and any(
+            ".olean" in e.message and "does not exist" in e.message for e in errors
+        ):
+            result["hint"] = (
+                "An imported module is not compiled. "
+                "Retry with build=true to compile project modules automatically."
+            )
+        return _json(result)
 
     except Exception as e:
         return _json(