@artil-ai/hermes 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @artil-ai/hermes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Artil platform for the [Hermes](https://hermes-agent.nousresearch.com)
+gateway. New email and texts to the agent account, and wake-ups from its team,
+reach the gateway as notices that `artil internal hermes-channel` prints, from
+where it left off; the agent answers them with the `artil` CLI.
+
+## Usage
+
+Install the [Artil CLI](https://artil.dev/INSTALL.md), sign in as the agent with
+`artil auth login`, and let it set up the plugin and the `artil` skill:
+
+```sh
+artil plugin install hermes
+```
+
+Or install the plugin with Hermes:
+
+```sh
+hermes plugins install artilai/plugins/plugins/hermes --enable
+```
+
+The gateway runs the `artil` that `platforms.artil.extra.command` names in
+Hermes' `config.yaml`, else the one on its PATH, else `~/.local/bin/artil`. See
+[Hermes](https://docs.artil.dev/hermes) in the docs.
+
+While the gateway runs, the plugin keeps `artil internal hermes-channel`
+running, which reaches Artil with the CLI's login. The plugin sends nothing
+itself: the agent answers with `artil` commands.
+
+| Entry point   | What it is                                              |
+| ------------- | ------------------------------------------------------- |
+| `plugin.yaml` | The plugin manifest; Hermes 0.21.5 or later loads it    |
+| `__init__.py` | The `artil` gateway platform and its system-prompt hint |
+
+## Development
+
+From the repository root, lint and format the plugin with
+[ruff](https://docs.astral.sh/ruff), then validate and test it inside the Hermes
+image:
+
+```sh
+uvx ruff check && uvx ruff format --check
+docker run --rm -v "$PWD/plugins/hermes:/plugin" -w /plugin --entrypoint hermes nousresearch/hermes-agent:latest plugins validate .
+docker run --rm -v "$PWD/plugins/hermes:/plugin" -w /plugin --entrypoint sh nousresearch/hermes-agent:latest -c \
+  'uv pip install -q --python /opt/hermes/.venv/bin/python pytest && PYTHONPATH=/opt/hermes /opt/hermes/.venv/bin/python -m pytest -p no:cacheprovider tests'
+```

package/__init__.py

@@ -0,0 +1,157 @@
+"""Artil for Hermes: notices about an agent account's new email and texts reach the gateway."""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platform_registry import PlatformEntry
+from gateway.platforms.base import BasePlatformAdapter, MessageEvent, MessageType, SendResult
+
+PLATFORM = "artil"
+
+HINT = (
+    "Notices about new email and texts to this Artil agent account, and wake-ups from its team, "
+    "arrive here. Read each message with the artil command its notice names, and answer it with "
+    "`artil email send --reply-to` or `artil sms send --reply-to`. "
+    "Nobody outside reads what you write in this conversation."
+)
+
+
+class ArtilAdapter(BasePlatformAdapter):
+    """Runs `artil internal hermes-channel` and hands each notice it prints to the gateway."""
+
+    STOP_GRACE_SECONDS = 2.0
+
+    def __init__(self, config: PlatformConfig) -> None:
+        config.extra = {**(config.extra or {}), "allow_from": [PLATFORM]}
+        super().__init__(config, Platform(PLATFORM))
+        # A gateway service may not have the PATH that finds artil where its installer put it.
+        self._command = str(
+            config.extra.get("command") or shutil.which("artil") or Path.home() / ".local/bin/artil"
+        )
+        self._process: asyncio.subprocess.Process | None = None
+        self._listening: asyncio.Task | None = None
+
+    async def connect(self, *, is_reconnect: bool = False) -> bool:
+        try:
+            process = await asyncio.create_subprocess_exec(
+                self._command,
+                "internal",
+                "hermes-channel",
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                start_new_session=True,
+            )
+        except OSError as error:
+            self._set_fatal_error(
+                "artil_missing", f"Could not run {self._command}: {error}", retryable=False
+            )
+            return False
+
+        self._process = process
+        self._listening = asyncio.create_task(self._listen(process))
+        self._mark_connected()
+        return True
+
+    async def _listen(self, process: asyncio.subprocess.Process) -> None:
+        problem = asyncio.create_task(process.stderr.read())
+
+        async for line in process.stdout:
+            await self._deliver(json.loads(line))
+
+        reason = (await problem).decode().strip()
+        code = await process.wait()
+        asked_to_stop = code in (0, -2, -15)
+
+        if asked_to_stop:
+            await asyncio.sleep(self.STOP_GRACE_SECONDS)
+
+        if process is not self._process or getattr(
+            self.gateway_runner, "_stop_requested_by_signal", False
+        ):
+            return
+
+        self._process = None
+        self._set_fatal_error(
+            "artil_stopped", reason or f"{self._command} stopped", retryable=asked_to_stop
+        )
+        await self._notify_fatal_error()
+
+    async def _deliver(self, notice: dict[str, Any]) -> None:
+        meta = notice.get("meta") or {}
+        source = self.build_source(
+            chat_id=PLATFORM,
+            chat_name="Artil",
+            chat_type="dm",
+            user_id=PLATFORM,
+            user_name="Artil",
+        )
+
+        await self.handle_message(
+            MessageEvent(
+                text=notice["content"],
+                message_type=MessageType.TEXT,
+                source=source,
+                message_id=meta.get("message_id"),
+                allow_gateway_control=False,
+            )
+        )
+
+    async def disconnect(self) -> None:
+        process, self._process = self._process, None
+
+        if process is not None and process.returncode is None:
+            process.stdin.close()
+
+            try:
+                await asyncio.wait_for(process.wait(), 5)
+            except TimeoutError:
+                process.kill()
+
+        if self._listening is not None:
+            self._listening.cancel()
+
+        self._mark_disconnected()
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> SendResult:
+        """The agent answers senders with the artil CLI, so its words here stay in the session."""
+        return SendResult(success=True)
+
+    async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
+        return {"name": "Artil", "type": "dm"}
+
+
+def _needs_nothing() -> bool:
+    return True
+
+
+def _service_fields() -> dict[str, Any]:
+    known = {field.name for field in dataclasses.fields(PlatformEntry)}
+    wanted = {"trusted_inbound": True, "display_tier": "minimal"}
+    return {name: value for name, value in wanted.items() if name in known}
+
+
+def register(ctx: Any) -> None:
+    ctx.register_platform(
+        name=PLATFORM,
+        label="Artil",
+        adapter_factory=ArtilAdapter,
+        check_fn=_needs_nothing,
+        platform_hint=HINT,
+        allow_update_command=False,
+        emoji="📨",
+        **_service_fields(),
+    )

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@artil-ai/hermes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Hear about your Artil agent's new messages in the Hermes gateway, and answer them with the artil CLI.",
+  "keywords": [
+    "artil",
+    "hermes-agent"
+  ],
+  "homepage": "https://docs.artil.dev/hermes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/artilai/plugins.git",
+    "directory": "plugins/hermes"
+  },
+  "files": [
+    "plugin.yaml",
+    "__init__.py"
+  ],
+  "exports": {
+    "./plugin.yaml": "./plugin.yaml",
+    "./__init__.py": "./__init__.py"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.yaml

@@ -0,0 +1,11 @@
+name: artil
+label: Artil
+kind: platform
+version: 0.1.1
+description: >
+  New email and texts to an Artil agent account, and wake-ups from its team,
+  reach the Hermes gateway through the artil CLI. The agent answers them with
+  the CLI.
+author: Artil
+homepage: https://docs.artil.dev/hermes
+requires_hermes: ">=0.21.5"