feat(plugins): expose register_slack_action_handler API (salvage #20589)

[kshitijk4poor]

What

Salvages #20589 (@bcsmith528) onto current main, preserving authorship. Adds a public plugin API for Slack Block Kit action handlers so plugins can respond to button clicks / overflow menus / datepickers without monkey-patching SlackAdapter.connect.

def register(ctx):
    async def on_approve(ack, body, action):
        await ack()          # within 3s (slack_bolt requirement)
        # ...do work, post a follow-up...
    ctx.register_slack_action_handler("inbox_sweep_approve", on_approve)

action_id accepts whatever slack_bolt.App.action() accepts — a literal string, a compiled re.Pattern, or a constraint dict ({"action_id": "...", "block_id": "..."}).

Why this is a salvage

#20589's base had gone stale and the PR was DIRTY (conflicts with main's Socket-Mode startup refactor). This branch cherry-picks both of @bcsmith528's commits onto current main and resolves the conflicts:

• hermes_cli/plugins.py — additive (_aux_tasks from main + _slack_action_handlers from the PR coexist).
• gateway/platforms/slack.py — the plugin-handler registration block now runs before main's self._start_socket_mode_handler() / watchdog path (main replaced the old inline AsyncSocketModeHandler(...) + create_task block since the PR was cut), so handlers are wired before Socket Mode starts dispatching.

Authorship is preserved: both commits are Author: Brad Smith, committer kshitijk4poor.

Why this implementation (vs the competing #20936)

#20936 proposed a broader surface (slash commands + actions + view/modal handlers) but its connect() wiring captures the loop variable as a default argument (async def handler(ack, body, action, _ext=_ext)). slack_bolt resolves listener args by name, not by Python defaults — it injects None for any unrecognized param name, so _ext is None at dispatch and None.handler raises AttributeError on the first real event. That PR's tests pass only because they bypass the connect() loops.

This PR (the second commit, fix(gateway): keep plugin action wrapper signature to (ack, body, action)) deliberately avoids that with a closure factory (_make_wrapper) — the wrapper signature stays exactly (ack, body, action), and each callback is defensively wrapped so a misbehaving plugin can't crash the gateway (it's still best-effort ack()'d).

Files changed

• gateway/platforms/slack.py — connect() wires plugin action handlers after built-in approval/confirm buttons, before Socket Mode start.
• hermes_cli/plugins.py — register_slack_action_handler on PluginContext, get_slack_action_handlers() accessor, queue cleared on force-rediscover.
• tests/gateway/test_slack_plugin_action_handlers.py — 14 tests: validation, multi-plugin registration, connect-time wiring, defensive exception handling, loader-failure fallback.
• website/docs/guides/build-a-hermes-plugin.md — "Handle Slack Block Kit button clicks" section.

Testing

pytest tests/gateway/test_slack_plugin_action_handlers.py
# 14 passed

pytest tests/hermes_cli/test_plugins.py tests/gateway/test_slack.py tests/gateway/test_slack_approval_buttons.py
# 303 passed (1 pre-existing env-dependent failure in
# TestPluginDiscovery::test_discover_project_plugins_skipped_by_default that
# fails identically on clean main — it discovers the local dev plugin dir)

Verified the wrapper dispatches correctly against the real slack_bolt.kwargs_injection.utils.build_required_kwargs + a live BoltRequest (the closure-factory captures survive; default-arg capture would have resolved to None).

Closes #20589. Supersedes #20936 (broken wiring, see above).