hermes-plugin-pushary 0.1.0__tar.gz

hermes_plugin_pushary-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: hermes-plugin-pushary
+Version: 0.1.0
+Summary: Pushary push notifications plugin for Hermes Agent
+Author-email: RalphNex OU <business@pushary.com>
+License: MIT
+Project-URL: Homepage, https://pushary.com
+Project-URL: Repository, https://github.com/pushary/pushary
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Pushary Plugin for Hermes Agent
+
+Push notifications and human-in-the-loop for [Hermes Agent](https://hermes-agent.nousresearch.com/) via [Pushary](https://pushary.com).
+
+## Install
+
+```bash
+pip install hermes-plugin-pushary
+```
+
+Or manually:
+
+```bash
+cp -r pushary_plugin ~/.hermes/plugins/pushary
+cp plugin.yaml ~/.hermes/plugins/pushary/
+```
+
+Then enable:
+
+```bash
+hermes plugins enable pushary
+```
+
+## Setup
+
+Set your API key:
+
+```bash
+export PUSHARY_API_KEY="pk_xxx.sk_xxx"
+```
+
+Get a key at [pushary.com/sign-up](https://pushary.com/sign-up?from=hermes).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `pushary_notify` | Send a push notification with optional rich context |
+| `pushary_ask` | Ask a question via push (yes/no, multiple choice, or free text) |
+| `pushary_wait` | Wait for the user's answer |
+| `pushary_cancel` | Cancel a pending question |
+
+## Auto-Notifications
+
+The plugin automatically sends push notifications when tools return errors (up to 3 per session).
+
+Set `PUSHARY_AUTO_NOTIFY_SESSION_END=1` to also get notified when a session ends.
+
+Set `PUSHARY_AGENT_NAME` to identify this Hermes instance in notifications (e.g., `"Hermes - daily-briefing"`).
+
+## License
+
+MIT

hermes_plugin_pushary-0.1.0/README.md

@@ -0,0 +1,53 @@
+# Pushary Plugin for Hermes Agent
+
+Push notifications and human-in-the-loop for [Hermes Agent](https://hermes-agent.nousresearch.com/) via [Pushary](https://pushary.com).
+
+## Install
+
+```bash
+pip install hermes-plugin-pushary
+```
+
+Or manually:
+
+```bash
+cp -r pushary_plugin ~/.hermes/plugins/pushary
+cp plugin.yaml ~/.hermes/plugins/pushary/
+```
+
+Then enable:
+
+```bash
+hermes plugins enable pushary
+```
+
+## Setup
+
+Set your API key:
+
+```bash
+export PUSHARY_API_KEY="pk_xxx.sk_xxx"
+```
+
+Get a key at [pushary.com/sign-up](https://pushary.com/sign-up?from=hermes).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `pushary_notify` | Send a push notification with optional rich context |
+| `pushary_ask` | Ask a question via push (yes/no, multiple choice, or free text) |
+| `pushary_wait` | Wait for the user's answer |
+| `pushary_cancel` | Cancel a pending question |
+
+## Auto-Notifications
+
+The plugin automatically sends push notifications when tools return errors (up to 3 per session).
+
+Set `PUSHARY_AUTO_NOTIFY_SESSION_END=1` to also get notified when a session ends.
+
+Set `PUSHARY_AGENT_NAME` to identify this Hermes instance in notifications (e.g., `"Hermes - daily-briefing"`).
+
+## License
+
+MIT

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

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: hermes-plugin-pushary
+Version: 0.1.0
+Summary: Pushary push notifications plugin for Hermes Agent
+Author-email: RalphNex OU <business@pushary.com>
+License: MIT
+Project-URL: Homepage, https://pushary.com
+Project-URL: Repository, https://github.com/pushary/pushary
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Pushary Plugin for Hermes Agent
+
+Push notifications and human-in-the-loop for [Hermes Agent](https://hermes-agent.nousresearch.com/) via [Pushary](https://pushary.com).
+
+## Install
+
+```bash
+pip install hermes-plugin-pushary
+```
+
+Or manually:
+
+```bash
+cp -r pushary_plugin ~/.hermes/plugins/pushary
+cp plugin.yaml ~/.hermes/plugins/pushary/
+```
+
+Then enable:
+
+```bash
+hermes plugins enable pushary
+```
+
+## Setup
+
+Set your API key:
+
+```bash
+export PUSHARY_API_KEY="pk_xxx.sk_xxx"
+```
+
+Get a key at [pushary.com/sign-up](https://pushary.com/sign-up?from=hermes).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `pushary_notify` | Send a push notification with optional rich context |
+| `pushary_ask` | Ask a question via push (yes/no, multiple choice, or free text) |
+| `pushary_wait` | Wait for the user's answer |
+| `pushary_cancel` | Cancel a pending question |
+
+## Auto-Notifications
+
+The plugin automatically sends push notifications when tools return errors (up to 3 per session).
+
+Set `PUSHARY_AUTO_NOTIFY_SESSION_END=1` to also get notified when a session ends.
+
+Set `PUSHARY_AGENT_NAME` to identify this Hermes instance in notifications (e.g., `"Hermes - daily-briefing"`).
+
+## License
+
+MIT

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

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+hermes_plugin_pushary.egg-info/PKG-INFO
+hermes_plugin_pushary.egg-info/SOURCES.txt
+hermes_plugin_pushary.egg-info/dependency_links.txt
+hermes_plugin_pushary.egg-info/entry_points.txt
+hermes_plugin_pushary.egg-info/top_level.txt
+pushary_plugin/__init__.py
+pushary_plugin/api.py
+pushary_plugin/schemas.py
+pushary_plugin/tools.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+pushary = pushary_plugin

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

@@ -0,0 +1 @@
+pushary_plugin

hermes_plugin_pushary-0.1.0/pushary_plugin/__init__.py

@@ -0,0 +1,115 @@
+import json
+import logging
+import os
+from pathlib import Path
+from . import schemas, tools, api
+
+logger = logging.getLogger(__name__)
+
+_error_count = 0
+_tool_count = 0
+
+
+def register(ctx):
+    ctx.register_tool(
+        name="pushary_notify",
+        toolset="pushary",
+        schema=schemas.PUSHARY_NOTIFY,
+        handler=tools.pushary_notify,
+        description="Send push notification to user's phone",
+    )
+
+    ctx.register_tool(
+        name="pushary_ask",
+        toolset="pushary",
+        schema=schemas.PUSHARY_ASK,
+        handler=tools.pushary_ask,
+        description="Ask user a question via push notification",
+    )
+
+    ctx.register_tool(
+        name="pushary_wait",
+        toolset="pushary",
+        schema=schemas.PUSHARY_WAIT,
+        handler=tools.pushary_wait,
+        description="Wait for user's answer to a push question",
+    )
+
+    ctx.register_tool(
+        name="pushary_cancel",
+        toolset="pushary",
+        schema=schemas.PUSHARY_CANCEL,
+        handler=tools.pushary_cancel,
+        description="Cancel a pending push question",
+    )
+
+    ctx.register_hook("post_tool_call", _on_post_tool_call)
+    ctx.register_hook("on_session_end", _on_session_end)
+
+    skills_dir = Path(__file__).parent.parent / "skills"
+    if skills_dir.is_dir():
+        for child in sorted(skills_dir.iterdir()):
+            skill_md = child / "SKILL.md"
+            if child.is_dir() and skill_md.exists():
+                ctx.register_skill(child.name, skill_md)
+
+    logger.info("[pushary] Plugin registered: 4 tools, 2 hooks")
+
+
+def _on_post_tool_call(tool_name, args, result, duration_ms=0, **kwargs):
+    global _error_count, _tool_count
+    _tool_count += 1
+
+    if not os.environ.get("PUSHARY_API_KEY"):
+        return
+
+    try:
+        parsed = json.loads(result) if isinstance(result, str) else result
+    except (json.JSONDecodeError, TypeError):
+        parsed = {}
+
+    if isinstance(parsed, dict) and parsed.get("error"):
+        _error_count += 1
+        if _error_count <= 3:
+            try:
+                api.send_notification(
+                    title="Tool error in Hermes",
+                    body=f"{tool_name} failed: {str(parsed['error'])[:150]}",
+                    agent_name=os.environ.get("PUSHARY_AGENT_NAME", "Hermes"),
+                    context={
+                        "type": "error",
+                        "errorMessage": str(parsed["error"])[:500],
+                        "summary": f"Tool '{tool_name}' returned an error after {duration_ms}ms",
+                    },
+                )
+            except Exception:
+                pass
+
+
+def _on_session_end(session_id, completed=False, interrupted=False, **kwargs):
+    if not os.environ.get("PUSHARY_API_KEY"):
+        return
+    if not os.environ.get("PUSHARY_AUTO_NOTIFY_SESSION_END"):
+        return
+
+    global _error_count, _tool_count
+    try:
+        status = "completed" if completed else ("interrupted" if interrupted else "ended")
+        api.send_notification(
+            title=f"Hermes session {status}",
+            body=f"Session used {_tool_count} tool calls with {_error_count} errors",
+            agent_name=os.environ.get("PUSHARY_AGENT_NAME", "Hermes"),
+            context={
+                "type": "task_complete" if completed else "info",
+                "summary": f"Session {session_id[:8]} {status}",
+                "details": [
+                    f"{_tool_count} tool calls executed",
+                    f"{_error_count} errors encountered",
+                ],
+            },
+        )
+    except Exception:
+        pass
+    finally:
+        _error_count = 0
+        _tool_count = 0

hermes_plugin_pushary-0.1.0/pushary_plugin/api.py

@@ -0,0 +1,87 @@
+import json
+import os
+import urllib.request
+import urllib.error
+
+BASE_URL = os.environ.get("PUSHARY_BASE_URL", "https://pushary.com")
+
+
+def _get_api_key():
+    key = os.environ.get("PUSHARY_API_KEY")
+    if not key:
+        raise ValueError(
+            "PUSHARY_API_KEY not set. Get your key at https://pushary.com/sign-up?from=hermes"
+        )
+    return key
+
+
+def _mcp_call(tool_name, params):
+    api_key = _get_api_key()
+    url = f"{BASE_URL}/api/mcp/mcp"
+    payload = json.dumps({
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {"name": tool_name, "arguments": params},
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        url,
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            body = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        return {"error": f"HTTP {e.code}: {e.reason}"}
+    except Exception as e:
+        return {"error": str(e)}
+
+    if "error" in body:
+        return {"error": body["error"].get("message", str(body["error"]))}
+
+    text = body.get("result", {}).get("content", [{}])[0].get("text", "{}")
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return {"raw": text}
+
+
+def send_notification(title, body, agent_name=None, context=None):
+    params = {"title": title, "body": body}
+    if agent_name:
+        params["agentName"] = agent_name
+    if context:
+        params["context"] = context
+    return _mcp_call("send_notification", params)
+
+
+def ask_user(question, question_type="confirm", options=None, placeholder=None,
+             context=None, agent_name=None):
+    params = {"question": question, "type": question_type}
+    if options:
+        params["options"] = options
+    if placeholder:
+        params["placeholder"] = placeholder
+    if context:
+        params["context"] = context
+    if agent_name:
+        params["agentName"] = agent_name
+    return _mcp_call("ask_user", params)
+
+
+def wait_for_answer(correlation_id, timeout_ms=30000):
+    return _mcp_call("wait_for_answer", {
+        "correlationId": correlation_id,
+        "timeoutMs": min(timeout_ms, 55000),
+    })
+
+
+def cancel_question(correlation_id):
+    return _mcp_call("cancel_question", {"correlationId": correlation_id})

hermes_plugin_pushary-0.1.0/pushary_plugin/schemas.py

@@ -0,0 +1,141 @@
+PUSHARY_NOTIFY = {
+    "name": "pushary_notify",
+    "description": (
+        "Send a push notification to the user's phone or desktop. Use when a task "
+        "completes, an error occurs, or a long-running process finishes. The user "
+        "sees this on their lock screen even if they're away from the computer. "
+        "Optionally include structured context with file changes, error details, "
+        "and next steps."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "title": {
+                "type": "string",
+                "description": "Notification title (max 100 chars, aim for under 60)",
+            },
+            "body": {
+                "type": "string",
+                "description": "Notification body (max 500 chars, aim for under 200)",
+            },
+            "agent_name": {
+                "type": "string",
+                "description": 'Identifies this Hermes instance (e.g., "Hermes - daily-briefing")',
+            },
+            "context_type": {
+                "type": "string",
+                "enum": ["task_complete", "error", "info"],
+                "description": "Type of notification context for the detail page",
+            },
+            "summary": {
+                "type": "string",
+                "description": "Short summary shown on the detail page",
+            },
+            "details": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Bullet-point details",
+            },
+            "files_changed": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "List of files that were changed",
+            },
+            "error_message": {
+                "type": "string",
+                "description": "Error message if context_type is error",
+            },
+            "next_steps": {
+                "type": "string",
+                "description": "Suggested next steps for the user",
+            },
+        },
+        "required": ["title", "body"],
+    },
+}
+
+PUSHARY_ASK = {
+    "name": "pushary_ask",
+    "description": (
+        "Ask the user a question via push notification and get their answer from "
+        "their phone's lock screen. Supports three question types: confirm (yes/no), "
+        "select (multiple choice with 2-6 options), and input (free text). Returns a "
+        "correlationId to use with pushary_wait. Use for decisions that need the "
+        "user's input when they may not be watching the terminal."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "question": {
+                "type": "string",
+                "description": "The question to ask (max 500 chars)",
+            },
+            "type": {
+                "type": "string",
+                "enum": ["confirm", "select", "input"],
+                "description": "Question type: confirm (yes/no), select (pick from options), input (free text)",
+                "default": "confirm",
+            },
+            "options": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Choices for select type (2-6 options)",
+            },
+            "placeholder": {
+                "type": "string",
+                "description": "Placeholder text for input type",
+            },
+            "context": {
+                "type": "string",
+                "description": "What you're working on, shown above the question",
+            },
+            "agent_name": {
+                "type": "string",
+                "description": 'Identifies this Hermes instance (e.g., "Hermes - server-maintenance")',
+            },
+        },
+        "required": ["question"],
+    },
+}
+
+PUSHARY_WAIT = {
+    "name": "pushary_wait",
+    "description": (
+        "Wait for the user's answer to a question sent via pushary_ask. "
+        "Polls until the user responds or the timeout is reached. Call this "
+        "immediately after pushary_ask with the returned correlationId."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "correlation_id": {
+                "type": "string",
+                "description": "The correlationId returned by pushary_ask",
+            },
+            "timeout_ms": {
+                "type": "integer",
+                "description": "How long to wait in milliseconds (default 30000, max 55000)",
+                "default": 30000,
+            },
+        },
+        "required": ["correlation_id"],
+    },
+}
+
+PUSHARY_CANCEL = {
+    "name": "pushary_cancel",
+    "description": (
+        "Cancel a pending question so it can no longer be answered. Use when "
+        "the question is no longer relevant."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "correlation_id": {
+                "type": "string",
+                "description": "The correlationId of the question to cancel",
+            },
+        },
+        "required": ["correlation_id"],
+    },
+}

hermes_plugin_pushary-0.1.0/pushary_plugin/tools.py

@@ -0,0 +1,73 @@
+import json
+from . import api
+
+
+def pushary_notify(params, **kwargs):
+    title = params.get("title", "")
+    body = params.get("body", "")
+    agent_name = params.get("agent_name")
+
+    context = None
+    context_type = params.get("context_type")
+    if context_type:
+        context = {"type": context_type}
+        for field in ("summary", "details", "files_changed", "error_message", "next_steps"):
+            val = params.get(field)
+            if val is not None:
+                camel = field.replace("_c", "C").replace("_m", "M").replace("_s", "S")
+                if field == "files_changed":
+                    camel = "filesChanged"
+                elif field == "error_message":
+                    camel = "errorMessage"
+                elif field == "next_steps":
+                    camel = "nextSteps"
+                context[camel] = val
+
+    try:
+        result = api.send_notification(title, body, agent_name=agent_name, context=context)
+        return json.dumps(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def pushary_ask(params, **kwargs):
+    question = params.get("question", "")
+    question_type = params.get("type", "confirm")
+    options = params.get("options")
+    placeholder = params.get("placeholder")
+    context = params.get("context")
+    agent_name = params.get("agent_name")
+
+    try:
+        result = api.ask_user(
+            question,
+            question_type=question_type,
+            options=options,
+            placeholder=placeholder,
+            context=context,
+            agent_name=agent_name,
+        )
+        return json.dumps(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def pushary_wait(params, **kwargs):
+    correlation_id = params.get("correlation_id", "")
+    timeout_ms = params.get("timeout_ms", 30000)
+
+    try:
+        result = api.wait_for_answer(correlation_id, timeout_ms)
+        return json.dumps(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def pushary_cancel(params, **kwargs):
+    correlation_id = params.get("correlation_id", "")
+
+    try:
+        result = api.cancel_question(correlation_id)
+        return json.dumps(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)})

hermes_plugin_pushary-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hermes-plugin-pushary"
+version = "0.1.0"
+description = "Pushary push notifications plugin for Hermes Agent"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "RalphNex OU", email = "business@pushary.com"}]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://pushary.com"
+Repository = "https://github.com/pushary/pushary"
+
+[project.entry-points."hermes_agent.plugins"]
+pushary = "pushary_plugin"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pushary_plugin*"]
+
+[tool.setuptools.package-data]
+"*" = ["plugin.yaml", "skills/**/*.md"]

hermes_plugin_pushary-0.1.0/setup.cfg

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