maverick-channels 0.1.2__tar.gz

maverick_channels-0.1.2/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: maverick-channels
+Version: 0.1.2
+Summary: Channel adapters for Maverick (Telegram, Discord, Slack, Signal, ...)
+Author: cdayAI
+License: MIT
+Project-URL: Homepage, https://github.com/cdayAI/maverick
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: maverick-agent>=0.1
+Provides-Extra: telegram
+Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
+Provides-Extra: discord
+Requires-Dist: discord.py>=2.4; extra == "discord"
+Provides-Extra: slack
+Requires-Dist: slack_sdk>=3.27; extra == "slack"
+Provides-Extra: matrix
+Requires-Dist: matrix-nio>=0.24; extra == "matrix"
+Provides-Extra: whatsapp
+Requires-Dist: fastapi>=0.110; extra == "whatsapp"
+Requires-Dist: uvicorn>=0.27; extra == "whatsapp"
+Requires-Dist: twilio>=9.0; extra == "whatsapp"
+Requires-Dist: python-multipart>=0.0.9; extra == "whatsapp"
+Provides-Extra: sms
+Requires-Dist: fastapi>=0.110; extra == "sms"
+Requires-Dist: uvicorn>=0.27; extra == "sms"
+Requires-Dist: twilio>=9.0; extra == "sms"
+Requires-Dist: python-multipart>=0.0.9; extra == "sms"
+Provides-Extra: all
+Requires-Dist: python-telegram-bot>=21.0; extra == "all"
+Requires-Dist: discord.py>=2.4; extra == "all"
+Requires-Dist: slack_sdk>=3.27; extra == "all"
+Requires-Dist: matrix-nio>=0.24; extra == "all"
+Requires-Dist: fastapi>=0.110; extra == "all"
+Requires-Dist: uvicorn>=0.27; extra == "all"
+Requires-Dist: twilio>=9.0; extra == "all"
+Requires-Dist: python-multipart>=0.0.9; extra == "all"
+
+# maverick-channels
+
+Channel adapters for Maverick. A channel normalizes incoming messages
+from any platform into a shared `{user_id, text, attachments}` shape,
+hands it to the orchestrator, and routes the response back.
+
+This is how phone-companion mode works: Maverick itself runs on your
+Desktop or VPS (`maverick serve`), and any of these channels gives your
+phone (or any other client) a frontend.
+
+## Channels
+
+| Channel  | Status   | Install                                  | Notes |
+|----------|----------|------------------------------------------|-------|
+| CLI      | ready    | bundled                                  | stdin/stdout, used by `maverick start` |
+| Telegram | ready    | `pip install '.[telegram]'`              | Long-poll, no public endpoint needed |
+| Discord  | ready    | `pip install '.[discord]'`               | Gateway WebSocket |
+| Slack    | ready    | `pip install '.[slack]'`                 | Socket Mode |
+| Signal   | ready    | bundled (needs `signal-cli` on PATH)     | JSON-RPC over subprocess |
+| Email    | ready    | bundled                                  | IMAP poll + SMTP send (stdlib) |
+| Matrix   | ready    | `pip install '.[matrix]'`                | Federated, end-to-end encryptable |
+| WhatsApp | scaffold | `pip install '.[whatsapp]'`              | Twilio webhook — needs public HTTPS |
+| SMS      | scaffold | `pip install '.[sms]'`                   | Twilio webhook — needs public HTTPS |
+| iMessage | scaffold | bundled                                  | macOS only, needs Full Disk Access |
+
+or everything at once:
+
+```bash
+pip install 'maverick-channels[all]'
+```
+
+## The interface
+
+Every channel implements:
+
+```python
+class Channel:
+    async def start(self) -> None: ...
+    async def send(self, user_id: str, text: str) -> None: ...
+    async def stop(self) -> None: ...
+```
+
+And dispatches `IncomingMessage(user_id, text, attachments)` to a single
+handler the wizard wires up.
+
+## Wiring channels
+
+In `~/.maverick/config.toml`:
+
+```toml
+[channels.telegram]
+enabled = true
+bot_token = "${TELEGRAM_BOT_TOKEN}"
+allowed_user_ids = ["123456789"]
+# optional alternative: allowed_chat_ids = ["-1001234567890"]
+
+[channels.discord]
+enabled = true
+bot_token = "${DISCORD_BOT_TOKEN}"
+
+[channels.slack]
+enabled = false
+app_token = "${SLACK_APP_TOKEN}"
+bot_token = "${SLACK_BOT_TOKEN}"
+
+[channels.signal]
+enabled = false
+phone_number = "+12345550199"
+
+[channels.email]
+enabled = false
+imap_host = "imap.gmail.com"
+imap_user = "${EMAIL_USER}"
+imap_password = "${EMAIL_APP_PASSWORD}"
+smtp_host = "smtp.gmail.com"
+smtp_port = 465
+smtp_user = "${EMAIL_USER}"
+smtp_password = "${EMAIL_APP_PASSWORD}"
+```
+
+Then run:
+
+```bash
+maverick serve
+```
+
+Multiple channels can be enabled simultaneously — each runs in its own
+async task.

