agentmb 0.1.0__tar.gz

agentmb-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+.npm-cache/
+.env
+.env.local
+.env.test
+*.log
+.DS_Store
+
+# Python SDK
+sdk/python/__pycache__/
+sdk/python/*.egg-info/
+sdk/python/.venv/
+sdk/python/dist/
+
+# agentmb runtime data
+~/.agentmb/

agentmb-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: agentmb
+Version: 0.1.0
+Summary: Python SDK for agentmb — local Chromium runtime daemon for AI agents
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentmb Python SDK
+
+Python client for the [agentmb](https://github.com/what552/agent-managed-browser) daemon — local Chromium runtime for AI agents.
+
+## Install
+
+```bash
+pip install agentmb
+```
+
+Or from source (editable):
+
+```bash
+pip install -e sdk/python
+```
+
+## Quick start
+
+```python
+from agentmb import BrowserClient
+
+with BrowserClient() as client:
+    with client.sessions.create(profile="myprofile") as sess:
+        sess.navigate("https://example.com")
+        shot = sess.screenshot()
+        shot.save("/tmp/out.png")
+```
+
+Async:
+
+```python
+import asyncio
+from agentmb import AsyncBrowserClient
+
+async def main():
+    async with AsyncBrowserClient() as client:
+        sess = await client.sessions.create(profile="demo")
+        async with sess:
+            await sess.navigate("https://example.com")
+            result = await sess.eval("document.title")
+            print(result.result)
+
+asyncio.run(main())
+```
+
+## Action methods
+
+| Method | Description |
+|---|---|
+| `sess.navigate(url)` | Navigate to URL |
+| `sess.screenshot()` | Capture screenshot → `ScreenshotResult` |
+| `sess.eval(expr)` | Run JS → `EvalResult` |
+| `sess.extract(selector)` | Extract text/attrs → `ExtractResult` |
+| `sess.click(selector)` | Click element |
+| `sess.fill(selector, value)` | Fill form field |
+| `sess.type(selector, text)` | Type char-by-char |
+| `sess.press(selector, key)` | Press key / combo (e.g. `"Enter"`, `"Control+a"`) |
+| `sess.select(selector, values)` | Select `<option>` in a `<select>` |
+| `sess.hover(selector)` | Hover over element |
+| `sess.wait_for_selector(selector, state)` | Wait for element visibility state |
+| `sess.wait_for_url(pattern)` | Wait for URL to match glob pattern |
+| `sess.wait_for_response(url_pattern, trigger)` | Wait for a network response |
+| `sess.upload(selector, file_path)` | Upload file to `<input type="file">` |
+| `sess.download(selector)` | Click download link → `DownloadResult` |
+| `sess.handoff_start()` | Switch to headed mode for human login |
+| `sess.handoff_complete()` | Return to headless after login |
+| `sess.cdp_send(method, params)` | Send raw CDP command |
+| `sess.logs(tail)` | Fetch audit log entries |
+
+### File upload / download
+
+```python
+# Upload
+result = sess.upload("#file-input", "/path/to/file.csv", mime_type="text/csv")
+print(result.filename, result.size_bytes)
+
+# Download: triggers click, returns base64 file content
+dl = sess.download("#download-link")
+dl.save("/tmp/report.pdf")
+```
+
+### Wait actions
+
+```python
+# Wait for element to appear
+sess.wait_for_selector("#modal", state="visible", timeout_ms=3000)
+
+# Wait for URL after SPA navigation
+sess.wait_for_url("**/dashboard**", timeout_ms=5000)
+
+# Wait for a specific network response (with navigate trigger)
+resp = sess.wait_for_response(
+    url_pattern="/api/data",
+    timeout_ms=10000,
+    trigger={"type": "navigate", "url": "https://app.example.com"},
+)
+print(resp.status_code)
+```
+
+## Requirements
+
+- Python 3.9+
+- agentmb daemon running (`agentmb start`)
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENTMB_PORT` | `19315` | Daemon port |
+| `AGENTMB_API_TOKEN` | (none) | API token if daemon started with one |
+
+## License
+
+MIT

agentmb-0.1.0/README.md

