repld-tool 0.0.1__tar.gz

repld_tool-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fredrik Angelsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

repld_tool-0.0.1/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: repld-tool
+Version: 0.0.1
+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
+Author-email: Fredrik Angelsen <fredrikangelsen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: duckdb>=1.5.2 ; extra == 'browser'
+Requires-Dist: websockets>=16.0 ; extra == 'browser'
+Requires-Dist: rich>=15.0.0 ; extra == 'pretty'
+Requires-Python: >=3.12
+Provides-Extra: browser
+Provides-Extra: pretty
+Description-Content-Type: text/markdown
+
+# repld
+
+Persistent Python runtime with MCP channel push. Dev shell and autonomous-agent substrate in one package.
+
+```bash
+uv tool install repld-tool
+```
+
+## What it does
+
+- **Stateful kernel** — auth once, hold the client, query across turns. State persists across cells.
+- **Async-native** — top-level `await`, `defer()` for fire-and-forget, `@every()` for periodic tasks. Long jobs never block the turn.
+- **Channel push** — task completion, webhooks, file changes, and timers arrive as `<channel>` injections. The agent reacts; it doesn't poll.
+- **Shared namespace** — human and agent operate on the same `__main__`. Stage data in one, use it in the other.
+- **Browser integration** — attach to your logged-in Chrome tabs via CDP. No API keys, no OAuth dance. The agent discovers the API surface from your traffic.
+- **Gists** — reusable Python modules that wrap any web app's API. The browser supplies auth; the gist captures the pattern.
+
+## Install
+
+```bash
+# install globally
+uv tool install repld-tool
+
+# in any project:
+cd path/to/project
+repld init               # writes .mcp.json + updates .gitignore
+repld                    # starts the kernel
+```
+
+Project-local alternative: `uv add --dev repld-tool`, then point `.mcp.json` at `uv run repld bridge`.
+
+`repld init` produces this `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "repld": { "type": "stdio", "command": "repld", "args": ["bridge"] }
+  }
+}
+```
+
+## Quick example
+
+The agent calls `exec` to run Python in the kernel:
+
+```python
+# runs inline — result returned immediately
+import httpx
+httpx.get("https://api.example.com/status").json()
+
+# long-running — returns task_id, pushes channel notification on completion
+await asyncio.sleep(30)
+notify("done", kind="migration")
+```
+
+Autonomous worker — five lines:
+
+```python
+@every(300)
+async def check_overdue():
+    for inv in await po.get_overdue():
+        notify(f"Overdue: {inv.customer} {inv.amount} NOK",
+               kind="overdue", invoice_id=inv.id)
+```
+
+The kernel runs the watcher; the agent reacts to each `<channel>` injection.
+
+## With an existing app
+
+`repld` inherits your project's environment. A `repl.py` at the project root:
+
+```python
+from myapp.main import app
+from myapp.db import async_session_maker
+import asyncio, uvicorn
+
+asyncio.create_task(uvicorn.Server(
+    uvicorn.Config(app, host="127.0.0.1", port=8000, log_level="warning")
+).serve())
+
+session = async_session_maker()
+print("FastAPI on :8000, db session ready")
+```
+
+```bash
+repld --init repl.py
+```
+
+The agent now has a live handle on your running app: inspect routes, query the ORM, call handlers bypassing HTTP.
+
+## Tools
+
+**Core:**
+
+| Tool | What it does |
+|------|-------------|
+| `exec` | Execute Python. Returns inline within timeout (default 2s); otherwise returns `task_id` and pushes channel on completion. |
+| `get_task` | Status + head/tail preview of a running task's output. |
+| `cancel` | Cancel a running task by id. |
+
+**Browser** (requires `uv tool install repld-tool[browser]`):
+
+| Tool | What it does |
+|------|-------------|
+| `browser_attach` | Watch URL pattern, auto-attach matching tabs. |
+| `browser_tabs` | List attached tabs. |
+| `browser_pages` | List all Chrome targets. |
+| `browser_js` | Evaluate JavaScript in a tab. |
+| `browser_network` | Query captured traffic (HAR-style, DuckDB). |
+| `browser_body` | Response body for a captured request. |
+| `browser_request` | Request headers/postData for a captured request. |
+| `browser_fetch` | In-page fetch (inherits auth/cookies). |
+| `browser_click` | Click element (trusted dispatch). |
+| `browser_type` | Type into element (trusted dispatch). |
+| `browser_key` | Send key press (Enter, Escape, etc). |
+| `browser_navigate` | Navigate tab to URL. |
+| `browser_open` | Open new tab. |
+| `browser_console` | Query console logs and exceptions. |
+| `browser_screenshot` | Capture page screenshot. |
+| `browser_cdp` | Raw CDP passthrough. |
+| `browser_clear` | Reset captured network/console. |
+| `browser_detach` | Remove watch pattern, detach tabs. |
+
+Output from every cell spills to `$XDG_RUNTIME_DIR/repld/` — the inline response carries a head/tail preview plus the spill path. Use standard `Read`/`Grep` tools for full output.
+
+## Helpers
+
+Available in the kernel namespace:
+
+```python
+notify(content, **meta)              # channel push to the agent
+ask(prompt)                          # block on free-form human input
+confirm(prompt)                      # block on yes/no
+choose(prompt, options)              # block on pick-one
+defer(coro, label=None)              # fire-and-forget, channel push on completion
+@every(seconds)                      # periodic ticker, fn.cancel() to stop
+```
+
+Browser builtins (when `repld[browser]` is installed):
+
+```python
+tab = await browser.get("*example.com*")  # find tab by URL glob
+tab = await browser.open("https://...")   # open new tab
+await browser.watch("*pattern*")          # auto-attach matching tabs
+
+await tab.js("document.title")            # eval JS
+await tab.fetch("/api/data")              # in-page fetch (inherits session)
+await tab.click("#submit")                # trusted click
+await tab.type_text("#search", "query")   # trusted typing
+tab.network(url="*api*")                  # query captured traffic
+```
+
+## Gists
+
+Gists are Python modules in `./gists/` (project) or `~/.repld/gists/` (global) that wrap anything into a callable API — web apps via the browser, databases, graph stores, embedding indexes, internal services.
+
+```python
+# gists/myapp.py
+"""MyApp — accounts and transactions."""
+
+class MyApp:
+    def __init__(self, tab): self._tab = tab
+
+    @classmethod
+    async def connect(cls):
+        from __main__ import browser
+        tab = await browser.get("*myapp.com*")
+        return cls(tab)
+
+    async def accounts(self):
+        return (await self._tab.fetch("/api/accounts"))["body"]
+```
+
+```python
+import myapp
+app = await myapp.MyApp.connect()
+await app.accounts()
+```
+
+Re-importing after edits auto-reloads. Gists can register MCP tools via `__repld_tools__` — scaffold with `repld gist <name>`. Run `repld help gists` for details.
+
+## Browser
+
+`repld[browser]` attaches to Chrome via CDP (`--remote-debugging-port=9222`). You log in normally; the agent sees your traffic, discovers the API surface, and works with your authenticated sessions.
+
+```python
+tab = await browser.get("*salesforce*")
+reqs = tab.network(url="*/api/*")           # discover API calls
+auth = reqs[0].request_headers["Authorization"]  # extract auth
+```
+
+Body capture via Fetch interception means login flows, redirects, and CSRF exchanges are never lost. See [docs/browser.md](docs/browser.md) for the full design.
+
+## Scope
+
+`repld` executes arbitrary Python in your project environment. It is a **dev-time tool** — never a runtime dependency. The IPC socket is localhost-only with user-only permissions.
+
+Channels are a research-preview feature of Claude Code. The current integration uses `--dangerously-load-development-channels server:repld`.
+
+## License
+
+[MIT](LICENSE)

