Generic registry hook for YAML→env config bridges (apply_yaml_config_fn)

Background

Eight platform adapters in gateway/platforms/ rely on platform-specific YAML→env bridges hardcoded in gateway/config.py::load_gateway_config(). Each block translates config.yaml keys into environment variables that the adapter later reads via os.getenv():

These coexist with a generic loop at gateway/config.py:758–826 that already handles platform-shared keys (unauthorized_dm_behavior, notice_delivery, reply_prefix, reply_in_thread, require_mention) by iterating over Platform enum values and writing into PlatformConfig.extra. The per-platform blocks layer adapter-specific keys on top of that.

The problem

When a built-in platform migrates to the bundled plugin system (e.g. Discord in #24356), its YAML→env bridge is still stuck in gateway/config.py. The plugin can't own its own config translation, so:

• The adapter still reads its config via os.getenv(...) rather than from PlatformConfig.extra, even though it now lives in plugins/platforms/<name>/.
• A core file (gateway/config.py) needs to know about every platform's YAML schema — exactly the per-platform-boilerplate tax #3823 is trying to eliminate.
• Third-party plugins under ~/.hermes/plugins/ cannot bridge YAML keys to env at all unless they monkey-patch load_gateway_config (community Xiaomi/Sidekick adapters reported similar friction in #3823).

The existing registry hooks (env_enablement_fn, setup_fn, standalone_sender_fn, etc.) don't cover this case:

• env_enablement_fn is called too late (after env-only enablement) and only seeds PlatformConfig.extra from env vars — it doesn't help with YAML→env direction.
• validate_config and is_connected are read-only inspection hooks, not transformations.

Proposal: apply_yaml_config_fn

Add an optional hook on PlatformEntry:

@dataclass
class PlatformEntry:
    ...
    # Optional: given the raw `yaml_cfg` dict (parsed config.yaml top-level)
    # and the platform's own sub-dict, translate YAML keys into env vars
    # and/or return a `dict` to merge into `PlatformConfig.extra`.
    #
    # Signature: (yaml_cfg: dict, platform_cfg: dict) -> Optional[dict]
    #
    # - Mutating os.environ is allowed (env-precedence semantics preserved).
    # - Returned dict is merged into PlatformConfig.extra at this platform's
    #   slot (None or empty dict = no-op).
    # - Called during load_gateway_config(), after the generic shared-key
    #   loop at line 758, before _apply_env_overrides().
    apply_yaml_config_fn: Optional[Callable[[dict, dict], Optional[dict]]] = None

gateway/config.py::load_gateway_config() invokes registered hooks after the existing generic loop:

# After the existing per-Platform shared-key loop:
for entry in platform_registry.all_entries():
    if entry.apply_yaml_config_fn is None:
        continue
    platform_cfg = yaml_cfg.get(entry.name, {})
    if not isinstance(platform_cfg, dict):
        continue
    try:
        seeded = entry.apply_yaml_config_fn(yaml_cfg, platform_cfg)
    except Exception as e:
        logger.debug("apply_yaml_config_fn for %s raised: %s", entry.name, e)
        continue
    if isinstance(seeded, dict) and seeded:
        try:
            plat = Platform(entry.name)
            if plat in config.platforms:
                config.platforms[plat].extra.update(seeded)
        except ValueError:
            pass  # plugin platform not in Platform enum

This lets each plugin own its YAML→env bridge as part of its register() block:

# plugins/platforms/discord/adapter.py
def _apply_yaml_config(yaml_cfg, discord_cfg) -> dict | None:
    if "require_mention" in discord_cfg and not os.getenv("DISCORD_REQUIRE_MENTION"):
        os.environ["DISCORD_REQUIRE_MENTION"] = str(discord_cfg["require_mention"]).lower()
    # ... 60 more lines of Discord-specific YAML bridging
    return None  # no extras to seed; everything goes via env

def register(ctx):
    ctx.register_platform(
        ...,
        apply_yaml_config_fn=_apply_yaml_config,
    )

Migration path

1. Add the hook to PlatformEntry + the dispatch loop in load_gateway_config. Pure addition, no behavior change. Single small PR.
2. Migrate platforms one at a time — each platform's bridge moves from gateway/config.py into its plugin (or, for still-in-gateway/platforms/ adapters, into a sibling helper imported and registered via the gateway's existing platform registration). One PR per platform. Discord is the natural first migration target since it just landed as a plugin in #24356.
3. Eventually delete the per-platform blocks at gateway/config.py:828–1080 once every platform has a plugin or self-registered hook. The generic shared-key loop stays.

Each migration step is independently mergeable and net-negative LOC.

Alternatives considered

Alternative A: refactor adapters to read from PlatformConfig.extra instead of os.getenv

Eliminates the YAML→env round-trip entirely — the adapter just reads extra["require_mention"] directly. This is what Teams does (no YAML bridge needed because the adapter doesn't read env vars for runtime config; it reads extra).

Trade-off: Discord's adapter has ~50 os.getenv call sites for runtime config. Migrating all of them is a separate, much larger refactor that would touch the adapter's hot paths. The hook approach lets the migration land incrementally without rewriting adapter internals.

Alternative B: keep the bridges in gateway/config.py forever

Status quo. Costs:

• Per-platform boilerplate stays in core (~252 LOC across 8 platforms today).
• Issue #3823's "adding a new platform requires touching 17 files" tax is still real for every YAML-keyed adapter.
• Third-party platform plugins can't expose YAML config without monkey-patching.

Alternative C: drop YAML config support; require env-only configuration

Breaking change for every existing user with a platforms.discord: (or .slack, .telegram, etc.) section in config.yaml. Off the table.

Out of scope for this issue

• The other Discord-shaped concerns called out in #24356 (Platform.DISCORD enum, _is_user_authorized allowlist maps, _UPDATE_ALLOWED_PLATFORMS frozenset, voice-mode adapter access) — those are independent generic-registry concerns and deserve their own scoping issues.
• Migrating any specific platform to the new hook — this issue is just about adding the hook itself. Each per-platform migration is a follow-up.

Asks

1. Is apply_yaml_config_fn the right name / signature? Open to alternatives — could be bridge_yaml_to_env_fn, read_yaml_config_fn, etc.
2. Is the dispatch order correct (after the generic shared-key loop, before _apply_env_overrides)?
3. Any preference between Alternative A (full adapter refactor) and this hook approach?

Happy to open a PR for the hook itself once the design is acked.

Refs #3823, #24356.