fix(mattermost): make thread routing configurable and reliable

[potatosalad]

What does this PR do?

Rebases the remaining Mattermost thread work onto current main, drops behavior that has already landed upstream, and makes automatic threading explicit for channels and direct messages.

Current main already contains the original PR's progress/media metadata plumbing and top-level channel root behavior. Those duplicate commits are no longer part of this branch.

Remaining changes

• Keep typing indicators inside the active Mattermost thread.

• Cache successful post-to-root lookups while allowing transient lookup failures to retry.

• Prefer trusted gateway thread metadata and preserve real Mattermost thread roots.

• Add independent settings for automatic thread creation:

  mattermost:
    auto_thread: true
    dm_auto_thread: false

• Add MATTERMOST_AUTO_THREAD and MATTERMOST_DM_AUTO_THREAD overrides.

• Deprecate MATTERMOST_REPLY_MODE as an environment compatibility fallback. When neither new setting is present, legacy thread enables both policies; either new setting can override that fallback independently.

• Preserve explicit channel and DM thread roots regardless of the automatic-thread settings.

• Resolve and cache the Mattermost channel type for uncached outbound targets, including cron/notification paths.

• Retain the existing silent no-op for missing local files; no local path is posted to Mattermost.

Behavior

Incoming message	Result
Existing channel/group thread	Always preserve its root and session
Existing DM thread	Always preserve its root and session
Top-level channel/group	Auto-thread only when auto_thread: true
Top-level DM	Auto-thread only when dm_auto_thread: true

The automatic-thread settings affect synthetic roots only. They never flatten a real existing thread.

Cron scope

This PR makes uncached outbound Mattermost targets classify correctly and preserves a real thread when a user replies there. Seeding the content of a proactively delivered cron brief into a newly created Mattermost thread session is cross-cutting scheduler/session work and remains separate from this adapter-focused PR.

Related work

Covered or consolidated here

• [Bug]: Mattermost threaded conversations ignore follow-ups and leak tool output to the main channel #4221 / fix(mattermost): resolve thread follow-ups and tool output leaks (#4221) #4230 — this PR covers the thread-root, progress/typing locality, and configurable synthetic-root portions of the original report.
• Mattermost adapter ignores metadata.thread_id, so gateway thread replies post to channel root #12063 / fix(mattermost): prefer metadata thread root over stale reply_to #12299 / fix(gateway): route Mattermost replies to thread roots #33470 / fix(mattermost): keep progress notices in threads #45861 — overlapping work around authoritative metadata.thread_id routing, real-root preservation, typing indicators, and side-channel sends.
• feat(mattermost): add reply_mode "auto" for thread-aware replies #47079 / fix(mattermost): root DM thread sessions at the first post #57357 — alternative top-level and DM policies; the separate auto_thread and dm_auto_thread settings allow either behavior without flattening an existing thread.

Already upstream and deliberately omitted from this branch

