watchline-hermes-plugin 0.1.0__tar.gz

watchline_hermes_plugin-0.1.0/LICENSE

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

watchline_hermes_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: watchline-hermes-plugin
+Version: 0.1.0
+Summary: Hermes Agent delivery adapter for Watchline.
+Author-email: Watchline <support@qordinate.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://watch.qordinate.ai
+Project-URL: Documentation, https://watch.qordinate.ai/docs/hermes
+Project-URL: Repository, https://github.com/qordinate-ai/watchline-hermes-plugin
+Project-URL: Issues, https://github.com/qordinate-ai/watchline-hermes-plugin/issues
+Keywords: watchline,hermes-agent,agents,mcp,plugin,pull-delivery
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6
+Dynamic: license-file
+
+# Watchline for Hermes Agent
+
+Watchline is an event layer for agents. This Hermes plugin delivers matched
+Watchline events into a local Hermes gateway without exposing your laptop to
+the internet.
+
+![Watchline Hermes delivery flow](https://watch.qordinate.ai/images/docs/watchline-hermes.png)
+
+Watchline uses two integration planes:
+
+- **Hosted MCP** gives Hermes the watch tools: `start_watch`,
+  `continue_watch`, `list_watches`, `pause_watch`, `resume_watch`, and
+  `delete_watch`.
+- **This plugin** registers a Hermes gateway platform named `watchline`. It
+  polls a Watchline pull channel and forwards matched events as inbound Hermes
+  messages.
+
+The plugin intentionally does not duplicate Watchline tools. Hermes discovers
+tools from the hosted MCP server, and this adapter only handles local delivery.
+
+## Install
+
+```bash
+hermes plugins install qordinate-ai/watchline-hermes-plugin --enable
+```
+
+After the first PyPI release, the package can also be installed directly:
+
+```bash
+python -m pip install watchline-hermes-plugin
+```
+
+For local development:
+
+```bash
+hermes plugins install file:///absolute/path/to/watchline-hermes-plugin --enable
+```
+
+## Configure
+
+Create a Watchline API key and pull channel at <https://watch.qordinate.ai>,
+then run:
+
+```bash
+hermes watchline configure \
+  --api-key wl_... \
+  --channel-id ch_... \
+  --user-id me \
+  --delivery-channel main \
+  --api-base-url https://api.watch.qordinate.ai
+```
+
+The command writes:
+
+- `gateway.platforms.watchline` for delivery.
+- `mcp_servers.watchline` for hosted watch tools.
+
+Restart the Hermes gateway after changing plugin or MCP config:
+
+```bash
+hermes gateway restart
+```
+
+## Use
+
+Ask Hermes to use Watchline:
+
+```text
+Use the Watchline start_watch tool to watch Gmail for emails from my boss.
+Ask me for the sender email address if needed.
+```
+
+When a matching event arrives, Watchline queues it on your pull channel. The
+plugin polls that channel, runs Hermes against your main/home channel, and
+acknowledges the delivery only after Hermes accepts it.
+
+## Commands
+
+```bash
+hermes watchline status
+hermes watchline install-mcp
+hermes watchline preview-delivery
+```
+
+## Configuration Reference
+
+| Field                   | Required | Description                                      |
+| ----------------------- | -------- | ------------------------------------------------ |
+| `api_key`               | Yes      | Watchline project API key.                       |
+| `channel_id`            | Yes      | Watchline pull channel ID.                       |
+| `user_id`               | No       | Stable Watchline user id. Defaults to `me`.      |
+| `api_base_url`          | No       | Watchline API base URL. Defaults to production.  |
+| `poll_interval_seconds` | No       | Delivery polling interval. Minimum is 5 seconds. |
+| `delivery_channel`      | No       | Hermes delivery target. Defaults to `main`, the first configured home channel. Use `telegram`, `discord`, or `telegram:<chat_id>[:thread_id]` to override. |
+
+## Links
+
+- Dashboard: <https://watch.qordinate.ai>
+- API: <https://api.watch.qordinate.ai>
+- Source: <https://github.com/qordinate-ai/watchline-hermes-plugin>

watchline_hermes_plugin-0.1.0/README.md

@@ -0,0 +1,100 @@
+# Watchline for Hermes Agent
+
+Watchline is an event layer for agents. This Hermes plugin delivers matched
+Watchline events into a local Hermes gateway without exposing your laptop to
+the internet.
+
+![Watchline Hermes delivery flow](https://watch.qordinate.ai/images/docs/watchline-hermes.png)
+
+Watchline uses two integration planes:
+
+- **Hosted MCP** gives Hermes the watch tools: `start_watch`,
+  `continue_watch`, `list_watches`, `pause_watch`, `resume_watch`, and
+  `delete_watch`.
+- **This plugin** registers a Hermes gateway platform named `watchline`. It
+  polls a Watchline pull channel and forwards matched events as inbound Hermes
+  messages.
+
+The plugin intentionally does not duplicate Watchline tools. Hermes discovers
+tools from the hosted MCP server, and this adapter only handles local delivery.
+
+## Install
+
+```bash
+hermes plugins install qordinate-ai/watchline-hermes-plugin --enable
+```
+
+After the first PyPI release, the package can also be installed directly:
+
+```bash
+python -m pip install watchline-hermes-plugin
+```
+
+For local development:
+
+```bash
+hermes plugins install file:///absolute/path/to/watchline-hermes-plugin --enable
+```
+
+## Configure
+
+Create a Watchline API key and pull channel at <https://watch.qordinate.ai>,
+then run:
+
+```bash
+hermes watchline configure \
+  --api-key wl_... \
+  --channel-id ch_... \
+  --user-id me \
+  --delivery-channel main \
+  --api-base-url https://api.watch.qordinate.ai
+```
+
+The command writes:
+
+- `gateway.platforms.watchline` for delivery.
+- `mcp_servers.watchline` for hosted watch tools.
+
+Restart the Hermes gateway after changing plugin or MCP config:
+
+```bash
+hermes gateway restart
+```
+
+## Use
+
+Ask Hermes to use Watchline:
+
+```text
+Use the Watchline start_watch tool to watch Gmail for emails from my boss.
+Ask me for the sender email address if needed.
+```
+
+When a matching event arrives, Watchline queues it on your pull channel. The
+plugin polls that channel, runs Hermes against your main/home channel, and
+acknowledges the delivery only after Hermes accepts it.
+
+## Commands
+
+```bash
+hermes watchline status
+hermes watchline install-mcp
+hermes watchline preview-delivery
+```
+
+## Configuration Reference
+
+| Field                   | Required | Description                                      |
+| ----------------------- | -------- | ------------------------------------------------ |
+| `api_key`               | Yes      | Watchline project API key.                       |
+| `channel_id`            | Yes      | Watchline pull channel ID.                       |
+| `user_id`               | No       | Stable Watchline user id. Defaults to `me`.      |
+| `api_base_url`          | No       | Watchline API base URL. Defaults to production.  |
+| `poll_interval_seconds` | No       | Delivery polling interval. Minimum is 5 seconds. |
+| `delivery_channel`      | No       | Hermes delivery target. Defaults to `main`, the first configured home channel. Use `telegram`, `discord`, or `telegram:<chat_id>[:thread_id]` to override. |
+
+## Links
+
+- Dashboard: <https://watch.qordinate.ai>
+- API: <https://api.watch.qordinate.ai>
+- Source: <https://github.com/qordinate-ai/watchline-hermes-plugin>

watchline_hermes_plugin-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "watchline-hermes-plugin"
+version = "0.1.0"
+description = "Hermes Agent delivery adapter for Watchline."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Watchline", email = "support@qordinate.ai" }]
+keywords = ["watchline", "hermes-agent", "agents", "mcp", "plugin", "pull-delivery"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["PyYAML>=6"]
+
+[project.urls]
+Homepage = "https://watch.qordinate.ai"
+Documentation = "https://watch.qordinate.ai/docs/hermes"
+Repository = "https://github.com/qordinate-ai/watchline-hermes-plugin"
+Issues = "https://github.com/qordinate-ai/watchline-hermes-plugin/issues"
+
+[project.entry-points."hermes_agent.plugins"]
+watchline = "watchline_hermes_plugin.adapter"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["watchline_hermes_plugin"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+addopts = ["--import-mode=importlib"]
+testpaths = ["tests"]

watchline_hermes_plugin-0.1.0/setup.cfg

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

watchline_hermes_plugin-0.1.0/tests/test_config.py

@@ -0,0 +1,26 @@
+import tempfile
+from pathlib import Path
+
+from watchline_hermes_plugin.config import (
+    load_hermes_config,
+    patch_mcp_config,
+    patch_watchline_config,
+)
+
+
+def test_configure_writes_platform_and_mcp_config():
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / "config.yaml"
+        config = patch_watchline_config(
+            api_key="wl_test",
+            channel_id="ch_test",
+            user_id="me",
+            path=path,
+        )
+        patch_mcp_config(config, path=path)
+
+        data = load_hermes_config(path)
+        assert "watchline" in data["plugins"]["enabled"]
+        assert data["gateway"]["platforms"]["watchline"]["extra"]["channel_id"] == "ch_test"
+        assert data["mcp_servers"]["watchline"]["headers"]["x-watchline-channel-id"] == "ch_test"
+        assert data["gateway"]["platforms"]["watchline"]["extra"]["delivery_channel"] == "main"

watchline_hermes_plugin-0.1.0/tests/test_delivery.py

@@ -0,0 +1,29 @@
+from watchline_hermes_plugin.delivery import format_delivery, parse_delivery_channel
+
+
+def test_match_delivery_text_contains_intent_and_event():
+    text = format_delivery(
+        {
+            "type": "watchline.match",
+            "intent": "emails from my boss",
+            "event": {"subject": "Launch plan"},
+        },
+    )
+
+    assert "Matched event with user intent: emails from my boss" in text
+    assert '"subject": "Launch plan"' in text
+
+
+def test_parse_default_delivery_channel():
+    channel = parse_delivery_channel("main")
+
+    assert channel.is_main
+
+
+def test_parse_explicit_delivery_channel():
+    channel = parse_delivery_channel("telegram:123:456")
+
+    assert not channel.is_main
+    assert channel.platform == "telegram"
+    assert channel.chat_id == "123"
+    assert channel.thread_id == "456"

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin/__init__.py

@@ -0,0 +1 @@
+"""Watchline Hermes plugin package."""

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin/adapter.py

@@ -0,0 +1,281 @@
+"""Hermes platform adapter for Watchline pull delivery."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+from datetime import datetime
+from typing import Any
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+from gateway.session import SessionSource
+
+from watchline_hermes_plugin.client import WatchlineClient
+from watchline_hermes_plugin.config import (
+    DEFAULT_API_BASE_URL,
+    WATCHLINE_PLATFORM_NAME,
+    config_from_platform,
+    normalize_config,
+)
+from watchline_hermes_plugin.delivery import delivery_id, format_delivery, parse_delivery_channel
+
+logger = logging.getLogger(__name__)
+
+
+class WatchlinePlatformAdapter(BasePlatformAdapter):
+    """Pull Watchline deliveries and feed them into Hermes' normal gateway."""
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config=config, platform=Platform(WATCHLINE_PLATFORM_NAME))
+        self.watchline_config = config_from_platform(config)
+        self.client = WatchlineClient(self.watchline_config)
+        self._poll_task: asyncio.Task | None = None
+        self.gateway_runner: Any | None = None
+
+    @property
+    def name(self) -> str:
+        return "Watchline"
+
+    async def connect(self) -> bool:
+        self._running = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+        return True
+
+    async def disconnect(self) -> None:
+        self._running = False
+        if self._poll_task:
+            self._poll_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._poll_task
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> SendResult:
+        return SendResult(
+            success=False,
+            error=(
+                "Watchline is an inbound delivery adapter and cannot send "
+                "messages back to Watchline."
+            ),
+        )
+
+    async def _poll_loop(self) -> None:
+        while self._running:
+            try:
+                delivered = await self._poll_once()
+                if delivered:
+                    logger.info("Watchline delivered %s event(s) into Hermes", delivered)
+            except Exception as error:
+                logger.warning("Watchline delivery poll failed: %s", error)
+            await asyncio.sleep(self.watchline_config.poll_interval_seconds)
+
+    async def _poll_once(self) -> int:
+        cursor: str | None = None
+        ack_ids: list[str] = []
+        delivered = 0
+        while True:
+            response = await asyncio.to_thread(self.client.pending, limit=50, cursor=cursor)
+            for item in response.get("data", []):
+                if isinstance(item, dict):
+                    await self._deliver(item)
+                    delivery_public_id = delivery_id(item)
+                    if delivery_public_id:
+                        ack_ids.append(delivery_public_id)
+                    delivered += 1
+            next_cursor = response.get("next_cursor")
+            cursor = next_cursor if isinstance(next_cursor, str) and next_cursor else None
+            if not cursor:
+                break
+        await asyncio.to_thread(self.client.ack, ack_ids)
+        return delivered
+
+    async def _deliver(self, delivery: dict[str, Any]) -> None:
+        if not self.gateway_runner:
+            raise RuntimeError("Hermes gateway runner is not ready.")
+        if not self._message_handler:
+            raise RuntimeError("Hermes gateway message handler is not ready.")
+        source = self._resolve_delivery_source(delivery)
+        message_id = delivery_id(delivery) or None
+        event = MessageEvent(
+            text=format_delivery(delivery),
+            message_type=MessageType.TEXT,
+            source=source,
+            raw_message=delivery,
+            message_id=message_id,
+            timestamp=datetime.now(),
+            internal=True,
+        )
+        response_text = await self.gateway_runner._handle_message(event)
+        if not response_text:
+            return
+
+        adapter = self.gateway_runner.adapters.get(source.platform)
+        if not adapter:
+            raise RuntimeError(f"Hermes adapter for {source.platform.value} is not active.")
+        metadata = {"thread_id": source.thread_id} if source.thread_id else None
+        result = await adapter.send(
+            chat_id=source.chat_id,
+            content=response_text,
+            metadata=metadata,
+        )
+        if not getattr(result, "success", False):
+            raise RuntimeError(getattr(result, "error", "Hermes send returned success=False"))
+
+    def _resolve_delivery_source(self, delivery: dict[str, Any]) -> SessionSource:
+        channel = parse_delivery_channel(self.watchline_config.delivery_channel)
+        if channel.is_main:
+            platform, chat_id, chat_name, thread_id = self._main_home_channel()
+        else:
+            platform = Platform(channel.platform or "")
+            if channel.chat_id:
+                chat_id = channel.chat_id
+                chat_name = channel.chat_id
+                thread_id = channel.thread_id
+            else:
+                home = self.gateway_runner.config.get_home_channel(platform)
+                if not home or not home.chat_id:
+                    raise RuntimeError(
+                        f"No Hermes home channel configured for {platform.value}; "
+                        "run /sethome there or set watchline.delivery_channel to "
+                        f"{platform.value}:<chat_id>."
+                    )
+                chat_id = str(home.chat_id)
+                chat_name = home.name
+                thread_id = str(home.thread_id) if home.thread_id else None
+
+        message_id = delivery_id(delivery) or None
+        return SessionSource(
+            platform=platform,
+            chat_id=chat_id,
+            chat_name=chat_name,
+            chat_type="dm",
+            user_id="system:watchline",
+            user_name="Watchline",
+            thread_id=thread_id,
+            message_id=message_id,
+        )
+
+    def _main_home_channel(self) -> tuple[Platform, str, str, str | None]:
+        excluded = {
+            self.platform,
+            Platform.LOCAL,
+            Platform.API_SERVER,
+            Platform.WEBHOOK,
+            Platform.MSGRAPH_WEBHOOK,
+        }
+        for platform in self.gateway_runner.adapters:
+            if platform in excluded:
+                continue
+            home = self.gateway_runner.config.get_home_channel(platform)
+            if home and home.chat_id:
+                return (
+                    platform,
+                    str(home.chat_id),
+                    home.name,
+                    str(home.thread_id) if home.thread_id else None,
+                )
+        raise RuntimeError(
+            "No Hermes main/home channel configured for Watchline delivery. "
+            "Run /sethome in the destination chat or set watchline.delivery_channel "
+            "to <platform>:<chat_id>."
+        )
+
+
+def check_requirements() -> bool:
+    return True
+
+
+def validate_config(config: Any) -> bool:
+    try:
+        config_from_platform(config)
+        return True
+    except Exception:
+        return False
+
+
+def env_enablement() -> dict[str, Any] | None:
+    api_key = os.getenv("WATCHLINE_API_KEY", "").strip()
+    channel_id = os.getenv("WATCHLINE_CHANNEL_ID", "").strip()
+    if not api_key or not channel_id:
+        return None
+    return {
+        "api_key": api_key,
+        "channel_id": channel_id,
+        "user_id": os.getenv("WATCHLINE_USER_ID", "me").strip() or "me",
+        "api_base_url": os.getenv("WATCHLINE_API_BASE_URL", DEFAULT_API_BASE_URL).strip()
+        or DEFAULT_API_BASE_URL,
+        "delivery_channel": os.getenv("WATCHLINE_DELIVERY_CHANNEL", "main").strip() or "main",
+    }
+
+
+def _apply_yaml_config(
+    yaml_cfg: dict[str, Any],
+    platform_cfg: dict[str, Any],
+) -> dict[str, Any] | None:
+    gateway_platforms = (
+        yaml_cfg.get("gateway", {}).get("platforms", {})
+        if isinstance(yaml_cfg.get("gateway"), dict)
+        else {}
+    )
+    raw = (
+        gateway_platforms.get(WATCHLINE_PLATFORM_NAME, {})
+        if isinstance(gateway_platforms, dict)
+        else {}
+    )
+    extra = raw.get("extra", {}) if isinstance(raw, dict) else {}
+    try:
+        normalized = normalize_config(extra)
+    except Exception:
+        return None
+    return {
+        "api_key": normalized.api_key,
+        "channel_id": normalized.channel_id,
+        "user_id": normalized.user_id,
+        "api_base_url": normalized.api_base_url,
+        "poll_interval_seconds": normalized.poll_interval_seconds,
+        "delivery_channel": normalized.delivery_channel,
+    }
+
+
+def register(ctx: Any) -> None:
+    ctx.register_platform(
+        name=WATCHLINE_PLATFORM_NAME,
+        label="Watchline",
+        adapter_factory=lambda cfg: WatchlinePlatformAdapter(cfg),
+        check_fn=check_requirements,
+        validate_config=validate_config,
+        is_connected=validate_config,
+        env_enablement_fn=env_enablement,
+        apply_yaml_config_fn=_apply_yaml_config,
+        allow_all_env="WATCHLINE_ALLOW_ALL_USERS",
+        allowed_users_env="WATCHLINE_ALLOWED_USERS",
+        platform_hint=(
+            "Watchline delivers matched external events. Treat each message as "
+            "fresh event context and avoid saying it came from a human chat."
+        ),
+        emoji="🔔",
+    )
+    _register_cli(ctx)
+
+
+def _register_cli(ctx: Any) -> None:
+    from watchline_hermes_plugin.watchline_cli import build_cli
+
+    ctx.register_cli_command(
+        name=WATCHLINE_PLATFORM_NAME,
+        help="Configure Watchline delivery and hosted MCP for Hermes.",
+        setup_fn=build_cli,
+        handler_fn=None,
+    )

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin/client.py

@@ -0,0 +1,57 @@
+"""Tiny Watchline API client used by the Hermes delivery adapter."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+from watchline_hermes_plugin.config import WatchlineConfig
+
+
+class WatchlineApiError(RuntimeError):
+    pass
+
+
+class WatchlineClient:
+    def __init__(self, config: WatchlineConfig):
+        self.config = config
+
+    def pending(self, *, limit: int = 50, cursor: str | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"channel_id": self.config.channel_id, "limit": limit}
+        if cursor:
+            body["cursor"] = cursor
+        return self._post("/v1/deliveries.pending", body)
+
+    def ack(self, delivery_ids: list[str]) -> None:
+        if not delivery_ids:
+            return
+        self._post(
+            "/v1/deliveries.ack",
+            {"channel_id": self.config.channel_id, "delivery_ids": delivery_ids},
+        )
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        raw_body = json.dumps(body).encode("utf-8")
+        request = Request(
+            f"{self.config.api_base_url.rstrip('/')}{path}",
+            data=raw_body,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.config.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "watchline-hermes-plugin/0.1.0",
+            },
+        )
+        try:
+            with urlopen(request, timeout=30) as response:
+                raw = response.read()
+        except HTTPError as error:
+            detail = error.read().decode("utf-8", errors="replace")
+            raise WatchlineApiError(f"Watchline API returned {error.code}: {detail}") from error
+        if not raw:
+            return {}
+        parsed = json.loads(raw.decode("utf-8"))
+        return parsed if isinstance(parsed, dict) else {}

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin/config.py

@@ -0,0 +1,215 @@
+"""Configuration helpers for the Watchline Hermes plugin.
+
+Hermes platform adapters receive a generic ``PlatformConfig`` object. Keeping
+Watchline-specific validation in this module lets the CLI commands and gateway
+adapter share the same rules.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from os import environ
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - Hermes normally ships PyYAML.
+    yaml = None
+
+DEFAULT_API_BASE_URL = "https://api.watch.qordinate.ai"
+DEFAULT_USER_ID = "me"
+DEFAULT_POLL_INTERVAL_SECONDS = 15
+MIN_POLL_INTERVAL_SECONDS = 5
+HERMES_CONFIG_PATH = Path.home() / ".hermes" / "config.yaml"
+WATCHLINE_PLATFORM_NAME = "watchline"
+DEFAULT_DELIVERY_CHANNEL = "main"
+
+
+@dataclass(frozen=True)
+class WatchlineConfig:
+    api_key: str
+    channel_id: str
+    user_id: str = DEFAULT_USER_ID
+    api_base_url: str = DEFAULT_API_BASE_URL
+    poll_interval_seconds: int = DEFAULT_POLL_INTERVAL_SECONDS
+    delivery_channel: str = DEFAULT_DELIVERY_CHANNEL
+
+    @property
+    def mcp_url(self) -> str:
+        return f"{self.api_base_url.rstrip('/')}/v1/mcp"
+
+
+def normalize_config(value: Any) -> WatchlineConfig:
+    """Normalize config from Hermes ``PlatformConfig.extra`` or raw YAML."""
+
+    raw = value if isinstance(value, dict) else {}
+    api_key = _read_string(raw, "api_key") or environ.get("WATCHLINE_API_KEY", "").strip()
+    channel_id = _read_string(raw, "channel_id") or environ.get("WATCHLINE_CHANNEL_ID", "").strip()
+    user_id = (
+        _read_string(raw, "user_id")
+        or environ.get("WATCHLINE_USER_ID", "").strip()
+        or DEFAULT_USER_ID
+    )
+    api_base_url = (
+        _read_string(raw, "api_base_url")
+        or environ.get("WATCHLINE_API_BASE_URL", "").strip()
+        or DEFAULT_API_BASE_URL
+    )
+    poll_interval_seconds = _read_int(raw, "poll_interval_seconds")
+    if poll_interval_seconds is None:
+        poll_interval_seconds = DEFAULT_POLL_INTERVAL_SECONDS
+    delivery_channel = (
+        _read_string(raw, "delivery_channel")
+        or environ.get("WATCHLINE_DELIVERY_CHANNEL", "").strip()
+        or DEFAULT_DELIVERY_CHANNEL
+    )
+
+    if not api_key:
+        raise ValueError("WATCHLINE_API_KEY or watchline.api_key is required.")
+    if not channel_id:
+        raise ValueError("WATCHLINE_CHANNEL_ID or watchline.channel_id is required.")
+
+    return WatchlineConfig(
+        api_key=api_key,
+        channel_id=channel_id,
+        user_id=user_id,
+        api_base_url=api_base_url.rstrip("/"),
+        poll_interval_seconds=max(MIN_POLL_INTERVAL_SECONDS, poll_interval_seconds),
+        delivery_channel=delivery_channel,
+    )
+
+
+def config_from_platform(platform_config: Any) -> WatchlineConfig:
+    return normalize_config(getattr(platform_config, "extra", {}) or {})
+
+
+def load_hermes_config(path: Path = HERMES_CONFIG_PATH) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    raw = path.read_text(encoding="utf-8")
+    if yaml is None:
+        import json
+
+        loaded = json.loads(raw) if raw.strip() else {}
+    else:
+        loaded = yaml.safe_load(raw)
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def write_hermes_config(data: dict[str, Any], path: Path = HERMES_CONFIG_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists():
+        backup = path.with_suffix(f"{path.suffix}.watchline.bak")
+        backup.write_text(path.read_text(encoding="utf-8"), encoding="utf-8")
+        backup.chmod(0o600)
+    if yaml is None:
+        import json
+
+        rendered = f"{json.dumps(data, indent=2)}\n"
+    else:
+        rendered = yaml.safe_dump(data, sort_keys=False)
+    path.write_text(rendered, encoding="utf-8")
+    path.chmod(0o600)
+
+
+def patch_watchline_config(
+    *,
+    api_key: str,
+    channel_id: str,
+    user_id: str = DEFAULT_USER_ID,
+    api_base_url: str = DEFAULT_API_BASE_URL,
+    poll_interval_seconds: int = DEFAULT_POLL_INTERVAL_SECONDS,
+    delivery_channel: str = DEFAULT_DELIVERY_CHANNEL,
+    path: Path = HERMES_CONFIG_PATH,
+) -> WatchlineConfig:
+    """Write both Hermes platform config and top-level Watchline config."""
+
+    config = normalize_config(
+        {
+            "api_key": api_key,
+            "channel_id": channel_id,
+            "user_id": user_id,
+            "api_base_url": api_base_url,
+            "poll_interval_seconds": poll_interval_seconds,
+            "delivery_channel": delivery_channel,
+        },
+    )
+    data = load_hermes_config(path)
+    plugins = _ensure_dict(data, "plugins")
+    enabled = plugins.setdefault("enabled", [])
+    if not isinstance(enabled, list):
+        enabled = []
+        plugins["enabled"] = enabled
+    if WATCHLINE_PLATFORM_NAME not in enabled:
+        enabled.append(WATCHLINE_PLATFORM_NAME)
+
+    gateway = _ensure_dict(data, "gateway")
+    platforms = _ensure_dict(gateway, "platforms")
+    platforms[WATCHLINE_PLATFORM_NAME] = {
+        "enabled": True,
+        "extra": {
+            "api_key": config.api_key,
+            "channel_id": config.channel_id,
+            "user_id": config.user_id,
+            "api_base_url": config.api_base_url,
+            "poll_interval_seconds": config.poll_interval_seconds,
+            "delivery_channel": config.delivery_channel,
+        },
+    }
+    write_hermes_config(data, path)
+    return config
+
+
+def patch_mcp_config(config: WatchlineConfig, path: Path = HERMES_CONFIG_PATH) -> None:
+    """Install the hosted Watchline MCP server into Hermes config.yaml."""
+
+    data = load_hermes_config(path)
+    mcp_servers = _ensure_dict(data, "mcp_servers")
+    mcp_servers[WATCHLINE_PLATFORM_NAME] = {
+        "url": config.mcp_url,
+        "headers": {
+            "Authorization": f"Bearer {config.api_key}",
+            "x-watchline-channel-id": config.channel_id,
+            "x-watchline-user-id": config.user_id,
+        },
+    }
+    write_hermes_config(data, path)
+
+
+def mcp_config_for_display(config: WatchlineConfig) -> dict[str, Any]:
+    return {
+        "url": config.mcp_url,
+        "headers": {
+            "Authorization": "Bearer wl_...",
+            "x-watchline-channel-id": config.channel_id,
+            "x-watchline-user-id": config.user_id,
+        },
+    }
+
+
+def _ensure_dict(parent: dict[str, Any], key: str) -> dict[str, Any]:
+    value = parent.setdefault(key, {})
+    if not isinstance(value, dict):
+        value = {}
+        parent[key] = value
+    return value
+
+
+def _read_string(raw: dict[str, Any], key: str) -> str | None:
+    value = raw.get(key)
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def _read_int(raw: dict[str, Any], key: str) -> int | None:
+    value = raw.get(key)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str) and value.strip():
+        try:
+            return int(value)
+        except ValueError:
+            return None
+    return None

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin/delivery.py

@@ -0,0 +1,82 @@
+"""Delivery formatting and polling primitives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class DeliveryClient(Protocol):
+    def pending(self, *, limit: int = 50, cursor: str | None = None) -> dict[str, Any]: ...
+
+    def ack(self, delivery_ids: list[str]) -> None: ...
+
+
+def format_delivery(delivery: dict[str, Any]) -> str:
+    """Render a Watchline delivery as the user message Hermes should receive."""
+
+    if delivery.get("type") == "watchline.match":
+        return "\n".join(
+            [
+                f"Matched event with user intent: {delivery.get('intent', '')}",
+                "",
+                "Use this event as fresh context. Only act if the user intent asks for action.",
+                "",
+                "Event:",
+                _stable_json(delivery.get("event", {})),
+            ],
+        )
+    return "\n".join(
+        [
+            f"Watch needs action: {delivery.get('action', '')}",
+            "",
+            f"User intent: {delivery.get('intent', '')}",
+            "",
+            "Connection links:",
+            _stable_json(delivery.get("connect_urls", {})),
+        ],
+    )
+
+
+@dataclass(frozen=True)
+class DeliveryChannel:
+    value: str
+    platform: str | None = None
+    chat_id: str | None = None
+    thread_id: str | None = None
+
+    @property
+    def is_main(self) -> bool:
+        return self.value == "main"
+
+    @property
+    def uses_home_channel(self) -> bool:
+        return self.platform is not None and self.chat_id is None
+
+
+def parse_delivery_channel(value: str | None) -> DeliveryChannel:
+    raw = (value or "main").strip()
+    if not raw or raw.lower() == "main":
+        return DeliveryChannel(value="main")
+
+    parts = raw.split(":", 2)
+    platform = parts[0].strip().lower()
+    chat_id = parts[1].strip() if len(parts) > 1 and parts[1].strip() else None
+    thread_id = parts[2].strip() if len(parts) > 2 and parts[2].strip() else None
+    return DeliveryChannel(
+        value=raw,
+        platform=platform,
+        chat_id=chat_id,
+        thread_id=thread_id,
+    )
+
+
+def delivery_id(delivery: dict[str, Any]) -> str:
+    raw = delivery.get("delivery_id")
+    return str(raw) if raw else ""
+
+
+def _stable_json(value: Any) -> str:
+    import json
+
+    return json.dumps(value, indent=2, sort_keys=True, ensure_ascii=False)

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin/watchline_cli.py

@@ -0,0 +1,116 @@
+"""Hermes CLI commands for Watchline setup."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from watchline_hermes_plugin.config import (
+    DEFAULT_API_BASE_URL,
+    DEFAULT_DELIVERY_CHANNEL,
+    DEFAULT_POLL_INTERVAL_SECONDS,
+    DEFAULT_USER_ID,
+    HERMES_CONFIG_PATH,
+    load_hermes_config,
+    mcp_config_for_display,
+    normalize_config,
+    patch_mcp_config,
+    patch_watchline_config,
+)
+
+
+def build_cli(parser: argparse.ArgumentParser) -> None:
+    subcommands = parser.add_subparsers(dest="watchline_command", required=True)
+
+    configure = subcommands.add_parser("configure", help="Save Watchline Hermes config")
+    configure.add_argument("--api-key", required=True)
+    configure.add_argument("--channel-id", required=True)
+    configure.add_argument("--user-id", default=DEFAULT_USER_ID)
+    configure.add_argument("--api-base-url", default=DEFAULT_API_BASE_URL)
+    configure.add_argument(
+        "--poll-interval-seconds",
+        type=int,
+        default=DEFAULT_POLL_INTERVAL_SECONDS,
+    )
+    configure.add_argument("--delivery-channel", default=DEFAULT_DELIVERY_CHANNEL)
+    configure.set_defaults(func=_configure)
+
+    install_mcp = subcommands.add_parser("install-mcp", help="Install Watchline hosted MCP config")
+    install_mcp.set_defaults(func=_install_mcp)
+
+    status = subcommands.add_parser("status", help="Print Watchline config status")
+    status.set_defaults(func=_status)
+
+    preview = subcommands.add_parser(
+        "preview-delivery",
+        help="Preview a Watchline delivery message",
+    )
+    preview.set_defaults(func=_preview_delivery)
+
+
+def _configure(args: argparse.Namespace) -> None:
+    config = patch_watchline_config(
+        api_key=args.api_key,
+        channel_id=args.channel_id,
+        user_id=args.user_id,
+        api_base_url=args.api_base_url,
+        poll_interval_seconds=args.poll_interval_seconds,
+        delivery_channel=args.delivery_channel,
+    )
+    patch_mcp_config(config)
+    print(f"Saved Watchline platform and MCP config to {HERMES_CONFIG_PATH}.")
+    print("Restart Hermes gateway to load the adapter and MCP tools.")
+
+
+def _install_mcp(_: argparse.Namespace) -> None:
+    config = _read_saved_config()
+    patch_mcp_config(config)
+    print(f"Saved Watchline MCP server to {HERMES_CONFIG_PATH}.")
+    print("Restart Hermes gateway or start a new Hermes session to load MCP tools.")
+
+
+def _status(_: argparse.Namespace) -> None:
+    config = _read_saved_config()
+    display = mcp_config_for_display(config)
+    print("Watchline is configured.")
+    print(f"  channel_id: {config.channel_id}")
+    print(f"  user_id:    {config.user_id}")
+    print(f"  api_base:   {config.api_base_url}")
+    print(f"  delivery:   {config.delivery_channel}")
+    print("")
+    print("Hermes MCP entry:")
+    print(json.dumps(display, indent=2))
+
+
+def _preview_delivery(_: argparse.Namespace) -> None:
+    from watchline_hermes_plugin.delivery import format_delivery
+
+    print(
+        format_delivery(
+            {
+                "type": "watchline.match",
+                "delivery_id": "del_preview",
+                "watch_id": "watch_preview",
+                "user_id": "me",
+                "intent": "urgent billing emails",
+                "event": {
+                    "from": "customer@example.com",
+                    "subject": "Production invoice failure",
+                    "snippet": "Our invoice payment is failing before renewal.",
+                },
+            },
+        ),
+    )
+
+
+def _read_saved_config() -> Any:
+    data = load_hermes_config()
+    try:
+        platform = data["gateway"]["platforms"]["watchline"]
+        return normalize_config(platform.get("extra", {}))
+    except Exception as error:
+        raise SystemExit(
+            "Watchline is not configured. Run `hermes watchline configure` "
+            f"first. ({error})"
+        ) from error

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: watchline-hermes-plugin
+Version: 0.1.0
+Summary: Hermes Agent delivery adapter for Watchline.
+Author-email: Watchline <support@qordinate.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://watch.qordinate.ai
+Project-URL: Documentation, https://watch.qordinate.ai/docs/hermes
+Project-URL: Repository, https://github.com/qordinate-ai/watchline-hermes-plugin
+Project-URL: Issues, https://github.com/qordinate-ai/watchline-hermes-plugin/issues
+Keywords: watchline,hermes-agent,agents,mcp,plugin,pull-delivery
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6
+Dynamic: license-file
+
+# Watchline for Hermes Agent
+
+Watchline is an event layer for agents. This Hermes plugin delivers matched
+Watchline events into a local Hermes gateway without exposing your laptop to
+the internet.
+
+![Watchline Hermes delivery flow](https://watch.qordinate.ai/images/docs/watchline-hermes.png)
+
+Watchline uses two integration planes:
+
+- **Hosted MCP** gives Hermes the watch tools: `start_watch`,
+  `continue_watch`, `list_watches`, `pause_watch`, `resume_watch`, and
+  `delete_watch`.
+- **This plugin** registers a Hermes gateway platform named `watchline`. It
+  polls a Watchline pull channel and forwards matched events as inbound Hermes
+  messages.
+
+The plugin intentionally does not duplicate Watchline tools. Hermes discovers
+tools from the hosted MCP server, and this adapter only handles local delivery.
+
+## Install
+
+```bash
+hermes plugins install qordinate-ai/watchline-hermes-plugin --enable
+```
+
+After the first PyPI release, the package can also be installed directly:
+
+```bash
+python -m pip install watchline-hermes-plugin
+```
+
+For local development:
+
+```bash
+hermes plugins install file:///absolute/path/to/watchline-hermes-plugin --enable
+```
+
+## Configure
+
+Create a Watchline API key and pull channel at <https://watch.qordinate.ai>,
+then run:
+
+```bash
+hermes watchline configure \
+  --api-key wl_... \
+  --channel-id ch_... \
+  --user-id me \
+  --delivery-channel main \
+  --api-base-url https://api.watch.qordinate.ai
+```
+
+The command writes:
+
+- `gateway.platforms.watchline` for delivery.
+- `mcp_servers.watchline` for hosted watch tools.
+
+Restart the Hermes gateway after changing plugin or MCP config:
+
+```bash
+hermes gateway restart
+```
+
+## Use
+
+Ask Hermes to use Watchline:
+
+```text
+Use the Watchline start_watch tool to watch Gmail for emails from my boss.
+Ask me for the sender email address if needed.
+```
+
+When a matching event arrives, Watchline queues it on your pull channel. The
+plugin polls that channel, runs Hermes against your main/home channel, and
+acknowledges the delivery only after Hermes accepts it.
+
+## Commands
+
+```bash
+hermes watchline status
+hermes watchline install-mcp
+hermes watchline preview-delivery
+```
+
+## Configuration Reference
+
+| Field                   | Required | Description                                      |
+| ----------------------- | -------- | ------------------------------------------------ |
+| `api_key`               | Yes      | Watchline project API key.                       |
+| `channel_id`            | Yes      | Watchline pull channel ID.                       |
+| `user_id`               | No       | Stable Watchline user id. Defaults to `me`.      |
+| `api_base_url`          | No       | Watchline API base URL. Defaults to production.  |
+| `poll_interval_seconds` | No       | Delivery polling interval. Minimum is 5 seconds. |
+| `delivery_channel`      | No       | Hermes delivery target. Defaults to `main`, the first configured home channel. Use `telegram`, `discord`, or `telegram:<chat_id>[:thread_id]` to override. |
+
+## Links
+
+- Dashboard: <https://watch.qordinate.ai>
+- API: <https://api.watch.qordinate.ai>
+- Source: <https://github.com/qordinate-ai/watchline-hermes-plugin>

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_config.py
+tests/test_delivery.py
+watchline_hermes_plugin/__init__.py
+watchline_hermes_plugin/adapter.py
+watchline_hermes_plugin/client.py
+watchline_hermes_plugin/config.py
+watchline_hermes_plugin/delivery.py
+watchline_hermes_plugin/watchline_cli.py
+watchline_hermes_plugin.egg-info/PKG-INFO
+watchline_hermes_plugin.egg-info/SOURCES.txt
+watchline_hermes_plugin.egg-info/dependency_links.txt
+watchline_hermes_plugin.egg-info/entry_points.txt
+watchline_hermes_plugin.egg-info/requires.txt
+watchline_hermes_plugin.egg-info/top_level.txt

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+watchline = watchline_hermes_plugin.adapter

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin.egg-info/requires.txt

@@ -0,0 +1 @@
+PyYAML>=6

watchline_hermes_plugin-0.1.0/watchline_hermes_plugin.egg-info/top_level.txt

@@ -0,0 +1 @@
+watchline_hermes_plugin