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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repld-tool
-Version: 0.2.0
+Version: 0.2.2
 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.0 → repld_tool-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "repld-tool"
-version = "0.2.0"
+version = "0.2.2"
 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.0 → repld_tool-0.2.2}/src/repld/__init__.py

@@ -11,7 +11,9 @@ if TYPE_CHECKING:
     from typing import Any, Callable, Coroutine
 
     def notify(content: Any, **meta: Any) -> None: ...
-    def defer(coro: Coroutine, label: str | None = None) -> str: ...
+    def defer(
+        coro: Coroutine | Callable[[], Coroutine], label: str | None = None
+    ) -> str: ...
     def every(
         seconds: float, *, label: str | None = None, delay: float = 0.0
     ) -> Callable: ...

{repld_tool-0.2.0 → repld_tool-0.2.2}/src/repld/bind.py

@@ -161,12 +161,50 @@ def adopt(venv: Path) -> Path | None:
     return sp
 
 
+def has_browser_extra() -> bool:
+    """Whether *this* interpreter can import the browser stack.
+
+    All three are load-bearing and imported eagerly, so the question is not
+    "which one" but "are they all here" — `browser/png.py` pulls in PIL at
+    module scope, and `kernel._inject_builtins` reads any one of them missing
+    as the whole extra being absent.
+
+    ``find_spec`` rather than an import: this runs on every bound start, and
+    importing duckdb to find out whether we could is most of the cost the extra
+    exists to avoid paying.
+    """
+    from importlib.util import find_spec
+
+    for mod in ("duckdb", "websockets", "PIL"):
+        try:
+            if find_spec(mod) is None:
+                return False
+        except (ImportError, ValueError):
+            return False
+    return True
+
+
 def uv_run_argv(argv: list[str]) -> list[str] | None:
     """The ``uv run`` command that relaunches ``repld <argv>`` under the
     project's interpreter, or None if uv isn't on PATH.
 
     Reuses ``relaunch._editable_path()`` so a local checkout keeps winning over
     the published package, exactly as it does for ``repld browser``.
+
+    **The browser extra is carried across the re-exec, or the rebind silently
+    takes it away.** ``uv run --with`` builds a fresh environment from the spec
+    it is given; the interpreter we are leaving does not contribute to it. So a
+    repld installed *with* the extra — the tool venv carrying duckdb,
+    websockets and PIL — re-execs into an environment that has none of them,
+    and the kernel comes up with no ``browser`` builtin, no browser MCP tools,
+    and nothing anywhere saying why. The observable shape of that bug is the
+    tell: browser worked in every project *without* a ``./.venv`` and in none
+    of the projects with one, since only the latter rebind at all.
+
+    Conditional on what we already have rather than unconditional, so a repld
+    installed without the extra doesn't start resolving duckdb behind the
+    user's back. The rule is that the re-exec must not *lose* a capability, not
+    that it should acquire one.
     """
     import shutil
 
@@ -175,8 +213,13 @@ def uv_run_argv(argv: list[str]) -> list[str] | None:
     uv = shutil.which("uv")
     if uv is None:
         return None
+    extra = "[browser]" if has_browser_extra() else ""
     path = _editable_path()
-    with_arg = ["--with-editable", path] if path else ["--with", "repld-tool"]
+    with_arg = (
+        ["--with-editable", f"{path}{extra}"]
+        if path
+        else ["--with", f"repld-tool{extra}"]
+    )
     return [uv, "run", *with_arg, "repld", *argv]
 
 

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

@@ -96,8 +96,6 @@ _PLAYBOOK = (
     "Read repld://docs/playbook for the full methodology."
 )
 
-_REFERENCE = "Reference: `repld help <topic>` — topics: exec, browser, gists, gates\nRead repld://docs/guide for exec patterns and gist conventions. Read repld://docs/browser for the full browser API and internals.\nRead repld://docs/production when graduating gists to FastMCP/FastAPI."
-
 
 # ---------------------------------------------------------------------------
 # PLAYBOOK (repld://docs/playbook resource — workflow methodology)
