claw-msg 0.1.0__tar.gz

claw_msg-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: claw-msg
+Version: 0.1.0
+Summary: Agent-to-agent messaging layer — pip install → 5 lines → agents talk
+Author-email: Sangbum <snuhsb@snu.ac.kr>
+License: MIT
+Keywords: agent,messaging,websocket,ai,multi-agent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: bcrypt>=4.1.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+
+# claw-msg
+
+Agent-to-agent messaging layer. `pip install → 5 lines → agents talk`.
+
+## Quick Start
+
+```bash
+pip install -e .
+
+# Start the broker
+claw-msg serve --port 8000
+
+# Register agents (in separate terminals)
+claw-msg register --name agent-a --broker http://localhost:8000
+claw-msg register --name agent-b --broker http://localhost:8000
+
+# Send a message
+claw-msg send --to <agent-b-id> --broker http://localhost:8000 --token <token-a> "hello!"
+
+# Listen for messages
+claw-msg listen --broker http://localhost:8000 --token <token-b>
+```
+
+## SDK Usage
+
+```python
+from claw_msg import Agent
+import asyncio
+
+async def main():
+    agent = Agent("http://localhost:8000", name="my-agent")
+    await agent.register()
+    print(f"registered: {agent.agent_id}")
+
+    # Send a direct message
+    await agent.send("<other-agent-id>", "hello!")
+
+    # Create and use rooms
+    room = await agent.create_room("general")
+    await agent.send_to_room(room["id"], "hello room!")
+
+asyncio.run(main())
+```
+
+## Features
+
+- **WebSocket real-time messaging** with auto-reconnect
+- **HTTP polling fallback** for stateless agents
+- **Rooms** for group messaging
+- **Offline queue** with 7-day TTL and at-least-once delivery
+- **Agent discovery** by name/capabilities
+- **Rate limiting** (60 msg/min token bucket)
+- **Presence tracking** (online/offline/last_seen)
+- **CLI** for all operations
+- **Daemon mode** with webhook forwarding + systemd/launchd service generation
+
+## Architecture
+
+Same package provides both **broker** (server) and **SDK** (client):
+
+```
+┌──────────┐  WebSocket   ┌──────────┐  WebSocket   ┌──────────┐
+│  Agent A  │◄────────────►│  Broker  │◄────────────►│  Agent B  │
+└──────────┘              └──────────┘              └──────────┘
+                               │
+                          SQLite + WAL
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```

claw_msg-0.1.0/README.md

@@ -0,0 +1,74 @@
+# claw-msg
+
+Agent-to-agent messaging layer. `pip install → 5 lines → agents talk`.
+
+## Quick Start
+
+```bash
+pip install -e .
+
+# Start the broker
+claw-msg serve --port 8000
+
+# Register agents (in separate terminals)
+claw-msg register --name agent-a --broker http://localhost:8000
+claw-msg register --name agent-b --broker http://localhost:8000
+
+# Send a message
+claw-msg send --to <agent-b-id> --broker http://localhost:8000 --token <token-a> "hello!"
+
+# Listen for messages
+claw-msg listen --broker http://localhost:8000 --token <token-b>
+```
+
+## SDK Usage
+
+```python
+from claw_msg import Agent
+import asyncio
+
+async def main():
+    agent = Agent("http://localhost:8000", name="my-agent")
+    await agent.register()
+    print(f"registered: {agent.agent_id}")
+
+    # Send a direct message
+    await agent.send("<other-agent-id>", "hello!")
+
+    # Create and use rooms
+    room = await agent.create_room("general")
+    await agent.send_to_room(room["id"], "hello room!")
+
+asyncio.run(main())
+```
+
+## Features
+
+- **WebSocket real-time messaging** with auto-reconnect
+- **HTTP polling fallback** for stateless agents
+- **Rooms** for group messaging
+- **Offline queue** with 7-day TTL and at-least-once delivery
+- **Agent discovery** by name/capabilities
+- **Rate limiting** (60 msg/min token bucket)
+- **Presence tracking** (online/offline/last_seen)
+- **CLI** for all operations
+- **Daemon mode** with webhook forwarding + systemd/launchd service generation
+
+## Architecture
+
+Same package provides both **broker** (server) and **SDK** (client):
+
+```
+┌──────────┐  WebSocket   ┌──────────┐  WebSocket   ┌──────────┐
+│  Agent A  │◄────────────►│  Broker  │◄────────────►│  Agent B  │
+└──────────┘              └──────────┘              └──────────┘
+                               │
+                          SQLite + WAL
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```

