agentwatcher 0.1.0__py3-none-any.whl

agentwatch/__init__.py

@@ -0,0 +1,14 @@
+"""agentwatch — DevTools-style overlay for browser-based AI agents.
+
+Public API:
+    from agentwatch import AgentWatch
+
+    with AgentWatch() as aw:
+        aw.announce(goal="Book a flight from SFO to JFK")
+        aw.announce(last_action="Clicked search button", next_action="Type 'SFO'")
+"""
+
+from .sdk import AgentWatch, announce, start, stop
+
+__all__ = ["AgentWatch", "announce", "start", "stop"]
+__version__ = "0.1.0"

agentwatch/sdk.py

@@ -0,0 +1,130 @@
+"""Public SDK — spawn a WS broadcast server in a background thread and
+let agent code push status events to any connected agentwatch overlay."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from typing import Optional
+
+import websockets
+
+
+class _Broadcaster:
+    def __init__(self, host: str, port: int) -> None:
+        self.host = host
+        self.port = port
+        self.clients: set = set()
+        self.last_state: dict = {}
+        self.loop: Optional[asyncio.AbstractEventLoop] = None
+        self.server = None
+        self._thread: Optional[threading.Thread] = None
+        self._ready = threading.Event()
+
+    async def _handler(self, ws):
+        self.clients.add(ws)
+        if self.last_state:
+            try:
+                await ws.send(json.dumps(self.last_state))
+            except Exception:
+                pass
+        try:
+            async for _msg in ws:
+                pass
+        finally:
+            self.clients.discard(ws)
+
+    async def _serve(self) -> None:
+        self.server = await websockets.serve(self._handler, self.host, self.port)
+        self._ready.set()
+        await self.server.wait_closed()
+
+    def start(self) -> None:
+        def run() -> None:
+            self.loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self.loop)
+            try:
+                self.loop.run_until_complete(self._serve())
+            except OSError:
+                self._ready.set()  # release waiter even if port is taken
+        self._thread = threading.Thread(target=run, name="agentwatch-ws", daemon=True)
+        self._thread.start()
+        self._ready.wait(timeout=2.0)
+
+    def broadcast(self, payload: dict) -> None:
+        if not self.loop or not self.loop.is_running():
+            return
+        merged = {**self.last_state, **payload}
+        self.last_state = merged
+        message = json.dumps(merged)
+
+        async def send_all() -> None:
+            dead = []
+            for client in list(self.clients):
+                try:
+                    await client.send(message)
+                except Exception:
+                    dead.append(client)
+            for d in dead:
+                self.clients.discard(d)
+        asyncio.run_coroutine_threadsafe(send_all(), self.loop)
+
+    def stop(self) -> None:
+        if self.server and self.loop:
+            self.loop.call_soon_threadsafe(self.server.close)
+
+
+_singleton: Optional[_Broadcaster] = None
+
+
+def start(host: str = "127.0.0.1", port: int = 8765) -> None:
+    """Start the WebSocket broadcaster (idempotent)."""
+    global _singleton
+    if _singleton is not None:
+        return
+    _singleton = _Broadcaster(host=host, port=port)
+    _singleton.start()
+
+
+def stop() -> None:
+    """Stop the broadcaster, releasing the port."""
+    global _singleton
+    if _singleton is not None:
+        _singleton.stop()
+        _singleton = None
+
+
+def announce(**fields) -> None:
+    """Push a status update to every connected agentwatch overlay.
+
+    Recognized keys (any subset): goal, last_action, next_action, step, error.
+    Arbitrary keys also work but won't be rendered by the default overlay.
+    """
+    if _singleton is None:
+        start()
+    assert _singleton is not None
+    _singleton.broadcast(fields)
+
+
+class AgentWatch:
+    """Context manager wrapper. Use as::
+
+        with AgentWatch() as aw:
+            aw.announce(goal="...")
+            aw.announce(last_action="clicked X", next_action="type 'hello'")
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 8765) -> None:
+        self.host = host
+        self.port = port
+
+    def __enter__(self) -> "AgentWatch":
+        start(self.host, self.port)
+        return self
+
+    def __exit__(self, *_exc) -> None:
+        stop()
+
+    def announce(self, **fields) -> None:
+        announce(**fields)