maverick_channels-0.1.2/README.md

@@ -0,0 +1,88 @@
+# maverick-channels
+
+Channel adapters for Maverick. A channel normalizes incoming messages
+from any platform into a shared `{user_id, text, attachments}` shape,
+hands it to the orchestrator, and routes the response back.
+
+This is how phone-companion mode works: Maverick itself runs on your
+Desktop or VPS (`maverick serve`), and any of these channels gives your
+phone (or any other client) a frontend.
+
+## Channels
+
+| Channel  | Status   | Install                                  | Notes |
+|----------|----------|------------------------------------------|-------|
+| CLI      | ready    | bundled                                  | stdin/stdout, used by `maverick start` |
+| Telegram | ready    | `pip install '.[telegram]'`              | Long-poll, no public endpoint needed |
+| Discord  | ready    | `pip install '.[discord]'`               | Gateway WebSocket |
+| Slack    | ready    | `pip install '.[slack]'`                 | Socket Mode |
+| Signal   | ready    | bundled (needs `signal-cli` on PATH)     | JSON-RPC over subprocess |
+| Email    | ready    | bundled                                  | IMAP poll + SMTP send (stdlib) |
+| Matrix   | ready    | `pip install '.[matrix]'`                | Federated, end-to-end encryptable |
+| WhatsApp | scaffold | `pip install '.[whatsapp]'`              | Twilio webhook — needs public HTTPS |
+| SMS      | scaffold | `pip install '.[sms]'`                   | Twilio webhook — needs public HTTPS |
+| iMessage | scaffold | bundled                                  | macOS only, needs Full Disk Access |
+
+or everything at once:
+
+```bash
+pip install 'maverick-channels[all]'
+```
+
+## The interface
+
+Every channel implements:
+
+```python
+class Channel:
+    async def start(self) -> None: ...
+    async def send(self, user_id: str, text: str) -> None: ...
+    async def stop(self) -> None: ...
+```
+
+And dispatches `IncomingMessage(user_id, text, attachments)` to a single
+handler the wizard wires up.
+
+## Wiring channels
+
+In `~/.maverick/config.toml`:
+
+```toml
+[channels.telegram]
+enabled = true
+bot_token = "${TELEGRAM_BOT_TOKEN}"
+allowed_user_ids = ["123456789"]
+# optional alternative: allowed_chat_ids = ["-1001234567890"]
+
+[channels.discord]
+enabled = true
+bot_token = "${DISCORD_BOT_TOKEN}"
+
+[channels.slack]
+enabled = false
+app_token = "${SLACK_APP_TOKEN}"
+bot_token = "${SLACK_BOT_TOKEN}"
+
+[channels.signal]
+enabled = false
+phone_number = "+12345550199"
+
+[channels.email]
+enabled = false
+imap_host = "imap.gmail.com"
+imap_user = "${EMAIL_USER}"
+imap_password = "${EMAIL_APP_PASSWORD}"
+smtp_host = "smtp.gmail.com"
+smtp_port = 465
+smtp_user = "${EMAIL_USER}"
+smtp_password = "${EMAIL_APP_PASSWORD}"
+```
+
+Then run:
+
+```bash
+maverick serve
+```
+
+Multiple channels can be enabled simultaneously — each runs in its own
+async task.

maverick_channels-0.1.2/maverick_channels/__init__.py

