feat(mattermost): add sticky thread routing

[wangai-studio]

What does this PR do?

Adds thread-aware Mattermost routing with a configurable sticky-thread mode.

This change targets the case where an agent is explicitly @mentioned inside a Mattermost thread. After that first explicit mention, the thread can stay bound to the active agent so later replies in the same thread do not need another @mention.

It also fixes the thread reply payload to prefer metadata.thread_id as the authoritative Mattermost thread root when MATTERMOST_REPLY_MODE=thread, while keeping MATTERMOST_REPLY_MODE=off as flat-channel behavior.

This PR overlaps with existing Mattermost thread work in #4230 and #6617, but adds two things that are not covered there:

• a configurable MATTERMOST_THREAD_STICKY mode
• persistent active-thread ownership shared across gateway processes via a small SQLite state store

It does not try to solve the separate scenario where a user opens a brand-new child thread under an agent-authored mainline post and expects that new thread to auto-inherit the agent without a fresh @mention.

Related Issue

Related to #4221
Related to #6617

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• 🔒 Security fix
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• add gateway/platforms/mattermost_thread_state.py with a shared SQLite-backed thread ownership store
• update gateway/platforms/mattermost.py to:
  • support MATTERMOST_THREAD_STICKY
  • allow already-claimed Mattermost threads to bypass repeated mention gating
  • switch thread ownership when another agent is explicitly mentioned
  • load visible Mattermost thread transcript when a different agent first enters the thread
  • prefer metadata.thread_id over reply_to when sending threaded replies
• add Mattermost gateway tests covering sticky routing, thread ownership persistence, transcript loading, and root_id selection
• document MATTERMOST_THREAD_STICKY and clarify MATTERMOST_REPLY_MODE in:
  • website/docs/reference/environment-variables.md
  • website/docs/user-guide/messaging/mattermost.md

How to Test

1. Create a Mattermost thread and @mention an agent inside it.
2. Reply again in the same thread without another @mention and confirm the same agent continues the conversation.
3. In the same thread, @mention a different agent and confirm the new agent replies in the thread and becomes the active agent for later unmentioned replies.
4. Set MATTERMOST_THREAD_STICKY=false and confirm unmentioned follow-ups in a thread are ignored.
5. Set MATTERMOST_REPLY_MODE=thread and confirm replies in an existing thread use the correct Mattermost root_id.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu 24.04 (via uv run --extra dev pytest tests/gateway/test_mattermost.py -q)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Targeted test run:

uv run --extra dev pytest tests/gateway/test_mattermost.py -q
56 passed in 1.76s

[alt-glitch]

Related to #12063 (Mattermost adapter ignores metadata.thread_id). This PR covers the thread_id fix plus adds sticky-thread ownership via SQLite state store.

[teknium1]

Thanks for the focused sticky-thread routing work. The core need remains: current main still drops unmentioned Mattermost channel replies at plugins/platforms/mattermost/adapter.py:849.

Problems

• The PR edits the removed legacy adapter at gateway/platforms/mattermost.py; Mattermost moved to plugins/platforms/mattermost/adapter.py in af973e407, so this needs a plugin-targeted port.
• The metadata.thread_id / root_id work is superseded by current _thread_root_for_send() and _resolve_root_id() at plugins/platforms/mattermost/adapter.py:163-176,326-340 (06161c6ed). Preserve that stronger resolver when salvaging.
• MATTERMOST_THREAD_STICKY is a new behavioral env setting. The existing plugin bridge at plugins/platforms/mattermost/adapter.py:1177-1205 should instead receive a mattermost.thread_sticky config.yaml setting, consistent with AGENTS.md:102-105.
• The environment-variable documentation hunk also removes unrelated current entries.

Suggested changes

• Port only sticky ownership and focused coverage to the plugin adapter; remove obsolete root-routing hunks and unrelated documentation edits.

Automated hermes-sweeper review.

[teknium1]

Current main no longer imports this adapter path: Mattermost was migrated to plugins/platforms/mattermost/adapter.py in af973e407. Port the sticky-state integration to the plugin adapter; this legacy module is absent from HEAD.

[teknium1]

Please make this a mattermost.thread_sticky config.yaml setting and extend the plugin YAML bridge, rather than documenting a new behavioral environment variable. AGENTS.md:102-105 reserves user-facing environment configuration for secrets.