repld-tool 0.2.2__tar.gz → 0.2.4__tar.gz

{repld_tool-0.2.2 → repld_tool-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repld-tool
-Version: 0.2.2
+Version: 0.2.4
 Summary: Persistent Python runtime with MCP channel push. Dev shell and autonomous-agent substrate in one package.
 Keywords: repl,mcp,agent,browser
 Author: Fredrik Angelsen

{repld_tool-0.2.2 → repld_tool-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "repld-tool"
-version = "0.2.2"
+version = "0.2.4"
 description = "Persistent Python runtime with MCP channel push. Dev shell and autonomous-agent substrate in one package."
 readme = "README.md"
 authors = [

{repld_tool-0.2.2 → repld_tool-0.2.4}/src/repld/bridge.py

@@ -34,10 +34,12 @@ Two rules that fall out of running arbitrary user code:
 """
 
 import json
+import os
 import socket
 import sys
 import threading
 import time
+import uuid
 from pathlib import Path
 
 from . import (
@@ -83,6 +85,68 @@ BRIDGE_INIT_ID = "repld-bridge-init"
 # intercept declines exactly the gist and browser URIs, which do need one.
 _NEEDS_KERNEL = frozenset({"tools/call", "resources/read"})
 
+
+def _ephemeral_socket_path() -> Path:
+    """A private, single-use socket path for `repld bridge --ephemeral`.
+
+    Deliberately outside PROJECTS_DIR: that tree is addressed by cwd
+    (`paths.project_dir`) precisely so a second bridge for the same project
+    attaches to the *same* kernel — the opposite of what --ephemeral
+    promises. A per-invocation subdirectory under RUNTIME_DIR, keyed on this
+    bridge's own pid plus a random suffix, guarantees no other bridge —
+    ephemeral or not — ever resolves to the same path, and the whole
+    directory is one `rmtree` for `_teardown_ephemeral` to remove on the way
+    out. That matters because neither `state.sweep_dead_pid_files` nor
+    `state.sweep_dead_project_dirs` would ever see it: the first only reaches
+    RUNTIME_DIR's flat `{pid}-…` files, the second only PROJECTS_DIR.
+
+    Two separate mkdir calls, not one `parents=True`: RUNTIME_DIR itself is
+    already 0700 (`ensure_runtime_dir`), but `mkdir(parents=True, mode=...)`
+    applies the mode only to the leaf it creates — the exact footgun
+    `ensure_runtime_dir`'s own docstring warns about — so an `ephemeral/`
+    parent brought into being implicitly would come out at umask default.
+    Each call here has an already-existing direct parent, so its `mode` is
+    the one that actually lands.
+    """
+    paths.ensure_runtime_dir()
+    root = paths.RUNTIME_DIR / "ephemeral"
+    root.mkdir(exist_ok=True, mode=0o700)
+    d = root / f"{os.getpid()}-{uuid.uuid4().hex[:8]}"
+    d.mkdir(mode=0o700)
+    return d / "kernel.sock"
+
+
+def _teardown_ephemeral(sock_path: Path, pid: int | None) -> None:
+    """Kill the one-off kernel `--ephemeral` spawned, then remove its directory.
+
+    SIGTERM first, so `_shutdown`'s `@every`/`defer()` drain gets its usual
+    2s budget — the same courtesy `restart_kernel` extends the kernel it
+    replaces. SIGKILL only if it's still alive after `WAIT_STEPS` ticks: an
+    ephemeral kernel outliving the bridge that owns it is exactly the leak
+    this flag exists to prevent, so waiting indefinitely isn't an option the
+    way it is for a kernel meant to keep running for weeks.
+    """
+    import shutil
+    import signal
+
+    if pid is not None:
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except OSError:
+            pid = None
+        else:
+            for _ in range(WAIT_STEPS):
+                if not state.pid_alive(pid):
+                    break
+                time.sleep(WAIT_STEP_SECONDS)
+            else:
+                try:
+                    os.kill(pid, signal.SIGKILL)
+                except OSError:
+                    pass
+    shutil.rmtree(sock_path.parent, ignore_errors=True)
+
+
 _static_docs_cache: dict[str, str] | None = None
 
 
@@ -136,9 +200,13 @@ def _rid_of(line: str) -> object | None:
 
 
 class Bridge:
-    def __init__(self, socket_path: Path) -> None:
+    def __init__(self, socket_path: Path, *, ephemeral: bool = False) -> None:
         self.socket_path = socket_path
         self.lock_path = paths.lock_for(socket_path)
+        # ephemeral spawns eagerly in run() rather than lazily on first real
+        # tool call, and tears the kernel down (_teardown_ephemeral) instead
+        # of leaving it running when stdin closes. See run_bridge's --ephemeral.
+        self._ephemeral = ephemeral
         self._sock: socket.socket | None = None
         self._kernel_pid: int | None = None
         self._generation = 0
@@ -718,6 +786,16 @@ class Bridge:
         # _try_bridge_intercept), and the first message that actually needs a
         # kernel — a real tools/call, a gist/browser resources/read — reaches
         # _ensure_kernel() in _handle_client_line and spawns one then.
+        #
+        # --ephemeral is the one exception, on purpose: its whole point is a
+        # live kernel for exactly this session, not a cache-backed discovery
+        # answer that defers spawning to the first real tool call. Spawning
+        # here also means every method — including `initialize` itself —
+        # forwards to a real kernel instead of the static/cached fallback,
+        # since _dispatch_client_line only takes that path while self._sock
+        # is still None.
+        if self._ephemeral:
+            self._ensure_kernel()
         try:
             for line in sys.stdin:
                 if not line.endswith("\n"):
@@ -732,12 +810,15 @@ class Bridge:
         # those replies, and the reader thread writes them to stdout.
         self._drain_inflight()
         # The kernel keeps running — its state is meant to outlive the session.
+        # --ephemeral inverts that: it dies with the bridge that spawned it.
         sock = self._sock
         if sock is not None:
             try:
                 sock.close()
             except OSError:
                 pass
+        if self._ephemeral:
+            _teardown_ephemeral(self.socket_path, self._kernel_pid)
         return 0
 
 
@@ -745,6 +826,12 @@ _BRIDGE_USAGE = (
     "repld bridge — stdio MCP proxy (spawned by Claude Code, not run by hand)\n"
     "\n"
     "  repld bridge [--socket PATH]\n"
+    "  repld bridge --ephemeral\n"
+    "\n"
+    "  --ephemeral spawns a private, single-use kernel for this bridge alone,\n"
+    "  eagerly rather than on first tool call, and kills it when stdin closes\n"
+    "  instead of leaving it running. Mutually exclusive with --socket: its\n"
+    "  whole point is a path nothing else could already be attached to.\n"
     "\n"
     "  Register with: claude mcp add repld -- repld bridge\n"
 )
@@ -760,6 +847,16 @@ def run_bridge(argv: list[str]) -> int:
     if cli_args.wants_help(argv):
         print(_BRIDGE_USAGE)
         return 0
+    if "--ephemeral" in argv:
+        rest = [a for a in argv if a != "--ephemeral"]
+        # No resolve_socket_path here: --ephemeral generates its own path and
+        # ignores REPLD_SOCKET too, so a bare --socket left in argv falls
+        # through to check_args as an unknown flag — which is exactly the
+        # mutual-exclusivity refusal, for free rather than as a special case.
+        bad = cli_args.check_args("repld bridge", rest, _BRIDGE_USAGE, positionals=0)
+        if bad is not None:
+            return bad
+        return Bridge(_ephemeral_socket_path(), ephemeral=True).run()
     socket_path, rest = paths.resolve_socket_path(argv)
     bad = cli_args.check_args("repld bridge", rest, _BRIDGE_USAGE, positionals=0)
     if bad is not None:

{repld_tool-0.2.2 → repld_tool-0.2.4}/src/repld/browser/tab.py

@@ -481,6 +481,40 @@ class Tab(TabQueryMixin):
                 ) from reattach_exc
             return await self._session.execute(method, params, timeout)
 
+    async def _ensure_front(self) -> None:
+        """Raise this tab if Chrome has it backgrounded, before dispatching input.
+
+        `click`/`tap`/`type_text`/`key` all ride `Input.dispatch*Event` —
+        the renderer's real input pipeline, which Chrome silently drops for
+        a tab whose window is occluded or backgrounded
+        (`document.visibilityState === "hidden"`): the CDP command still
+        acks, no exception is raised, and no handler on the page ever
+        fires. Resolving a selector doesn't hit this — `DOM.getContentQuads`
+        and `Runtime.evaluate` both work fine on a hidden tab, which is why
+        the failure looks like nothing happened rather than an error. Costs
+        one `Runtime.evaluate` round trip on every call and `Page.bringToFront`
+        only on the degraded path — the multi-window watch workflow this
+        kernel exists for means N-1 tabs are hidden at any given time, so
+        this can't be opt-in.
+        """
+        result = await self._exec(
+            "Runtime.evaluate",
+            {"expression": "document.visibilityState", "returnByValue": True},
+        )
+        if result.get("result", {}).get("value") == "hidden":
+            await self._exec("Page.bringToFront")
+
+    async def front(self) -> None:
+        """Bring this tab's window to the front (Page.bringToFront).
+
+        click()/tap()/type_text()/key() already do this automatically when
+        the tab is backgrounded — call this directly to raise a tab for its
+        own sake (e.g. before a screenshot a human is watching for), or to
+        avoid paying the visibility check on every call in a script that
+        knows it's about to do a lot of input against one tab.
+        """
+        await self._exec("Page.bringToFront")
+
     # ------------------------------------------------------------------
 
     async def js(
@@ -643,6 +677,7 @@ class Tab(TabQueryMixin):
 
         Selector: CSS, text=Label, role=button[name='OK'], or tag:has-text('...')
         """
+        await self._ensure_front()
         x, y = await self._element_center(selector)
 
         for event_type in ("mousePressed", "mouseReleased"):
@@ -670,6 +705,7 @@ class Tab(TabQueryMixin):
         Selects all existing content then types over it.
         Selector: CSS, text=Label, role=textbox, label=Name, or tag:has-text('...')
         """
+        await self._ensure_front()
         node_id, js_expr = await self._wait_for_node(selector)
 
         if node_id:
@@ -712,6 +748,7 @@ class Tab(TabQueryMixin):
 
     async def key(self, key: str) -> None:
         """Dispatch a keyDown+keyUp pair for a named key (e.g. "Enter", "Escape")."""
+        await self._ensure_front()
         for event_type in ("keyDown", "keyUp"):
             await self._exec(
                 "Input.dispatchKeyEvent",
@@ -735,6 +772,7 @@ class Tab(TabQueryMixin):
         Uses Input.dispatchTouchEvent — triggers touchstart/touchend listeners
         that dispatchMouseEvent won't reach. Use for mobile Chrome via ADB.
         """
+        await self._ensure_front()
         if y is not None:
             x, y = float(selector_or_x), y
         else:
@@ -759,6 +797,7 @@ class Tab(TabQueryMixin):
         Dispatches touchStart → touchMove × steps → touchEnd.
         For scrolling on mobile Chrome via ADB.
         """
+        await self._ensure_front()
         await self._touch("touchStart", [{"x": x1, "y": y1}])
         delay = duration_ms / steps / 1000
         for i in range(1, steps + 1):

{repld_tool-0.2.2 → repld_tool-0.2.4}/src/repld/help.py

@@ -482,6 +482,14 @@ Convention: add data-testid to your root layout component.
       3s timeout — raises TimeoutError if the page's touch handler blocks
       (common on complex apps like Messenger/React).
 
+  tab.front()                                                 → None
+      Bring this tab's window to the front (Page.bringToFront).
+      click/tap/type_text/key already call this automatically when Chrome
+      has the tab backgrounded — coordinate/key input silently does nothing
+      on a hidden tab otherwise (Chrome drops it, no error). Call directly
+      to raise a tab for its own sake, or to skip the per-call visibility
+      check in a script doing a lot of input against one tab.
+
   tab.swipe(x1, y1, x2, y2, *, steps=10, duration_ms=300)   → None
       Touch swipe: touchStart → touchMove × steps → touchEnd.
       For scrolling on mobile Chrome via ADB.
@@ -1116,6 +1124,10 @@ defer(coro, label=None) → task_id
   coro can also be a zero-arg callable that builds the awaitable —
   defer(lambda: asyncio.gather(a(), b())) — so gather()/create_task()
   construct on the kernel's loop instead of a sync cell's own thread.
+  A non-None return value is printed (into the push) and recoverable
+  afterward as get_task(task_id)["result"] (a bounded repr — there's no
+  cell number to bind _/_N to instead). no_display() suppresses the print
+  but not the get_task recovery, same as it does for an exec cell.
 
 every(seconds, label=, delay=0)(fn) → fn   periodic ticker; fn.cancel() stops
   delay= defers the first tick (default: tick now)
@@ -1152,6 +1164,7 @@ Tab (async unless noted):
   tab.tree()                                       → list[str]
   tab.click(selector, button=, click_count=)       → None (auto-waits 2s, mouse event)
   tab.tap(selector_or_x, y=)                       → None (touch event, 3s timeout)
+  tab.front()                                      → None (Page.bringToFront; click/tap/type_text/key auto-call this on a hidden tab)
   tab.swipe(x1, y1, x2, y2, steps=, duration_ms=)  → None (touch scroll)
   tab.scroll(selector, dy=, dx=, steps=, duration_ms=) → None (touch-scroll container)
   tab.type_text(selector, text, delay_ms=, press_enter=)  → None (clears first, auto-waits)

{repld_tool-0.2.2 → repld_tool-0.2.4}/src/repld/kernel.py

@@ -487,6 +487,21 @@ async def _run_cell(task_id: str, src: str, n: int, *, wait_ready: bool = True)
             task["exception"] = type(exc).__name__
 
 
+_RESULT_REPR_LIMIT = 2000  # get_task's "result" field — a preview, not a payload
+
+
+def _safe_repr(value: object) -> str:
+    """repr() a deferred task's result, bounded so a huge or unrepr-able value
+    can't take the task down (or blow up get_task's `json.dumps(snap)`)."""
+    try:
+        text = repr(value)
+    except Exception as exc:
+        return f"<repr() failed: {type(exc).__name__}>"
+    if len(text) > _RESULT_REPR_LIMIT:
+        text = text[:_RESULT_REPR_LIMIT] + f"… ({len(text)} chars total)"
+    return text
+
+
 async def _run_deferred(task_id: str, thunk) -> None:
     """Build and await a user-supplied awaitable within the task lifecycle.
 
@@ -500,7 +515,14 @@ async def _run_deferred(task_id: str, thunk) -> None:
     and a sync cell's body runs off-loop (`asyncio.to_thread`) to keep the
     kernel responsive — so building one directly in the cell raises "no
     current event loop" before defer() ever gets a look at it.
+
+    An `exec` cell's trailing expression gets `_`/`_N` plus a printed repr()
+    (`runtime.run_cell`); a deferred task has no cell number to bind, so it
+    gets the printed half instead (into the spill, and so into the
+    task_done push) plus a bounded repr in `task["result"]` for `get_task`.
     """
+    from . import runtime
+
     async with _task_scope(task_id) as task:
         try:
             awaitable = thunk()
@@ -509,7 +531,11 @@ async def _run_deferred(task_id: str, thunk) -> None:
                     "defer() factory must return an awaitable, got "
                     f"{type(awaitable).__name__}"
                 )
-            await awaitable
+            result, quiet = runtime.unwrap_display(await awaitable)
+            if result is not None:
+                task["result"] = _safe_repr(result)
+                if not quiet:
+                    runtime.print_display(result)
         except asyncio.CancelledError:
             task["exception"] = "CancelledError"
         except BaseException as exc:
@@ -966,6 +992,10 @@ def _boot_runtime(sock_path: Path, display: bool) -> None:
     try:
         paths.ensure_runtime_dir()
         state.sweep_dead_pid_files(paths.RUNTIME_DIR)
+        # 2a-ii. Same idea, one level up: reclaim a dead kernel's whole
+        # PROJECTS_DIR/<slug>/ directory, not just the per-process scratch
+        # above — see state.sweep_dead_project_dirs' docstring.
+        state.sweep_dead_project_dirs(paths.PROJECTS_DIR)
     except Exception as e:
         print(f"repld: could not sweep stale runtime files: {e}", file=sys.stderr)
 

{repld_tool-0.2.2 → repld_tool-0.2.4}/src/repld/paths.py

@@ -32,6 +32,13 @@ driven by ``tasks._sweep_orphans``), which is the half boot-time sweeping can
 never cover for a process that stays up for weeks. Keep the prefix on anything
 new written here or neither rule will find it.
 
+A dead kernel's ``PROJECTS_DIR/<slug>/`` directory itself is a third case
+those two rules don't reach — they sweep files sitting flat in RUNTIME_DIR,
+never the per-project subdirectories one level up. ``state.sweep_dead_project_dirs``
+is that third rule: same boot-time pass, same liveness check via
+``state.read_lock``, applied to ``kernel.lock`` instead of a ``{pid}-…``
+filename.
+
 Without ``XDG_RUNTIME_DIR`` (macOS, most containers, any env-scrubbed spawn)
 the tree falls back to ``/tmp/repld-{uid}``. The uid suffix is load-bearing:
 ``/tmp`` is world-writable, so a shared unsuffixed name could be pre-created

{repld_tool-0.2.2 → repld_tool-0.2.4}/src/repld/runtime.py

@@ -48,6 +48,27 @@ def no_display(value: Any) -> Any:
     return _NoDisplay(value)
 
 
+def unwrap_display(result: Any) -> tuple[Any, bool]:
+    """Unwrap a `no_display()` wrapper, if `result` is one. Returns (value, quiet).
+
+    The one sanctioned way to inspect `_NoDisplay` from outside this module —
+    `defer()`'s deferred tasks have the same suppress-print-but-not-recovery
+    need as a cell's trailing expression, with no cell number to route
+    through `run_cell` for.
+    """
+    if isinstance(result, _NoDisplay):
+        return result.value, True
+    return result, False
+
+
+def print_display(result: Any) -> None:
+    """Print `result` the way a cell's auto-displayed trailing expression does."""
+    if isinstance(result, str) and "\n" in result:
+        print(result)
+    else:
+        print(repr(result))
+
+
 def _assign_target_names(stmts: list) -> set:
     """Collect top-level simple-assignment target names from a statement list.
 
@@ -157,14 +178,9 @@ async def run_cell(compiled: tuple, ns: dict, n: int) -> Any:
             await _eval(code, ns)
             _unwrap_assigned(ns, names)
         if tag in ("eval", "exec_eval") and result is not None:
-            quiet = isinstance(result, _NoDisplay)
-            if quiet:
-                result = result.value
+            result, quiet = unwrap_display(result)
             if not quiet:
-                if isinstance(result, str) and "\n" in result:
-                    print(result)
-                else:
-                    print(repr(result))
+                print_display(result)
             # Shift history: _ → __, __ → ___. Matches IPython convention.
             ns["___"] = ns.get("__")
             ns["__"] = ns.get("_")

{repld_tool-0.2.2 → repld_tool-0.2.4}/src/repld/state.py

@@ -17,6 +17,7 @@ import io
 import json
 import os
 import re
+import shutil
 import time
 from pathlib import Path
 from typing import IO, Any, Literal, overload
@@ -243,6 +244,44 @@ def sweep_own_stale_files(
     return removed
 
 
+def sweep_dead_project_dirs(projects_dir: Path) -> int:
+    """Reclaim a dead kernel's whole per-project directory under PROJECTS_DIR.
+
+    The third boot-time sweep rule described in paths.py's module docstring —
+    applied one level up from `sweep_dead_pid_files`, to the
+    ``PROJECTS_DIR/<slug>/`` directory itself rather than files inside it.
+
+    Only reclaims a directory whose ``kernel.lock`` exists *and* names a dead
+    pid — the same asymmetry `sweep_dead_pid_files` uses, in the same
+    direction. A directory with no lock yet may be another kernel mid-boot
+    (flock taken in `_claim_project`, lock not written until
+    `_write_lockfile` much later in `_start_services`); reclaiming it would
+    race that boot. A directory with no lock *ever* (a client resolved
+    `project_dir()` — `repld status`, `repld exec` — but no kernel started
+    there) is left alone too: there's nothing here to say it's abandoned
+    rather than simply unused, and it costs nothing to leave standing.
+    """
+    removed = 0
+    try:
+        entries = list(projects_dir.iterdir())
+    except OSError:
+        return 0
+    for entry in entries:
+        if not entry.is_dir():
+            continue
+        lock_path = entry / "kernel.lock"
+        if not lock_path.exists():
+            continue
+        if isinstance(read_lock(lock_path), dict):
+            continue  # pid alive
+        try:
+            shutil.rmtree(entry)
+        except OSError:
+            continue
+        removed += 1
+    return removed
+
+
 def acquire_lock(flock_path: Path) -> int | None:
     """Take the single-kernel-per-project mutex.
 

{repld_tool-0.2.2 → repld_tool-0.2.4}/src/repld/tasks.py

@@ -135,6 +135,11 @@ def new_task(origin: object = None) -> tuple[str, dict]:
     task: dict = {
         "done_event": threading.Event(),
         "exception": None,
+        # Bounded-repr'd, never the raw object: this dict feeds straight into
+        # get_task's `json.dumps(snap)`, and an arbitrary result (a DataFrame,
+        # a custom class) would break that RPC. Set only by `_run_deferred`;
+        # an `exec` cell's result goes to `_`/`_N` instead.
+        "result": None,
         "spill_file": None,
         "spill_path": None,
         "nudged": False,
@@ -284,6 +289,7 @@ def snapshot(task_id: str) -> dict | None:
         "spilled": task["spill_path"] is not None,
         "spill_path": task["spill_path"],
         "exception": task["exception"],
+        "result": task.get("result"),
         "done": task["done_event"].is_set(),
         "label": task.get("label"),
     }