hermes-notify 0.1.0__tar.gz

hermes_notify-0.1.0/LICENSE

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

hermes_notify-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: hermes-notify
+Version: 0.1.0
+Summary: A config-driven notification router — rule matching, audio playback, multi-backend command execution
+Author-email: LinQuan <i@linquan.name>
+License: MIT
+Project-URL: homepage, https://github.com/mlinquan/hermes-notify
+Project-URL: repository, https://github.com/mlinquan/hermes-notify
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# hermes-notify
+
+[English](./README.md) | [中文](./README.zh.md)
+
+A config-driven notification router for Hermes Agent — rule matching, context injection, audio playback, and custom command execution.
+
+Transport-agnostic. Reads messages from stdin or a Bus hook, matches against `notify.yaml` rules, and executes the configured action.
+
+## What is this?
+
+hermes-notify is a **message router** for the Hermes Agent ecosystem. When a message arrives (from a bus, a script, or stdin), it checks the message type against your `notify.yaml` rules. If a rule matches, it executes the configured command — anything from a macOS notification to a Slack webhook.
+
+### Quickstart
+
+1. Install: `pip install hermes-notify`
+2. Create a `notify.yaml` config file with a rule (see Configuration below)
+3. Send a message: `notify-hermes --to my-service --type task_done "Hello"`
+4. The callback matches `match_type: task_done` and runs your command
+
+## Install
+
+```bash
+pip install hermes-notify
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/mlinquan/hermes-notify.git
+cd hermes-notify && pip install -e .
+```
+
+## CLI
+
+```bash
+# Send a message to any bus endpoint
+notify-hermes --to my-service --type task_done "Task completed"
+notify-hermes --to my-service --type progress "50% done"
+notify-hermes --to my-service --type ack "Received"
+
+# Send a notification to a tmux session
+notify-agent mysession "Start working"
+notify-agent --simple mysession "FYI: something happened"
+
+# Process a callback message from stdin
+echo '{"body":{"type":"task_done","text":"done"}}' | hermes-callback
+```
+
+## Configuration
+
+Messages are routed by `notify.yaml`. Each callback rule specifies a `match_type` and a `command` to execute:
+
+```yaml
+callbacks:
+  - match_type: task_error
+    print: false
+    context: true
+    command: "notify-send 'Task failed'"
+
+  - match_type: task_done
+    print: false
+    context: true
+    command: "afplay ~/sounds/done.mp3"
+```
+
+Two boolean fields control behavior: `print` (terminal output), `context` (inject into LLM context).
+
+The `command` field receives these environment variables:
+- `MESSAGE` — full message JSON
+- `TYPE` — message type
+- `FROM` — sender endpoint name
+- Stdin — raw message JSON (for backward compatibility)
+
+Example callback scripts are bundled in `examples/`:
+
+```bash
+examples/macos-notify.py    # macOS notification via osascript
+examples/play-sound.py      # Play random sound via afplay  
+examples/slack-notify.sh    # Slack webhook (set SLACK_WEBHOOK_URL)
+```
+
+## Architecture
+
+```
+stdin / Bus hook ──→ bus_callback.py ──→ notify.yaml rules
+                                              │
+                                         Match?
+                                        ├─ yes → execute command
+                                        └─ no  → silent
+
+notify-hermes — Bus message sender
+notify-agent  — tmux notification sender
+```
+
+## Session Aliases
+
+Map tmux session names to human-readable sender names in `notify.yaml`:
+
+```yaml
+session_aliases:
+  session-1: alias-1
+  session-2: alias-2
+
+default_sender: notify-agent
+```

hermes_notify-0.1.0/README.md