@@ -0,0 +1,24 @@
+"""Channel adapters for Maverick.
+
+A channel normalizes incoming messages from any platform into a shared
+``IncomingMessage`` shape, hands it to the orchestrator, and routes the
+response back. This is the surface Maverick uses to power phone-companion
+mode — the agent itself runs on Desktop or VPS, and channels give a
+phone (or any other client) a way to talk to it.
+
+Available channels (status as of v0.1):
+  - cli       (ready)
+  - telegram  (ready)
+  - discord   (ready)
+  - slack     (ready)
+  - signal    (ready, requires signal-cli on PATH)
+  - email     (ready, stdlib only)
+  - matrix    (ready, requires matrix-nio)
+  - whatsapp  (scaffold, requires Twilio + public webhook)
+  - sms       (scaffold, requires Twilio + public webhook)
+  - imessage  (macOS only)
+"""
+from .base import Channel, IncomingMessage, Handler
+
+__version__ = "0.1.2"
+__all__ = ["Channel", "IncomingMessage", "Handler"]

maverick_channels-0.1.2/maverick_channels/base.py

@@ -0,0 +1,87 @@
+"""Channel interface.
+
+Normalize every platform (CLI, Telegram, iMessage, ...) to the same shape
+so the agent loop doesn't have to care where a message came from.
+"""
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Awaitable, Callable
+
+
+def normalize_allowlist(values, env_name: str) -> set:
+    """Build an access allowlist from an explicit arg or a comma-separated
+    env var (e.g. ``DISCORD_ALLOWED_USER_IDS``). Shared so every channel
+    enforces access the same way instead of each rolling its own."""
+    if values is not None:
+        return {str(v).strip() for v in values if str(v).strip()}
+    raw = os.environ.get(env_name, "")
+    return {item.strip() for item in raw.split(",") if item.strip()}
+
+
+def is_allowed(user_id, allowlist) -> bool:
+    """True only if ``user_id`` is an explicit allowlist member. A missing
+    id or the ``"anonymous"`` fallback NEVER passes — treat unknown as deny
+    so a channel that can't identify the sender can't be driven by anyone."""
+    if not allowlist:
+        return False
+    uid = str(user_id or "").strip()
+    if not uid or uid == "anonymous":
+        return False
+    return uid in allowlist
+
+
+def _max_inbound_chars() -> int:
+    """Cap on inbound text fed to the swarm. A single oversized inbound
+    message (a 200KB email, an attacker-crafted mention) would otherwise
+    drive an uncapped-context, uncapped-cost agent run. Override with
+    MAVERICK_MAX_INBOUND_CHARS; 0 disables the cap."""
+    try:
+        return int(os.environ.get("MAVERICK_MAX_INBOUND_CHARS", "100000"))
+    except ValueError:
+        return 100000
+
+
+@dataclass
+class IncomingMessage:
+    user_id: str
+    text: str
+    attachments: list[dict] = field(default_factory=list)
+    channel: str = ""
+    raw: object = None
+
+    def __post_init__(self) -> None:
+        cap = _max_inbound_chars()
+        if cap and isinstance(self.text, str) and len(self.text) > cap:
+            self.text = self.text[:cap] + "\n\n[...truncated by Maverick inbound cap]"
+
+
+Handler = Callable[[IncomingMessage], Awaitable[str]]
+"""A handler takes a normalized message and returns the agent's reply."""
+
+
+class Channel(ABC):
+    """Abstract channel adapter.
+
+    Lifecycle:
+      - ``start()`` blocks (or runs in background) accepting messages.
+      - For each message it dispatches to the registered ``Handler``.
+      - ``send(user_id, text)`` pushes a reply back to that user.
+      - ``stop()`` cleans up.
+    """
+
+    name: str
+
+    def __init__(self, handler: Handler):
+        self.handler = handler
+
+    @abstractmethod
+    async def start(self) -> None: ...
+
+    @abstractmethod
+    async def send(self, user_id: str, text: str) -> None: ...
+
+    @abstractmethod
+    async def stop(self) -> None: ...

maverick_channels-0.1.2/maverick_channels/bluesky.py