@@ -992,7 +990,9 @@ def static_instructions() -> str:
     depends on kernel state — the browser model, the gist listing, and
     registered gist tools.
     """
-    return "\n\n".join([_EXEC_MODEL, _GISTS_MODEL, _deps_hint(), _PLAYBOOK, _REFERENCE])
+    return "\n\n".join(
+        [_EXEC_MODEL, _GISTS_MODEL, _deps_hint(), _PLAYBOOK, _reference()]
+    )
 
 
 def build_instructions() -> str:
@@ -1029,7 +1029,7 @@ def build_instructions() -> str:
 
     parts.append(_deps_hint())
     parts.append(_PLAYBOOK)
-    parts.append(_REFERENCE)
+    parts.append(_reference())
     return "\n\n".join(parts)
 
 
@@ -1113,6 +1113,9 @@ no_display(value) → value
 
 defer(coro, label=None) → task_id
   Fire-and-forget. Channel push on done. Visible to get_task/cancel.
+  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.
 
 every(seconds, label=, delay=0)(fn) → fn   periodic ticker; fn.cancel() stops
   delay= defers the first tick (default: tick now)
@@ -1366,10 +1369,55 @@ Emits awaiting_human channel while blocked.
 
 notify(content, **meta)
   One-shot channel push to all MCP sessions.
+""",
+    "migration": """\
+Why a repld project has no state files (0.1.x → 0.2).
+
+repld 0.2 writes nothing into a project directory. Files an older setup
+created are absent on purpose — none of these are missing, they are gone:
+
+  .pyrepl.lock/.sock/.dashboard  runtime state; now
+                                 $XDG_RUNTIME_DIR/repld/projects/<slug>/ as
+                                 kernel.lock/.sock/.dashboard. `repld status`
+                                 prints the live paths.
+  .mcp.json                      never written now. Register the server with
+                                 `claude mcp add repld -- repld bridge`.
+  CLAUDE.md repld:start block    gone; that content is the MCP `initialize`
+                                 instructions, composed fresh each session.
+  repl.py + --init               now ./repld_init.py, auto-detected and run by
+                                 every kernel, whoever started it.
+  __repld_tools__                removed in 0.2 and ignored, so a file still
+                                 declaring one has silently lost its tools.
+                                 `repld gist lint` is what reports it.
+
+Still in the project and yours to commit: ./gists/, ./gists/.links, ./.env,
+./repld_init.py.
+
+If you FIND a .pyrepl.* file, it is 0.1.x leftover, not something this version
+made. .pyrepl.lock names a pid that may still be running — check it with
+`ps -p <pid> -o pid,command` before signalling, since a stale lockfile can name
+a reused pid. .pyrepl.dashboard holds a dead dashboard's API token; it was only
+gitignored where `repld init` ran, so check `git ls-files | grep pyrepl`.
+Cleanup: https://angelsen.github.io/repld/docs/guides/upgrading/
 """,
 }
 
 
+def _reference() -> str:
+    """The always-loaded pointer block. Topic list derives from _TOPICS.
+
+    It was a literal listing four topics by hand, which is a second copy of
+    `sorted(_TOPICS)` in the one string every session loads — so adding a topic
+    silently published a list that omitted it.
+    """
+    return (
+        f"Reference: `repld help <topic>` — topics: {', '.join(sorted(_TOPICS))}\n"
+        "Read repld://docs/guide for exec patterns and gist conventions. "
+        "Read repld://docs/browser for the full browser API and internals.\n"
+        "Read repld://docs/production when graduating gists to FastMCP/FastAPI."
+    )
+
+
 # `== Builtins ==` below recaps _EXEC_MODEL's builtins — keep in sync.
 GUIDE = """\
 repld — working guide
@@ -1421,6 +1469,14 @@ For intentionally long work, use defer():
 
   defer(download_all_invoices(), label="invoice sync")
 
+Fanning out with asyncio.gather()/create_task() inside defer() needs one
+more step: those reach for a running loop when *built*, not just when
+awaited, and a sync cell (no top-level await) runs in a worker thread with
+no loop of its own. Pass defer() a zero-arg callable instead of a
+pre-built awaitable, so the gather() call happens on the kernel's loop:
+
+  defer(lambda: asyncio.gather(one("a"), one("b"), return_exceptions=True))
+
 This returns the task_id immediately. The channel notification arrives
 when the coroutine completes (or fails).
 

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

@@ -487,14 +487,29 @@ async def _run_cell(task_id: str, src: str, n: int, *, wait_ready: bool = True)
             task["exception"] = type(exc).__name__
 
 
-async def _run_deferred(task_id: str, coro) -> None:
-    """Await a user-supplied coroutine within the task lifecycle.
-
-    Like _run_cell but skips compile/eval — just awaits the coroutine directly.
+async def _run_deferred(task_id: str, thunk) -> None:
+    """Build and await a user-supplied awaitable within the task lifecycle.
+
+    `thunk` is always a zero-arg callable — defer() wraps a coroutine object
+    passed directly as ``lambda: coro``, so this only has one code path.
+    Calling it here, inside a coroutine already scheduled on the kernel's
+    loop (`asyncio.run_coroutine_threadsafe`), is what lets a factory like
+    ``lambda: asyncio.gather(...)`` build its awaitable with a loop actually
+    running: `asyncio.gather()`/`create_task()`/`ensure_future()` all reach
+    for the *current thread's* loop at construction time, not just to await,
+    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.
     """
     async with _task_scope(task_id) as task:
         try:
-            await coro
+            awaitable = thunk()
+            if not inspect.isawaitable(awaitable):
+                raise TypeError(
+                    "defer() factory must return an awaitable, got "
+                    f"{type(awaitable).__name__}"
+                )
+            await awaitable
         except asyncio.CancelledError:
             task["exception"] = "CancelledError"
         except BaseException as exc:
@@ -508,13 +523,32 @@ def _make_defer(loop: asyncio.AbstractEventLoop):
     def defer(coro, label: str | None = None) -> str:
         """Schedule a coroutine as a tracked task. Returns task_id immediately.
 
+        `coro` is normally a coroutine object (`defer(my_async_fn())`). It
+        may also be a zero-arg callable that *builds* one —
+        `defer(lambda: asyncio.gather(one(), two()))` — for constructs that
+        need a running loop to construct, not just to await. A sync cell's
+        body runs in a worker thread with no event loop set, so calling
+        `asyncio.gather(...)` there eagerly (as a `defer()` argument) fails
+        before `defer()` is even entered; wrapping it in a zero-arg callable
+        defers the call itself onto the kernel's loop, where it belongs.
+
         The task is visible to get_task and cancel. On completion, a task_done
         channel notification is pushed.
         """
-        if not inspect.iscoroutine(coro):
+        if inspect.iscoroutine(coro):
+            thunk = lambda c=coro: c  # noqa: E731
+        elif inspect.iscoroutinefunction(coro):
             raise TypeError(
-                f"defer() expects a coroutine object, got {type(coro).__name__}. "
-                "Call it as: defer(my_async_fn())"
+                f"defer() expects a coroutine object, got the function "
+                f"{coro.__name__!r} itself. Call it as: defer({coro.__name__}())"
+            )
+        elif callable(coro):
+            thunk = coro
+        else:
+            raise TypeError(
+                "defer() expects a coroutine object (or a zero-arg callable "
+                f"that builds one), got {type(coro).__name__}. Call it as: "
+                "defer(my_async_fn()) or defer(lambda: asyncio.gather(...))"
             )
         # Inherit the calling cell's originating session so a background task
         # reports back to whoever asked for it. defer() from an @every body or
@@ -527,7 +561,7 @@ def _make_defer(loop: asyncio.AbstractEventLoop):
             task["label"] = label
         src_label = label or "..."
         events.emit(CellStart(task_id, f"defer({src_label})", time.time()))
-        asyncio.run_coroutine_threadsafe(_run_deferred(task_id, coro), loop)
+        asyncio.run_coroutine_threadsafe(_run_deferred(task_id, thunk), loop)
         return task_id
 
     return defer
@@ -1017,8 +1051,20 @@ def _inject_builtins(loop: asyncio.AbstractEventLoop) -> None:
         # themselves up anyway — the pill's staleness check removes it, and the
         # beforeunload guard with it, once Python stops heartbeating, which is
         # exactly what a stopped loop looks like from the page.
-    except ImportError:
-        pass  # repld[browser] not installed — no browser builtin
+    except ImportError as e:
+        # Not an error — most projects never install the extra. But swallowing
+        # it silently means the failure surfaces much later and somewhere else:
+        # `NameError: name 'browser' is not defined` in a cell, or 21 tools
+        # simply absent from tools/list. Both read as "this kernel has no
+        # browser" and neither says *why*, which sends the reader looking at
+        # the browser stack instead of at the environment. This is the only
+        # place that knows which module was missing, so it says so.
+        print(
+            f"repld: browser disabled — cannot import {e.name or e}. "
+            "Install the `browser` extra, or run `repld browser` instead of "
+            "`repld`.",
+            file=sys.stderr,
+        )
 
 
 def _start_services(

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

@@ -221,8 +221,16 @@ def _format_user_traceback(exc: BaseException) -> str:
             )
         elif "no current event loop" in msg or "no running event loop" in msg:
             formatted += (
-                "\nHint: this cell ran in a background thread "
-                "(no 'await' detected). Use defer() to schedule async work:\n"
-                "  defer(some_coroutine())\n"
+                "\nHint: this cell ran in a background thread (no top-level "
+                "'await' in the cell), so asyncio.gather()/create_task()/"
+                "ensure_future() had no loop to attach to — they reach for "
+                "one at construction, not just to await it. Build it inside "
+                "an async def instead:\n"
+                "  async def _run():\n"
+                "      return await asyncio.gather(a(), b())\n"
+                "  await _run()\n"
+                "or, if deferring it, pass defer() a zero-arg callable so it "
+                "builds on the kernel's loop rather than in this thread:\n"
+                "  defer(lambda: asyncio.gather(a(), b()))\n"
             )
     return formatted