@@ -0,0 +1,105 @@
+# hermes-notify
+
+[English](./README.md) | [中文](./README.zh.md)
+
+A config-driven notification router for Hermes Agent — rule matching, context injection, audio playback, and custom command execution.
+
+Transport-agnostic. Reads messages from stdin or a Bus hook, matches against `notify.yaml` rules, and executes the configured action.
+
+## What is this?
+
+hermes-notify is a **message router** for the Hermes Agent ecosystem. When a message arrives (from a bus, a script, or stdin), it checks the message type against your `notify.yaml` rules. If a rule matches, it executes the configured command — anything from a macOS notification to a Slack webhook.
+
+### Quickstart
+
+1. Install: `pip install hermes-notify`
+2. Create a `notify.yaml` config file with a rule (see Configuration below)
+3. Send a message: `notify-hermes --to my-service --type task_done "Hello"`
+4. The callback matches `match_type: task_done` and runs your command
+
+## Install
+
+```bash
+pip install hermes-notify
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/mlinquan/hermes-notify.git
+cd hermes-notify && pip install -e .
+```
+
+## CLI
+
+```bash
+# Send a message to any bus endpoint
+notify-hermes --to my-service --type task_done "Task completed"
+notify-hermes --to my-service --type progress "50% done"
+notify-hermes --to my-service --type ack "Received"
+
+# Send a notification to a tmux session
+notify-agent mysession "Start working"
+notify-agent --simple mysession "FYI: something happened"
+
+# Process a callback message from stdin
+echo '{"body":{"type":"task_done","text":"done"}}' | hermes-callback
+```
+
+## Configuration
+
+Messages are routed by `notify.yaml`. Each callback rule specifies a `match_type` and a `command` to execute:
+
+```yaml
+callbacks:
+  - match_type: task_error
+    print: false
+    context: true
+    command: "notify-send 'Task failed'"
+
+  - match_type: task_done
+    print: false
+    context: true
+    command: "afplay ~/sounds/done.mp3"
+```
+
+Two boolean fields control behavior: `print` (terminal output), `context` (inject into LLM context).
+
+The `command` field receives these environment variables:
+- `MESSAGE` — full message JSON
+- `TYPE` — message type
+- `FROM` — sender endpoint name
+- Stdin — raw message JSON (for backward compatibility)
+
+Example callback scripts are bundled in `examples/`:
+
+```bash
+examples/macos-notify.py    # macOS notification via osascript
+examples/play-sound.py      # Play random sound via afplay  
+examples/slack-notify.sh    # Slack webhook (set SLACK_WEBHOOK_URL)
+```
+
+## Architecture
+
+```
+stdin / Bus hook ──→ bus_callback.py ──→ notify.yaml rules
+                                              │
+                                         Match?
+                                        ├─ yes → execute command
+                                        └─ no  → silent
+
+notify-hermes — Bus message sender
+notify-agent  — tmux notification sender
+```
+
+## Session Aliases
+
+Map tmux session names to human-readable sender names in `notify.yaml`:
+
+```yaml
+session_aliases:
+  session-1: alias-1
+  session-2: alias-2
+
+default_sender: notify-agent
+```

hermes_notify-0.1.0/hermes_notify/__init__.py

@@ -0,0 +1,13 @@
+"""Hermes notification plugin — rule matching, audio playback, display control.
+
+Transport-agnostic.
+Reads messages from stdin JSON or Bus hook, matches against notify.yaml rules.
+
+Multi-backend architecture:
+ stdin / Bus hook -> bus_callback.py -> notify.yaml rules -> execute callback
+
+Current backends:
+ - bus (subprocess hook mode)
+Backends to add:
+ - tmux, stdout, webhook
+"""

