# Hermes Chatto Plugin

A [Chatto](https://github.com/chattocorp/chatto) platform adapter plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Connects your self-hosted Chatto server to Hermes so you can interact with the agent through chat rooms and DMs.

## Features

- **WebSocket realtime** — binary protobuf codec for Chatto's realtime protocol (no protobuf library needed — pure stdlib)
- **ConnectRPC REST API** — JSON over HTTP for outbound messages, room discovery, user lookup
- **Thread support** — `GetThreadEvents` for thread replies, auto-thread creation, proper `threadRootEventId` handling
- **DM support** — DMs always get a response, no threading in DM rooms
- **Mention filtering** — `require_mention` (default true) with `free_response_channels` for no-tag rooms
- **Dynamic room discovery** — auto-joins new rooms without gateway restart
- **Event handling** — `message_posted`, `mention_notification`, `new_dm_notification`, `session_terminated` (force reconnect), `message_retracted`, `user_left_room`, `room_created`, `user_joined_room`
- **Presence broadcasting** — periodic presence refresh
- **Notification dismissal** — marks notifications as read after processing
- **Standalone cron delivery** — works outside the gateway process

## Installation

```bash
# Clone into your Hermes plugins directory
git clone https://github.com/jrimmer/hermes-chatto-plugin.git /tmp/chatto-plugin

# Copy the plugin into place
cp -r /tmp/chatto-plugin/plugins/platforms/chatto ~/.hermes/plugins/platforms/chatto
```

Or if you're using a profile:

```bash
cp -r /tmp/chatto-plugin/plugins/platforms/chatto ~/.hermes/profiles/<profile>/plugins/platforms/chatto
```

## Configuration

Add your Chatto credentials to `~/.hermes/.env`:

```bash
CHATTO_URL=https://chat.example.com
CHATTO_LOGIN=max
CHATTO_PASSWORD=your-password
CHATTO_HOME_CHANNEL=REljMv5Pgolo6Y9
```

Then enable the plugin in `~/.hermes/config.yaml`:

```yaml
plugins:
  enabled:
    - platforms/chatto

gateway:
  platforms:
    chatto:
      enabled: true
      extra:
        url: https://chat.example.com
        require_mention: true
        home_channel: REljMv5Pgolo6Y9
        free_response_channels: []
```

Restart the gateway:

```bash
hermes gateway restart
```

## Configuration Options

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CHATTO_URL` | Yes | Base URL of your Chatto server |
| `CHATTO_LOGIN` | Yes | Chatto username |
| `CHATTO_PASSWORD` | Yes | Chatto password |
| `CHATTO_HOME_CHANNEL` | No | Room ID for cron/notification delivery (defaults to first watched room) |
| `CHATTO_CHANNELS` | No | Comma-separated room IDs to watch (default: all joined rooms) |
| `CHATTO_REQUIRE_MENTION` | No | Only respond to @mentions in rooms (default: true). DMs always respond. |
| `CHATTO_AUTO_THREAD` | No | Auto-create threads for replies in rooms (default: true) |
| `CHATTO_FREE_RESPONSE_CHANNELS` | No | Comma-separated room IDs where bot responds without being tagged |
| `CHATTO_ALLOWED_USERS` | No | Comma-separated Chatto logins allowed to talk to the bot |
| `CHATTO_ALLOW_ALL_USERS` | No | Allow any Chatto user to talk to the bot (true/false) |

### YAML Config

| Key | Default | Description |
|-----|---------|-------------|
| `url` | — | Chatto server URL |
| `require_mention` | `true` | Only respond to @mentions in public rooms |
| `home_channel` | first room | Room ID for cron delivery |
| `free_response_channels` | `[]` | Rooms where the bot responds without being tagged |
| `channels` | all joined | List of room IDs to watch |

## How It Works

The adapter connects to Chatto via two channels:

1. **WebSocket** (`/api/realtime`) — receives realtime events (messages, mentions, DMs, room changes) as binary protobuf frames
2. **ConnectRPC REST** (`/api/connect/`) — sends messages, fetches room events, joins rooms, manages presence

When a message is received:
1. The WebSocket frame is decoded as a protobuf envelope
2. If it's a `message_posted` event, the message body is fetched via REST (`GetRoomEvents` or `GetThreadEvents` for thread replies)
3. The message is dispatched to the Hermes agent
4. The agent's response is sent back via `CreateMessage` with proper threading

## Tested Against

Chatto v0.4.19. Protocol version 1 (binary protobuf over WebSocket).

## License

MIT