agentwatcher-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: agentwatcher
+Version: 0.1.0
+Summary: DevTools overlay for browser-based AI agents — see what your agent is doing in real time.
+Project-URL: Homepage, https://github.com/yubinkim444/agentwatch
+Project-URL: Repository, https://github.com/yubinkim444/agentwatch
+Project-URL: Issues, https://github.com/yubinkim444/agentwatch/issues
+Author: yubinkim444
+License-Expression: MIT
+Keywords: ai-agents,browser-agent,browser-use,debugging,developer-tools,playwright,selenium
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
+# agentwatch
+
+> **React DevTools, for browser AI agents.**
+> Drop a translucent overlay onto every tab that shows what your agent is
+> trying to do, what it just clicked, and what it's about to do next.
+
+[![PyPI](https://img.shields.io/pypi/v/agentwatch)](https://pypi.org/project/agentwatch/)
+[![Chrome](https://img.shields.io/badge/Chrome-MV3-4285F4)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)]()
+
+---
+
+## Why
+
+Browser-use, Playwright agents, computer-use models — they're all **black
+boxes** to the developer watching them. The agent moves the mouse, types
+into a field, the page reloads, then it errors out, and you're left
+guessing what it thought it was doing.
+
+`agentwatch` adds a tiny floating overlay to every tab. Your agent code
+pushes one-line status updates ("goal: book a flight", "last action:
+clicked search", "next action: type SFO"), and the overlay shows them
+live, framework-agnostic.
+
+The result: bug screenshots that are **self-explanatory**. Demo GIFs that
+viewers actually understand. Pair-debugging sessions where the human can
+intervene the moment the agent goes off-rails.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────┐        ws://127.0.0.1:8765        ┌──────────────────────────┐
+│  Your agent (any lang)   │ ──────────────────────────────▶   │  Chrome MV3 extension    │
+│  agentwatch.announce(    │      broadcasts status JSON       │  injects floating overlay│
+│      goal=..., last=...) │                                   │  on every tab            │
+└──────────────────────────┘                                   └──────────────────────────┘
+```
+
+The SDK runs a localhost WebSocket broadcaster in a background thread.
+The extension's content script connects to it on every page load. Each
+`announce()` call updates the overlay in place with a green flash.
+
+---
+
+## Install (2 steps)
+
+### 1. Install the Chrome extension
+
+```bash
+git clone https://github.com/yubinkim444/agentwatch.git
+cd agentwatch
+```
+
+In Chrome / Edge / Brave:
+- Open `chrome://extensions`
+- Toggle **Developer mode** (top-right)
+- Click **Load unpacked**
+- Select the `extension/` folder
+
+A small overlay appears in the bottom-right of every tab, showing a
+disconnected (yellow) dot until your agent connects.
+
+### 2. Install the SDK
+
+```bash
+pip install agentwatcher
+```
+
+---
+
+## Use it
+
+### Python
+
+```python
+from agentwatch import AgentWatch
+
+with AgentWatch() as aw:
+    aw.announce(goal="Book a one-way flight SFO → JFK for tomorrow")
+
+    # ...do agent stuff...
+
+    aw.announce(step=1, last_action="Opened google.com/flights",
+                next_action="Click the origin field")
+    # ...
+    aw.announce(step=2, last_action="Typed 'SFO'",
+                next_action="Click the destination field")
+```
+
+Or imperatively, without the context manager:
+
+```python
+import agentwatch
+agentwatch.start()
+agentwatch.announce(goal="...", last_action="...", next_action="...")
+```
+
+### Any other language
+
+Open a WebSocket to `ws://127.0.0.1:8765` and send JSON like:
+
+```json
+{"goal": "Book a flight", "last_action": "Clicked search", "next_action": "Type SFO"}
+```
+
+Every connected tab's overlay updates immediately.
+
+---
+
+## Recognized fields
+
+| Field | What the overlay shows |
+|-------|------------------------|
+| `goal` | Top-line objective. |
+| `last_action` | What the agent just did. |
+| `next_action` | What the agent is about to do. |
+| `step` | Optional step counter / index. |
+| `error` | Highlighted in red. The error row only appears when set. |
+
+Any other keys are kept in the broadcast payload but not rendered by the
+default overlay — fork the extension if you want to add custom rows.
+
+---
+
+## Pairs nicely with
+
+- [`playwright`](https://playwright.dev), [`selenium`](https://selenium.dev),
+  [`browser-use`](https://github.com/browser-use/browser-use), any computer-use agent.
+- A screen-recorder. The overlay + your tool together produce demo GIFs
+  that explain themselves.
+
+---
+
+## Companion projects
+
+- **[mcp-rec](https://github.com/yubinkim444/mcp-rec)** — VCR for MCP servers.
+- **[llm-cache-proxy](https://github.com/yubinkim444/llm-cache-proxy)** — disk cache for OpenAI/Anthropic API calls.
+- **[promptlock](https://github.com/yubinkim444/promptlock)** — lockfile for prompts.
+- **[context-diff](https://github.com/yubinkim444/context-diff)** — git diff for Claude Code context windows.
+
+---
+
+## License
+
+MIT © yubinkim444

agentwatcher-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+agentwatch/__init__.py,sha256=W3K2UdkiZ8mZCL50ePG47SQTK-bSvSogHxE2VtXgBpA,425
+agentwatch/sdk.py,sha256=9w445iJfRhHO-IY5VYNEgwOBVZ2f7q0E0u6-jCsdNcI,3842
+agentwatcher-0.1.0.dist-info/METADATA,sha256=YLgjeo-aqMNHqxRnGgPKiDnEbifpyV3jviEIYQMD3-A,5755
+agentwatcher-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentwatcher-0.1.0.dist-info/RECORD,,

agentwatcher-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any