agentping 0.1.0__tar.gz

agentping-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment files
+.env
+.env.local
+.env.production
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node
+node_modules/
+.next/
+
+# Claude
+.claude/

agentping-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AgentRelay
+
+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.

agentping-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: agentping
+Version: 0.1.0
+Summary: MCP server that bridges AI coding agents to developers via AgentPing
+Author: Saadman Soor
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,approval,claude,copilot,cursor,mcp,notification
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pydantic>=2.4.0
+Requires-Dist: websockets>=11.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentPing — MCP Server
+
+Thin MCP server that bridges any MCP-compatible AI coding agent (Copilot, Cursor, Claude Code, Cline, Aider, Windsurf) to you via the AgentPing cloud relay.
+
+## Install
+
+```bash
+pip install agentping
+```
+
+## Setup
+
+```bash
+agentping setup
+```
+
+Paste your API key when prompted. Get your key at [app.agentping.dev](https://app.agentping.dev).
+
+## IDE Configuration
+
+Add to your VS Code / Cursor MCP config (`.vscode/mcp.json` or `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "agentping": {
+      "command": "agentping",
+      "env": {
+        "AGENTPING_API_KEY": "sk-ap_live_..."
+      }
+    }
+  }
+}
+```
+
+## MCP Tools
+
+| Tool | Purpose | Blocks? |
+|------|---------|---------|
+| `bridge_ping` | Test connectivity | No |
+| `bridge_send_approval` | Ask dev to approve/reject | No |
+| `bridge_ask_question` | Free-form question | No |
+| `bridge_wait_response` | Block until reply | Yes |
+| `bridge_check_response` | Non-blocking poll | No |
+| `bridge_approve_and_wait` | Send + wait combo | Yes |
+| `bridge_send_update` | Progress notification | No |
+| `bridge_task_complete` | Task finished notification | No |
+| `bridge_list_pending` | List unanswered requests | No |
+
+## License
+
+MIT

agentping-0.1.0/README.md

@@ -0,0 +1,52 @@
+# AgentPing — MCP Server
+
+Thin MCP server that bridges any MCP-compatible AI coding agent (Copilot, Cursor, Claude Code, Cline, Aider, Windsurf) to you via the AgentPing cloud relay.
+
+## Install
+
+```bash
+pip install agentping
+```
+
+## Setup
+
+```bash
+agentping setup
+```
+
+Paste your API key when prompted. Get your key at [app.agentping.dev](https://app.agentping.dev).
+
+## IDE Configuration
+
+Add to your VS Code / Cursor MCP config (`.vscode/mcp.json` or `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "agentping": {
+      "command": "agentping",
+      "env": {
+        "AGENTPING_API_KEY": "sk-ap_live_..."
+      }
+    }
+  }
+}
+```
+
+## MCP Tools
+
+| Tool | Purpose | Blocks? |
+|------|---------|---------|
+| `bridge_ping` | Test connectivity | No |
+| `bridge_send_approval` | Ask dev to approve/reject | No |
+| `bridge_ask_question` | Free-form question | No |
+| `bridge_wait_response` | Block until reply | Yes |
+| `bridge_check_response` | Non-blocking poll | No |
+| `bridge_approve_and_wait` | Send + wait combo | Yes |
+| `bridge_send_update` | Progress notification | No |
+| `bridge_task_complete` | Task finished notification | No |
+| `bridge_list_pending` | List unanswered requests | No |
+
+## License
+
+MIT

agentping-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentping"
+version = "0.1.0"
+description = "MCP server that bridges AI coding agents to developers via AgentPing"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Saadman Soor" }]
+keywords = ["mcp", "ai", "agent", "copilot", "cursor", "claude", "notification", "approval"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "websockets>=11.0",
+    "pydantic>=2.4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.scripts]
+agentping = "agentping.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentping"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

agentping-0.1.0/src/agentping/__init__.py

@@ -0,0 +1,3 @@
+"""AgentPing MCP server — bridges AI coding agents to developers."""
+
+__version__ = "0.1.0"

agentping-0.1.0/src/agentping/cli.py

@@ -0,0 +1,101 @@
+"""CLI entry point — setup wizard and MCP server runner."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from agentping.config import DEFAULT_RELAY_URL, get_api_key, load_config, save_config
+
+
+def setup() -> None:
+    """Interactive setup wizard."""
+    print("=" * 50)
+    print("  AgentPing Setup")
+    print("=" * 50)
+    print()
+    print("Get your API key at: https://app.agentping.dev/settings")
+    print()
+
+    existing = load_config()
+
+    # API Key
+    current_key = existing.get("api_key", "")
+    masked = f"{current_key[:8]}...{current_key[-4:]}" if len(current_key) > 12 else "(not set)"
+    api_key = input(f"API Key [{masked}]: ").strip()
+    if not api_key:
+        api_key = current_key
+
+    if not api_key:
+        print("\nError: API key is required.")
+        sys.exit(1)
+
+    if not api_key.startswith("sk-ap_"):
+        print("\nWarning: Key doesn't start with 'sk-ap_'. Make sure you copied the full key.")
+
+    # Agent name
+    current_name = existing.get("agent_name", "")
+    agent_name = input(f"Agent name [{current_name or 'auto-detect'}]: ").strip()
+    if not agent_name:
+        agent_name = current_name
+
+    # Relay URL
+    current_url = existing.get("relay_url", DEFAULT_RELAY_URL)
+    relay_url = input(f"Relay URL [{current_url}]: ").strip()
+    if not relay_url:
+        relay_url = current_url
+
+    # Save
+    config = {
+        "api_key": api_key,
+        "agent_name": agent_name,
+        "relay_url": relay_url,
+    }
+    save_config(config)
+
+    print()
+    print("Configuration saved to ~/.agentping/config.json")
+    print()
+    print("Next steps:")
+    print("  1. Add AgentPing to your IDE's MCP config:")
+    print()
+
+    mcp_config = {
+        "mcpServers": {
+            "agentping": {
+                "command": "agentping",
+                "env": {
+                    "AGENTPING_API_KEY": api_key,
+                },
+            }
+        }
+    }
+    print(f"     {json.dumps(mcp_config, indent=2)}")
+    print()
+    print("  2. Restart your IDE / MCP host.")
+    print("  3. The agent can now use bridge_* tools to reach you!")
+    print()
+
+
+def main() -> None:
+    """CLI entry point."""
+    if len(sys.argv) > 1 and sys.argv[1] == "setup":
+        setup()
+        return
+
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help", "help"):
+        print("Usage:")
+        print("  agentping          Run the MCP server (for IDE integration)")
+        print("  agentping setup    Configure API key and settings")
+        print("  agentping help     Show this help message")
+        return
+
+    # Default: run as MCP server
+    api_key = get_api_key()
+    if not api_key:
+        print("Error: No API key configured.")
+        print("Run `agentping setup` or set AGENTPING_API_KEY env var.")
+        sys.exit(1)
+
+    from agentping.server import main as server_main
+    server_main()

agentping-0.1.0/src/agentping/config.py

@@ -0,0 +1,57 @@
+"""Configuration for the AgentPing MCP server."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+_CONFIG_DIR = Path.home() / ".agentping"
+_CONFIG_FILE = _CONFIG_DIR / "config.json"
+
+DEFAULT_RELAY_URL = "wss://relay.agentping.dev/ws"
+
+
+def get_api_key() -> str:
+    """Get API key from env var or config file."""
+    key = os.environ.get("AGENTPING_API_KEY", "")
+    if key:
+        return key
+    config = load_config()
+    return config.get("api_key", "")
+
+
+def get_relay_url() -> str:
+    """Get relay WebSocket URL from env var or config file."""
+    url = os.environ.get("AGENTPING_RELAY_URL", "")
+    if url:
+        return url
+    config = load_config()
+    return config.get("relay_url", DEFAULT_RELAY_URL)
+
+
+def get_agent_name() -> str:
+    """Get agent name from env var or config file."""
+    name = os.environ.get("AGENTPING_AGENT_NAME", "")
+    if name:
+        return name
+    config = load_config()
+    return config.get("agent_name", "unknown")
+
+
+def load_config() -> dict:
+    """Load config from ~/.agentping/config.json."""
+    if not _CONFIG_FILE.exists():
+        return {}
+    try:
+        return json.loads(_CONFIG_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_config(config: dict) -> None:
+    """Save config to ~/.agentping/config.json."""
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    _CONFIG_FILE.write_text(json.dumps(config, indent=2))
+    # Restrict permissions — config contains API key
+    _CONFIG_FILE.chmod(0o600)

agentping-0.1.0/src/agentping/server.py

@@ -0,0 +1,152 @@
+"""MCP server exposing 9 bridge tools via the AgentPing relay."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, List, Optional
+
+from mcp.server.fastmcp import FastMCP
+from agentping.config import get_agent_name, get_api_key, get_relay_url
+from agentping.ws_client import RelayClient
+
+logger = logging.getLogger("agentping")
+mcp = FastMCP("AgentPing", description="Bridge between AI coding agents and developers")
+_client: Optional[RelayClient] = None
+
+
+async def _get_client() -> RelayClient:
+    global _client
+    if _client is None:
+        api_key = get_api_key()
+        if not api_key:
+            raise RuntimeError("No API key. Run `agentping setup` or set AGENTPING_API_KEY.")
+        _client = RelayClient(get_relay_url(), api_key, get_agent_name())
+        await _client.connect()
+    return _client
+
+
+def _err(msg: str) -> Dict[str, Any]:
+    return {"status": "error", "error": msg}
+
+
+async def _send(msg_type: str, title: str, **kwargs) -> Dict[str, Any]:
+    """Helper: connect, send message, return result."""
+    try:
+        client = await _get_client()
+        if not await client.wait_connected(timeout=10.0):
+            return _err("Not connected to relay")
+        mid = await client.send_message(message_type=msg_type, title=title, **kwargs)
+        if mid:
+            return {"status": "sent", "request_id": mid} if msg_type in ("approval", "question") \
+                else {"status": "sent", "message_id": mid}
+        return _err(f"Failed to send {msg_type} (no ack)")
+    except Exception as e:
+        return _err(str(e))
+
+
+@mcp.tool()
+async def bridge_ping() -> Dict[str, Any]:
+    """Test connectivity to the AgentPing relay service."""
+    try:
+        client = await _get_client()
+        if await client.wait_connected(timeout=10.0):
+            return {"status": "connected", "relay": client._relay_url,
+                    "connection_id": client._connection_id}
+        return _err("Could not connect to relay within 10 seconds")
+    except Exception as e:
+        return _err(str(e))
+
+
+@mcp.tool()
+async def bridge_send_approval(
+    title: str, description: str = "", options: Optional[List[str]] = None,
+    code_context: str = "", urgency: str = "medium",
+) -> Dict[str, Any]:
+    """Send an approval request to the developer. Returns a request_id for polling."""
+    return await _send("approval", title, description=description or None,
+                       code_context=code_context or None, options=options, urgency=urgency)
+
+
+@mcp.tool()
+async def bridge_ask_question(
+    question: str, context: str = "", options: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Ask the developer a free-form question. Returns a request_id for polling."""
+    return await _send("question", question, description=context or None, options=options)
+
+
+@mcp.tool()
+async def bridge_wait_response(request_id: str, timeout: int = 300) -> Dict[str, Any]:
+    """Block until the developer responds to a request."""
+    try:
+        client = await _get_client()
+        result = await client.wait_response(request_id, timeout=float(timeout))
+        if result.get("has_response"):
+            return {"status": result["status"], "response": result.get("response_text"),
+                    "responder": "developer"}
+        return {"status": "timeout", "response": None, "responder": None}
+    except Exception as e:
+        return _err(str(e))
+
+
+@mcp.tool()
+async def bridge_check_response(request_id: str) -> Dict[str, Any]:
+    """Non-blocking check if the developer has responded."""
+    try:
+        client = await _get_client()
+        result = await client.check_response(request_id)
+        if result is None:
+            return _err("Failed to check response (relay timeout)")
+        return {"has_response": result.get("has_response", False),
+                "status": result.get("status", "pending"),
+                "response": result.get("response_text")}
+    except Exception as e:
+        return _err(str(e))
+
+
+@mcp.tool()
+async def bridge_approve_and_wait(
+    title: str, description: str = "", options: Optional[List[str]] = None,
+    code_context: str = "", urgency: str = "medium", timeout: int = 300,
+) -> Dict[str, Any]:
+    """Send an approval request and wait for response (combo of send + wait)."""
+    result = await bridge_send_approval(title, description, options, code_context, urgency)
+    if result.get("status") == "error":
+        return result
+    return await bridge_wait_response(result["request_id"], timeout)
+
+
+@mcp.tool()
+async def bridge_send_update(
+    title: str, details: str = "", progress_pct: Optional[int] = None, status: str = "in_progress",
+) -> Dict[str, Any]:
+    """Send a progress update to the developer (fire-and-forget, no response needed)."""
+    return await _send("update", title, description=details or None, progress_pct=progress_pct,
+                       urgency="low", metadata={"status_label": status} if status else None)
+
+
+@mcp.tool()
+async def bridge_task_complete(
+    title: str, summary: str = "", files_changed: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Notify the developer that a task is complete (fire-and-forget)."""
+    return await _send("task_complete", title, description=summary or None,
+                       files_changed=files_changed, urgency="low")
+
+
+@mcp.tool()
+async def bridge_list_pending() -> Dict[str, Any]:
+    """List all unanswered requests waiting for developer response."""
+    try:
+        client = await _get_client()
+        if not await client.wait_connected(timeout=10.0):
+            return _err("Not connected to relay")
+        msgs = await client.list_pending()
+        return {"status": "ok", "pending": msgs, "count": len(msgs)}
+    except Exception as e:
+        return _err(str(e))
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(name)s: %(message)s")
+    mcp.run()

agentping-0.1.0/src/agentping/ws_client.py

@@ -0,0 +1,203 @@
+"""WebSocket client with auto-reconnect, heartbeat, and message queuing."""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import random
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional
+from uuid import uuid4
+
+import websockets
+from websockets.exceptions import ConnectionClosed
+
+logger = logging.getLogger("agentping")
+_BASE_BACKOFF, _MAX_BACKOFF, _MAX_QUEUE = 1.0, 30.0, 100
+
+
+class RelayClient:
+    """WebSocket client for the AgentPing relay service."""
+
+    def __init__(self, relay_url: str, api_key: str, agent_name: str = "unknown") -> None:
+        self._relay_url = relay_url
+        self._api_key = api_key
+        self._agent_name = agent_name
+        self._ws: Optional[websockets.WebSocketClientProtocol] = None
+        self._connection_id: Optional[str] = None
+        self._user_id: Optional[str] = None
+        self._connected = asyncio.Event()
+        self._closing = False
+        self._queue: List[Dict[str, Any]] = []
+        self._response_waiters: Dict[str, asyncio.Future] = {}
+        self._reconnect_attempt = 0
+
+    async def connect(self) -> None:
+        self._closing = False
+        asyncio.ensure_future(self._connection_loop())
+
+    async def close(self) -> None:
+        self._closing = True
+        self._connected.clear()
+        if self._ws:
+            try: await self._ws.close()
+            except Exception: pass
+
+    async def wait_connected(self, timeout: float = 30.0) -> bool:
+        try:
+            await asyncio.wait_for(self._connected.wait(), timeout=timeout)
+            return True
+        except asyncio.TimeoutError:
+            return False
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected.is_set()
+
+    async def send_message(self, message_type: str, title: str, **kwargs) -> Optional[str]:
+        """Send a message to the relay. Returns message_id on ack, or None."""
+        msg_id = str(uuid4())
+        frame = self._envelope("send_message", msg_id, payload={
+            "message_type": message_type, "title": title, **{k: v for k, v in kwargs.items()}
+        })
+        fut: asyncio.Future = asyncio.get_event_loop().create_future()
+        self._response_waiters[msg_id] = fut
+        await self._send_or_queue(frame)
+        try:
+            result = await asyncio.wait_for(fut, timeout=30.0)
+            return result.get("message_id")
+        except asyncio.TimeoutError:
+            self._response_waiters.pop(msg_id, None)
+            return None
+
+    async def check_response(self, message_id: str) -> Optional[Dict]:
+        """Non-blocking poll for a response."""
+        return await self._request("check_response", message_id=message_id)
+
+    async def wait_response(self, message_id: str, timeout: float = 300.0) -> Dict:
+        """Block until response received, polling every 5s."""
+        deadline = asyncio.get_event_loop().time() + timeout
+        while asyncio.get_event_loop().time() < deadline:
+            result = await self.check_response(message_id)
+            if result and result.get("has_response"):
+                return result
+            await asyncio.sleep(min(5.0, deadline - asyncio.get_event_loop().time()))
+        return {"has_response": False, "status": "timeout", "message_id": message_id}
+
+    async def list_pending(self) -> List[Dict]:
+        """List all pending messages."""
+        result = await self._request("list_pending")
+        return result.get("messages", []) if result else []
+
+    # --- Internal helpers ---
+
+    async def _request(self, msg_type: str, **extra) -> Optional[Dict]:
+        msg_id = str(uuid4())
+        frame = self._envelope(msg_type, msg_id, **extra)
+        fut: asyncio.Future = asyncio.get_event_loop().create_future()
+        self._response_waiters[msg_id] = fut
+        await self._send_or_queue(frame)
+        try:
+            return await asyncio.wait_for(fut, timeout=15.0)
+        except asyncio.TimeoutError:
+            self._response_waiters.pop(msg_id, None)
+            return None
+
+    async def _connection_loop(self) -> None:
+        while not self._closing:
+            try:
+                headers = {"Authorization": f"Bearer {self._api_key}",
+                           "X-Agent-Name": self._agent_name}
+                async with websockets.connect(
+                    self._relay_url, extra_headers=headers,
+                    ping_interval=None, close_timeout=5,
+                ) as ws:
+                    self._ws = ws
+                    ack = json.loads(await asyncio.wait_for(ws.recv(), timeout=10.0))
+                    if ack.get("type") == "connection_error":
+                        logger.error("Rejected: %s (code %s)", ack.get("error"), ack.get("code"))
+                        if ack.get("code") in (4001, 4002, 4004):
+                            self._closing = True
+                            return
+                        break
+                    if ack.get("type") == "connection_ack":
+                        self._connection_id = ack.get("connection_id")
+                        self._user_id = ack.get("user_id")
+                        self._reconnect_attempt = 0
+                        self._connected.set()
+                        logger.info("Connected (id=%s, plan=%s, remaining=%s)",
+                                    self._connection_id, ack.get("plan"),
+                                    ack.get("messages_remaining"))
+                        await self._flush_queue()
+                        await self._receive_loop(ws)
+            except (ConnectionClosed, OSError, asyncio.TimeoutError) as e:
+                logger.warning("Connection lost: %s", e)
+            except Exception:
+                logger.exception("Connection loop error")
+            self._connected.clear()
+            self._ws = None
+            if self._closing:
+                break
+            backoff = min(_BASE_BACKOFF * (2 ** self._reconnect_attempt), _MAX_BACKOFF)
+            jitter = backoff * (0.5 + random.random() * 0.5)
+            self._reconnect_attempt += 1
+            logger.info("Reconnecting in %.1fs (attempt %d)", jitter, self._reconnect_attempt)
+            await asyncio.sleep(jitter)
+
+    async def _receive_loop(self, ws) -> None:
+        async for raw in ws:
+            try: data = json.loads(raw)
+            except json.JSONDecodeError: continue
+            t = data.get("type")
+            if t == "ping":
+                await ws.send(json.dumps(self._envelope("pong", str(uuid4()))))
+            elif t == "message_ack":
+                self._resolve(data.get("ref_id"), data)
+            elif t in ("check_response_result", "pending_list"):
+                self._resolve_any(data)
+            elif t == "response_received":
+                logger.info("Response for %s: %s", data.get("message_id"), data.get("status"))
+            elif t == "error":
+                self._resolve(data.get("ref_id"), {"error": data.get("error")})
+                logger.warning("Relay error: %s", data.get("error"))
+
+    def _resolve(self, key: Optional[str], data: Dict) -> None:
+        if key:
+            fut = self._response_waiters.pop(key, None)
+            if fut and not fut.done():
+                fut.set_result(data)
+
+    def _resolve_any(self, data: Dict) -> None:
+        """Resolve the oldest pending waiter."""
+        self._resolve(data.get("id"), data)
+        if not any(True for _ in []):  # id didn't match, try FIFO
+            for key in list(self._response_waiters):
+                fut = self._response_waiters.get(key)
+                if fut and not fut.done():
+                    self._response_waiters.pop(key)
+                    fut.set_result(data)
+                    return
+
+    async def _send_or_queue(self, frame: Dict) -> None:
+        if self._connected.is_set() and self._ws:
+            try:
+                await self._ws.send(json.dumps(frame))
+                return
+            except Exception:
+                pass
+        if len(self._queue) >= _MAX_QUEUE:
+            self._queue.pop(0)
+        self._queue.append(frame)
+
+    async def _flush_queue(self) -> None:
+        while self._queue and self._ws:
+            frame = self._queue.pop(0)
+            try: await self._ws.send(json.dumps(frame))
+            except Exception:
+                self._queue.insert(0, frame)
+                break
+
+    @staticmethod
+    def _envelope(msg_type: str, msg_id: str, **kwargs) -> Dict:
+        return {"type": msg_type, "id": msg_id,
+                "timestamp": datetime.now(timezone.utc).isoformat(), **kwargs}

agentping-0.1.0/tests/conftest.py

@@ -0,0 +1,28 @@
+"""Test fixtures and mcp module mock for Python <3.10 environments."""
+
+from __future__ import annotations
+
+import sys
+from unittest.mock import MagicMock
+
+# Mock the mcp module if not installed (Python <3.10)
+if "mcp" not in sys.modules:
+    mcp_mock = MagicMock()
+
+    # Mock FastMCP so @mcp.tool() decorators pass through
+    class FakeFastMCP:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def tool(self, *args, **kwargs):
+            def decorator(fn):
+                return fn
+            return decorator
+
+        def run(self):
+            pass
+
+    mcp_mock.server.fastmcp.FastMCP = FakeFastMCP
+    sys.modules["mcp"] = mcp_mock
+    sys.modules["mcp.server"] = mcp_mock.server
+    sys.modules["mcp.server.fastmcp"] = mcp_mock.server.fastmcp

agentping-0.1.0/tests/test_config.py

@@ -0,0 +1,77 @@
+"""Tests for config loading and saving."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+from agentping.config import (
+    DEFAULT_RELAY_URL,
+    get_agent_name,
+    get_api_key,
+    get_relay_url,
+    load_config,
+    save_config,
+)
+
+
+class TestConfig:
+    def test_get_api_key_from_env(self):
+        with patch.dict(os.environ, {"AGENTPING_API_KEY": "sk-ap_live_test123"}):
+            assert get_api_key() == "sk-ap_live_test123"
+
+    def test_get_relay_url_from_env(self):
+        with patch.dict(os.environ, {"AGENTPING_RELAY_URL": "wss://custom.relay.dev/ws"}):
+            assert get_relay_url() == "wss://custom.relay.dev/ws"
+
+    def test_get_relay_url_default(self):
+        with patch.dict(os.environ, {}, clear=True):
+            with patch("agentping.config.load_config", return_value={}):
+                assert get_relay_url() == DEFAULT_RELAY_URL
+
+    def test_get_agent_name_from_env(self):
+        with patch.dict(os.environ, {"AGENTPING_AGENT_NAME": "claude-code"}):
+            assert get_agent_name() == "claude-code"
+
+    def test_get_agent_name_default(self):
+        with patch.dict(os.environ, {}, clear=True):
+            with patch("agentping.config.load_config", return_value={}):
+                assert get_agent_name() == "unknown"
+
+    def test_save_and_load_config(self, tmp_path):
+        config_file = tmp_path / "config.json"
+        config_dir = tmp_path
+
+        with patch("agentping.config._CONFIG_DIR", config_dir), \
+             patch("agentping.config._CONFIG_FILE", config_file):
+            save_config({"api_key": "sk-ap_test", "relay_url": "wss://test/ws"})
+
+            loaded = load_config()
+            assert loaded["api_key"] == "sk-ap_test"
+            assert loaded["relay_url"] == "wss://test/ws"
+
+            # Check file permissions (0o600)
+            mode = config_file.stat().st_mode & 0o777
+            assert mode == 0o600
+
+    def test_load_config_missing_file(self, tmp_path):
+        config_file = tmp_path / "nonexistent.json"
+        with patch("agentping.config._CONFIG_FILE", config_file):
+            assert load_config() == {}
+
+    def test_load_config_invalid_json(self, tmp_path):
+        config_file = tmp_path / "config.json"
+        config_file.write_text("not json")
+        with patch("agentping.config._CONFIG_FILE", config_file):
+            assert load_config() == {}
+
+    def test_env_overrides_config_file(self, tmp_path):
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({"api_key": "from-file"}))
+
+        with patch("agentping.config._CONFIG_FILE", config_file), \
+             patch.dict(os.environ, {"AGENTPING_API_KEY": "from-env"}):
+            assert get_api_key() == "from-env"

agentping-0.1.0/tests/test_server.py

@@ -0,0 +1,176 @@
+"""Tests for MCP server tool functions."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+import agentping.server as server_module
+from agentping.server import (
+    bridge_ask_question,
+    bridge_check_response,
+    bridge_list_pending,
+    bridge_ping,
+    bridge_send_approval,
+    bridge_send_update,
+    bridge_task_complete,
+    bridge_wait_response,
+)
+
+
+@pytest.fixture(autouse=True)
+def reset_client():
+    """Reset the global client before each test."""
+    server_module._client = None
+    yield
+    server_module._client = None
+
+
+@pytest.fixture
+def mock_client():
+    """Create a mock RelayClient."""
+    client = AsyncMock()
+    client._relay_url = "wss://test/ws"
+    client._connection_id = "conn-123"
+    client.is_connected = True
+    client.wait_connected = AsyncMock(return_value=True)
+    return client
+
+
+class TestBridgePing:
+    @pytest.mark.asyncio
+    async def test_ping_connected(self, mock_client):
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_ping()
+            assert result["status"] == "connected"
+            assert result["connection_id"] == "conn-123"
+
+    @pytest.mark.asyncio
+    async def test_ping_not_connected(self, mock_client):
+        mock_client.wait_connected = AsyncMock(return_value=False)
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_ping()
+            assert result["status"] == "error"
+
+
+class TestBridgeSendApproval:
+    @pytest.mark.asyncio
+    async def test_send_approval_success(self, mock_client):
+        mock_client.send_message = AsyncMock(return_value="msg-456")
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_send_approval(
+                title="Refactor auth module",
+                description="Extract into service",
+                urgency="high",
+            )
+            assert result["status"] == "sent"
+            assert result["request_id"] == "msg-456"
+
+    @pytest.mark.asyncio
+    async def test_send_approval_no_ack(self, mock_client):
+        mock_client.send_message = AsyncMock(return_value=None)
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_send_approval(title="Test")
+            assert result["status"] == "error"
+
+
+class TestBridgeAskQuestion:
+    @pytest.mark.asyncio
+    async def test_ask_question_success(self, mock_client):
+        mock_client.send_message = AsyncMock(return_value="msg-789")
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_ask_question(
+                question="Which DB driver?",
+                options=["psycopg2", "asyncpg"],
+            )
+            assert result["status"] == "sent"
+            assert result["request_id"] == "msg-789"
+
+
+class TestBridgeWaitResponse:
+    @pytest.mark.asyncio
+    async def test_wait_response_approved(self, mock_client):
+        mock_client.wait_response = AsyncMock(return_value={
+            "has_response": True,
+            "status": "approved",
+            "response_text": None,
+        })
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_wait_response(request_id="msg-456", timeout=10)
+            assert result["status"] == "approved"
+            assert result["responder"] == "developer"
+
+    @pytest.mark.asyncio
+    async def test_wait_response_timeout(self, mock_client):
+        mock_client.wait_response = AsyncMock(return_value={
+            "has_response": False,
+            "status": "timeout",
+            "message_id": "msg-456",
+        })
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_wait_response(request_id="msg-456", timeout=1)
+            assert result["status"] == "timeout"
+
+
+class TestBridgeCheckResponse:
+    @pytest.mark.asyncio
+    async def test_check_response_pending(self, mock_client):
+        mock_client.check_response = AsyncMock(return_value={
+            "has_response": False,
+            "status": "pending",
+        })
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_check_response(request_id="msg-456")
+            assert result["has_response"] is False
+            assert result["status"] == "pending"
+
+    @pytest.mark.asyncio
+    async def test_check_response_replied(self, mock_client):
+        mock_client.check_response = AsyncMock(return_value={
+            "has_response": True,
+            "status": "replied",
+            "response_text": "Use asyncpg",
+        })
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_check_response(request_id="msg-456")
+            assert result["has_response"] is True
+            assert result["response"] == "Use asyncpg"
+
+
+class TestBridgeSendUpdate:
+    @pytest.mark.asyncio
+    async def test_send_update(self, mock_client):
+        mock_client.send_message = AsyncMock(return_value="msg-upd")
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_send_update(
+                title="Running tests",
+                progress_pct=65,
+            )
+            assert result["status"] == "sent"
+
+
+class TestBridgeTaskComplete:
+    @pytest.mark.asyncio
+    async def test_task_complete(self, mock_client):
+        mock_client.send_message = AsyncMock(return_value="msg-done")
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_task_complete(
+                title="Auth refactoring complete",
+                files_changed=["auth.py", "tests/test_auth.py"],
+            )
+            assert result["status"] == "sent"
+
+
+class TestBridgeListPending:
+    @pytest.mark.asyncio
+    async def test_list_pending(self, mock_client):
+        mock_client.list_pending = AsyncMock(return_value=[
+            {"message_id": "1", "type": "approval", "title": "Approve refactor"},
+            {"message_id": "2", "type": "question", "title": "Which driver?"},
+        ])
+        with patch.object(server_module, "_client", mock_client):
+            result = await bridge_list_pending()
+            assert result["status"] == "ok"
+            assert result["count"] == 2
+            assert len(result["pending"]) == 2

agentping-0.1.0/tests/test_ws_client.py

@@ -0,0 +1,116 @@
+"""Tests for WebSocket client — message construction, queue, and state."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from agentping.ws_client import RelayClient
+
+
+class TestRelayClientState:
+    def test_initial_state(self):
+        client = RelayClient("wss://test/ws", "sk-ap_test", "test-agent")
+        assert not client.is_connected
+        assert client._queue == []
+        assert client._reconnect_attempt == 0
+
+    def test_envelope(self):
+        env = RelayClient._envelope("send_message", "msg-1", payload={"title": "test"})
+        assert env["type"] == "send_message"
+        assert env["id"] == "msg-1"
+        assert "timestamp" in env
+        assert env["payload"]["title"] == "test"
+
+
+class TestMessageQueue:
+    @pytest.mark.asyncio
+    async def test_queue_when_disconnected(self):
+        client = RelayClient("wss://test/ws", "sk-ap_test")
+        # Not connected, so message should be queued
+        frame = {"type": "send_message", "id": "1"}
+        await client._send_or_queue(frame)
+        assert len(client._queue) == 1
+        assert client._queue[0] == frame
+
+    @pytest.mark.asyncio
+    async def test_queue_max_size(self):
+        client = RelayClient("wss://test/ws", "sk-ap_test")
+        for i in range(105):
+            await client._send_or_queue({"type": "send_message", "id": str(i)})
+        # Should cap at 100, dropping oldest
+        assert len(client._queue) == 100
+        assert client._queue[0]["id"] == "5"  # first 5 dropped
+
+    @pytest.mark.asyncio
+    async def test_send_when_connected(self):
+        client = RelayClient("wss://test/ws", "sk-ap_test")
+        mock_ws = AsyncMock()
+        client._ws = mock_ws
+        client._connected.set()
+
+        frame = {"type": "send_message", "id": "1"}
+        await client._send_or_queue(frame)
+
+        mock_ws.send.assert_called_once_with(json.dumps(frame))
+        assert len(client._queue) == 0
+
+    @pytest.mark.asyncio
+    async def test_queue_on_send_failure(self):
+        client = RelayClient("wss://test/ws", "sk-ap_test")
+        mock_ws = AsyncMock()
+        mock_ws.send.side_effect = Exception("connection lost")
+        client._ws = mock_ws
+        client._connected.set()
+
+        frame = {"type": "send_message", "id": "1"}
+        await client._send_or_queue(frame)
+
+        # Should fall back to queue
+        assert len(client._queue) == 1
+
+    @pytest.mark.asyncio
+    async def test_flush_queue(self):
+        client = RelayClient("wss://test/ws", "sk-ap_test")
+        client._queue = [
+            {"type": "send_message", "id": "1"},
+            {"type": "send_message", "id": "2"},
+        ]
+        mock_ws = AsyncMock()
+        client._ws = mock_ws
+
+        await client._flush_queue()
+
+        assert len(client._queue) == 0
+        assert mock_ws.send.call_count == 2
+
+
+class TestCloseAndCleanup:
+    @pytest.mark.asyncio
+    async def test_close(self):
+        client = RelayClient("wss://test/ws", "sk-ap_test")
+        client._connected.set()
+        mock_ws = AsyncMock()
+        client._ws = mock_ws
+
+        await client.close()
+
+        assert client._closing is True
+        assert not client.is_connected
+        mock_ws.close.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_wait_connected_timeout(self):
+        client = RelayClient("wss://test/ws", "sk-ap_test")
+        result = await client.wait_connected(timeout=0.1)
+        assert result is False
+
+    @pytest.mark.asyncio
+    async def test_wait_connected_already_connected(self):
+        client = RelayClient("wss://test/ws", "sk-ap_test")
+        client._connected.set()
+        result = await client.wait_connected(timeout=1.0)
+        assert result is True