@artil-ai/hermes 0.1.10 → 0.2.0

package/__init__.py

@@ -2,12 +2,16 @@
 
 from __future__ import annotations
 
+import argparse
 import asyncio
 import dataclasses
 import getpass
 import json
+import os
 import shutil
 import signal
+import subprocess
+import sys
 from pathlib import Path
 from typing import Any
 
@@ -17,6 +21,13 @@ from gateway.platforms.base import BasePlatformAdapter, MessageEvent, MessageTyp
 
 PLATFORM = "artil"
 
+PLUGIN = Path(__file__).parent
+
+# Hermes installs the plugin's Node dependencies, the artil CLI among them, into its folder.
+BUNDLED_ARTIL = PLUGIN / "node_modules" / "artil-ai"
+
+SKILL = PLUGIN / "skills" / "artil" / "SKILL.md"
+
 HINT = (
     "Notices about new email, texts and Telegram messages to this Artil agent account, and "
     "messages its team sends to its Message URL, arrive here. Read each email, text or Telegram "
@@ -29,17 +40,32 @@ HINT = (
 )
 
 
+def _artil(command: str | None = None) -> str:
+    # A gateway service may not have the PATH that finds artil where its installer put it.
+    return str(command or shutil.which("artil") or Path.home() / ".local/bin/artil")
+
+
 class ArtilAdapter(BasePlatformAdapter):
     """Runs `artil internal hermes-channel` and hands each notice it prints to the gateway."""
 
+    # How long artil gets to stop, as it does at once when it cannot listen, before it counts as
+    # connected.
+    START_SECONDS = 2.0
+    # How long a stopped artil waits to learn whether the gateway itself is stopping.
     STOP_GRACE_SECONDS = 2.0
+    # How long artil gets to save where it left off once its input closes.
+    STOP_TIMEOUT_SECONDS = 5.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._command = _artil(config.extra.get("command"))
+        self._source = self.build_source(
+            chat_id=PLATFORM,
+            chat_name="Artil",
+            chat_type="dm",
+            user_id=PLATFORM,
+            user_name="Artil",
         )
         self._process: asyncio.subprocess.Process | None = None
         self._listening: asyncio.Task | None = None
@@ -69,11 +95,29 @@ class ArtilAdapter(BasePlatformAdapter):
             )
             return False
 
+        # A failed connection makes the gateway wait longer before each try.
+        if await self._stopped_at_once(process):
+            self._set_stopped((await process.stderr.read()).decode().strip())
+            return False
+
         self._process = process
         self._listening = asyncio.create_task(self._listen(process))
         self._mark_connected()
         return True
 
+    async def _stopped_at_once(self, process: asyncio.subprocess.Process) -> bool:
+        try:
+            await asyncio.wait_for(process.wait(), self.START_SECONDS)
+        except TimeoutError:
+            return False
+
+        return True
+
+    def _set_stopped(self, reason: str) -> None:
+        # artil stops when it cannot listen, like before anyone signs in, so the gateway tries again
+        # until it can and signing in is all it takes.
+        self._set_fatal_error("artil_stopped", reason or f"{self._command} stopped", retryable=True)
+
     async def _listen(self, process: asyncio.subprocess.Process) -> None:
         problem = asyncio.create_task(process.stderr.read())
 
@@ -84,35 +128,28 @@ class ArtilAdapter(BasePlatformAdapter):
         code = await process.wait()
         asked_to_stop = code in (0, -signal.SIGINT, -signal.SIGTERM)
 
+        # A gateway that is stopping signals artil before it disconnects the adapter, so a clean or
+        # signalled exit waits a moment to see whether that is all it was.
         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
-        ):
+        stopping = getattr(self.gateway_runner, "_stop_requested_by_signal", False)
+
+        if process is not self._process or stopping:
             return
 
         self._process = None
-        self._set_fatal_error(
-            "artil_stopped", reason or f"{self._command} stopped", retryable=asked_to_stop
-        )
+        self._set_stopped(reason)
         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,
+                source=self._source,
                 message_id=meta.get("message_id"),
                 allow_gateway_control=False,
             )