hermes_notify-0.1.0/hermes_notify/bus_callback.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Bus message callback router.
+
+Spawned by Bus Server as post-route hook.
+Reads message JSON from stdin, matches callbacks config rules, executes callbacks.
+"""
+import json
+import logging
+import os
+import subprocess
+import sys
+import time
+from typing import Optional
+
+HERMES_HOME = os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))
+_notify_dir = os.path.join(HERMES_HOME, "hermes-notify")
+if os.path.isdir(_notify_dir):
+    sys.path.insert(0, _notify_dir)
+
+CONFIG_PATH = os.path.join(HERMES_HOME, "hermes-notify", "notify.yaml")
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+    datefmt="%Y-%m-%dT%H:%M:%S",
+    filename=os.path.join(HERMES_HOME, "logs", "errors.log"),
+    filemode="a",
+)
+log = logging.getLogger("bus.callback")
+
+# Consecutive failure count: rule_key -> (fail_count, last_fail_time, suppressed)
+_failure_tracker: dict[str, list] = {}
+FAILURE_THRESHOLD = 3
+FAILURE_SUPPRESS_SECONDS = 300  # suppress for 5 minutes after threshold
+
+
+def load_yaml_config(path: str) -> dict:
+    """Load YAML config file (no third-party deps)."""
+    if not os.path.exists(path):
+        log.warning(f"Config file not found: {path}")
+        return {"callbacks": []}
+
+    with open(path) as f:
+        content = f.read()
+
+    config = {"callbacks": []}
+    current_rule = None
+
+    for line in content.split("\n"):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(line) - len(line.lstrip())
+
+        if any(stripped.startswith(f"- {p}:") for p in
+               ["match_type", "command"]):
+            current_rule = {}
+            config["callbacks"].append(current_rule)
+            key, _, val = stripped.lstrip("- ").partition(":")
+            current_rule[key.strip()] = val.strip().strip("'\"")
+
+        elif current_rule is not None and indent >= 4:
+            key, _, val = stripped.partition(":")
+            key = key.strip()
+            val = val.strip().strip("'\"")
+
+            if key == "priority":
+                current_rule[key] = int(val)
+            elif key in ("print", "context"):
+                current_rule[key] = val.lower() in ("true", "yes", "1")
+            elif key == "command":
+                current_rule[key] = os.path.expanduser(val)
+            elif key == "match_type":
+                current_rule[key] = val
+            else:
+                current_rule[key] = val
+
+    return config
+
+
+def should_suppress(rule_key: str) -> bool:
+    """Check if this rule should be suppressed (too many consecutive failures)."""
+    if rule_key not in _failure_tracker:
+        return False
+    count, last_fail, suppressed = _failure_tracker[rule_key]
+    if suppressed and time.time() - last_fail < FAILURE_SUPPRESS_SECONDS:
+        return True
+    if suppressed and time.time() - last_fail >= FAILURE_SUPPRESS_SECONDS:
+        # Unsuppress
+        del _failure_tracker[rule_key]
+        return False
+    return False
+
+
+def record_failure(rule_key: str):
+    """Record one failure."""
+    if rule_key not in _failure_tracker:
+        _failure_tracker[rule_key] = [1, time.time(), False]
+    else:
+        _failure_tracker[rule_key][0] += 1
+        _failure_tracker[rule_key][1] = time.time()
+        if _failure_tracker[rule_key][0] >= FAILURE_THRESHOLD:
+            _failure_tracker[rule_key][2] = True
+            log.warning(
+                f"callback rule [{rule_key}] failed {FAILURE_THRESHOLD} consecutive times, "
+                f"suppressed for {FAILURE_SUPPRESS_SECONDS}s"
+            )
+
+
+def record_success(rule_key: str):
+    """Reset failure count after success."""
+    _failure_tracker.pop(rule_key, None)
+
+
+def pick_best_rule(text: str, msg_type: Optional[str],
+                   callbacks: list[dict]) -> Optional[dict]:
+    """Select best matching rule. Single message triggers once only.
+
+    Match body.type against match_type, pick highest priority.
+    Returns None if no match.
+    """
+    if msg_type:
+        type_matches = [r for r in callbacks if r.get("match_type") == msg_type]
+        if type_matches:
+            return min(type_matches, key=lambda r: r.get("priority", 100))
+
+    return None
+
+
+def run_callback(rule: dict, message: dict):
+    """Execute callback command with MESSAGE/TYPE/FROM as env vars."""
+    command = rule.get("command", "")
+    if not command:
+        return
+
+    body = message.get("body", {})
+    msg_type = body.get("type", "") if isinstance(body, dict) else ""
+    from_ep = message.get("from", "unknown")
+    msg_json = json.dumps(message, ensure_ascii=False)
+
+    rule_key = f"{rule.get('match_type','')}:{rule.get('command','')}"
+
+    if should_suppress(rule_key):
+        return
+
+    env = os.environ.copy()
+    env["MESSAGE"] = msg_json
+    env["TYPE"] = msg_type
+    env["FROM"] = from_ep
+
+    try:
+        proc = subprocess.Popen(
+            command,
+            shell=True,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            env=env,
+        )
+        proc.stdin.write(msg_json.encode())
+        proc.stdin.close()
+        # Let it run asynchronously (no wait)
+        record_success(rule_key)
+    except Exception as e:
+        log.warning(f"callback [{rule_key}] failed: {type(e).__name__}: {e}")
+        record_failure(rule_key)
+
+
+def main():
+    # read stdin
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return
+        msg = json.loads(raw)
+    except json.JSONDecodeError:
+        log.warning("stdin is not valid JSON")
+        return
+    except Exception as e:
+        log.warning(f"stdin read failed: {e}")
+        return
+
+    # Load config
+    config = load_yaml_config(CONFIG_PATH)
+    callbacks = config.get("callbacks", [])
+    if not callbacks:
+        return
+
+    # Extract text and type
+    body = msg.get("body", {})
+    text = body.get("text", "") if isinstance(body, dict) else str(body)
+    msg_type = body.get("type", None) if isinstance(body, dict) else None
+
+    # type exact match, single trigger
+    best = pick_best_rule(text, msg_type, callbacks)
+    if best:
+        run_callback(best, msg)
+
+
+if __name__ == "__main__":
+    main()

hermes_notify-0.1.0/hermes_notify/bus_notifier.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Bus message notification daemon.
+
+Listens to Hermes Bus broadcast messages, matches notify.yaml callbacks
+by body.type against match_type (highest priority wins), then executes
+the configured command with MESSAGE / TYPE / FROM as environment variables.
+"""
+import json
+import logging
+import os
+import signal
+import subprocess
+import sys
+import time
+from typing import Optional
+
+HERMES_HOME = os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))
+_bus_dir = os.path.join(HERMES_HOME, "hermes-bus")
+if os.path.isdir(_bus_dir):
+    sys.path.insert(0, _bus_dir)
+_notify_dir = os.path.join(HERMES_HOME, "hermes-notify")
+DEFAULT_CONFIG = os.path.join(_notify_dir, "notify.yaml")
+DEFAULT_SOCKET = os.path.join(HERMES_HOME, "hermes-bus.sock")
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("bus-notifier")
+
+
+def load_yaml_config(path: str) -> dict:
+    """Load notify.yaml config. Returns dict with callbacks list."""
+    if not os.path.exists(path):
+        log.error(f"Config file not found: {path}")
+        sys.exit(1)
+
+    with open(path) as f:
+        content = f.read()
+
+    config = {"callbacks": []}
+    current_rule = None
+
+    for line in content.split("\n"):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(line) - len(line.lstrip())
+
+        # Top-level callbacks section marker
+        if stripped == "callbacks:":
+            continue
+
+        # New callback entry (starts with "- match_type:" or "- command:" etc.)
+        if stripped.startswith("- ") and ":" in stripped:
+            # Check if this starts a new callback block
+            key = stripped[2:].split(":")[0].strip()
+            if key in ("match_type", "command", "print", "context", "priority"):
+                current_rule = {}
+                config["callbacks"].append(current_rule)
+
+        if current_rule is not None and stripped.startswith("- "):
+            key, _, val = stripped[2:].partition(":")
+            key = key.strip()
+            val = val.strip().strip("'\"")
+
+            if key == "priority":
+                current_rule[key] = int(val)
+            elif key in ("print", "context"):
+                current_rule[key] = val.lower() in ("true", "yes", "1")
+            elif key == "command":
+                current_rule[key] = os.path.expanduser(val)
+            else:
+                current_rule[key] = val
+
+        elif current_rule is not None and indent >= 4:
+            key, _, val = stripped.partition(":")
+            key = key.strip()
+            val = val.strip().strip("'\"")
+
+            if key == "command":
+                current_rule[key] = os.path.expanduser(val)
+            elif key == "priority":
+                current_rule[key] = int(val)
+            elif key in ("print", "context"):
+                current_rule[key] = val.lower() in ("true", "yes", "1")
+            elif key == "match_type":
+                current_rule[key] = val
+            else:
+                current_rule[key] = val
+
+    return config
+
+
+def pick_best_rule(msg_type: Optional[str], callbacks: list[dict]) -> Optional[dict]:
+    """Select best matching callback by body.type exact match against match_type.
+    Highest priority (lowest number) wins. Returns None if no match."""
+    if not msg_type:
+        return None
+    type_matches = [r for r in callbacks if r.get("match_type") == msg_type]
+    if not type_matches:
+        return None
+    return min(type_matches, key=lambda r: r.get("priority", 100))
+
+
+def run_command(rule: dict, msg: dict):
+    """Execute the rule's command with MESSAGE/TYPE/FROM as env vars.
+
+    Also writes the full message JSON to stdin for backward compatibility.
+    """
+    command = rule.get("command", "")
+    if not command:
+        return
+
+    body = msg.get("body", {})
+    msg_type = body.get("type", "") if isinstance(body, dict) else ""
+    from_ep = msg.get("from", "unknown")
+    msg_json = json.dumps(msg, ensure_ascii=False)
+
+    env = os.environ.copy()
+    env["MESSAGE"] = msg_json
+    env["TYPE"] = msg_type
+    env["FROM"] = from_ep
+
+    try:
+        proc = subprocess.Popen(
+            command,
+            shell=True,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            env=env,
+        )
+        proc.stdin.write(msg_json.encode())
+        proc.stdin.close()
+    except Exception as e:
+        log.warning(f"Command failed for type [{msg_type}]: {e}")
+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Bus message notification daemon")
+    parser.add_argument("--config", default=DEFAULT_CONFIG, help="Config file path")
+    parser.add_argument("--socket", default=DEFAULT_SOCKET, help="Bus socket path")
+    parser.add_argument("--dry-run", action="store_true", help="Match only, do not execute commands")
+    parser.add_argument("--poll-interval", type=float, default=1.0, help="Poll interval (seconds)")
+    args = parser.parse_args()
+
+    # Load config
+    config = load_yaml_config(args.config)
+    callbacks = config.get("callbacks", [])
+    if not callbacks:
+        log.error("No callbacks found in config file")
+        sys.exit(1)
+    log.info(f"Loaded {len(callbacks)} callbacks")
+
+    # Connect to Bus
+    log.info(f"Connecting to Bus: {args.socket}")
+    try:
+        from hermes_bus.client import BusClient
+
+        client = BusClient("bus-notifier", socket_path=args.socket)
+        if not client.connect():
+            log.error("Bus connection failed")
+            sys.exit(1)
+        log.info(f"Bus connected (sid={client.bus_session_id[:8] if client.bus_session_id else '?'})")
+    except Exception as e:
+        log.error(f"Bus init failed: {e}")
+        sys.exit(1)
+
+    # Signal handler
+    running = True
+
+    def _shutdown(signum, frame):
+        nonlocal running
+        log.info(f"Received signal {signum}, exiting...")
+        running = False
+
+    signal.signal(signal.SIGTERM, _shutdown)
+    signal.signal(signal.SIGINT, _shutdown)
+
+    # Stats
+    total_messages = 0
+    total_matched = 0
+    total_executed = 0
+
+    # Listen loop
+    log.info("Listening for Bus messages...")
+    log.info(f"  Callbacks: {len(callbacks)} | Dry-run: {args.dry_run}")
+    log.info("-" * 50)
+
+    while running:
+        try:
+            msgs = client.poll()
+        except Exception as e:
+            log.warning(f"Poll exception: {e}")
+            time.sleep(args.poll_interval)
+            continue
+
+        for msg in msgs:
+            total_messages += 1
+
+            body = msg.get("body", {})
+            text = body.get("text", "") if isinstance(body, dict) else str(body)
+            msg_type = body.get("type", None) if isinstance(body, dict) else None
+            from_ep = msg.get("from", "unknown")
+
+            # Match by type
+            best = pick_best_rule(msg_type, callbacks)
+            if best is None:
+                continue
+
+            total_matched += 1
+            rule_type = best.get("match_type", "unknown")
+            command = best.get("command", "")
+
+            log.info(f"Matched [{rule_type}] from={from_ep} text={text[:60]}...")
+
+            if not command:
+                log.info(f"  No command configured for type [{rule_type}], skipping")
+                continue
+
+            if args.dry_run:
+                log.info(f"  [DRY-RUN] Would execute: {command}")
+            else:
+                log.info(f"  Executing: {command}")
+                run_command(best, msg)
+                total_executed += 1
+
+        time.sleep(args.poll_interval)
+
+    # Graceful exit
+    log.info("-" * 50)
+    log.info(f"Stopped. Total messages: {total_messages} | Matched: {total_matched} | Executed: {total_executed}")
+    client.disconnect()
+    log.info("Exited")
+
+
+if __name__ == "__main__":
+    main()