• [Bug]: Mattermost gateway threading doesn't work after first reply. #25181 / bug(mattermost): CRT Thread replies fail with 400 Invalid RootId when using reply_to as root_id #28005 / fix(mattermost): resolve thread root_id properly for CRT replies (#28251) #28354 — resolving nested Mattermost post IDs to the real CRT root and avoiding Invalid RootId failures.
• Mattermost root threads share one session and block parallel conversations #18279 / Mattermost: media attachments (generated images/files) post to channel root instead of threading under the triggering message #35844 / fix(mattermost): preserve thread-local delivery hygiene #46885 / fix(mattermost): harden thread routing and delivery hygiene #47250 — top-level channel session roots plus progress/media delivery hygiene that current main already contains.
• refactor(gateway): migrate Mattermost adapter to bundled plugin (salvage of #30916) #31748 — migration of the Mattermost adapter into the bundled plugin path.

Related follow-ups not claimed by this PR

• feat(mattermost): in-thread auto-response — @mention required on every turn #54188 / feat(mattermost): follow thread after @mention (Slack parity) #54193 / feat(mattermost): add sticky thread routing #9731 — bypassing repeated @mention checks after the bot is engaged in a thread (sticky thread ownership).
• feat(mattermost): add _fetch_thread_context() to seed prior thread messages into LLM context #37695 / feat(mattermost): thread context seeding, allowlist-filtered #43805 / feat(mattermost): seed prior thread posts into first-turn context #64270 — fetching pre-existing Mattermost thread history when Hermes first joins a thread.
• bug(mattermost): mattermost.reply_mode in config.yaml silently ignored #54227 / fix(mattermost): honor reply_mode from config.yaml #67810 — the pre-existing mattermost.reply_mode YAML bridge bug. This PR makes mattermost.auto_thread and mattermost.dm_auto_thread canonical and retains MATTERMOST_REPLY_MODE only as a deprecated environment fallback; it does not claim to repair the deprecated YAML key.
• [Bug] Mattermost cron job delivery fails with "Timeout context manager should be used inside a task" #39836 — Mattermost cron delivery's separate aiohttp timeout failure. The cron behavior discussed in this PR is thread classification/context, not transport failure.

Validation

• scripts/run_tests.sh tests/gateway/test_mattermost.py tests/gateway/test_send_multiple_images.py -q — 60 passed
• scripts/run_tests.sh tests/gateway/test_config.py tests/gateway/test_platform_registry.py -q — 90 passed
• ruff check on changed Python files
• python3 -m py_compile on changed Python files
• git diff --check

Rebased onto current origin/main (a3bcb2c23). All five commits in the PR range are GPG-signed. Contributor commit c84653107 retains its original authorship beneath signed merge commit 9237a811c.

Screenshot

[nickaknudson]

I have been using this on top of v0.13 for several days with no issues; would be happy to see it merged

[BrianMcBrayer]

Agreed. We need this to make Mattermost useful. Otherwise I cannot use this integration at all. I had coded up a fix but this PR is much better than mine!

[potatosalad]

@teknium1 Did the changes that were manually merged address everything that this pull request addresses or should I rebase and resolve merge conflicts?

[legard]

Hey @potatosalad — I run Hermes against a Mattermost server and this one drives me up the wall, so I went digging to answer the question you asked @teknium1 (whether the manual merge already covered this).

From what I can tell, it didn't — not fully. What landed (06161c6ed plus the move to the bundled plugin) fixes replies inside an existing thread and the Invalid RootId error. But the first-turn case still looks broken: on a fresh top-level @mention the adapter sets thread_id = post.get("root_id") or None, so there's no root to hang anything on and the bot's progress/tool output still spills into the main channel — the original #4221 symptom. So this PR is still addressing something main doesn't.

The other thing worth knowing: the reason it won't rebase cleanly isn't that it's obsolete — the adapter got moved out from under it. gateway/platforms/mattermost.py is now plugins/platforms/mattermost/adapter.py (rename in af973e407), so the diff is now pointing at a file that no longer exists.

Figured that was worth flagging since you'd asked whether it was already covered.

[potatosalad]

@legard Ah cool, I'll get it rebased soon then.

[legard]

Hi @teknium1, when you get a chance, could you review this? It's an important issue for corporate users relying on the agent, and I'd really value your call on whether it's something you'd consider merging.

[aaron-trout]

I am new to Hermes and trying out MatterMost as the chat interface. An issue I've seen is that when you start a thread Hermes can lose context of earlier messages. For example I asked it to write a skill about my kubernetes setup; ~30 mins later when I asked for a follow up modification in the same thread, it had no idea what I was talking about:

❓ What are we trying to connect to? Is it:

Your desktop via computer_use / cua-driver?
A specific service or application?
Something else entirely?
desktop via computer_use
specific service/app
something else
Reply with the number, the option text, or your own answer.

Would this fix also resolve that issue? 🤔 I can try to test out this PR on my instance perhaps...

[potatosalad]

Would this fix also resolve that issue? 🤔 I can try to test out this PR on my instance perhaps...

Yes, that's one of the issues that this PR fixes for me, too.

[cantrellsolutions]

I'm concerned with flattening DMs in thread mode. If I send a DM and the mode is thread, I expect the reply back to be in a thread from that DM, and I’d expect replies in that DM thread to keep the same Hermes context.

I'm 100% in agreement with the rest of this. I just don’t think DM threads should all collapse into one flat DM session when thread mode is enabled. For workflows where bots send multiple separate task/status messages by DM, those threads need to stay scoped independently or the contexts bleed together.

Cron probably needs to be looked at as well. If a cron message is delivered automatically and I reply to it in a thread, the Hermes agent should know the context I’m replying to instead of me having to explain what the thread is about.

[imapotato123]

Current-state check against current main (9da6d455c): this PR is still needed, and the narrow metadata-precedence fix remains live in the branch.

• Head 2b02df8e0 contains the metadata-root resolution work from fix(mattermost): resolve metadata thread root before use potatosalad/hermes-agent#1 / 378ffd319.
• send() now prefers authoritative metadata["thread_id"] over a stale reply_to, resolves reply IDs to their real root, and has direct regression coverage.
• tests/gateway/test_mattermost.py + test_mattermost_plugin_setup.py: 52 passed locally on the PR head.
• A merge-tree against current main finds only one content conflict, in tests/gateway/test_mattermost.py; the adapter and config changes auto-merge.

@potatosalad could you rebase once more and resolve that test-file conflict? I don't think this should be closed as obsolete: current main still starts _thread_root_for_send() from reply_to and consults metadata only when it is absent, so conflicting stale reply_to can still win upstream.

[potatosalad]

@teknium1 This has been open for over three months. Is it still on track to merge, or are there remaining changes needed?

[cantrellsolutions]

I took another pass over this from the perspective of our Mattermost-based Hermes orgs.

This PR covers the Mattermost behavior we have been carrying a small local patch for: task-rooted Mattermost sessions where top-level DMs can become their own Hermes session roots and replies under that Mattermost root reuse the same Hermes session. With mattermost.auto_thread: true and mattermost.dm_auto_thread: true, this would let us drop that local adapter overlay and move to upstream behavior.

The explicit split between channel and DM auto-threading is useful — for our operator/agent UX we want both enabled, but I can see why upstream defaults may stay conservative. The metadata-root precedence/resolution and preserving real existing roots are also important for avoiding the “same visible Mattermost thread, different Hermes session” failure mode.

So from our usage: this PR is material and would replace downstream patching for better Mattermost support, assuming the new settings are configured explicitly.