repld_tool-0.0.1/README.md

@@ -0,0 +1,202 @@
+# repld
+
+Persistent Python runtime with MCP channel push. Dev shell and autonomous-agent substrate in one package.
+
+```bash
+uv tool install repld-tool
+```
+
+## What it does
+
+- **Stateful kernel** — auth once, hold the client, query across turns. State persists across cells.
+- **Async-native** — top-level `await`, `defer()` for fire-and-forget, `@every()` for periodic tasks. Long jobs never block the turn.
+- **Channel push** — task completion, webhooks, file changes, and timers arrive as `<channel>` injections. The agent reacts; it doesn't poll.
+- **Shared namespace** — human and agent operate on the same `__main__`. Stage data in one, use it in the other.
+- **Browser integration** — attach to your logged-in Chrome tabs via CDP. No API keys, no OAuth dance. The agent discovers the API surface from your traffic.
+- **Gists** — reusable Python modules that wrap any web app's API. The browser supplies auth; the gist captures the pattern.
+
+## Install
+
+```bash
+# install globally
+uv tool install repld-tool
+
+# in any project:
+cd path/to/project
+repld init               # writes .mcp.json + updates .gitignore
+repld                    # starts the kernel
+```
+
+Project-local alternative: `uv add --dev repld-tool`, then point `.mcp.json` at `uv run repld bridge`.
+
+`repld init` produces this `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "repld": { "type": "stdio", "command": "repld", "args": ["bridge"] }
+  }
+}
+```
+
+## Quick example
+
+The agent calls `exec` to run Python in the kernel:
+
+```python
+# runs inline — result returned immediately
+import httpx
+httpx.get("https://api.example.com/status").json()
+
+# long-running — returns task_id, pushes channel notification on completion
+await asyncio.sleep(30)
+notify("done", kind="migration")
+```
+
+Autonomous worker — five lines:
+
+```python
+@every(300)
+async def check_overdue():
+    for inv in await po.get_overdue():
+        notify(f"Overdue: {inv.customer} {inv.amount} NOK",
+               kind="overdue", invoice_id=inv.id)
+```
+
+The kernel runs the watcher; the agent reacts to each `<channel>` injection.
+
+## With an existing app
+
+`repld` inherits your project's environment. A `repl.py` at the project root:
+
+```python
+from myapp.main import app
+from myapp.db import async_session_maker
+import asyncio, uvicorn
+
+asyncio.create_task(uvicorn.Server(
+    uvicorn.Config(app, host="127.0.0.1", port=8000, log_level="warning")
+).serve())
+
+session = async_session_maker()
+print("FastAPI on :8000, db session ready")
+```
+
+```bash
+repld --init repl.py
+```
+
+The agent now has a live handle on your running app: inspect routes, query the ORM, call handlers bypassing HTTP.
+
+## Tools
+
+**Core:**
+
+| Tool | What it does |
+|------|-------------|
+| `exec` | Execute Python. Returns inline within timeout (default 2s); otherwise returns `task_id` and pushes channel on completion. |
+| `get_task` | Status + head/tail preview of a running task's output. |
+| `cancel` | Cancel a running task by id. |
+
+**Browser** (requires `uv tool install repld-tool[browser]`):
+
+| Tool | What it does |
+|------|-------------|
+| `browser_attach` | Watch URL pattern, auto-attach matching tabs. |
+| `browser_tabs` | List attached tabs. |
+| `browser_pages` | List all Chrome targets. |
+| `browser_js` | Evaluate JavaScript in a tab. |
+| `browser_network` | Query captured traffic (HAR-style, DuckDB). |
+| `browser_body` | Response body for a captured request. |
+| `browser_request` | Request headers/postData for a captured request. |
+| `browser_fetch` | In-page fetch (inherits auth/cookies). |
+| `browser_click` | Click element (trusted dispatch). |
+| `browser_type` | Type into element (trusted dispatch). |
+| `browser_key` | Send key press (Enter, Escape, etc). |
+| `browser_navigate` | Navigate tab to URL. |
+| `browser_open` | Open new tab. |
+| `browser_console` | Query console logs and exceptions. |
+| `browser_screenshot` | Capture page screenshot. |
+| `browser_cdp` | Raw CDP passthrough. |
+| `browser_clear` | Reset captured network/console. |
+| `browser_detach` | Remove watch pattern, detach tabs. |
+
+Output from every cell spills to `$XDG_RUNTIME_DIR/repld/` — the inline response carries a head/tail preview plus the spill path. Use standard `Read`/`Grep` tools for full output.
+
+## Helpers
+
+Available in the kernel namespace:
+
+```python
+notify(content, **meta)              # channel push to the agent
+ask(prompt)                          # block on free-form human input
+confirm(prompt)                      # block on yes/no
+choose(prompt, options)              # block on pick-one
+defer(coro, label=None)              # fire-and-forget, channel push on completion
+@every(seconds)                      # periodic ticker, fn.cancel() to stop
+```
+
+Browser builtins (when `repld[browser]` is installed):
+
+```python
+tab = await browser.get("*example.com*")  # find tab by URL glob
+tab = await browser.open("https://...")   # open new tab
+await browser.watch("*pattern*")          # auto-attach matching tabs
+
+await tab.js("document.title")            # eval JS
+await tab.fetch("/api/data")              # in-page fetch (inherits session)
+await tab.click("#submit")                # trusted click
+await tab.type_text("#search", "query")   # trusted typing
+tab.network(url="*api*")                  # query captured traffic
+```
+
+## Gists
+
+Gists are Python modules in `./gists/` (project) or `~/.repld/gists/` (global) that wrap anything into a callable API — web apps via the browser, databases, graph stores, embedding indexes, internal services.
+
+```python
+# gists/myapp.py
+"""MyApp — accounts and transactions."""
+
+class MyApp:
+    def __init__(self, tab): self._tab = tab
+
+    @classmethod
+    async def connect(cls):
+        from __main__ import browser
+        tab = await browser.get("*myapp.com*")
+        return cls(tab)
+
+    async def accounts(self):
+        return (await self._tab.fetch("/api/accounts"))["body"]
+```
+
+```python
+import myapp
+app = await myapp.MyApp.connect()
+await app.accounts()
+```
+
+Re-importing after edits auto-reloads. Gists can register MCP tools via `__repld_tools__` — scaffold with `repld gist <name>`. Run `repld help gists` for details.
+
+## Browser
+
+`repld[browser]` attaches to Chrome via CDP (`--remote-debugging-port=9222`). You log in normally; the agent sees your traffic, discovers the API surface, and works with your authenticated sessions.
+
+```python
+tab = await browser.get("*salesforce*")
+reqs = tab.network(url="*/api/*")           # discover API calls
+auth = reqs[0].request_headers["Authorization"]  # extract auth
+```
+
+Body capture via Fetch interception means login flows, redirects, and CSRF exchanges are never lost. See [docs/browser.md](docs/browser.md) for the full design.
+
+## Scope
+
+`repld` executes arbitrary Python in your project environment. It is a **dev-time tool** — never a runtime dependency. The IPC socket is localhost-only with user-only permissions.
+
+Channels are a research-preview feature of Claude Code. The current integration uses `--dangerously-load-development-channels server:repld`.
+
+## License
+
+[MIT](LICENSE)