hermes_notify-0.1.0/hermes_notify/notify_agent.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Generic tmux notification tool — sends messages to tmux sessions via send-keys.
+
+Sender name resolution:
+  1. --from override (highest priority)
+  2. notify.yaml default_sender config value
+
+Usage:
+    python3 notify-agent.py --from <sender> <session> <message>
+    python3 notify-agent.py --from <sender> --simple <session> <message>
+    python3 notify-agent.py <session> <message>               # sender from config or none
+"""
+import os
+import sys
+import subprocess
+import time
+
+
+def _get_config_path() -> str:
+    home = os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))
+    return os.path.join(home, "hermes-notify", "notify.yaml")
+
+
+def _load_default_sender(config_path: str = None) -> str:
+    """Load default_sender from notify.yaml config. Falls back to empty string."""
+    path = config_path or _get_config_path()
+    if not os.path.exists(path):
+        return ""
+
+    with open(path) as f:
+        for line in f:
+            stripped = line.strip()
+            if stripped.startswith("default_sender:"):
+                return stripped.split(":", 1)[1].strip()
+    return ""
+
+
+def main():
+    simple_mode = False
+    sender = None
+    config_path = None
+    args = sys.argv[1:]
+
+    # Parse --config
+    if args and args[0] == '--config':
+        if len(args) >= 2:
+            config_path = args[1]
+            args = args[2:]
+        else:
+            print("Usage: --config <path>", file=sys.stderr)
+            sys.exit(1)
+
+    # Parse --from parameter
+    if args and args[0] == '--from':
+        if len(args) >= 2:
+            sender = args[1]
+            args = args[2:]
+        else:
+            print("Usage: --from <sender_name>", file=sys.stderr)
+            sys.exit(1)
+
+    if args and args[0] == '--simple':
+        simple_mode = True
+        args = args[1:]
+
+    if len(args) < 2:
+        print("Usage: python3 notify-agent.py [--config <path>] [--from <sender>] [--simple] <session> <message>",
+              file=sys.stderr)
+        sys.exit(1)
+
+    session = args[0]
+
+    if sender:
+        message = sender + ': ' + ' '.join(args[1:])
+    else:
+        default = _load_default_sender(config_path)
+        if default:
+            message = default + ': ' + ' '.join(args[1:])
+        else:
+            message = ' '.join(args[1:])
+
+    # Clear input area first (C-c to interrupt any running task)
+    subprocess.run(['tmux', 'send-keys', '-t', session, 'C-c'], timeout=3)
+    time.sleep(0.5)
+
+    # Send message
+    subprocess.run(['tmux', 'send-keys', '-t', session, message], timeout=3)
+    time.sleep(0.3)
+
+    # Triple Enter to submit
+    for _ in range(3):
+        subprocess.run(['tmux', 'send-keys', '-t', session, 'Enter'], timeout=3)
+        time.sleep(0.2)
+
+    print(f'OK: notified {session}')
+
+
+if __name__ == "__main__":
+    main()

hermes_notify-0.1.0/hermes_notify/notify_hermes.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""Generic message bus notification sender.
+
+Short-lived connection: connect to bus -> send one message -> disconnect.
+Does not register endpoint, does not pollute endpoint_map.
+
+Sender name resolution:
+  1. --from manual override (highest priority)
+  2. tmux session -> notify.yaml session_aliases lookup
+  3. raw tmux session name (fallback)
+  4. "notify-hermes" (default)
+
+Usage:
+    python3 notify-hermes.py --to <endpoint> "message"
+    python3 notify-hermes.py --to <endpoint> --type task_done "Task done"
+    python3 notify-hermes.py --to <endpoint> --from "MyName" "message"
+    python3 notify-hermes.py --to <endpoint> --body '{"text":"hello"}'
+"""
+import json
+import os
+import socket
+import struct
+import subprocess
+import sys
+import time
+import uuid
+
+
+def _get_config_path() -> str:
+    home = os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))
+    return os.path.join(home, "hermes-notify", "notify.yaml")
+
+
+def _load_config(config_path: str = None) -> dict:
+    """Load notify.yaml config. Returns dict with optional session_aliases."""
+    path = config_path or _get_config_path()
+    config = {}
+    if not os.path.exists(path):
+        return config
+
+    with open(path) as f:
+        content = f.read()
+
+    current_section = None
+    for line in content.split("\n"):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.endswith(":") and not stripped.startswith("-"):
+            current_section = stripped[:-1].strip()
+            if current_section == "session_aliases":
+                config["session_aliases"] = {}
+            elif current_section == "callbacks":
+                config["callbacks"] = []
+            continue
+        if current_section == "session_aliases" and ":" in stripped:
+            key, _, val = stripped.partition(":")
+            config["session_aliases"][key.strip()] = val.strip()
+
+    return config
+
+
+def _resolve_sender_name(override: str = None, config: dict = None) -> str:
+    """Determine sender name.
+
+    Priority: --from manual override > session_aliases lookup > tmux session name > default.
+    """
+    if override:
+        return override
+
+    aliases = (config or {}).get("session_aliases", {})
+
+    # Auto-detect from tmux session
+    try:
+        result = subprocess.run(
+            ["tmux", "display-message", "-p", "#S"],
+            capture_output=True, text=True, timeout=2,
+        )
+        if result.returncode == 0:
+            session = result.stdout.strip()
+            if session:
+                return aliases.get(session, session)
+    except Exception:
+        pass
+
+    return "notify-hermes"
+
+
+def _get_bus_socket_path() -> str:
+    home = os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))
+    return os.path.join(home, "hermes-bus.sock")
+
+
+def _ensure_bus_running(socket_path: str):
+    """Start bus server if not already running."""
+    if os.path.exists(socket_path):
+        test = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        test.settimeout(0.5)
+        try:
+            test.connect(socket_path)
+            test.close()
+            return
+        except Exception:
+            try:
+                os.unlink(socket_path)
+            except Exception:
+                pass
+        finally:
+            test.close()
+
+    # Run bus server via hermes-busd (uses correct Python with package installed)
+    subprocess.Popen(
+        ["hermes-busd", "start"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    for _ in range(40):
+        time.sleep(0.1)
+        if os.path.exists(socket_path):
+            break
+
+
+def _send_frame(sock: socket.socket, msg: dict):
+    data = json.dumps(msg, ensure_ascii=False).encode("utf-8")
+    header = struct.pack(">I", len(data))
+    sock.sendall(header + data)
+
+
+def send_notification(endpoint: str, body: dict, socket_path: str = None,
+                      from_ep: str = None, config: dict = None) -> bool:
+    """Send one message to bus via short-lived connection, then disconnect."""
+    sp = socket_path or _get_bus_socket_path()
+    _ensure_bus_running(sp)
+
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.settimeout(5)
+
+    try:
+        sock.connect(sp)
+    except Exception as e:
+        print(f"ERROR: Cannot connect to bus: {e}", file=sys.stderr)
+        return False
+
+    sender = _resolve_sender_name(from_ep, config)
+    msg = {
+        "type": "message",
+        "to": endpoint,
+        "from": sender,
+        "id": str(uuid.uuid4()),
+        "ts": time.time(),
+        "body": body,
+    }
+
+    try:
+        _send_frame(sock, msg)
+        sock.settimeout(1.0)
+        header = b""
+        while len(header) < 4:
+            try:
+                chunk = sock.recv(4 - len(header))
+            except socket.timeout:
+                return True
+            if not chunk:
+                return True
+            header += chunk
+        if len(header) == 4:
+            payload_len = struct.unpack(">I", header)[0]
+            payload = b""
+            while len(payload) < payload_len:
+                try:
+                    chunk = sock.recv(payload_len - len(payload))
+                except socket.timeout:
+                    break
+                if not chunk:
+                    break
+                payload += chunk
+            if payload:
+                reply = json.loads(payload.decode("utf-8"))
+                if reply.get("type") == "error":
+                    print(f"WARNING: {reply.get('detail', reply)}", file=sys.stderr)
+                    return False
+        return True
+    except socket.timeout:
+        return True
+    except Exception as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return False
+    finally:
+        try:
+            sock.close()
+        except Exception:
+            pass
+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Generic message bus notification sender",
+    )
+    parser.add_argument(
+        "--to",
+        required=True,
+        help="Target endpoint name (any string, e.g. cli, gateway, my-custom-endpoint)",
+    )
+    parser.add_argument(
+        "message",
+        nargs="?",
+        default=None,
+        help="Message text (ignored if --body is set)",
+    )
+    parser.add_argument(
+        "--body",
+        default=None,
+        help="JSON body dict (advanced, overrides positional message)",
+    )
+    parser.add_argument(
+        "--socket",
+        default=None,
+        help="Custom socket path",
+    )
+    parser.add_argument(
+        "--from",
+        dest="from_ep",
+        default=None,
+        help="Override sender name (default: auto-detect from tmux session or config)",
+    )
+    parser.add_argument(
+        "--type",
+        choices=["task_start", "task_done", "plan_ready", "task_error", "need_decision", "ack", "progress"],
+        default=None,
+        help="Message type for callback matching",
+    )
+    parser.add_argument(
+        "--config",
+        default=None,
+        help="Path to notify.yaml config file (for session_aliases)",
+    )
+
+    args = parser.parse_args()
+
+    config = _load_config(args.config)
+
+    if args.body:
+        try:
+            body = json.loads(args.body)
+        except json.JSONDecodeError as e:
+            print(f"ERROR: Invalid JSON body: {e}", file=sys.stderr)
+            sys.exit(1)
+    elif args.message:
+        body = {"text": args.message}
+    else:
+        print("ERROR: Either message text or --body is required", file=sys.stderr)
+        sys.exit(1)
+
+    if args.type:
+        body["type"] = args.type
+
+    success = send_notification(args.to, body, args.socket,
+                                from_ep=args.from_ep, config=config)
+    if success:
+        print(f"OK: notified {args.to}")
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: hermes-notify
+Version: 0.1.0
+Summary: A config-driven notification router — rule matching, audio playback, multi-backend command execution
+Author-email: LinQuan <i@linquan.name>
+License: MIT
+Project-URL: homepage, https://github.com/mlinquan/hermes-notify
+Project-URL: repository, https://github.com/mlinquan/hermes-notify
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# hermes-notify
+
+[English](./README.md) | [中文](./README.zh.md)
+
+A config-driven notification router for Hermes Agent — rule matching, context injection, audio playback, and custom command execution.
+
+Transport-agnostic. Reads messages from stdin or a Bus hook, matches against `notify.yaml` rules, and executes the configured action.
+
+## What is this?
+
+hermes-notify is a **message router** for the Hermes Agent ecosystem. When a message arrives (from a bus, a script, or stdin), it checks the message type against your `notify.yaml` rules. If a rule matches, it executes the configured command — anything from a macOS notification to a Slack webhook.
+
+### Quickstart
+
+1. Install: `pip install hermes-notify`
+2. Create a `notify.yaml` config file with a rule (see Configuration below)
+3. Send a message: `notify-hermes --to my-service --type task_done "Hello"`
+4. The callback matches `match_type: task_done` and runs your command
+
+## Install
+
+```bash
+pip install hermes-notify
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/mlinquan/hermes-notify.git
+cd hermes-notify && pip install -e .
+```
+
+## CLI
+
+```bash
+# Send a message to any bus endpoint
+notify-hermes --to my-service --type task_done "Task completed"
+notify-hermes --to my-service --type progress "50% done"
+notify-hermes --to my-service --type ack "Received"
+
+# Send a notification to a tmux session
+notify-agent mysession "Start working"
+notify-agent --simple mysession "FYI: something happened"
+
+# Process a callback message from stdin
+echo '{"body":{"type":"task_done","text":"done"}}' | hermes-callback
+```
+
+## Configuration
+
+Messages are routed by `notify.yaml`. Each callback rule specifies a `match_type` and a `command` to execute:
+
+```yaml
+callbacks:
+  - match_type: task_error
+    print: false
+    context: true
+    command: "notify-send 'Task failed'"
+
+  - match_type: task_done
+    print: false
+    context: true
+    command: "afplay ~/sounds/done.mp3"
+```
+
+Two boolean fields control behavior: `print` (terminal output), `context` (inject into LLM context).
+
+The `command` field receives these environment variables:
+- `MESSAGE` — full message JSON
+- `TYPE` — message type
+- `FROM` — sender endpoint name
+- Stdin — raw message JSON (for backward compatibility)
+
+Example callback scripts are bundled in `examples/`:
+
+```bash
+examples/macos-notify.py    # macOS notification via osascript
+examples/play-sound.py      # Play random sound via afplay  
+examples/slack-notify.sh    # Slack webhook (set SLACK_WEBHOOK_URL)
+```
+
+## Architecture
+
+```
+stdin / Bus hook ──→ bus_callback.py ──→ notify.yaml rules
+                                              │
+                                         Match?
+                                        ├─ yes → execute command
+                                        └─ no  → silent
+
+notify-hermes — Bus message sender
+notify-agent  — tmux notification sender
+```
+
+## Session Aliases
+
+Map tmux session names to human-readable sender names in `notify.yaml`:
+
+```yaml
+session_aliases:
+  session-1: alias-1
+  session-2: alias-2
+
+default_sender: notify-agent
+```

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

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+hermes_notify/__init__.py
+hermes_notify/bus_callback.py
+hermes_notify/bus_notifier.py
+hermes_notify/notify_agent.py
+hermes_notify/notify_hermes.py
+hermes_notify.egg-info/PKG-INFO
+hermes_notify.egg-info/SOURCES.txt
+hermes_notify.egg-info/dependency_links.txt
+hermes_notify.egg-info/entry_points.txt
+hermes_notify.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,4 @@
+[console_scripts]
+hermes-callback = hermes_notify.bus_callback:main
+notify-agent = hermes_notify.notify_agent:main
+notify-hermes = hermes_notify.notify_hermes:main

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

@@ -0,0 +1 @@
+hermes_notify

hermes_notify-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "hermes-notify"
+version = "0.1.0"
+description = "A config-driven notification router — rule matching, audio playback, multi-backend command execution"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "LinQuan", email = "i@linquan.name"}]
+requires-python = ">=3.10"
+dependencies = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "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 :: Software Development :: Libraries",
+]
+
+[project.urls]
+homepage = "https://github.com/mlinquan/hermes-notify"
+repository = "https://github.com/mlinquan/hermes-notify"
+
+[project.scripts]
+notify-hermes = "hermes_notify.notify_hermes:main"
+notify-agent = "hermes_notify.notify_agent:main"
+hermes-callback = "hermes_notify.bus_callback:main"
+
+[tool.setuptools.packages.find]
+include = ["hermes_notify*"]
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"

hermes_notify-0.1.0/setup.cfg

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