claw_msg-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "claw-msg"
+version = "0.1.0"
+description = "Agent-to-agent messaging layer — pip install → 5 lines → agents talk"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Sangbum", email = "snuhsb@snu.ac.kr"}
+]
+keywords = ["agent", "messaging", "websocket", "ai", "multi-agent"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Framework :: FastAPI",
+    "Topic :: Communications",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.110.0",
+    "uvicorn[standard]>=0.27.0",
+    "aiosqlite>=0.20.0",
+    "bcrypt>=4.1.0",
+    "websockets>=12.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "click>=8.1.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+claw-msg = "claw_msg.cli.main:cli"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

claw_msg-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claw_msg-0.1.0/src/claw_msg/__init__.py

@@ -0,0 +1,6 @@
+"""claw-msg: Agent-to-agent messaging layer."""
+
+from claw_msg.client.agent import Agent
+
+__all__ = ["Agent"]
+__version__ = "0.1.0"

claw_msg-0.1.0/src/claw_msg/cli/main.py

@@ -0,0 +1,211 @@
+"""claw-msg CLI — register, send, listen, serve, rooms, daemon."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+
+import click
+
+
+@click.group()
+def cli():
+    """claw-msg — Agent-to-agent messaging layer."""
+    pass
+
+
+@cli.command()
+@click.option("--host", default="0.0.0.0", help="Host to bind to")
+@click.option("--port", default=8000, type=int, help="Port to bind to")
+def serve(host: str, port: int):
+    """Start the claw-msg broker server."""
+    import uvicorn
+    from claw_msg.server.app import app
+
+    uvicorn.run(app, host=host, port=port)
+
+
+@cli.command()
+@click.option("--name", required=True, help="Agent name")
+@click.option("--broker", required=True, help="Broker URL")
+@click.option("--capabilities", default="", help="Comma-separated capabilities")
+@click.option("--application", is_flag=True, help="Register as application agent")
+def register(name: str, broker: str, capabilities: str, application: bool):
+    """Register a new agent with the broker."""
+
+    async def _register():
+        from claw_msg.client.agent import Agent
+
+        caps = [c.strip() for c in capabilities.split(",") if c.strip()] if capabilities else []
+        agent = Agent(broker, name=name, capabilities=caps)
+        agent_id = await agent.register()
+        click.echo(f"Registered: {agent_id}")
+        click.echo(f"Token: {agent.token}")
+        click.echo(f"Credentials saved to ~/.claw-msg/credentials.json")
+
+    asyncio.run(_register())
+
+
+@cli.command()
+@click.option("--to", "to_agent", required=True, help="Recipient agent ID")
+@click.option("--broker", required=True, help="Broker URL")
+@click.option("--token", required=True, help="Your agent token")
+@click.argument("message")
+def send(to_agent: str, broker: str, token: str, message: str):
+    """Send a message to another agent."""
+
+    async def _send():
+        from claw_msg.client.agent import Agent
+
+        agent = Agent(broker, token=token)
+        result = await agent.send(to_agent, message)
+        click.echo(f"Sent: {result.get('id', 'ok') if result else 'ok'}")
+
+    asyncio.run(_send())
+
+
+@cli.command()
+@click.option("--broker", required=True, help="Broker URL")
+@click.option("--token", required=True, help="Your agent token")
+def listen(broker: str, token: str):
+    """Listen for incoming messages via WebSocket."""
+
+    async def _listen():
+        from claw_msg.client.agent import Agent
+
+        agent = Agent(broker, token=token)
+
+        @agent.on_message
+        async def handle(msg):
+            click.echo(f"[{msg.get('from_agent', '?')}] {msg.get('content', '')}")
+
+        click.echo("Listening for messages (Ctrl+C to stop)...")
+        await agent.listen()
+
+    try:
+        asyncio.run(_listen())
+    except KeyboardInterrupt:
+        click.echo("\nStopped.")
+
+
+@cli.group()
+def rooms():
+    """Room management commands."""
+    pass
+
+
+@rooms.command("create")
+@click.option("--broker", required=True, help="Broker URL")
+@click.option("--token", required=True, help="Your agent token")
+@click.option("--name", required=True, help="Room name")
+@click.option("--description", default="", help="Room description")
+def room_create(broker: str, token: str, name: str, description: str):
+    """Create a new room."""
+
+    async def _create():
+        from claw_msg.client.agent import Agent
+
+        agent = Agent(broker, token=token)
+        result = await agent.create_room(name=name, description=description)
+        click.echo(f"Room created: {result.get('id', '')}")
+
+    asyncio.run(_create())
+
+
+@rooms.command("join")
+@click.option("--broker", required=True, help="Broker URL")
+@click.option("--token", required=True, help="Your agent token")
+@click.option("--room-id", required=True, help="Room ID to join")
+def room_join(broker: str, token: str, room_id: str):
+    """Join an existing room."""
+
+    async def _join():
+        from claw_msg.client.agent import Agent
+
+        agent = Agent(broker, token=token)
+        await agent.join_room(room_id)
+        click.echo(f"Joined room: {room_id}")
+
+    asyncio.run(_join())
+
+
+@rooms.command("leave")
+@click.option("--broker", required=True, help="Broker URL")
+@click.option("--token", required=True, help="Your agent token")
+@click.option("--room-id", required=True, help="Room ID to leave")
+def room_leave(broker: str, token: str, room_id: str):
+    """Leave a room."""
+
+    async def _leave():
+        from claw_msg.client.agent import Agent
+
+        agent = Agent(broker, token=token)
+        await agent.leave_room(room_id)
+        click.echo(f"Left room: {room_id}")
+
+    asyncio.run(_leave())
+
+
+@cli.command()
+@click.option("--broker", required=True, help="Broker URL")
+@click.option("--token", required=True, help="Your agent token")
+@click.option("--webhook", required=True, help="Webhook URL to forward messages to")
+def daemon(broker: str, token: str, webhook: str):
+    """Run as a daemon — forward messages to a webhook URL."""
+
+    async def _run():
+        from claw_msg.daemon.runner import run_daemon
+
+        await run_daemon(broker, token, webhook)
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        click.echo("\nDaemon stopped.")
+
+
+@cli.command("install-service")
+@click.option("--broker", required=True, help="Broker URL")
+@click.option("--token", required=True, help="Your agent token")
+@click.option("--webhook", required=True, help="Webhook URL")
+@click.option("--type", "svc_type", type=click.Choice(["systemd", "launchd"]), default="systemd")
+def install_service(broker: str, token: str, webhook: str, svc_type: str):
+    """Install a system service for the daemon."""
+    from claw_msg.daemon.service import install_launchd_service, install_systemd_service
+
+    if svc_type == "systemd":
+        path = install_systemd_service(broker, token, webhook)
+        click.echo(f"Systemd service installed: {path}")
+        click.echo("Run: systemctl --user enable --now claw-msg-daemon")
+    else:
+        path = install_launchd_service(broker, token, webhook)
+        click.echo(f"Launchd plist installed: {path}")
+        click.echo("Run: launchctl load ~/Library/LaunchAgents/com.claw-msg.daemon.plist")
+
+
+@cli.command("agents")
+@click.option("--broker", required=True, help="Broker URL")
+@click.option("--name", default=None, help="Search by name")
+def list_agents(broker: str, name: str | None):
+    """Search for agents on the broker."""
+
+    async def _search():
+        from claw_msg.client.http import HttpClient
+
+        http = HttpClient(broker, "")
+        async with __import__("httpx").AsyncClient() as c:
+            params = {}
+            if name:
+                params["name"] = name
+            resp = await c.get(f"{broker.rstrip('/')}/agents/", params=params)
+            resp.raise_for_status()
+            for agent in resp.json():
+                status = agent.get("status", "?")
+                click.echo(f"  {agent['id']}  {agent['name']}  [{status}]")
+
+    asyncio.run(_search())
+
+
+if __name__ == "__main__":
+    cli()

claw_msg-0.1.0/src/claw_msg/client/agent.py

@@ -0,0 +1,148 @@
+"""High-level Agent SDK — the main public interface for claw-msg."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable, Coroutine
+
+from claw_msg.client.connection import Connection
+from claw_msg.client.credentials import store_credentials
+from claw_msg.client.http import HttpClient
+
+
+class Agent:
+    """
+    Agent SDK — register, send/receive messages, join rooms.
+
+    Usage::
+
+        agent = Agent("http://localhost:8000", name="my-agent")
+        await agent.register()
+        await agent.send("agent-id-here", "hello!")
+    """
+
+    def __init__(
+        self,
+        broker_url: str,
+        name: str = "unnamed-agent",
+        capabilities: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        token: str | None = None,
+        agent_id: str | None = None,
+    ):
+        self._broker_url = broker_url.rstrip("/")
+        self._name = name
+        self._capabilities = capabilities or []
+        self._metadata = metadata or {}
+        self._token = token
+        self._agent_id = agent_id
+        self._connection: Connection | None = None
+        self._http: HttpClient | None = None
+        self._message_handlers: list[Callable[[dict], Coroutine]] = []
+
+    @property
+    def agent_id(self) -> str | None:
+        return self._agent_id
+
+    @property
+    def token(self) -> str | None:
+        return self._token
+
+    @property
+    def connected(self) -> bool:
+        return self._connection is not None and self._connection.connected
+
+    async def register(self) -> str:
+        """Register this agent with the broker. Returns agent_id."""
+        http = HttpClient(self._broker_url, "")
+        result = await http.register(
+            name=self._name,
+            capabilities=self._capabilities,
+            metadata=self._metadata,
+        )
+        self._agent_id = result["agent_id"]
+        self._token = result["token"]
+        self._http = HttpClient(self._broker_url, self._token)
+
+        store_credentials(self._broker_url, self._agent_id, self._token, self._name)
+        return self._agent_id
+
+    def on_message(self, handler: Callable[[dict], Coroutine]):
+        """Register a message handler (decorator-style)."""
+        self._message_handlers.append(handler)
+        return handler
+
+    async def _dispatch_message(self, msg: dict):
+        for handler in self._message_handlers:
+            await handler(msg)
+
+    async def connect(self):
+        """Establish WebSocket connection to the broker."""
+        if not self._token:
+            raise RuntimeError("Must register or provide a token before connecting")
+        self._connection = Connection(
+            self._broker_url,
+            self._token,
+            on_message=self._dispatch_message,
+        )
+        self._agent_id = await self._connection.connect()
+        self._http = HttpClient(self._broker_url, self._token)
+
+    async def listen(self):
+        """Start listening for messages (blocking). Auto-reconnects."""
+        if not self._token:
+            raise RuntimeError("Must register or provide a token before listening")
+        self._connection = Connection(
+            self._broker_url,
+            self._token,
+            on_message=self._dispatch_message,
+        )
+        await self._connection.listen()
+
+    async def send(self, to: str, content: str, content_type: str = "text/plain", reply_to: str | None = None) -> dict | None:
+        """Send a direct message. Uses WebSocket if connected, HTTP otherwise."""
+        if self._connection and self._connection.connected:
+            await self._connection.send_message(to=to, content=content, content_type=content_type, reply_to=reply_to)
+            return None
+        else:
+            return await self._get_http().send_message(to=to, content=content, content_type=content_type, reply_to=reply_to)
+
+    async def send_to_room(self, room_id: str, content: str, content_type: str = "text/plain") -> dict | None:
+        """Send a message to a room."""
+        if self._connection and self._connection.connected:
+            await self._connection.send_message(room_id=room_id, content=content, content_type=content_type)
+            return None
+        else:
+            return await self._get_http().send_message(room_id=room_id, content=content, content_type=content_type)
+
+    async def get_messages(self, since: str | None = None, limit: int = 50) -> list[dict]:
+        """Fetch message history via HTTP."""
+        return await self._get_http().get_messages(since=since, limit=limit)
+
+    async def search_agents(self, name: str | None = None, capability: str | None = None) -> list[dict]:
+        """Search for agents."""
+        return await self._get_http().search_agents(name=name, capability=capability)
+
+    async def create_room(self, name: str, description: str = "", max_members: int = 50) -> dict:
+        """Create a room."""
+        return await self._get_http().create_room(name=name, description=description, max_members=max_members)
+
+    async def join_room(self, room_id: str) -> dict:
+        """Join a room."""
+        return await self._get_http().join_room(room_id)
+
+    async def leave_room(self, room_id: str) -> dict:
+        """Leave a room."""
+        return await self._get_http().leave_room(room_id)
+
+    async def close(self):
+        """Close connection."""
+        if self._connection:
+            await self._connection.close()
+
+    def _get_http(self) -> HttpClient:
+        if not self._http:
+            if not self._token:
+                raise RuntimeError("Must register or provide a token")
+            self._http = HttpClient(self._broker_url, self._token)
+        return self._http