repld_tool-0.0.1/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "repld-tool"
+version = "0.0.1"
+description = "Persistent Python runtime with MCP channel push. Dev shell and autonomous-agent substrate in one package."
+readme = "README.md"
+authors = [
+    { name = "Fredrik Angelsen", email = "fredrikangelsen@gmail.com" }
+]
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+]
+keywords = ["repl", "mcp", "agent", "browser"]
+dependencies = []
+
+[project.scripts]
+repld = "repld:main"
+
+[project.optional-dependencies]
+pretty = [
+    "rich>=15.0.0",
+]
+browser = [
+    "duckdb>=1.5.2",
+    "websockets>=16.0",
+]
+
+[tool.uv.build-backend]
+module-name = "repld"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+typeCheckingMode = "standard"

repld_tool-0.0.1/src/repld/__init__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+__all__ = ["main"]

repld_tool-0.0.1/src/repld/bridge.py

@@ -0,0 +1,70 @@
+"""Stdio MCP ↔ unix-socket bridge.
+
+Dumb bidirectional byte-pipe. Does not parse MCP. Reads the kernel's socket
+path from ./.pyrepl.lock, connects, then:
+
+    stdin  → socket   (thread 1)
+    socket → stdout   (thread 2)
+
+Exits on EOF from either side. One bridge = one MCP client session.
+"""
+
+import socket
+import sys
+import threading
+from pathlib import Path
+
+from .ipc import connect_to_kernel
+
+LOCK_PATH = Path.cwd() / ".pyrepl.lock"
+
+
+def _err(msg: str) -> None:
+    print(f"repld bridge: {msg}", file=sys.stderr, flush=True)
+
+
+def run_bridge(argv: list[str]) -> int:
+    result = connect_to_kernel(LOCK_PATH)
+    if isinstance(result, str):
+        _err(result)
+        return 1
+    sock, _lock = result
+
+    stop = threading.Event()
+
+    def stdin_to_sock() -> None:
+        try:
+            for line in sys.stdin:
+                if not line.endswith("\n"):
+                    line = line + "\n"
+                sock.sendall(line.encode("utf-8"))
+        except (BrokenPipeError, OSError):
+            stop.set()
+        finally:
+            # Half-close write side so the kernel sees EOF and drains/closes.
+            # DO NOT set stop here: in-flight responses may still be inbound.
+            try:
+                sock.shutdown(socket.SHUT_WR)
+            except OSError:
+                pass
+
+    def sock_to_stdout() -> None:
+        try:
+            rfile = sock.makefile("r", encoding="utf-8")
+            for line in rfile:
+                sys.stdout.write(line)
+                sys.stdout.flush()
+        except (BrokenPipeError, OSError):
+            pass
+        finally:
+            # Socket-side EOF drives shutdown.
+            stop.set()
+
+    threading.Thread(target=stdin_to_sock, daemon=True, name="bridge-stdin").start()
+    threading.Thread(target=sock_to_stdout, daemon=True, name="bridge-stdout").start()
+    stop.wait()
+    try:
+        sock.close()
+    except OSError:
+        pass
+    return 0