Metadata-Version: 2.4
Name: hermes-bus-plugin
Version: 0.3.1
Summary: Hermes bus integration plugin — auto-start, auto-register, message injection, bus tools
Author-email: LinQuan <i@linquan.name>
License: MIT
Project-URL: homepage, https://github.com/mlinquan/hermes-bus-plugin
Project-URL: repository, https://github.com/mlinquan/hermes-bus-plugin
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-bus-plugin

[English](./README.md) | [中文](./README.zh.md)

Hermes Agent plugin for message bus integration — lifecycle management, external message injection, bus tools.

A thin integration layer between Hermes Agent and the `hermes-bus` / `hermes-notify` packages.

## Install

```bash
# Via Hermes plugin manager
hermes plugins install hermes-bus-plugin

# Or copy to ~/.hermes/hermes-agent/plugins/
cp -r hermes-bus-plugin ~/.hermes/hermes-agent/plugins/
hermes plugins enable hermes-bus-plugin
```

## Session Naming

Each CLI window registers a unique bus endpoint on startup. The default endpoint is `hermes-bus` (first session), with `hermes-bus-2`, `hermes-bus-3`, etc. for additional sessions. To give your session a stable name that survives reconnection:

```bash
/title my-agent-name
```

The plugin uses the title set by `/title` as the bus endpoint name.

| Action | When | Description |
|--------|------|-------------|
| Start bus daemon | Plugin load | Ensures hermes-bus is running |
| Register listener | Plugin load | Opens a bus endpoint for incoming messages |
| Print notifications | On bus message | Messages matching notify.yaml rules with `print: true` are printed to terminal immediately |
| Inject context | `pre_llm_call` | Queued bus messages (matching rules with `context: true`) are injected into LLM context |

## Provided Tools

**bus_send** — send a message through the bus to any endpoint:
```
bus_send(target="notifier", type="progress", text="50% done")
```

**bus_status** — check bus health and connected endpoints:
```
bus_status()
```

**bus_info** — show current session's bus connection details:
```
bus_info()
```

## Route Rules

Messages arriving at the bus are matched against `~/.hermes/bus-rules.yaml` rules.
Each rule can trigger three independent actions — all, some, or none:

| Field | Behavior | Default |
|-------|----------|---------|
| `print` | Print to terminal immediately | `false` |
| `print_format` | Template for terminal output (see below) | `[{from}] {text}` |
| `context` | Inject into LLM context on next agent call | `false` |
| `command` | Execute shell command (audio, script, etc.) | none |

The three actions are **independent** — `print: true` and `context: true` and a `command`
will all fire for the same message.

### Print Format

`print_format` supports ANSI colors and placeholders:

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `{from}` | Sender endpoint name | `银锭` |
| `{text}` | Message body text | `任务完成` |
| `{type}` | Message type | `task_done` |
| `{ts}` | Unix timestamp (raw) | `1744986323` |
| `{ts:%Y-%m-%d %H:%M:%S}` | strftime formatted | `2026-05-18 17:45:23` |
| `{color:cyan}` | Foreground color | `black`/`red`/`green`/`yellow`/`blue`/`magenta`/`cyan`/`white` |
| `{color:bold_green}` | Bold color variant | `bold_red`, `bold_green`, ... |
| `{bold}` | Bold text | |
| `{reset}` | Reset all styles | |

Example rule with all three actions:

```yaml
callbacks:
  - match_type: task_done
    print: true
    print_format: "{color:bold_green}✔ {from}{reset}  {color:cyan}[{ts:%H:%M:%S}]{reset}  {text}"
    context: true
    command: "afplay ~/sounds/done.mp3"
```

## Requirements

- `hermes-bus` (pip)
- `hermes-notify` (pip)

Both are auto-detected — the plugin degrades gracefully if they're missing.

## Architecture

```
External process ──→ hermes-bus ──→ hermes-bus-plugin ──→ LLM context
                        (socket)        (pre_llm_call hook)
                        
Hermes session ──→ bus_send tool ──→ hermes-bus ──→ target endpoint
```