@@ -0,0 +1,114 @@
+# agentmb Python SDK
+
+Python client for the [agentmb](https://github.com/what552/agent-managed-browser) daemon — local Chromium runtime for AI agents.
+
+## Install
+
+```bash
+pip install agentmb
+```
+
+Or from source (editable):
+
+```bash
+pip install -e sdk/python
+```
+
+## Quick start
+
+```python
+from agentmb import BrowserClient
+
+with BrowserClient() as client:
+    with client.sessions.create(profile="myprofile") as sess:
+        sess.navigate("https://example.com")
+        shot = sess.screenshot()
+        shot.save("/tmp/out.png")
+```
+
+Async:
+
+```python
+import asyncio
+from agentmb import AsyncBrowserClient
+
+async def main():
+    async with AsyncBrowserClient() as client:
+        sess = await client.sessions.create(profile="demo")
+        async with sess:
+            await sess.navigate("https://example.com")
+            result = await sess.eval("document.title")
+            print(result.result)
+
+asyncio.run(main())
+```
+
+## Action methods
+
+| Method | Description |
+|---|---|
+| `sess.navigate(url)` | Navigate to URL |
+| `sess.screenshot()` | Capture screenshot → `ScreenshotResult` |
+| `sess.eval(expr)` | Run JS → `EvalResult` |
+| `sess.extract(selector)` | Extract text/attrs → `ExtractResult` |
+| `sess.click(selector)` | Click element |
+| `sess.fill(selector, value)` | Fill form field |
+| `sess.type(selector, text)` | Type char-by-char |
+| `sess.press(selector, key)` | Press key / combo (e.g. `"Enter"`, `"Control+a"`) |
+| `sess.select(selector, values)` | Select `<option>` in a `<select>` |
+| `sess.hover(selector)` | Hover over element |
+| `sess.wait_for_selector(selector, state)` | Wait for element visibility state |
+| `sess.wait_for_url(pattern)` | Wait for URL to match glob pattern |
+| `sess.wait_for_response(url_pattern, trigger)` | Wait for a network response |
+| `sess.upload(selector, file_path)` | Upload file to `<input type="file">` |
+| `sess.download(selector)` | Click download link → `DownloadResult` |
+| `sess.handoff_start()` | Switch to headed mode for human login |
+| `sess.handoff_complete()` | Return to headless after login |
+| `sess.cdp_send(method, params)` | Send raw CDP command |
+| `sess.logs(tail)` | Fetch audit log entries |
+
+### File upload / download
+
+```python
+# Upload
+result = sess.upload("#file-input", "/path/to/file.csv", mime_type="text/csv")
+print(result.filename, result.size_bytes)
+
+# Download: triggers click, returns base64 file content
+dl = sess.download("#download-link")
+dl.save("/tmp/report.pdf")
+```
+
+### Wait actions
+
+```python
+# Wait for element to appear
+sess.wait_for_selector("#modal", state="visible", timeout_ms=3000)
+
+# Wait for URL after SPA navigation
+sess.wait_for_url("**/dashboard**", timeout_ms=5000)
+
+# Wait for a specific network response (with navigate trigger)
+resp = sess.wait_for_response(
+    url_pattern="/api/data",
+    timeout_ms=10000,
+    trigger={"type": "navigate", "url": "https://app.example.com"},
+)
+print(resp.status_code)
+```
+
+## Requirements
+
+- Python 3.9+
+- agentmb daemon running (`agentmb start`)
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENTMB_PORT` | `19315` | Daemon port |
+| `AGENTMB_API_TOKEN` | (none) | API token if daemon started with one |
+
+## License
+
+MIT

agentmb-0.1.0/agentmb/__init__.py

@@ -0,0 +1,61 @@
+"""agentmb Python SDK"""
+
+from .client import BrowserClient, AsyncBrowserClient
+from .models import (
+    SessionInfo,
+    NavigateResult,
+    ScreenshotResult,
+    EvalResult,
+    ActionResult,
+    ExtractResult,
+    HandoffResult,
+    AuditEntry,
+    TypeResult,
+    PressResult,
+    SelectResult,
+    HoverResult,
+    WaitForSelectorResult,
+    WaitForUrlResult,
+    WaitForResponseResult,
+    UploadResult,
+    DownloadResult,
+    PageInfo,
+    PageListResult,
+    NewPageResult,
+    RouteMock,
+    RouteEntry,
+    RouteListResult,
+    TraceResult,
+    PolicyInfo,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "BrowserClient",
+    "AsyncBrowserClient",
+    "SessionInfo",
+    "NavigateResult",
+    "ScreenshotResult",
+    "EvalResult",
+    "ActionResult",
+    "ExtractResult",
+    "HandoffResult",
+    "AuditEntry",
+    "TypeResult",
+    "PressResult",
+    "SelectResult",
+    "HoverResult",
+    "WaitForSelectorResult",
+    "WaitForUrlResult",
+    "WaitForResponseResult",
+    "UploadResult",
+    "DownloadResult",
+    "PageInfo",
+    "PageListResult",
+    "NewPageResult",
+    "RouteMock",
+    "RouteEntry",
+    "RouteListResult",
+    "TraceResult",
+    "PolicyInfo",
+]

agentmb-0.1.0/agentmb/client.py

@@ -0,0 +1,747 @@
+"""agentmb Python SDK — sync and async clients."""
+
+from __future__ import annotations
+
+import os
+from contextlib import asynccontextmanager, contextmanager
+from typing import AsyncGenerator, Generator, List, Optional
+
+import httpx
+
+from .models import (
+    ActionResult,
+    AuditEntry,
+    DaemonStatus,
+    DownloadResult,
+    EvalResult,
+    ExtractResult,
+    HandoffResult,
+    HoverResult,
+    NavigateResult,
+    NewPageResult,
+    PageListResult,
+    PressResult,
+    ScreenshotResult,
+    SelectResult,
+    SessionInfo,
+    TypeResult,
+    UploadResult,
+    WaitForResponseResult,
+    WaitForSelectorResult,
+    WaitForUrlResult,
+)
+
+_DEFAULT_BASE_URL = "http://127.0.0.1:19315"
+
+
+def _base_url() -> str:
+    port = os.environ.get("AGENTMB_PORT", "19315")
+    return f"http://127.0.0.1:{port}"
+
+
+def _base_headers(api_token: Optional[str], operator: Optional[str] = None) -> dict:
+    """Headers that go on every request (no content-type — set per-method)."""
+    h: dict = {}
+    if api_token:
+        h["X-API-Token"] = api_token
+    if operator:
+        h["X-Operator"] = operator
+    return h
+
+
+def _headers(api_token: Optional[str]) -> dict:
+    """Legacy alias — not used for client default headers anymore."""
+    return _base_headers(api_token)
+
+
+# ---------------------------------------------------------------------------
+# Sync session handle
+# ---------------------------------------------------------------------------
+
+class Session:
+    """Handle for a single browser session (synchronous)."""
+
+    def __init__(self, session_id: str, client: "BrowserClient") -> None:
+        self.id = session_id
+        self._client = client
+
+    def navigate(self, url: str, wait_until: str = "load", purpose: Optional[str] = None, operator: Optional[str] = None) -> NavigateResult:
+        body: dict = {"url": url, "wait_until": wait_until}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/navigate", body, NavigateResult)
+
+    def click(self, selector: str, timeout_ms: int = 5000, purpose: Optional[str] = None, operator: Optional[str] = None) -> ActionResult:
+        body: dict = {"selector": selector, "timeout_ms": timeout_ms}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/click", body, ActionResult)
+
+    def fill(self, selector: str, value: str, purpose: Optional[str] = None, operator: Optional[str] = None) -> ActionResult:
+        body: dict = {"selector": selector, "value": value}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/fill", body, ActionResult)
+
+    def eval(self, expression: str, purpose: Optional[str] = None, operator: Optional[str] = None) -> EvalResult:
+        body: dict = {"expression": expression}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/eval", body, EvalResult)
+
+    def extract(self, selector: str, attribute: Optional[str] = None, purpose: Optional[str] = None, operator: Optional[str] = None) -> ExtractResult:
+        body: dict = {"selector": selector}
+        if attribute:
+            body["attribute"] = attribute
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/extract", body, ExtractResult)
+
+    def screenshot(self, format: str = "png", full_page: bool = False, purpose: Optional[str] = None, operator: Optional[str] = None) -> ScreenshotResult:
+        body: dict = {"format": format, "full_page": full_page}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/screenshot", body, ScreenshotResult)
+
+    def logs(self, tail: int = 20) -> List[AuditEntry]:
+        raw = self._client._get(f"/api/v1/sessions/{self.id}/logs?tail={tail}")
+        return [AuditEntry.model_validate(e) for e in raw]
+
+    def cdp_info(self) -> dict:
+        """Return CDP target info for this session's page."""
+        return self._client._get(f"/api/v1/sessions/{self.id}/cdp")
+
+    def cdp_send(self, method: str, params: Optional[dict] = None) -> dict:
+        """Send a single CDP command and return the result."""
+        return self._client._post(
+            f"/api/v1/sessions/{self.id}/cdp",
+            {"method": method, "params": params or {}},
+            dict,
+        )
+
+    def cdp_ws_url(self) -> dict:
+        """Return the browser-level CDP WebSocket URL for native DevTools connection."""
+        return self._client._get(f"/api/v1/sessions/{self.id}/cdp/ws")
+
+    # ------------------------------------------------------------------
+    # Trace export (T08)
+    # ------------------------------------------------------------------
+
+    def trace_start(self, screenshots: bool = True, snapshots: bool = True) -> dict:
+        """Start Playwright trace recording for this session."""
+        return self._client._post(
+            f"/api/v1/sessions/{self.id}/trace/start",
+            {"screenshots": screenshots, "snapshots": snapshots},
+            dict,
+        )
+
+    def trace_stop(self) -> "TraceResult":
+        """Stop trace recording and return the trace ZIP as base64."""
+        from .models import TraceResult as _T
+        return self._client._post(f"/api/v1/sessions/{self.id}/trace/stop", {}, _T)
+
+    # ------------------------------------------------------------------
+    # Network route mocks (T07)
+    # ------------------------------------------------------------------
+
+    def routes(self) -> "RouteListResult":
+        """List all active network route mocks for this session."""
+        from .models import RouteListResult as _R
+        return self._client._get(f"/api/v1/sessions/{self.id}/routes", _R)
+
+    def route(self, pattern: str, mock: Optional[dict] = None) -> dict:
+        """Register a network route mock (intercept requests matching pattern)."""
+        return self._client._post(
+            f"/api/v1/sessions/{self.id}/route",
+            {"pattern": pattern, "mock": mock or {}},
+            dict,
+        )
+
+    def unroute(self, pattern: str) -> None:
+        """Remove a network route mock."""
+        self._client._delete_with_body(f"/api/v1/sessions/{self.id}/route", {"pattern": pattern})
+
+    def type(self, selector: str, text: str, delay_ms: int = 0, purpose: Optional[str] = None, operator: Optional[str] = None) -> TypeResult:
+        body: dict = {"selector": selector, "text": text, "delay_ms": delay_ms}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/type", body, TypeResult)
+
+    def press(self, selector: str, key: str, purpose: Optional[str] = None, operator: Optional[str] = None) -> PressResult:
+        body: dict = {"selector": selector, "key": key}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/press", body, PressResult)
+
+    def select(self, selector: str, values: List[str], purpose: Optional[str] = None, operator: Optional[str] = None) -> SelectResult:
+        body: dict = {"selector": selector, "values": values}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/select", body, SelectResult)
+
+    def hover(self, selector: str, purpose: Optional[str] = None, operator: Optional[str] = None) -> HoverResult:
+        body: dict = {"selector": selector}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/hover", body, HoverResult)
+
+    def wait_for_selector(self, selector: str, state: str = "visible", timeout_ms: int = 5000, purpose: Optional[str] = None, operator: Optional[str] = None) -> WaitForSelectorResult:
+        body: dict = {"selector": selector, "state": state, "timeout_ms": timeout_ms}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/wait_for_selector", body, WaitForSelectorResult)
+
+    def wait_for_url(self, url_pattern: str, timeout_ms: int = 5000, purpose: Optional[str] = None, operator: Optional[str] = None) -> WaitForUrlResult:
+        body: dict = {"url_pattern": url_pattern, "timeout_ms": timeout_ms}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/wait_for_url", body, WaitForUrlResult)
+
+    def wait_for_response(self, url_pattern: str, timeout_ms: int = 10000, trigger: Optional[dict] = None, purpose: Optional[str] = None, operator: Optional[str] = None) -> WaitForResponseResult:
+        body: dict = {"url_pattern": url_pattern, "timeout_ms": timeout_ms}
+        if trigger: body["trigger"] = trigger
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/wait_for_response", body, WaitForResponseResult)
+
+    def upload(self, selector: str, file_path: str, mime_type: str = "application/octet-stream", purpose: Optional[str] = None, operator: Optional[str] = None) -> UploadResult:
+        import base64 as _b64
+        import os as _os
+        with open(file_path, "rb") as f:
+            content = _b64.b64encode(f.read()).decode()
+        body: dict = {"selector": selector, "content": content, "filename": _os.path.basename(file_path), "mime_type": mime_type}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/upload", body, UploadResult)
+
+    def download(self, selector: str, timeout_ms: int = 30000, purpose: Optional[str] = None, operator: Optional[str] = None) -> DownloadResult:
+        body: dict = {"selector": selector, "timeout_ms": timeout_ms}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return self._client._post(f"/api/v1/sessions/{self.id}/download", body, DownloadResult)
+
+    # ------------------------------------------------------------------
+    # Multi-page management (T03)
+    # ------------------------------------------------------------------
+
+    def pages(self) -> PageListResult:
+        """List all open pages in this session."""
+        return self._client._get(f"/api/v1/sessions/{self.id}/pages", PageListResult)
+
+    def new_page(self) -> NewPageResult:
+        """Open a new tab/page in this session."""
+        return self._client._post(f"/api/v1/sessions/{self.id}/pages", {}, NewPageResult)
+
+    def switch_page(self, page_id: str) -> dict:
+        """Make the given page_id the active target for actions."""
+        return self._client._post(f"/api/v1/sessions/{self.id}/pages/switch", {"page_id": page_id}, dict)
+
+    def close_page(self, page_id: str) -> None:
+        """Close a specific page by page_id."""
+        self._client._delete(f"/api/v1/sessions/{self.id}/pages/{page_id}")
+
+    def switch_mode(self, mode: str) -> None:
+        """Switch between 'headless' and 'headed' mode."""
+        self._client._post(
+            f"/api/v1/sessions/{self.id}/mode",
+            {"mode": mode},
+            dict,
+        )
+
+    def handoff_start(self) -> HandoffResult:
+        """Switch to headed mode for human login. Call handoff_complete() when done."""
+        return self._client._post(
+            f"/api/v1/sessions/{self.id}/handoff/start",
+            {},
+            HandoffResult,
+        )
+
+    def handoff_complete(self) -> HandoffResult:
+        """Return session to headless mode after human login is complete."""
+        return self._client._post(
+            f"/api/v1/sessions/{self.id}/handoff/complete",
+            {},
+            HandoffResult,
+        )
+
+    def set_policy(self, profile: str, allow_sensitive_actions: Optional[bool] = None) -> "PolicyInfo":
+        """Override the safety execution policy for this session (r06-c02).
+
+        Args:
+            profile: 'safe' | 'permissive' | 'disabled'
+            allow_sensitive_actions: Explicitly enable/disable sensitive action guardrail.
+        """
+        from .models import PolicyInfo
+        body: dict = {"profile": profile}
+        if allow_sensitive_actions is not None:
+            body["allow_sensitive_actions"] = allow_sensitive_actions
+        return self._client._post(f"/api/v1/sessions/{self.id}/policy", body, PolicyInfo)
+
+    def get_policy(self) -> "PolicyInfo":
+        """Get the current safety execution policy for this session."""
+        from .models import PolicyInfo
+        return self._client._get(f"/api/v1/sessions/{self.id}/policy", PolicyInfo)
+
+    def close(self) -> None:
+        self._client._delete(f"/api/v1/sessions/{self.id}")
+
+    def __enter__(self) -> "Session":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Async session handle
+# ---------------------------------------------------------------------------
+
+class AsyncSession:
+    """Handle for a single browser session (async)."""
+
+    def __init__(self, session_id: str, client: "AsyncBrowserClient") -> None:
+        self.id = session_id
+        self._client = client
+
+    async def navigate(self, url: str, wait_until: str = "load", purpose: Optional[str] = None, operator: Optional[str] = None) -> NavigateResult:
+        body: dict = {"url": url, "wait_until": wait_until}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/navigate", body, NavigateResult)
+
+    async def click(self, selector: str, timeout_ms: int = 5000, purpose: Optional[str] = None, operator: Optional[str] = None) -> ActionResult:
+        body: dict = {"selector": selector, "timeout_ms": timeout_ms}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/click", body, ActionResult)
+
+    async def fill(self, selector: str, value: str, purpose: Optional[str] = None, operator: Optional[str] = None) -> ActionResult:
+        body: dict = {"selector": selector, "value": value}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/fill", body, ActionResult)
+
+    async def eval(self, expression: str, purpose: Optional[str] = None, operator: Optional[str] = None) -> EvalResult:
+        body: dict = {"expression": expression}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/eval", body, EvalResult)
+
+    async def extract(self, selector: str, attribute: Optional[str] = None, purpose: Optional[str] = None, operator: Optional[str] = None) -> ExtractResult:
+        body: dict = {"selector": selector}
+        if attribute:
+            body["attribute"] = attribute
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/extract", body, ExtractResult)
+
+    async def screenshot(self, format: str = "png", full_page: bool = False, purpose: Optional[str] = None, operator: Optional[str] = None) -> ScreenshotResult:
+        body: dict = {"format": format, "full_page": full_page}
+        if purpose:
+            body["purpose"] = purpose
+        if operator:
+            body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/screenshot", body, ScreenshotResult)
+
+    async def logs(self, tail: int = 20) -> List[AuditEntry]:
+        raw = await self._client._get(f"/api/v1/sessions/{self.id}/logs?tail={tail}")
+        return [AuditEntry.model_validate(e) for e in raw]
+
+    async def cdp_info(self) -> dict:
+        """Return CDP target info for this session's page."""
+        return await self._client._get(f"/api/v1/sessions/{self.id}/cdp")
+
+    async def cdp_send(self, method: str, params: Optional[dict] = None) -> dict:
+        """Send a single CDP command and return the result."""
+        return await self._client._post(
+            f"/api/v1/sessions/{self.id}/cdp",
+            {"method": method, "params": params or {}},
+            dict,
+        )
+
+    async def cdp_ws_url(self) -> dict:
+        """Return the browser-level CDP WebSocket URL for native DevTools connection."""
+        return await self._client._get(f"/api/v1/sessions/{self.id}/cdp/ws")
+
+    # ------------------------------------------------------------------
+    # Trace export (T08)
+    # ------------------------------------------------------------------
+
+    async def trace_start(self, screenshots: bool = True, snapshots: bool = True) -> dict:
+        """Start Playwright trace recording for this session."""
+        return await self._client._post(
+            f"/api/v1/sessions/{self.id}/trace/start",
+            {"screenshots": screenshots, "snapshots": snapshots},
+            dict,
+        )
+
+    async def trace_stop(self) -> "TraceResult":
+        """Stop trace recording and return the trace ZIP as base64."""
+        from .models import TraceResult as _T
+        return await self._client._post(f"/api/v1/sessions/{self.id}/trace/stop", {}, _T)
+
+    # ------------------------------------------------------------------
+    # Network route mocks (T07)
+    # ------------------------------------------------------------------
+
+    async def routes(self) -> "RouteListResult":
+        """List all active network route mocks for this session."""
+        from .models import RouteListResult as _R
+        return await self._client._get(f"/api/v1/sessions/{self.id}/routes", _R)
+
+    async def route(self, pattern: str, mock: Optional[dict] = None) -> dict:
+        """Register a network route mock."""
+        return await self._client._post(
+            f"/api/v1/sessions/{self.id}/route",
+            {"pattern": pattern, "mock": mock or {}},
+            dict,
+        )
+
+    async def unroute(self, pattern: str) -> None:
+        """Remove a network route mock."""
+        await self._client._delete_with_body(f"/api/v1/sessions/{self.id}/route", {"pattern": pattern})
+
+    async def type(self, selector: str, text: str, delay_ms: int = 0, purpose: Optional[str] = None, operator: Optional[str] = None) -> TypeResult:
+        body: dict = {"selector": selector, "text": text, "delay_ms": delay_ms}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/type", body, TypeResult)
+
+    async def press(self, selector: str, key: str, purpose: Optional[str] = None, operator: Optional[str] = None) -> PressResult:
+        body: dict = {"selector": selector, "key": key}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/press", body, PressResult)
+
+    async def select(self, selector: str, values: List[str], purpose: Optional[str] = None, operator: Optional[str] = None) -> SelectResult:
+        body: dict = {"selector": selector, "values": values}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/select", body, SelectResult)
+
+    async def hover(self, selector: str, purpose: Optional[str] = None, operator: Optional[str] = None) -> HoverResult:
+        body: dict = {"selector": selector}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/hover", body, HoverResult)
+
+    async def wait_for_selector(self, selector: str, state: str = "visible", timeout_ms: int = 5000, purpose: Optional[str] = None, operator: Optional[str] = None) -> WaitForSelectorResult:
+        body: dict = {"selector": selector, "state": state, "timeout_ms": timeout_ms}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/wait_for_selector", body, WaitForSelectorResult)
+
+    async def wait_for_url(self, url_pattern: str, timeout_ms: int = 5000, purpose: Optional[str] = None, operator: Optional[str] = None) -> WaitForUrlResult:
+        body: dict = {"url_pattern": url_pattern, "timeout_ms": timeout_ms}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/wait_for_url", body, WaitForUrlResult)
+
+    async def wait_for_response(self, url_pattern: str, timeout_ms: int = 10000, trigger: Optional[dict] = None, purpose: Optional[str] = None, operator: Optional[str] = None) -> WaitForResponseResult:
+        body: dict = {"url_pattern": url_pattern, "timeout_ms": timeout_ms}
+        if trigger: body["trigger"] = trigger
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/wait_for_response", body, WaitForResponseResult)
+
+    async def upload(self, selector: str, file_path: str, mime_type: str = "application/octet-stream", purpose: Optional[str] = None, operator: Optional[str] = None) -> UploadResult:
+        import base64 as _b64
+        import os as _os
+        import asyncio as _asyncio
+        def _read() -> str:
+            with open(file_path, "rb") as f:
+                return _b64.b64encode(f.read()).decode()
+        content = await _asyncio.to_thread(_read)
+        body: dict = {"selector": selector, "content": content, "filename": _os.path.basename(file_path), "mime_type": mime_type}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/upload", body, UploadResult)
+
+    async def download(self, selector: str, timeout_ms: int = 30000, purpose: Optional[str] = None, operator: Optional[str] = None) -> DownloadResult:
+        body: dict = {"selector": selector, "timeout_ms": timeout_ms}
+        if purpose: body["purpose"] = purpose
+        if operator: body["operator"] = operator
+        return await self._client._post(f"/api/v1/sessions/{self.id}/download", body, DownloadResult)
+
+    # ------------------------------------------------------------------
+    # Multi-page management (T03)
+    # ------------------------------------------------------------------
+
+    async def pages(self) -> PageListResult:
+        return await self._client._get(f"/api/v1/sessions/{self.id}/pages", PageListResult)
+
+    async def new_page(self) -> NewPageResult:
+        return await self._client._post(f"/api/v1/sessions/{self.id}/pages", {}, NewPageResult)
+
+    async def switch_page(self, page_id: str) -> dict:
+        return await self._client._post(f"/api/v1/sessions/{self.id}/pages/switch", {"page_id": page_id}, dict)
+
+    async def close_page(self, page_id: str) -> None:
+        await self._client._delete(f"/api/v1/sessions/{self.id}/pages/{page_id}")
+
+    async def handoff_start(self) -> HandoffResult:
+        """Switch to headed mode for human login. Call handoff_complete() when done."""
+        return await self._client._post(
+            f"/api/v1/sessions/{self.id}/handoff/start",
+            {},
+            HandoffResult,
+        )
+
+    async def handoff_complete(self) -> HandoffResult:
+        """Return session to headless mode after human login is complete."""
+        return await self._client._post(
+            f"/api/v1/sessions/{self.id}/handoff/complete",
+            {},
+            HandoffResult,
+        )
+
+    async def set_policy(self, profile: str, allow_sensitive_actions: Optional[bool] = None) -> "PolicyInfo":
+        """Override the safety execution policy for this session."""
+        from .models import PolicyInfo
+        body: dict = {"profile": profile}
+        if allow_sensitive_actions is not None:
+            body["allow_sensitive_actions"] = allow_sensitive_actions
+        return await self._client._post(f"/api/v1/sessions/{self.id}/policy", body, PolicyInfo)
+
+    async def get_policy(self) -> "PolicyInfo":
+        """Get the current safety execution policy for this session."""
+        from .models import PolicyInfo
+        return await self._client._get(f"/api/v1/sessions/{self.id}/policy", PolicyInfo)
+
+    async def close(self) -> None:
+        await self._client._delete(f"/api/v1/sessions/{self.id}")
+
+    async def __aenter__(self) -> "AsyncSession":
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self.close()
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+class BrowserClient:
+    """Synchronous agentmb client.
+
+    Usage::
+
+        client = BrowserClient()
+        with client.sessions.create(profile="myprofile") as sess:
+            sess.navigate("https://example.com")
+            shot = sess.screenshot()
+            shot.save("/tmp/out.png")
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_token: Optional[str] = None,
+        timeout: float = 30.0,
+        operator: Optional[str] = None,
+    ) -> None:
+        self._base_url = base_url or _base_url()
+        self._api_token = api_token or os.environ.get("AGENTMB_API_TOKEN")
+        self._operator = operator or os.environ.get("AGENTMB_OPERATOR")
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            headers=_base_headers(self._api_token, self._operator),
+            timeout=timeout,
+        )
+        self.sessions = _SyncSessionManager(self)
+
+    def health(self) -> DaemonStatus:
+        return self._get("/health", DaemonStatus)
+
+    def _post(self, path: str, body: dict, model=None):
+        resp = self._http.post(path, json=body, headers={"content-type": "application/json"})
+        resp.raise_for_status()
+        data = resp.json()
+        if model and model is not dict:
+            return model.model_validate(data)
+        return data
+
+    def _get(self, path: str, model=None):
+        resp = self._http.get(path)
+        resp.raise_for_status()
+        data = resp.json()
+        if model:
+            return model.model_validate(data)
+        return data
+
+    def _delete(self, path: str) -> None:
+        resp = self._http.delete(path)
+        if resp.status_code not in (200, 204, 404):
+            resp.raise_for_status()
+
+    def _delete_with_body(self, path: str, body: dict) -> None:
+        resp = self._http.request("DELETE", path, json=body, headers={"content-type": "application/json"})
+        if resp.status_code not in (200, 204, 404):
+            resp.raise_for_status()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "BrowserClient":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+
+class _SyncSessionManager:
+    def __init__(self, client: BrowserClient) -> None:
+        self._client = client
+
+    def create(
+        self,
+        profile: str = "default",
+        headless: bool = True,
+        agent_id: Optional[str] = None,
+        accept_downloads: bool = False,
+    ) -> Session:
+        info = self._client._post(
+            "/api/v1/sessions",
+            {"profile": profile, "headless": headless, "agent_id": agent_id, "accept_downloads": accept_downloads},
+            SessionInfo,
+        )
+        return Session(info.session_id, self._client)
+
+    def list(self) -> List[SessionInfo]:
+        raw = self._client._get("/api/v1/sessions")
+        return [SessionInfo.model_validate(s) for s in raw]
+
+    def get(self, session_id: str) -> SessionInfo:
+        return self._client._get(f"/api/v1/sessions/{session_id}", SessionInfo)
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+class AsyncBrowserClient:
+    """Async agentmb client (for use with asyncio / LangGraph).
+
+    Usage::
+
+        async with AsyncBrowserClient() as client:
+            async with client.sessions.create() as sess:
+                await sess.navigate("https://example.com")
+                result = await sess.eval("document.title")
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_token: Optional[str] = None,
+        timeout: float = 30.0,
+        operator: Optional[str] = None,
+    ) -> None:
+        self._base_url = base_url or _base_url()
+        self._api_token = api_token or os.environ.get("AGENTMB_API_TOKEN")
+        self._operator = operator or os.environ.get("AGENTMB_OPERATOR")
+        self._timeout = timeout
+        self._http: Optional[httpx.AsyncClient] = None
+        self.sessions = _AsyncSessionManager(self)
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        if self._http is None:
+            self._http = httpx.AsyncClient(
+                base_url=self._base_url,
+                headers=_base_headers(self._api_token, self._operator),
+                timeout=self._timeout,
+            )
+        return self._http
+
+    async def health(self) -> DaemonStatus:
+        return await self._get("/health", DaemonStatus)
+
+    async def _post(self, path: str, body: dict, model=None):
+        client = await self._ensure_client()
+        resp = await client.post(path, json=body, headers={"content-type": "application/json"})
+        resp.raise_for_status()
+        data = resp.json()
+        if model and model is not dict:
+            return model.model_validate(data)
+        return data
+
+    async def _get(self, path: str, model=None):
+        client = await self._ensure_client()
+        resp = await client.get(path)
+        resp.raise_for_status()
+        data = resp.json()
+        if model:
+            return model.model_validate(data)
+        return data
+
+    async def _delete(self, path: str) -> None:
+        client = await self._ensure_client()
+        resp = await client.delete(path)
+        if resp.status_code not in (200, 204, 404):
+            resp.raise_for_status()
+
+    async def _delete_with_body(self, path: str, body: dict) -> None:
+        client = await self._ensure_client()
+        resp = await client.request("DELETE", path, json=body, headers={"content-type": "application/json"})
+        if resp.status_code not in (200, 204, 404):
+            resp.raise_for_status()
+
+    async def close(self) -> None:
+        if self._http:
+            await self._http.aclose()
+            self._http = None
+
+    async def __aenter__(self) -> "AsyncBrowserClient":
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self.close()
+
+
+class _AsyncSessionManager:
+    def __init__(self, client: AsyncBrowserClient) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        profile: str = "default",
+        headless: bool = True,
+        agent_id: Optional[str] = None,
+        accept_downloads: bool = False,
+    ) -> AsyncSession:
+        info = await self._client._post(
+            "/api/v1/sessions",
+            {"profile": profile, "headless": headless, "agent_id": agent_id, "accept_downloads": accept_downloads},
+            SessionInfo,
+        )
+        return AsyncSession(info.session_id, self._client)
+
+    async def list(self) -> List[SessionInfo]:
+        raw = await self._client._get("/api/v1/sessions")
+        return [SessionInfo.model_validate(s) for s in raw]
+
+    async def get(self, session_id: str) -> SessionInfo:
+        return await self._client._get(f"/api/v1/sessions/{session_id}", SessionInfo)

agentmb-0.1.0/agentmb/models.py

@@ -0,0 +1,222 @@
+"""Pydantic v2 models for agentmb SDK responses."""
+
+from __future__ import annotations
+
+import base64
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class SessionInfo(BaseModel):
+    session_id: str
+    profile: str
+    headless: bool
+    created_at: str
+    state: str = "live"  # 'live' | 'zombie'
+    agent_id: Optional[str] = None
+    accept_downloads: bool = False
+
+
+class NavigateResult(BaseModel):
+    status: str
+    url: str
+    title: str
+    duration_ms: int
+
+
+class ActionResult(BaseModel):
+    status: str
+    selector: Optional[str] = None
+    duration_ms: int
+
+
+class EvalResult(BaseModel):
+    status: str
+    result: Any
+    duration_ms: int
+
+
+class ScreenshotResult(BaseModel):
+    status: str
+    data: str  # base64-encoded PNG or JPEG
+    format: str
+    duration_ms: int
+
+    def to_bytes(self) -> bytes:
+        """Decode base64 data to raw bytes."""
+        return base64.b64decode(self.data)
+
+    def save(self, path: str) -> None:
+        """Write screenshot bytes to a file."""
+        with open(path, "wb") as f:
+            f.write(self.to_bytes())
+
+
+class ExtractResult(BaseModel):
+    status: str
+    selector: str
+    items: List[Dict[str, Any]]
+    count: int
+    duration_ms: int
+
+
+class TypeResult(BaseModel):
+    status: str
+    selector: str
+    duration_ms: int
+
+
+class PressResult(BaseModel):
+    status: str
+    selector: str
+    key: str
+    duration_ms: int
+
+
+class SelectResult(BaseModel):
+    status: str
+    selector: str
+    selected: List[str]
+    duration_ms: int
+
+
+class HoverResult(BaseModel):
+    status: str
+    selector: str
+    duration_ms: int
+
+
+class WaitForSelectorResult(BaseModel):
+    status: str
+    selector: str
+    state: str
+    duration_ms: int
+
+
+class WaitForUrlResult(BaseModel):
+    status: str
+    url: str
+    duration_ms: int
+
+
+class WaitForResponseResult(BaseModel):
+    status: str
+    url: str
+    status_code: int
+    duration_ms: int
+
+
+class UploadResult(BaseModel):
+    status: str
+    selector: str
+    filename: str
+    size_bytes: int
+    duration_ms: int
+
+
+class PageInfo(BaseModel):
+    page_id: str
+    url: str
+    active: bool
+
+
+class PageListResult(BaseModel):
+    session_id: str
+    pages: List[PageInfo]
+
+
+class NewPageResult(BaseModel):
+    session_id: str
+    page_id: str
+    url: str
+
+
+class RouteMock(BaseModel):
+    status: Optional[int] = 200
+    headers: Optional[Dict[str, str]] = None
+    body: Optional[str] = None
+    content_type: Optional[str] = None
+
+
+class RouteEntry(BaseModel):
+    pattern: str
+    mock: RouteMock
+
+
+class RouteListResult(BaseModel):
+    session_id: str
+    routes: List[RouteEntry]
+
+
+class DownloadResult(BaseModel):
+    status: str
+    filename: str
+    data: str  # base64-encoded file content
+    size_bytes: int
+    duration_ms: int
+
+    def to_bytes(self) -> bytes:
+        """Decode base64 data to raw bytes."""
+        return base64.b64decode(self.data)
+
+    def save(self, path: str) -> None:
+        """Write downloaded file bytes to a file."""
+        with open(path, "wb") as f:
+            f.write(self.to_bytes())
+
+
+class TraceResult(BaseModel):
+    session_id: str
+    data: str  # base64-encoded ZIP
+    format: str  # always 'zip'
+    size_bytes: int
+
+    def to_bytes(self) -> bytes:
+        return base64.b64decode(self.data)
+
+    def save(self, path: str) -> None:
+        with open(path, "wb") as f:
+            f.write(self.to_bytes())
+
+
+class AuditEntry(BaseModel):
+    ts: Optional[str] = None
+    v: Optional[int] = None
+    session_id: Optional[str] = None
+    action_id: Optional[str] = None
+    type: str
+    action: Optional[str] = None
+    url: Optional[str] = None
+    selector: Optional[str] = None
+    params: Optional[Dict[str, Any]] = None
+    result: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    purpose: Optional[str] = None    # why this action is being taken
+    operator: Optional[str] = None   # who/what is invoking
+
+
+class HandoffResult(BaseModel):
+    session_id: str
+    mode: str  # 'headed' | 'headless'
+    message: str
+
+
+class DaemonStatus(BaseModel):
+    status: str
+    version: str
+    uptime_s: int
+    sessions_active: int
+
+
+
+class PolicyInfo(BaseModel):
+    """Current safety policy for a session (r06-c02)."""
+    session_id: str
+    profile: str  # 'safe' | 'permissive' | 'disabled'
+    domain_min_interval_ms: int
+    jitter_ms: List[int]
+    cooldown_after_error_ms: int
+    max_retries_per_domain: int
+    max_actions_per_minute: int
+    allow_sensitive_actions: bool

agentmb-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentmb"
+version = "0.1.0"
+description = "Python SDK for agentmb — local Chromium runtime daemon for AI agents"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["agentmb"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"