@@ -0,0 +1,245 @@
+"""Bluesky / AT Protocol channel adapter.
+
+Polls the user's notifications timeline for mentions + DMs, dispatches
+each as an IncomingMessage. Replies go back via the AT Proto REST API.
+
+Auth: env vars BLUESKY_HANDLE + BLUESKY_PASSWORD. The 'password' is an
+app password generated at bsky.app -> Settings -> App Passwords; never
+the account password.
+
+Heavy deps deferred to import time; the optional install is
+``pip install 'maverick-channels[bluesky]'`` which pulls in httpx
+(already a transitive of openai-compat providers).
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import Optional, Set
+
+from .base import Channel, Handler, IncomingMessage
+
+log = logging.getLogger(__name__)
+
+
+_API_BASE = "https://bsky.social/xrpc"
+_POLL_INTERVAL_SEC = 30.0
+
+
+class BlueskyChannel(Channel):
+    """Bluesky AT Proto channel.
+
+    Reuses the same Handler / IncomingMessage shape as the other
+    channel adapters. Polls notifications every 30s; on a `mention`
+    or `reply` event, dispatches to the handler and posts the reply
+    as a thread reply.
+    """
+
+    name = "bluesky"
+
+    def __init__(
+        self,
+        handler: Handler,
+        *,
+        handle: Optional[str] = None,
+        password: Optional[str] = None,
+        allowed_user_ids: Optional[set[str]] = None,
+        poll_interval: float = _POLL_INTERVAL_SEC,
+    ):
+        super().__init__(handler)
+        self.handle = handle or os.environ.get("BLUESKY_HANDLE", "")
+        self.password = password or os.environ.get("BLUESKY_PASSWORD", "")
+        self.allowed_user_ids = self._normalize_allowlist(
+            allowed_user_ids,
+            env_name="BLUESKY_ALLOWED_USER_IDS",
+        )
+        if not self.allowed_user_ids:
+            raise ValueError(
+                "Set BLUESKY_ALLOWED_USER_IDS to restrict access"
+            )
+        self.poll_interval = poll_interval
+        self._session: dict = {}
+        self._last_seen_indexed_at: Optional[str] = None
+        self._running = False
+        self._stop_event = asyncio.Event()
+
+    @staticmethod
+    def _normalize_allowlist(values: Optional[set[str]], env_name: str) -> Set[str]:
+        if values is not None:
+            return {str(v).strip() for v in values if str(v).strip()}
+        raw = os.environ.get(env_name, "")
+        return {item.strip() for item in raw.split(",") if item.strip()}
+
+    async def _ensure_session(self) -> dict:
+        if self._session.get("accessJwt"):
+            return self._session
+        try:
+            import httpx
+        except ImportError as e:
+            raise RuntimeError(
+                "httpx not installed. Run: pip install 'maverick-channels[bluesky]'"
+            ) from e
+        if not self.handle or not self.password:
+            raise RuntimeError(
+                "Bluesky channel requires BLUESKY_HANDLE and BLUESKY_PASSWORD."
+            )
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.post(
+                f"{_API_BASE}/com.atproto.server.createSession",
+                json={"identifier": self.handle, "password": self.password},
+            )
+            resp.raise_for_status()
+            self._session = resp.json()
+        return self._session
+
+    async def _poll_once(self) -> list[dict]:
+        """Fetch any new notifications since last poll."""
+        sess = await self._ensure_session()
+        try:
+            import httpx
+        except ImportError:
+            return []
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.get(
+                f"{_API_BASE}/app.bsky.notification.listNotifications",
+                headers={"Authorization": f"Bearer {sess['accessJwt']}"},
+                params={"limit": 50},
+            )
+            if resp.status_code == 401:
+                # Session expired; force a re-login on next call.
+                self._session = {}
+                return []
+            resp.raise_for_status()
+            notifs = (resp.json() or {}).get("notifications") or []
+        # Filter: only new mentions / replies / DMs.
+        new: list[dict] = []
+        for n in notifs:
+            reason = n.get("reason")
+            if reason not in ("mention", "reply"):
+                continue
+            ts = n.get("indexedAt", "")
+            if self._last_seen_indexed_at and ts <= self._last_seen_indexed_at:
+                continue
+            new.append(n)
+        if new:
+            self._last_seen_indexed_at = max(n.get("indexedAt", "") for n in new)
+        return new
+
+    async def _dispatch(self, notif: dict) -> None:
+        record = notif.get("record") or {}
+        text = record.get("text", "")
+        author = notif.get("author") or {}
+        user_id = author.get("did") or author.get("handle") or "anonymous"
+        if user_id not in self.allowed_user_ids:
+            log.warning("unauthorized bluesky access: user_id=%s", user_id)
+            return
+        msg = IncomingMessage(
+            user_id=user_id, text=text,
+            channel=self.name, raw=notif,
+        )
+        try:
+            reply = await self.handler(msg)
+        except Exception as e:
+            log.exception("bluesky handler raised: %s", e)
+            return
+        if reply:
+            await self._reply(notif, reply)
+
+    async def _reply(self, parent_notif: dict, text: str) -> None:
+        """Post a reply in-thread to a notification."""
+        sess = await self._ensure_session()
+        try:
+            import httpx
+        except ImportError:
+            return
+        record = parent_notif.get("record") or {}
+        reply_root = record.get("reply", {}).get("root") or {
+            "uri": parent_notif.get("uri"),
+            "cid": parent_notif.get("cid"),
+        }
+        body = {
+            "repo": sess.get("did"),
+            "collection": "app.bsky.feed.post",
+            "record": {
+                "$type": "app.bsky.feed.post",
+                "text": text[:300],  # 300-char limit
+                "createdAt": __import__("datetime").datetime.utcnow().isoformat() + "Z",
+                "reply": {
+                    "root": reply_root,
+                    "parent": {
+                        "uri": parent_notif.get("uri"),
+                        "cid": parent_notif.get("cid"),
+                    },
+                },
+            },
+        }
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.post(
+                f"{_API_BASE}/com.atproto.repo.createRecord",
+                headers={"Authorization": f"Bearer {sess['accessJwt']}"},
+                json=body,
+            )
+            if resp.status_code >= 400:
+                log.warning("bluesky post failed (%d): %s", resp.status_code, resp.text[:200])
+
+    async def start(self) -> None:
+        self._running = True
+        await self._ensure_session()
+        # Seed the cursor to "now" so the first poll only dispatches
+        # notifications that arrive AFTER startup. Without this, a cold
+        # start (or any restart) re-runs the agent swarm on the last 50
+        # mentions in history — duplicate replies + real LLM spend.
+        if self._last_seen_indexed_at is None:
+            import datetime as _dt
+            self._last_seen_indexed_at = (
+                _dt.datetime.now(_dt.timezone.utc)
+                .strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+            )
+        log.info("Bluesky channel started (handle=%s)", self.handle)
+        try:
+            while not self._stop_event.is_set():
+                try:
+                    notifs = await self._poll_once()
+                except Exception as e:
+                    log.warning("bluesky poll failed: %s", e)
+                    notifs = []
+                for n in notifs:
+                    await self._dispatch(n)
+                try:
+                    await asyncio.wait_for(
+                        self._stop_event.wait(), timeout=self.poll_interval,
+                    )
+                except asyncio.TimeoutError:
+                    pass
+        finally:
+            self._running = False
+
+    async def send(self, user_id: str, text: str) -> None:
+        """Send a stand-alone message to a user (not in-thread)."""
+        # Bluesky doesn't have proper DMs in the public API yet;
+        # this falls back to a top-level post mentioning the user.
+        sess = await self._ensure_session()
+        try:
+            import httpx
+        except ImportError:
+            return
+        body = {
+            "repo": sess.get("did"),
+            "collection": "app.bsky.feed.post",
+            "record": {
+                "$type": "app.bsky.feed.post",
+                "text": f"@{user_id}: {text[:280]}",
+                "createdAt": __import__("datetime").datetime.utcnow().isoformat() + "Z",
+            },
+        }
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            await client.post(
+                f"{_API_BASE}/com.atproto.repo.createRecord",
+                headers={"Authorization": f"Bearer {sess['accessJwt']}"},
+                json=body,
+            )
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+        self._running = False

maverick_channels-0.1.2/maverick_channels/cli.py

@@ -0,0 +1,38 @@
+"""Stdin/stdout channel.
+
+The default channel — reads lines from stdin, dispatches them to the
+handler, prints replies to stdout. Used by ``maverick start`` directly
+and by tests.
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from .base import Channel, IncomingMessage
+
+
+class CLIChannel(Channel):
+    name = "cli"
+
+    async def start(self) -> None:
+        loop = asyncio.get_event_loop()
+        while True:
+            line = await loop.run_in_executor(None, sys.stdin.readline)
+            if not line:
+                return
+            text = line.rstrip("\n")
+            if not text:
+                continue
+            msg = IncomingMessage(user_id="local", text=text, channel="cli")
+            try:
+                reply = await self.handler(msg)
+            except Exception as e:  # one bad run must not kill the session
+                reply = f"Sorry, I ran into an error: {e}"
+            await self.send("local", reply)
+
+    async def send(self, user_id: str, text: str) -> None:
+        print(text, flush=True)
+
+    async def stop(self) -> None:
+        pass