feat(gateway): platform adapter plugins via PluginContext.register_platform_adapter

[HongmingWang-Rabbit]

What

Adds platform adapters to the set of plugin-extensible surfaces in hermes_cli/plugins.py. Today the existing PluginContext collector pattern lets external plugins (loaded from ~/.hermes/plugins/, ./.hermes/plugins/, or pip entry_points group hermes_agent.plugins) contribute tools, hooks, CLI commands, slash commands, context engines, and skills — but platform adapters are the only plugin type still hardcoded in gateway/run.py:_create_adapter. This PR closes that gap with the smallest possible upstream change.

Why

Anyone shipping a hermes integration for a non-built-in platform (custom A2A protocol, internal chat system, IoT bus, etc.) currently has to either (a) maintain a fork or (b) get their adapter merged upstream. Both are friction. Every other plugin type already has a clean external path; platform adapters should too.

Concrete consumer: an hermes-platform-molecule-a2a package currently shipping privately, which we'd like to make pip-installable once this lands. Built + validated locally against this branch (see Test plan).

How

Four commits, each scoped to one concern:

1. feat(gateway): platform adapter plugins via PluginContext.register_platform_adapter — adds the registration surface. New method on PluginContext, new dict on PluginManager, module-level get_plugin_platform_adapter(name) accessor. Rejects names that shadow built-in Platform enum members. Rejects duplicate registrations (warns + skips, doesn't replace).

2. feat(gateway): wire register_platform_adapter into config + boot path — GatewayConfig.plugin_platforms: Dict[str, PlatformConfig] sibling to existing platforms: Dict[Platform, PlatformConfig]. Held separately so the closed Platform enum stays closed. from_dict triggers plugin discovery before parsing platform names, then routes unknown-but-claimed names into plugin_platforms. New GatewayRunner._create_plugin_adapter(name, config) keeps the in-tree if/elif chain free of plugin concerns.

3. feat(gateway): add PluginPlatformIdentifier helper for plugin adapters — BasePlatformAdapter.__init__(config, platform: Platform) requires a Platform-shaped second arg. Plugin adapters can't extend the closed enum, so this helper class quacks like a Platform value (.value, hashable, equality). Distinct hash bucket prevents accidental collision with built-in members.

4. feat(gateway): plugin-platform-safe deserialization via resolve_platform_id — without this, plugin platforms survive the runtime hot path but die on daemon restart: SessionSource.from_dict calls Platform(value) which raises ValueError for any name not in the enum. New resolve_platform_id() helper falls back to PluginPlatformIdentifier only when a currently-loaded plugin actually claims the name — so bare typos and corrupted state still raise loudly. Wired into the three known from_dict call sites: SessionSource, SessionEntry, HomeChannel.

Total: ~120 LOC added, 6 LOC changed.

Backward compatibility

• Platform enum unchanged. No new members, no synthetic values.
• Existing from_dict deserializers reject unknown strings exactly as before — the fallback only kicks in when a plugin claims the name.
• In-tree adapters take precedence over plugin claims at registration time (same name = registration rejected with a warning).
• GatewayConfig.plugin_platforms defaults to empty; configs that don't enable any plugin platform see zero behavior change.

Test plan

Existing suite still green (pre-existing isolation failures noted below):

• pytest tests/gateway/test_session.py — 62/62 pass, including test_invalid_platform_raises (the narrow fallback preserves loud-fail semantics).
• pytest tests/hermes_cli/test_plugins.py tests/hermes_cli/test_plugins_cmd.py tests/test_plugin_skills.py — 132/132 pass on a clean dev box (no entry-point plugins installed).

New validation against an external consumer (hermes-platform-molecule-a2a):

• 11/11 unit tests on adapter lifecycle, inbound HTTP auth, outbound POST routing, plugin entry-point shape.
• 8/8 production-path E2E checkpoints: pip entry_points discovery → platform registry → GatewayConfig.from_dict routing → _create_plugin_adapter instantiation → live HTTP listener → MessageEvent(internal=True) dispatch → callback POST roundtrip → SessionSource to_dict/from_dict round-trip.
• 9/9 user-dir-discovery validation against the patched PluginContext / PluginManager.

Pre-existing test isolation issue (independent of this PR, surfaced during validation): tests/hermes_cli/test_plugins.py::test_discover_is_idempotent, ::test_discover_skips_dir_without_manifest, and ::test_commands_in_list_plugins_output assert len(list_plugins()) == N after creating N test plugins in tmp_path. They fail on any dev box that has a hermes plugin pip-installed because discover_and_load() always scans entry_points (global, not isolated by HERMES_HOME). These three tests would benefit from either filtering entry-point plugins out, or a discover_only_user_dir=True test hook. Happy to follow up in a separate PR — the fix is unrelated to this change but caught while validating.

Tested on

macOS arm64, Python 3.11. Behavior is pure-Python with no platform-specific syscalls; should work identically on Linux.

Open questions for review

1. Naming. register_platform_adapter matches existing register_* collector methods. Short forms (register_platform, register_channel) are also reasonable. Defaulting to the long form for consistency.
2. PluginPlatformIdentifier vs Platform.from_string(). I went with a dedicated class so the closed enum stays closed. An alternative would be a Platform.from_string() classmethod returning either a real member or a synthetic one — also workable, but it changes what isinstance(x, Platform) means. Open to either direction.
3. Bundled example plugin. tests/plugins/ has fixture-only plugins. Would maintainers prefer a real bundled example adapter (matching how plugins/memory/<name>/ ships real implementations), or is the fixture-only approach the right shape here?
4. Multi-account plugins. Built-ins (Telegram, Slack) support multi-account via the extra config dict. Plugin-registered adapters can do the same, but no convention is enforced. Worth a docs note?

Out of scope

• Migrating plugins/memory/__init__.py to use the unified discovery path. Orthogonal cleanup.
• A "Plugins Hub" analogous to Skills Hub. Useful but separate proposal — ship the contract first.

Happy to split into smaller PRs if preferred — each commit is independently reviewable.

[alt-glitch]

Related to #17751 (merged), #17664, #7942 — earlier iterations of pluggable platform adapters. This appears to be a follow-up or alternative implementation.

[alt-glitch]

Related to #17751 (merged), #17664, #7942 — earlier iterations of pluggable platform adapters.

[HongmingWang-Rabbit]

Update: pushed ece9e34e — fixes a real integration bug caught while validating against a real hermes gateway run subprocess.

Previously the plugin-platform boot loop did self.adapters[plugin_name] = adapter (string key), while built-in adapters use a Platform enum key. Mismatch escaped the in-process tests because they don't exercise GatewayRunner.start() — only _create_plugin_adapter directly. A real subprocess test caught it on the first run:

File "gateway/run.py", line 2027, in <listcomp>
    "platforms": [p.value for p in self.adapters.keys()],
AttributeError: 'str' object has no attribute 'value'

Fix: self.adapters[adapter.platform] = adapter — adapter.platform is the PluginPlatformIdentifier instance, which has the .value attribute every downstream consumer needs. This is the original reason PluginPlatformIdentifier exists; commit #2 just wasn't using it consistently.

After the fix, a fresh hermes gateway run subprocess on a tmp HERMES_HOME with platforms.molecule-a2a enabled passes 4/4 checkpoints:

• gateway boots and stays up
• /a2a/health returns 200
• /a2a/inbound POST returns 200 with the queued ack
• clean shutdown on SIGTERM

The validation script lives at https://github.com/Molecule-AI/hermes-platform-molecule-a2a/blob/main/scripts/e2e_real_hermes_subprocess.py and runs the real binary in ~7s on macOS.

[HongmingWang-Rabbit]

Closing as superseded by #17751 (merged 2026-04-30 — feat: pluggable gateway platforms — drop-in messaging adapters (salvage of #17664)).

#17751 ships a more comprehensive pluggable-platform system with:

• ctx.register_platform(name, label, adapter_factory, check_fn, ...) (richer signature than my register_platform_adapter — supports labels, install hints, optional validate_config / setup_fn)
• Open Platform enum via _missing_() (cleaner than my PluginPlatformIdentifier)
• Dedicated gateway/platform_registry.py with PlatformEntry dataclass

The downstream consumer plugin I built against my API (Molecule-AI/hermes-channel-molecule) has migrated to the #17751 API in its 754d162 commit, with a dual-mode fallback for installations still on pre-#17751 forks. No outstanding need for #18775's narrower shape.

Thanks @alt-glitch for the pointer to the predecessor PRs.