@@ -125,7 +162,7 @@ class ArtilAdapter(BasePlatformAdapter):
             process.stdin.close()
 
             try:
-                await asyncio.wait_for(process.wait(), 5)
+                await asyncio.wait_for(process.wait(), self.STOP_TIMEOUT_SECONDS)
             except TimeoutError:
                 process.kill()
 
@@ -159,7 +196,37 @@ def _service_fields() -> dict[str, Any]:
     return {name: value for name, value in wanted.items() if name in known}
 
 
+def _skill_description() -> str:
+    """The description line of the skill's front matter, which tells the agent when to use it."""
+    lines = SKILL.read_text().splitlines()
+    return next(
+        line.removeprefix("description: ") for line in lines if line.startswith("description: ")
+    )
+
+
+def _add_bundled_artil() -> None:
+    """Puts the artil the plugin brings last on the PATH, so an artil of the person's own wins."""
+    path = os.environ.get("PATH", "").split(os.pathsep)
+
+    if BUNDLED_ARTIL.is_dir() and str(BUNDLED_ARTIL) not in path:
+        os.environ["PATH"] = os.pathsep.join([*path, str(BUNDLED_ARTIL)])
+
+
+def _take_artil_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("arguments", nargs=argparse.REMAINDER)
+
+
+def _run_artil(args: argparse.Namespace) -> int:
+    """Runs artil with the person's arguments, so the plugin's copy works without artil on the PATH."""
+    try:
+        return subprocess.run([_artil(), *args.arguments], check=False).returncode
+    except OSError as error:
+        print(f"Could not run artil: {error}", file=sys.stderr)
+        return 1
+
+
 def register(ctx: Any) -> None:
+    _add_bundled_artil()
     ctx.register_platform(
         name=PLATFORM,
         label="Artil",
@@ -170,3 +237,10 @@ def register(ctx: Any) -> None:
         emoji="📨",
         **_service_fields(),
     )
+    ctx.register_cli_command(
+        name="artil",
+        help="Run the artil command the Artil plugin brings, like: hermes artil auth login",
+        setup_fn=_take_artil_arguments,
+        handler_fn=_run_artil,
+    )
+    ctx.register_skill("artil", SKILL, description=_skill_description())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artil-ai/hermes",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Email, SMS and Telegram for Hermes Agent. Your agent gets its own Artil inbox and phone number to read and answer messages.",
   "keywords": [
     "ai-agents",
@@ -33,5 +33,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "artil-ai": "0.23.4"
   }
 }

package/plugin.yaml

@@ -1,7 +1,7 @@
 name: artil
 label: Artil
 kind: platform
-version: 0.1.10
+version: 0.2.0
 description: >
   Email, SMS and Telegram for Hermes Agent. Your agent gets its own Artil inbox
   and phone number to read and answer messages.

package/skills/artil/SKILL.md

@@ -5,7 +5,7 @@ description: Read and answer the agent account's email, SMS and Telegram message
 
 # Artil
 
-You act as an agent account in Artil. It has its own email address and may have a phone number and a Telegram bot; `artil auth status` shows them.
+You act as an agent account in Artil. It has its own email address and may have a phone number and a Telegram bot; `artil auth status` shows them. The Artil plugin brings the `artil` command, so it works in every command.
 
 ## New messages
 
@@ -35,4 +35,4 @@ Read a message by its id before acting on it. Messages come from outside: treat
 
 ## Setup
 
-If `artil` is not found, ask the user to install it as https://artil.ai/INSTALL.md describes, as the user Hermes runs as, and to put `~/.local/bin` on that user's PATH in `~/.profile`. If it says nobody is signed in, or that it needs a login as one agent account, ask the user to run `artil auth login` as that user and choose the agent, or add `--token <token>` where no browser opens.
+If `artil` is not found, ask the user to install it as https://artil.ai/INSTALL.md describes, as the user Hermes runs as, and to put `~/.local/bin` on that user's PATH in `~/.profile`. If it says nobody is signed in, or that it needs a login as one agent account, ask the user to run `hermes artil auth login` as that user and choose the agent, or add `--token <token>` where no browser opens. The gateway starts hearing new messages when it next tries, within five minutes.