clauder 0.1.0__tar.gz

clauder-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.DS_Store
+*.mov
+.Rproj.user
+ClaudeR.Rproj
+.Rhistory
+
+# Credentials — never commit
+.mcpregistry_*
+
+# Build artifacts
+clauder-mcp/dist/
+__pycache__/
+*.pyc
+
+# R plot artifacts
+Rplots.pdf

clauder-0.1.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.5
+Name: clauder
+Version: 0.1.0
+Summary: Connect AI agents to a live Python session (Positron, Jupyter, VS Code, or a bare REPL) over the ClaudeR protocol
+Author: Nykko Vitali
+License: MIT
+Keywords: data-science,jupyter,llm,mcp,positron
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# clauder
+
+Expose a live Python session to MCP-based AI agents. The Python half of
+[ClaudeR](https://github.com/IMNMV/ClaudeR).
+
+```python
+import clauder
+clauder.start()
+```
+
+The agent then executes code in this session, where your loaded data and
+fitted models already are, and sees the figures it draws. Every line it runs
+is logged and attributed. Works in Positron, Jupyter, VS Code, and a bare
+REPL.
+
+```python
+clauder.start(session_name = "analysis", port = 8790)
+clauder.status()
+clauder.stop()
+```

clauder-0.1.0/README.md

@@ -0,0 +1,20 @@
+# clauder
+
+Expose a live Python session to MCP-based AI agents. The Python half of
+[ClaudeR](https://github.com/IMNMV/ClaudeR).
+
+```python
+import clauder
+clauder.start()
+```
+
+The agent then executes code in this session, where your loaded data and
+fitted models already are, and sees the figures it draws. Every line it runs
+is logged and attributed. Works in Positron, Jupyter, VS Code, and a bare
+REPL.
+
+```python
+clauder.start(session_name = "analysis", port = 8790)
+clauder.status()
+clauder.stop()
+```

clauder-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "clauder"
+version = "0.1.0"
+description = "Connect AI agents to a live Python session (Positron, Jupyter, VS Code, or a bare REPL) over the ClaudeR protocol"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Nykko Vitali" }]
+keywords = ["mcp", "llm", "positron", "jupyter", "data-science"]
+license = { text = "MIT" }
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

clauder-0.1.0/src/clauder/__init__.py

@@ -0,0 +1,13 @@
+"""clauder: expose a live Python session to MCP agents.
+
+    import clauder
+    clauder.start()
+
+Speaks the same protocol as the ClaudeR R addin, so one MCP bridge reaches
+both an R session and a Python session, and an agent picks either by name.
+"""
+
+from .server import start, status, stop
+
+__version__ = "0.1.0"
+__all__ = ["start", "stop", "status"]

clauder-0.1.0/src/clauder/discovery.py

@@ -0,0 +1,166 @@
+"""Discovery records, byte-compatible with the R side.
+
+Both languages write into ~/.claude_r_sessions so one bridge can see every
+session regardless of which one it is. The record shape, the lock protocol and
+the atomic replace all match R/ui.R deliberately. The only addition is the
+`language` field, which is absent in records written by R before this existed
+and therefore means "r" when missing.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import tempfile
+import time
+from typing import Any, Dict, Optional
+
+# Frozen shared contract. Do not rename these.
+DISCOVERY_DIRNAME = ".claude_r_sessions"
+TOKEN_HEADER = "X-Clauder-Token"
+
+_BAD_NAME = re.compile(r'[\\/:<>"|?*\x00-\x1f]')
+
+
+def home_dir() -> str:
+    if sys.platform == "win32":
+        return os.environ.get("USERPROFILE") or os.path.expanduser("~")
+    return os.path.expanduser("~")
+
+
+def discovery_dir() -> str:
+    return os.path.join(home_dir(), DISCOVERY_DIRNAME)
+
+
+def discovery_path(session_name: str) -> str:
+    if (not session_name or session_name in (".", "..")
+            or _BAD_NAME.search(session_name)):
+        raise ValueError("Invalid discovery session name")
+    return os.path.join(discovery_dir(), session_name + ".json")
+
+
+def pid_is_alive(pid: Any) -> Optional[bool]:
+    """True, False, or None for "cannot tell".
+
+    None matters. A permission error must not be read as permission to delete
+    another session's record, which is why this is tri-state like the R side.
+    """
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return None
+    if pid <= 0:
+        return None
+    if sys.platform == "win32":
+        try:
+            import ctypes
+            SYNCHRONIZE = 0x00100000
+            h = ctypes.windll.kernel32.OpenProcess(SYNCHRONIZE, False, pid)
+            if h:
+                ctypes.windll.kernel32.CloseHandle(h)
+                return True
+            return False if ctypes.windll.kernel32.GetLastError() == 87 else None
+        except Exception:
+            return None
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True          # alive, owned by someone else
+    except Exception:
+        return None
+
+
+class _Lock:
+    """Directory lock, the same mechanism R uses, so the two interoperate."""
+
+    def __init__(self, path: str):
+        self.lock = path + ".lock"
+
+    def __enter__(self):
+        try:
+            os.mkdir(self.lock, 0o700)
+        except FileExistsError:
+            raise RuntimeError(
+                "Discovery record is locked; do not remove another writer's lock"
+            ) from None
+        return self
+
+    def __exit__(self, *exc):
+        try:
+            os.rmdir(self.lock)
+        except OSError:
+            pass
+        return False
+
+
+def write_record(session_name: str, port: int, token: str,
+                 plot_auto: bool = True, tool_sets: Any = "all") -> str:
+    d = discovery_dir()
+    os.makedirs(d, mode=0o700, exist_ok=True)
+    f = discovery_path(session_name)
+    with _Lock(f):
+        other = None
+        if os.path.exists(f):
+            try:
+                with open(f) as fh:
+                    other = json.load(fh)
+            except Exception as e:
+                raise RuntimeError(
+                    "Unreadable discovery record at %s (%s). Inspect or remove "
+                    "it, then start the server again." % (f, e)
+                ) from None
+        if other is not None and not isinstance(other, dict):
+            raise RuntimeError(
+                "Unreadable discovery identity in %s; explicit inspection required" % f)
+        if other is not None and int(other.get("pid", -1)) != os.getpid() \
+                and pid_is_alive(other.get("pid")) is not False:
+            raise RuntimeError(
+                "Session name '%s' is already owned by a live or unknown process"
+                % session_name)
+
+        same_owner = (other is not None
+                      and int(other.get("pid", -1)) == os.getpid()
+                      and other.get("token") == token)
+        started = (other.get("started_at") if same_owner and other.get("started_at")
+                   else time.strftime("%Y-%m-%dT%H:%M:%S"))
+
+        info: Dict[str, Any] = {
+            "session_name": session_name,
+            "port": int(port),
+            "pid": os.getpid(),
+            "token": token,
+            "started_at": started,
+            "plot_auto": bool(plot_auto),
+            "tool_sets": tool_sets,
+            "language": "python",
+        }
+        fd, tmp = tempfile.mkstemp(prefix=".discovery-", dir=d)
+        try:
+            with os.fdopen(fd, "w") as fh:
+                json.dump(info, fh, indent=2)
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, f)      # atomic, including on Windows
+        finally:
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+    return f
+
+
+def remove_record(session_name: str) -> None:
+    """Delete our own record only. Never another process's."""
+    f = discovery_path(session_name)
+    if not os.path.exists(f):
+        return
+    with _Lock(f):
+        try:
+            with open(f) as fh:
+                info = json.load(fh)
+        except Exception:
+            return
+        if isinstance(info, dict) and int(info.get("pid", -1)) == os.getpid():
+            os.unlink(f)

clauder-0.1.0/src/clauder/server.py

@@ -0,0 +1,420 @@
+"""The HTTP server that runs inside the user's Python session.
+
+Speaks the same wire protocol as the R addin, so the existing bridge needs no
+new transport. POST {code, agent_id, want_plot} and get back
+{success, output, plot, error}. GET returns a status object.
+
+Execution goes through IPython's run_cell when a shell is present, so output,
+display hooks and the IDE's plot pane behave exactly as if the user had typed
+the code. Outside IPython it falls back to exec against a persistent namespace.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import os
+import secrets
+import threading
+import time
+import traceback
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any, Dict, List, Optional
+
+from .discovery import TOKEN_HEADER, remove_record, write_record
+
+MAX_OUTPUT_CHARS = 100_000
+
+# Frozen log markers, matching R so one log file holds both sides and the
+# existing parsers keep working.
+_LOG_HEADER = "# --- [%s] ---\n# Code executed by %s:\n%s\n\n"
+_LOG_OUTPUT = "#> "
+
+
+class _State:
+    def __init__(self) -> None:
+        self.httpd: Optional[HTTPServer] = None
+        self.thread: Optional[threading.Thread] = None
+        self.session_name: str = "default"
+        self.port: Optional[int] = None
+        self.token: Optional[str] = None
+        self.require_token: bool = False
+        self.plot_auto: bool = True
+        self.log_path: Optional[str] = None
+        self.print_to_console: bool = True
+        self.execution_count: int = 0
+        self.agents: List[str] = []
+        self.namespace: Dict[str, Any] = {}
+        # R is single threaded and serialises on its event loop. Python can be
+        # re-entered from the server thread, so serialise here instead.
+        self.exec_lock = threading.Lock()
+
+
+STATE = _State()
+
+
+def _shell():
+    try:
+        from IPython import get_ipython
+        return get_ipython()
+    except Exception:
+        return None
+
+
+def _log(code: str, agent: str) -> None:
+    """Write the code entry. Called before execution, so a hang still leaves
+    a record of what was running."""
+    if not STATE.log_path:
+        return
+    try:
+        with open(STATE.log_path, "a") as fh:
+            fh.write(_LOG_HEADER % (time.strftime("%Y-%m-%d %H:%M:%S"), agent, code))
+    except Exception:
+        pass
+
+
+def _log_output(output: str) -> None:
+    """Append what the code printed, under the entry just written for it.
+    The "#> " prefix marks these lines as output rather than code, which is
+    what the R-side log parsers already skip."""
+    if not STATE.log_path or not output.strip():
+        return
+    try:
+        lines = output.rstrip("\n").split("\n")
+        if len(lines) > 40:
+            lines = lines[:40] + ["... %d more lines not logged" % (len(lines) - 40)]
+        with open(STATE.log_path, "a") as fh:
+            fh.write("".join(_LOG_OUTPUT + l + "\n" for l in lines) + "\n")
+    except Exception:
+        pass
+
+
+class _Tee(io.TextIOBase):
+    """Capture a copy while the user still sees their own output.
+
+    This is the Python counterpart of sink(split = TRUE) on the R side.
+    """
+
+    def __init__(self, real):
+        self.real = real
+        self.buf = io.StringIO()
+
+    def write(self, s):
+        try:
+            self.real.write(s)
+        except Exception:
+            pass
+        return self.buf.write(s)
+
+    def flush(self):
+        try:
+            self.real.flush()
+        except Exception:
+            pass
+
+
+def _figure_png(fignum: Optional[int] = None) -> Optional[str]:
+    """PNG of the figure the executed code produced.
+
+    Rendering must go through Agg. An IDE backend may carry no raster
+    renderer of its own, and then a plain savefig quietly produces a broken
+    image rather than failing: measured against Positron's
+    FigureCanvasPositron, savefig gave 2098 bytes with the title missing and
+    labels clipped, where Agg gave 12504 correct ones. savefig(backend="agg")
+    renders through Agg for this one call and leaves fig.canvas alone, so the
+    figure still belongs to the IDE and still shows in its plot pane.
+
+    Two things that look like fixes and are not. bbox_inches="tight" computes
+    a degenerate box on a figure the IDE has not drawn yet, and
+    canvas.draw() on such a canvas leaves it unrenderable. Rendering a
+    pickled copy loses data outright: a four-bar chart came back as one bar
+    on a default 0-to-1 axis.
+    """
+    try:
+        import matplotlib.pyplot as plt
+    except Exception:
+        return None
+    nums = plt.get_fignums()
+    if not nums:
+        return None
+    target = fignum if fignum in nums else nums[-1]
+    try:
+        fig = plt.figure(target)
+    except Exception:
+        return None
+
+    data = b""
+    try:
+        buf = io.BytesIO()
+        fig.savefig(buf, format="png", backend="agg")
+        data = buf.getvalue()
+    except (TypeError, ValueError):
+        # The backend keyword arrived in matplotlib 3.4. Older versions get
+        # a plain savefig, which is correct wherever the canvas can raster.
+        try:
+            buf = io.BytesIO()
+            fig.savefig(buf, format="png")
+            data = buf.getvalue()
+        except Exception:
+            return None
+    except Exception:
+        return None
+
+    # A rendered figure is never this small. Refuse rather than hand back a
+    # blank picture that reads as a real result.
+    if len(data) < 1000:
+        return None
+    return base64.b64encode(data).decode()
+
+
+def _run(code: str, agent_id: Optional[str], want_plot: bool) -> Dict[str, Any]:
+    import sys as _sys
+
+    agent = agent_id or "agent"
+    if agent not in STATE.agents:
+        STATE.agents.append(agent)
+
+    if STATE.print_to_console:
+        try:
+            print("\n### LLM [%s] executing the following code ###\n%s\n"
+                  "### End of LLM code ###\n" % (agent, code))
+        except Exception:
+            pass
+
+    _log(code, agent)
+
+    with STATE.exec_lock:
+        try:
+            import matplotlib.pyplot as _plt
+            before = set(_plt.get_fignums())
+        except Exception:
+            before = set()
+
+        tee_out, tee_err = _Tee(_sys.stdout), _Tee(_sys.stderr)
+        real_out, real_err = _sys.stdout, _sys.stderr
+        _sys.stdout, _sys.stderr = tee_out, tee_err
+        error = None
+        try:
+            sh = _shell()
+            if sh is not None:
+                res = sh.run_cell(code, store_history=False, silent=False)
+                if getattr(res, "error_in_exec", None) is not None:
+                    error = "".join(traceback.format_exception_only(
+                        type(res.error_in_exec), res.error_in_exec)).strip()
+                elif getattr(res, "error_before_exec", None) is not None:
+                    error = str(res.error_before_exec)
+            else:
+                exec(compile(code, "<clauder>", "exec"), STATE.namespace)
+        except Exception as e:
+            error = "".join(traceback.format_exception_only(type(e), e)).strip()
+        finally:
+            _sys.stdout, _sys.stderr = real_out, real_err
+
+        output = tee_out.buf.getvalue() + tee_err.buf.getvalue()
+        if len(output) > MAX_OUTPUT_CHARS:
+            output = output[:MAX_OUTPUT_CHARS] + "\n... output truncated"
+
+        try:
+            import matplotlib.pyplot as _plt
+            after = set(_plt.get_fignums())
+        except Exception:
+            after = set()
+        new_figs = after - before
+        drew = bool(new_figs) or (bool(after) and bool(before) and want_plot)
+        # The user may already have figures open, so identify ours rather than
+        # assuming the highest number is the one this call drew.
+        target_fig = max(new_figs) if new_figs else (max(after) if after else None)
+
+    STATE.execution_count += 1
+    resp: Dict[str, Any] = {"success": error is None, "output": output}
+    _log_output(output if error is None else (output + "\n" + error).strip())
+    if error is not None:
+        resp["error"] = error
+
+    if drew:
+        # want_plot is the with_plot tool asking outright, and always wins.
+        if want_plot or STATE.plot_auto:
+            png = _figure_png(target_fig)
+            if png:
+                resp["plot"] = {"data": png, "mime_type": "image/png"}
+        else:
+            resp["plot_available"] = True
+            resp["output"] = (resp["output"] + ("\n" if resp["output"] else "")
+                              + "[a plot was drawn; ask for it with the plot tool]")
+    return resp
+
+
+class _Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, *a):  # keep the user's console clean
+        pass
+
+    def _send(self, obj: Dict[str, Any], status: int = 200) -> None:
+        body = json.dumps(obj).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _authorised(self) -> bool:
+        # Only browsers set Origin, and the bridge never does, so this closes
+        # the drive-by webpage vector at no compatibility cost.
+        if self.headers.get("Origin"):
+            self._send({"error": "Cross-origin requests are not allowed"}, 403)
+            return False
+        if STATE.require_token:
+            if self.headers.get(TOKEN_HEADER) != STATE.token:
+                self._send({"error": "Missing or invalid session token"}, 401)
+                return False
+        return True
+
+    def do_GET(self):
+        if not self._authorised():
+            return
+        self._send({
+            "running": True,
+            "language": "python",
+            "session_name": STATE.session_name,
+            "port": STATE.port,
+            "execution_count": STATE.execution_count,
+            "connected_agents": list(STATE.agents),
+            "plot_auto": STATE.plot_auto,
+            "log_to_file": bool(STATE.log_path),
+            "log_file_path": STATE.log_path or "",
+        })
+
+    def do_POST(self):
+        if not self._authorised():
+            return
+        try:
+            n = int(self.headers.get("Content-Length") or 0)
+            body = json.loads(self.rfile.read(n) or b"{}")
+        except Exception:
+            self._send({"error": "Invalid JSON in request body"}, 400)
+            return
+        code = body.get("code")
+        if not isinstance(code, str):
+            self._send({"success": False, "error": "No code supplied"}, 400)
+            return
+        try:
+            self._send(_run(code, body.get("agent_id"),
+                            bool(body.get("want_plot"))))
+        except Exception as e:
+            self._send({"success": False, "error": "clauder internal error: %s" % e}, 500)
+
+
+def start(session_name: str = "default", port: int = 8790,
+          require_token: bool = False, log_file: Optional[str] = None,
+          plot_auto: bool = True, print_to_console: bool = True,
+          quiet: bool = False) -> Dict[str, Any]:
+    """Expose this Python session to MCP agents.
+
+    Returns a dict describing the running server. Call stop() to shut it down.
+    """
+    requested_port = int(port)
+    if STATE.httpd is not None:
+        if not quiet:
+            print("clauder: already running on port %s as '%s'."
+                  % (STATE.port, STATE.session_name))
+        return {"running": True, "port": STATE.port,
+                "session_name": STATE.session_name}
+
+    STATE.session_name = session_name
+    STATE.require_token = require_token
+    STATE.plot_auto = plot_auto
+    STATE.print_to_console = print_to_console
+    STATE.token = secrets.token_hex(32)
+    STATE.execution_count = 0
+    STATE.agents = []
+    STATE.log_path = log_file if log_file is not None else os.path.join(
+        home_dir_safe(), "clauder_python_log.py")
+
+    # Walk forward to the next free port rather than failing. A second session,
+    # or a server the OS has not finished releasing, should not stop you
+    # starting; being told which port you got is enough.
+    httpd = None
+    first_error = None
+    for candidate in range(int(port), int(port) + 20):
+        try:
+            httpd = HTTPServer(("127.0.0.1", candidate), _Handler)
+            port = candidate
+            break
+        except OSError as e:
+            if first_error is None:
+                first_error = e
+    if httpd is None:
+        raise RuntimeError(
+            "No free port in %d-%d (%s). Pass port= explicitly."
+            % (int(port), int(port) + 19, first_error)
+        ) from None
+
+    STATE.httpd = httpd
+    STATE.port = int(port)
+    try:
+        write_record(session_name, STATE.port, STATE.token,
+                     plot_auto=plot_auto, tool_sets="all")
+    except Exception:
+        httpd.server_close()
+        STATE.httpd = None
+        STATE.port = None
+        raise
+
+    t = threading.Thread(target=httpd.serve_forever, daemon=True,
+                         name="clauder-server")
+    t.start()
+    STATE.thread = t
+
+    if not quiet:
+        moved = " (requested port was busy)" if STATE.port != int(requested_port) else ""
+        print("clauder: listening on http://127.0.0.1:%d as session '%s'%s.\n"
+              "Agents can now reach this Python session. Call clauder.stop() "
+              "to end it." % (STATE.port, session_name, moved))
+    return {"running": True, "port": STATE.port, "session_name": session_name,
+            "language": "python", "token_required": require_token}
+
+
+def home_dir_safe() -> str:
+    from .discovery import home_dir
+    return home_dir()
+
+
+def stop(quiet: bool = False) -> None:
+    """Shut the server down and remove this session's discovery record."""
+    if STATE.httpd is None:
+        if not quiet:
+            print("clauder: not running.")
+        return
+    try:
+        STATE.httpd.shutdown()
+    except Exception:
+        pass
+    try:
+        STATE.httpd.server_close()
+    except Exception:
+        pass
+    try:
+        remove_record(STATE.session_name)
+    except Exception:
+        pass
+    STATE.httpd = None
+    STATE.thread = None
+    STATE.port = None
+    if not quiet:
+        print("clauder: stopped.")
+
+
+def status() -> Dict[str, Any]:
+    return {
+        "running": STATE.httpd is not None,
+        "session_name": STATE.session_name,
+        "port": STATE.port,
+        "language": "python",
+        "execution_count": STATE.execution_count,
+        "connected_agents": list(STATE.agents),
+        "plot_auto": STATE.plot_auto,
+        "log_file": STATE.log_path,
+        "token_required": STATE.require_token,
+    }

clauder-0.1.0/tests/test_clauder.py

@@ -0,0 +1,266 @@
+"""Tests for the Python session server.
+
+Each test runs against a private discovery directory, never the user's real
+~/.claude_r_sessions, so a test run cannot disturb a live research session.
+"""
+
+import base64
+import json
+import os
+import sys
+import tempfile
+import unittest
+import urllib.error
+import urllib.request
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from clauder import server as srv          # noqa: E402
+from clauder import discovery as disc      # noqa: E402
+
+PORT = 8894
+
+
+class Base(unittest.TestCase):
+    def setUp(self):
+        self.dir = tempfile.mkdtemp()
+        self._real_home = disc.home_dir
+        disc.home_dir = lambda: self.dir
+        self.log = os.path.join(self.dir, "log.py")
+
+    def tearDown(self):
+        srv.stop(quiet=True)
+        disc.home_dir = self._real_home
+
+    def start(self, **kw):
+        kw.setdefault("session_name", "t")
+        kw.setdefault("port", PORT)
+        kw.setdefault("quiet", True)
+        kw.setdefault("print_to_console", False)
+        kw.setdefault("log_file", self.log)
+        return srv.start(**kw)
+
+    def post(self, code, want_plot=False, token=None, origin=None, agent="tester"):
+        body = {"code": code, "agent_id": agent}
+        if want_plot:
+            body["want_plot"] = True
+        h = {"Content-Type": "application/json"}
+        if token:
+            h[disc.TOKEN_HEADER] = token
+        if origin:
+            h["Origin"] = origin
+        r = urllib.request.Request("http://127.0.0.1:%d" % PORT,
+                                   json.dumps(body).encode(), h)
+        return json.load(urllib.request.urlopen(r, timeout=25))
+
+    def record(self):
+        with open(disc.discovery_path("t")) as fh:
+            return json.load(fh)
+
+
+class DiscoveryTests(Base):
+    def test_record_declares_python_and_matches_r_shape(self):
+        self.start()
+        rec = self.record()
+        # The bridge reads these keys for every session regardless of language.
+        for k in ("session_name", "port", "pid", "token", "started_at",
+                  "plot_auto", "tool_sets", "language"):
+            self.assertIn(k, rec)
+        self.assertEqual(rec["language"], "python")
+        self.assertEqual(rec["port"], PORT)
+        self.assertEqual(rec["pid"], os.getpid())
+
+    def test_record_is_private(self):
+        self.start()
+        mode = os.stat(disc.discovery_path("t")).st_mode & 0o777
+        self.assertEqual(mode, 0o600)
+
+    def test_stop_removes_only_our_record(self):
+        self.start()
+        p = disc.discovery_path("t")
+        self.assertTrue(os.path.exists(p))
+        srv.stop(quiet=True)
+        self.assertFalse(os.path.exists(p))
+
+    def test_refuses_name_held_by_another_live_process(self):
+        os.makedirs(disc.discovery_dir(), mode=0o700, exist_ok=True)
+        with open(disc.discovery_path("t"), "w") as fh:
+            json.dump({"session_name": "t", "port": 1, "pid": 1,
+                       "token": "x", "started_at": "s"}, fh)
+        with self.assertRaises(RuntimeError):
+            self.start()
+
+    def test_pid_probe_is_tristate(self):
+        self.assertIs(disc.pid_is_alive(os.getpid()), True)
+        self.assertIs(disc.pid_is_alive(999999), False)
+        self.assertIsNone(disc.pid_is_alive("nonsense"))
+
+    def test_rejects_unsafe_session_names(self):
+        for bad in ("..", "a/b", "a\\b", "a:b", ""):
+            with self.assertRaises(ValueError):
+                disc.discovery_path(bad)
+
+
+class ExecutionTests(Base):
+    def test_executes_and_persists_namespace(self):
+        self.start()
+        self.assertTrue(self.post("zz = 6 * 7")["success"])
+        r = self.post("print('zz is', zz)")
+        self.assertIn("zz is 42", r["output"])
+
+    def test_reports_errors_without_dying(self):
+        self.start()
+        r = self.post("1/0")
+        self.assertFalse(r["success"])
+        self.assertIn("ZeroDivisionError", r["error"])
+        self.assertTrue(self.post("1+1")["success"])   # still serving
+
+    def test_captures_stdout(self):
+        self.start()
+        r = self.post("for i in range(3): print('row', i)")
+        self.assertIn("row 0", r["output"])
+        self.assertIn("row 2", r["output"])
+
+    def test_logs_code_and_output_with_attribution(self):
+        self.start()
+        self.post("print('logged')", agent="agent-7")
+        text = open(self.log).read()
+        self.assertIn("# Code executed by agent-7:", text)   # frozen R marker
+        self.assertIn("#> logged", text)                     # output marker
+        # The code must appear exactly once, not once per log call.
+        self.assertEqual(text.count("print('logged')"), 1)
+
+    def test_output_is_truncated(self):
+        # Lower the cap rather than printing a huge string: the tee echoes to
+        # the real console by design, and a 200k flood makes test output
+        # unreadable.
+        self.start()
+        original = srv.MAX_OUTPUT_CHARS
+        srv.MAX_OUTPUT_CHARS = 100
+        try:
+            r = self.post("print('x' * 500)")
+            self.assertLessEqual(len(r["output"]), 100 + 40)
+            self.assertIn("truncated", r["output"])
+        finally:
+            srv.MAX_OUTPUT_CHARS = original
+
+
+class SecurityTests(Base):
+    def test_origin_header_is_refused(self):
+        self.start()
+        with self.assertRaises(urllib.error.HTTPError) as e:
+            self.post("1+1", origin="http://evil.test")
+        self.assertEqual(e.exception.code, 403)
+
+    def test_token_enforced_when_required(self):
+        self.start(require_token=True)
+        tok = self.record()["token"]
+        with self.assertRaises(urllib.error.HTTPError) as e:
+            self.post("1+1")
+        self.assertEqual(e.exception.code, 401)
+        self.assertTrue(self.post("1+1", token=tok)["success"])
+
+    def test_token_absent_by_default(self):
+        self.start()
+        self.assertTrue(self.post("1+1")["success"])
+
+
+class PlotTests(Base):
+    def setUp(self):
+        super().setUp()
+        try:
+            import matplotlib
+            matplotlib.use("Agg")
+        except ImportError:
+            self.skipTest("matplotlib not installed")
+
+    def draw(self, **kw):
+        return self.post("import matplotlib.pyplot as plt\n"
+                         "plt.figure(); plt.plot([1, 4, 9])", **kw)
+
+    def test_returns_png_when_a_figure_is_drawn(self):
+        self.start()
+        r = self.draw()
+        self.assertIn("plot", r)
+        self.assertEqual(r["plot"]["mime_type"], "image/png")
+        self.assertTrue(base64.b64decode(r["plot"]["data"]).startswith(b"\x89PNG"))
+
+    def test_no_plot_when_nothing_drawn(self):
+        self.start()
+        self.assertNotIn("plot", self.post("q = 1"))
+
+    def test_plot_auto_off_withholds_image_but_says_so(self):
+        self.start(plot_auto=False)
+        r = self.draw()
+        self.assertNotIn("plot", r)
+        self.assertTrue(r["plot_available"])
+        self.assertIn("plot was drawn", r["output"])
+
+    def test_want_plot_overrides_plot_auto(self):
+        self.start(plot_auto=False)
+        self.assertIn("plot", self.draw(want_plot=True))
+
+
+class StatusTests(Base):
+    def test_get_reports_language_and_agents(self):
+        self.start()
+        self.post("1+1", agent="agent-a")
+        r = urllib.request.Request("http://127.0.0.1:%d" % PORT)
+        r.get_method = lambda: "GET"
+        info = json.load(urllib.request.urlopen(r, timeout=10))
+        self.assertEqual(info["language"], "python")
+        self.assertTrue(info["running"])
+        self.assertIn("agent-a", info["connected_agents"])
+
+    def test_status_helper(self):
+        self.start()
+        self.assertTrue(srv.status()["running"])
+        srv.stop(quiet=True)
+        self.assertFalse(srv.status()["running"])
+
+    def test_double_start_is_a_no_op(self):
+        a = self.start()
+        b = self.start()
+        self.assertEqual(a["port"], b["port"])
+
+    def test_busy_port_moves_to_the_next_free_one(self):
+        # Occupy the requested port from outside. Calling start() twice would
+        # hit the already-running guard and never reach the bind.
+        import socket
+        sock = socket.socket()
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind(("127.0.0.1", PORT + 1))
+        sock.listen(1)
+        try:
+            info = srv.start(session_name="t", port=PORT + 1, quiet=True,
+                             log_file=self.log)
+            self.assertNotEqual(info["port"], PORT + 1)
+            self.assertGreater(info["port"], PORT + 1)
+            # The record must carry the port actually bound, not the one asked
+            # for, or the bridge would post to the wrong place.
+            self.assertEqual(self.record()["port"], info["port"])
+        finally:
+            sock.close()
+
+    def test_gives_up_when_the_whole_range_is_busy(self):
+        import socket
+        base = PORT + 40
+        socks = []
+        try:
+            for i in range(20):
+                s_ = socket.socket()
+                s_.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                s_.bind(("127.0.0.1", base + i))
+                s_.listen(1)
+                socks.append(s_)
+            with self.assertRaises(RuntimeError) as e:
+                srv.start(session_name="t", port=base, quiet=True,
+                          log_file=self.log)
+            self.assertIn("No free port", str(e.exception))
+        finally:
+            for s_ in socks:
+                s_.close()
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)