feat(mattermost): add interactive approval buttons via send_exec_approval

[clean-logic]

Summary

Adds full interactive-button support to the Mattermost gateway plugin — exec
approval, slash confirm, update prompt, and clarify — bringing it to parity with
Discord and beyond.

Re-architected onto the bundled-plugin model introduced in af973e407 (Mattermost
moved from gateway/platforms/mattermost.py to plugins/platforms/mattermost/).
Interactive callbacks are served by a plugin-owned aiohttp server (the Teams/Line
pattern) — zero core edits.

What it does

• send_exec_approval — Allow Once / Allow Session / Always Allow / Deny → resolve_gateway_approval
• send_slash_confirm — Approve Once / Always / Cancel → tools.slash_confirm.resolve
• send_update_prompt — Yes / No update decisions
• send_clarify — per-option buttons → resolve_gateway_clarify
• Local HTTP callback server (three-tier callback_host/callback_port, default
  127.0.0.1:18065), MATTERMOST_ALLOWED_USERS auth, double-click guard,
  original-message updates on click.

Why buttons (not text)

Mattermost intercepts messages starting with /, so the plain-text /approve
fallback in #27587 is impossible to action. Buttons are the only working approval
path.

Relation to #26537

Supersedes @shawnfeng0's #26537 (same goal). This PR is plugin-native (his targets
the now-deleted core adapter), adds send_clarify, full registration hooks, and
tests + docs. Credit to his callback-server design and review exchange.

Fixes #27587 (primary item; the slash-command-registration secondary item is out of
scope).

[alt-glitch]

Competing with #26537 (by @shawnfeng0), which is broader in scope (covers send_exec_approval, send_slash_confirm, and send_update_prompt). Implements #27587. Prior closed attempt: #8184. Maintainers should compare the two architectural approaches (reuse WebhookAdapter routes vs standalone aiohttp listener).

[llealloo]

hermes mattermost integration is dead without this!

please approve this PR with a cherry on top

[teknium1]

Thanks for carrying the Mattermost implementation into the bundled-plugin layout. The interactive gap is real on current main, but this needs correction before salvage.

Problems

• plugins/platforms/mattermost/adapter.py:1059 can return SendResult(success=False) when the callback listener is unavailable. Current gateway/run.py:14655-14664 ignores that result, sets sent_buttons = True, and suppresses the text fallback; the prompt is then marked pending at gateway/run.py:14678-14683.
• adapter.py:930 resolves by session only. tools/approval.py:1488-1521 resolves the oldest pending entry for that session, so a stale button can resolve a newer command approval.
• gateway/platforms/webhook.py:152-200 adds an extra-route API with no PR caller. The adapter instead creates its own app at adapter.py:329-338; please remove the unused core hook.

Suggested changes

• Check SendResult.success in the update watcher and add an end-to-end regression for listener startup failure.
• Bind approval clicks to an exact approval ID, with a stale-button/newer-approval regression test.
• Keep the plugin-owned listener and drop the unused webhook change.

Automated hermes-sweeper review.

[teknium1]

This resolves only by session_key, but tools.approval.resolve_gateway_approval() resolves the session FIFO. A click on an old button can therefore resolve a newer command approval in the same session. Please plumb and resolve an exact approval ID before enabling this command-approval path.

[clean-logic]

@.git_pr_reply_approval_id.md

[teknium1]

The PR-head Mattermost adapter never calls register_extra_route; it starts a separate aiohttp app instead. Please remove this unused core hook rather than adding speculative infrastructure and middleware to every webhook request.

[clean-logic]

@.git_pr_reply_webhook.md

[clean-logic]

Thanks for the review — rebased onto current main and addressed all three points.

Rebase

Upstream advanced ~2,900 commits since this branch was cut, but only 3 touched plugins/platforms/mattermost/adapter.py (leading-space slash commands, per-platform multiplex config validation, mass-mention hardening). Rebuilt as 3 commits instead of a mechanical rebase of the old history:

1. fix(approval): add exact approval-ID resolution for gateway buttons — core plumbing
2. fix(gateway): honor SendResult.success in the update-prompt watcher — core fix
3. feat(mattermost): add interactive approval buttons via send_exec_approval — the plugin itself

Review point 1 — SendResult(success=False) on listener failure

adapter.py:1059 can return SendResult(success=False) ... gateway/run.py:14655-14664 ignores that result ... the prompt is then marked pending

Confirmed and split into two states:

• The exec-approval notify path (gateway/run.py, _approval_notify_sync) already checks SendResult.success and falls back to text on main — that part had already been fixed upstream since this PR was opened.
• The update-prompt watcher had the identical bug and was still unfixed: it set sent_buttons = True unconditionally whenever send_update_prompt() didn't raise, even on a non-raising success=False. Fixed in commit 2, with a regression test (tests/gateway/test_update_streaming.py::test_falls_back_to_text_when_button_prompt_send_fails) that fails on the old code and passes with the fix.

Review point 2 — exact approval-ID resolution

adapter.py:930 resolves by session only ... a stale button could resolve a newer command approval

Added core support in commit 1 (tools/approval.py):

• _ApprovalEntry.approval_id — generated per pending entry, surfaced to notify callbacks via approval_data["approval_id"] (no callback signature change).
• resolve_gateway_approval_by_id(session_key, approval_id, choice, reason=None) — resolves only the exact matching entry; a stale/unknown id resolves nothing (returns 0) and never falls back to FIFO.
• Plumbed through gateway/run.py's _approval_notify_sync into send_exec_approval(..., approval_id=...), and accepted (currently unused) on every other adapter implementing that method — Telegram, Teams, Slack, Matrix, Feishu, Discord, WhatsApp Cloud, QQ — so the signature is uniform. Only Mattermost adopts it in this PR; converting the others is the separate cross-platform PR you mentioned.
• Mattermost's _resolve_approval now resolves by approval_id when present, with a legacy session-FIFO fallback for prompts registered before this adapter started stamping ids (e.g. across a gateway restart). A stale tap shows "⌛ Approval expired — command was not run" instead of silently resolving the wrong entry.
• Regression test: tests/tools/test_approval.py::TestApprovalIdResolution::test_stale_button_does_not_resolve_newer_approval — two approvals pending in the same session, resolving by the older id leaves the newer one untouched.

Review point 3 — unused webhook.py hook

The PR-head Mattermost adapter never calls register_extra_route

Removed. The adapter uses its own plugin-owned aiohttp app; gateway/platforms/webhook.py is untouched in this version.

Also picked up while rebasing

• Upstream's send_exec_approval contract grew allow_permanent / allow_session / smart_denied kwargs since this branch was cut. Mattermost now accepts them and hides Allow Session / Always Allow the same way Discord and Slack do.
• Clarify now renders Telegram-style: full option text goes in the post body (numbered), buttons shrink to short numeric labels (1, 2, ...) plus "Other (type answer)". Mattermost attachment button labels were getting cut off for long options.
• Applied the same mass-mention hardening upstream added for send/edit_message/file uploads to the new prompt-posting paths (approval/slash/update/clarify), since prompt text can echo back content that may contain @channel/@all.
• Found and removed a latent bug in this branch's own _env_enablement hook (unrelated to buttons): it seeded home_channel without a name key, silently discarding MATTERMOST_HOME_CHANNEL_NAME and breaking an existing upstream test (test_mattermost_home_channel). Not needed for this feature — removed rather than fixed in place.

Tests: tests/gateway/test_mattermost.py (63) + tests/gateway/test_mattermost_approval_buttons.py (49) + the two core test files above all pass locally; full suite via CI.