messaging-gateway-operations

Files (4)

• SKILL.md
• mattermost-mobile-slash-commands.md · references/
• mattermost-thread-dm-routing.md · references/
• telegram-topics-and-gateway-routing.md · references/

SKILL.md (first lines)

# Messaging Gateway Operations

## Overview

Use this skill for operational work on Hermes as a messaging bot: verifying that the gateway is running, changing platform behavior in `~/.hermes/config.yaml` or `.env`, restarting the service, proving the bot is connected, and explaining platform routing semantics to the user.

This is a supplement to the protected `hermes-agent` skill. Load `hermes-agent` first for authoritative CLI/config references, then use this skill for the practical messaging-gateway workflow and pitfalls captured from real sessions.

## When to Use

- A messaging platform bot is silent or only responds in some places.
- The user wants group/channel responses without explicit mentions.
- The user asks about Telegram groups, forum topics, private DM topic mode, or thread routing.
- You need to verify that a gateway config change took effect after restart.
- You need to map a platform chat/thread ID from logs or API output into Hermes delivery/config syntax.

Do not use this for model/provider setup unless it directly affects gateway operation; use `hermes-agent` for general Hermes setup.

## Core Workflow

1. Confirm gateway state before changing behavior:
   - `hermes gateway status`
   - inspect recent `~/.hermes/logs/gateway.log` for platform connection lines.

2. Inspect configuration without leaking secrets:
   - Use `hermes config` / `hermes config set` for non-secret config.
   - Read `.env` only to confirm whether keys exist; never reproduce token values.

3. Identify the platform gate:
   - service stopped vs connected
   - platform auth failure vs WebSocket/polling connected
   - allowlist restriction
   - mention requirement / privacy mode
   - platform-native limitation, such as Telegram bots not creating groups
   - thread/topic mismatch

4. Apply the smallest config change and restart the gateway:
   - `hermes config set <section.key> <value>` for YAML settings.
   - `hermes gateway restart` for service-backed gateway.
   - If service is not installed, use `hermes gateway install` or foreground `hermes gateway run` only as a diagnostic.

5. Verify with real output:
   - service active/running
   - platform connected/authenticated
   - relevant log line after restart
   - config value now reads as expected

6. Explain the user-visible behavior in platform terms, not just config terms.

## Session Reset Policy Semantics

When explaining or changing gateway conversation-history resets, inspect both config and implementation semantics before answering. `session_reset.mode` controls which fields are active:

- `idle`: only `idle_minutes` matters; `at_hour` may still appear as a default/inert field but does **not** trigger a 4am reset.
- `daily`: `at_hour` matters; idle timeout is inactive.
- `both`: whichever trigger fires first: daily boundary or idle timeout.
- `none`: no automatic reset; context is managed by compression/manual reset.

If the user asks whether an inert-looking field is “necessary,” answer in behavior terms first: e.g. `mode: idle` + `idle_minutes: 2400` means reset after 40 hours of inactivity, not at 4am. Offer to remove inert fields only for clarity; do not imply they change runtime behavior.

## Mattermost Mobile Slash Command Interception

Mattermost mobile (Android/iOS) intercepts any message that starts with `/` and tries to run it as a native Mattermost slash command before Hermes sees it. The client error usually says `Command with a trigger of '<name>' not found` and suggests adding a leading space. That workaround only helps if the Mattermost adapter normalizes command-shaped leading-space messages before gateway dispatch.

When diagnosing `/approve`, `/deny`, `/restart`, `/new`, `/status`, or similar commands failing only on Mattermost mobile:

1. Confirm whether Mattermost blocked the message client-side (the message never appears in chat) versus Hermes receiving it as normal text.
2. Inspect the Mattermost adapter intake path for strict `message_text.startswith("/")` / `MessageEvent.text.startswith("/")` handling.
3. Preferred low-risk fix: in the Mattermost adapter only, strip leading whitespace **only when** the first non-whitespace character is `/`, then classify as `MessageType.COMMAND`. Preserve leading whitespace for ordinary text.
4. Add regression tests for both `" /approve" -> "/approve" + COMMAND` and `"  hello"` staying TEXT with whitespace preserved.
5. Better UX follow-up: consider a Mattermost `!command` alias, matching Slack/Matrix patterns, and set `typed_command_prefix = "!"` so prompts say `!approve` instead of an unusable mobile `/approve`. Only rewrite `!<known Hermes command>` so casual exclamations remain chat text.
6. Full native solution is Mattermost custom slash-command registration from the central command registry, but it is higher-surface-area: requires integrations permissions, an HTTP endpoint, token validation, team-specific idempotent registration, built-in trigger conflict handling, and careful routing/thread semantics.

See `references/mattermost-mobile-slash-commands.md` for the concise reproduction, local probe, and fix trade-offs.

## Mattermost Mention Gate Pattern

For Mattermost channel messages, `mattermost.require_mention: true` makes Hermes ignore non-DM messages unless the bot is mentioned. If the user wants normal channel prompts to trigger Hermes, set it false and restart:

```bash
hermes config set mattermost.require_mention false
hermes gateway restart
hermes gateway status
```

Verify the config afterward and check that Mattermost reconnects/authenticates in gateway logs. If `allowed_channels` is empty, there is no Hermes-side channel allowlist restriction.

## Mattermost Thread Reply Pattern

For Mattermost threaded replies, the durable switch is `MATTERMOST_REPLY_MODE=thread` in the Hermes env file. `config.yaml` covers gates such as `mattermost.require_mention`, but the adapter currently reads reply mode from the Mattermost env variable / platform extra. Inspect the value without leaking tokens, update it carefully, then restart the gateway from outside the running gateway process:

```bash
# inspect without printing secrets
ENV=$(hermes config env-path)
grep -E '^MATTERMOST_REPLY_MODE=' "$ENV" || true

# set to threaded replies
# Prefer a careful editor or small script; .env is protected because it contains credentials.
# Ensure the final line is exactly:
MATTERMOST_REPLY_MODE=thread

# must be run from a normal shell outside the gateway process, or by the user as /restart
hermes gateway restart
hermes gateway status
```

Important DM/channel split from the local Hermes Mattermost adapter: **DMs intentionally stay flat even when `MATTERMOST_REPLY_MODE=thread` is enabled.** Channel/group posts thread; DMs ignore `root_id` for session routing and send-side delivery refuses to set `root_id` for Mattermost `D` channels. If a Mattermost DM session shows `thread=None`, that is expected after the DM-flat patch, not evidence that channel thread routing broke. There is no live `MATTERMOST_THREAD_DMS` switch in the local adapter unless future code adds one.

If running commands from a Mattermost-originated Hermes session, `hermes gateway restart` may be refused to prevent restart loops. In that case ask the user to run `hermes gateway restart` in a server shell, or use the gateway `/restart` command if allowed in the chat.

Verification options:

1. User-visible: ask the user to post a top-level Mattermost channel message and confirm Hermes replies in a thread; then reply inside that thread and confirm Hermes stays there. Do not use DMs for this verification because DMs intentionally stay flat.
2. API-level: using the bot token locally, create a temporary channel root post with `POST /api/v4/posts`, create a reply with the root post's `root_id`, verify the reply's `root_id` matches, then delete both posts. Never print the token.

Mattermost delivery targets can use `mattermost:<channel_id>:<thread_id>` for proactive delivery into a specific channel thread. DM deliveries should normally remain `mattermost:<dm_channel_id>` flat.

### Diagnosing Mattermost DM “amnesia” after thread/flat changes

From choephix/my-agents, MIT.

More from choephix/my-agents