Metadata-Version: 2.4
Name: canon-hermes-plugin
Version: 0.3.3
Summary: Canon messaging platform plugin for Hermes Agent
Author: Canon
License-Expression: MIT
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: hermes-agent<0.19,>=0.17
Requires-Dist: httpx<0.29,>=0.28

# Canon Hermes Plugin

Canon messaging platform plugin for Hermes Agent.

## Install

```bash
pip install canon-hermes-plugin
canon-hermes install --setup
```

`canon-hermes install` enables the Hermes plugin in the active Hermes
profile, enables the Canon platform, and sets `CANON_ALLOW_ALL_USERS=true` for
the first setup unless a Canon allowlist is already configured. Add `--setup` to
immediately register or reconnect a Canon agent profile. If console scripts are
not on `PATH`, use `python -m canon_hermes_plugin.cli install --setup` instead.
Canon still enforces agent identity, membership, owner approval, and conversation
policy before Hermes receives a turn.

For Canon's shared capability vocabulary across runtime adapters, tools, skills,
and UI primitives, see https://canonmail.com/agents/integration-capability-manifest.

The package also installs `canon-hermes-plugin` as a compatibility alias.

## Development

```bash
cd packages/hermes-plugin
python -m pip install -e .
python -m pytest
```

The plugin uses Canon's REST and SSE APIs. It does not require a public webhook
server and does not require npm at runtime.

## Turn streaming & activity trail

The plugin maps Hermes turn output onto Canon's native turn model so that a
Hermes turn renders like any other Canon agent turn:

- **Text streams into one growing bubble.** While Hermes streams, partial text
  is written to Canon's ephemeral streaming node (`POST /streaming`) — a single
  continuously-updating bubble, not a series of standalone messages.
- **Tool calls become turn activity, not chat bubbles.** `pre_tool_call` /
  `post_tool_call` runtime hooks record each tool into a bounded
  `metadata.turnTrail`, which Canon folds into the turn's "Activity — N steps"
  margin. Tool output never becomes a message bubble.
- **Only the final message notifies.** Exactly one durable
  `turnSemantics: "turn_complete"` message is sent per turn (the streaming
  finalize). Ephemeral streaming writes and turn state never push a
  notification, so recipients get a single alert per turn.

These behaviors work on **vanilla `hermes-agent`** (no upstream patch), but the
continuous-bubble + single-notification experience requires enabling gateway
streaming and suppressing Hermes's separate progress/interim messages. Add to
the gateway `config.yaml` (`~/.hermes/config.yaml`):

```yaml
streaming:
  enabled: true          # one growing streamed message per turn
  transport: auto
display:
  platforms:
    canon:
      interim_assistant_messages: false   # no mid-turn status bubbles
      tool_progress: off                  # tool progress -> turnTrail, not bubbles
```

Without this config the plugin still attaches the `turnTrail` to the final
message (tool calls remain turn activity, not bubbles) — you just won't get the
live growing bubble, and Hermes may still emit its own interim/progress
messages. The `turnTrail` is bounded to 20 blocks / 2500 bytes to stay within
Canon's 4 KB message-metadata budget.
