feat(plugins): expose register_slack_action_handler API

[bcsmith528]

What

Adds a public way for Hermes plugins to register Slack Block Kit action handlers (button clicks, overflow menus, datepickers, etc.) without monkey-patching SlackAdapter.connect.

New API on PluginContext:

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 for matching multiple ids, or a constraint dict like {\"action_id\": \"...\", \"block_id\": \"...\"}.

Why

The plugin API already exposes register_tool, register_hook, register_command, register_platform, and register_context_engine, but nothing for slack_bolt action handlers. Plugins that post Block Kit messages with interactive elements had no documented hook for the resulting click events.

The only previous workaround was for the plugin to monkey-patch SlackAdapter.connect from inside register() — fragile, fights with the official API, and breaks on every Hermes update. Block Kit interactivity is core to the Slack experience, so plugins should have first-class access to it.

Before / after

Before — plugin had to reach into gateway.platforms.slack, wrap SlackAdapter.connect, and register handlers post-connect on self._app:

def register(ctx):
    import gateway.platforms.slack as slack_mod
    orig = slack_mod.SlackAdapter.connect
    async def patched(self, *a, **kw):
        result = await orig(self, *a, **kw)
        self._app.action(\"my_action\")(my_handler)
        return result
    slack_mod.SlackAdapter.connect = patched

After:

def register(ctx):
    ctx.register_slack_action_handler(\"my_action\", my_handler)

How it works

1. PluginContext.register_slack_action_handler(action_id, callback) validates inputs and queues (action_id, callback, plugin_name) on PluginManager._slack_action_handlers.
2. PluginManager.get_slack_action_handlers() exposes the queue to consumers.
3. SlackAdapter.connect, after wiring its built-in approval and slash-confirm buttons, iterates the queue and registers each via self._app.action(matcher)(callback).
4. Each callback is wrapped defensively — exceptions inside a plugin handler are logged with the plugin name and a best-effort ack() is still issued so Slack stops retrying the click.
5. If get_plugin_manager() itself raises (e.g. plugin layer unhealthy), the gateway logs and proceeds with built-ins only rather than failing to start.

Files changed

• hermes_cli/plugins.py — new register_slack_action_handler method on PluginContext, new get_slack_action_handlers() accessor on PluginManager, queue cleared on force-rediscover.
• gateway/platforms/slack.py — connect() consumes the queue after the existing built-in app.action() blocks.
• tests/gateway/test_slack_plugin_action_handlers.py — new file, 13 tests covering input validation, multi-plugin registration, the connect-time wiring, defensive exception handling, and the plugin-loader-failure fallback path.
• website/docs/guides/build-a-hermes-plugin.md — new "Handle Slack Block Kit button clicks" section alongside the existing slash-command + dispatch_tool docs.

How to test

# new tests
pytest tests/gateway/test_slack_plugin_action_handlers.py -v

# all plugin + Slack tests still pass
pytest tests/hermes_cli/test_plugins.py \\
       tests/hermes_cli/test_plugins_cmd.py \\
       tests/hermes_cli/test_plugin_cli_registration.py \\
       tests/hermes_cli/test_plugin_scanner_recursion.py \\
       tests/test_plugin_skills.py \\
       tests/gateway/test_slack.py \\
       tests/gateway/test_slack_approval_buttons.py \\
       tests/gateway/test_plugin_platform_interface.py \\
       tests/gateway/test_platform_registry.py -q
# 416 passed, 7 skipped

ruff check hermes_cli/plugins.py gateway/platforms/slack.py \\
           tests/gateway/test_slack_plugin_action_handlers.py
# All checks passed!

Manual smoke test — wrote a tiny test plugin that calls ctx.register_slack_action_handler(\"foo\", cb), posted a Block Kit message with that action_id, clicked the button, callback fired with the expected (ack, body, action) and the plugin name appeared in the gateway log under [Slack] Wired N plugin action handler(s).

Compatibility

• No behavioural change for plugins that don't call the new method — get_slack_action_handlers() returns [] and the new for loop in connect() is a no-op.
• No change to built-in approval/confirm handlers — the new block runs after them.
• Forward-compatible with slack_bolt matcher types: literal string, compiled regex, and constraint dict are all accepted unchanged.

Tested on

• macOS (Python 3.11.1)

Checklist

• Branch named feat/...
• Conventional Commits
• Tests added (13 new, all passing)
• Lint clean (ruff)
• Adjacent test suites still pass (416 plugin + Slack tests, 0 failures)
• Docs updated (build-a-hermes-plugin.md)