feat(gateway): generic plugin hooks for env enablement + cron delivery

Widen the platform-plugin surface so plugins can self-configure from env
vars and opt into cron home-channel delivery without editing core files.
Closes the scope gap that forced every new platform (Google Chat, Teams,
IRC, future) to either touch gateway/config.py, cron/scheduler.py, and
hermes_cli/config.py or live without env-only setup.

Changes:

- gateway/platform_registry.py: two new optional PlatformEntry fields.
  - env_enablement_fn: () -> Optional[dict]. Called during
    _apply_env_overrides BEFORE the adapter is constructed. Returned
    dict fields are merged into PlatformConfig.extra; the special
    'home_channel' key (if present) becomes a proper HomeChannel
    dataclass on the PlatformConfig.
  - cron_deliver_env_var: name of the *_HOME_CHANNEL env var. When set,
    the plugin platform is a valid cron deliver= target and cron reads
    the env var to resolve the default chat/room ID.

- gateway/config.py: the existing plugin-platform enable pass at the
  bottom of _apply_env_overrides now calls env_enablement_fn and seeds
  extras/home_channel. No effect on plugins that don't set the new
  field.

- cron/scheduler.py: _is_known_delivery_platform and
  _resolve_home_env_var fall through to the registry when the platform
  isn't in the hardcoded built-in sets. New _iter_home_target_platforms
  helper iterates built-ins + plugin platforms for the deliver=origin
  fallback.

- gateway/run.py: _home_target_env_var now consults the new resolver so
  plugin-defined home channels work for non-cron call sites too.

- hermes_cli/config.py: new _inject_platform_plugin_env_vars() sibling
  of _inject_profile_env_vars(). Scans plugins/platforms/*/plugin.yaml
  at import time and contributes entries to OPTIONAL_ENV_VARS so
  'hermes config' UI discovers them. Supports bare-string and rich-dict
  requires_env entries plus a new optional_env list for non-required
  vars (home channels, allowlists).

All additions are strictly opt-in. Existing plugins (IRC, Teams,
image_gen, memory) see zero behavior change until they adopt the new
fields.
This commit is contained in:
Teknium 2026-05-07 06:33:23 -07:00
parent c8e3e39185
commit af9336d575
5 changed files with 220 additions and 11 deletions

View file

@ -152,9 +152,54 @@ def _resolve_origin(job: dict) -> Optional[dict]:
return None
def _plugin_cron_env_var(platform_name: str) -> str:
"""Return the cron home-channel env var registered by a plugin platform.
Falls through the platform registry so plugins that set
``cron_deliver_env_var`` on their ``PlatformEntry`` get cron delivery
support without editing this module.
"""
try:
from hermes_cli.plugins import discover_plugins
discover_plugins() # idempotent
from gateway.platform_registry import platform_registry
entry = platform_registry.get(platform_name.lower())
if entry and entry.cron_deliver_env_var:
return entry.cron_deliver_env_var
except Exception:
pass
return ""
def _is_known_delivery_platform(platform_name: str) -> bool:
"""Whether ``platform_name`` is a valid cron delivery target.
Hardcoded built-ins in ``_KNOWN_DELIVERY_PLATFORMS`` are checked first;
plugin platforms registered via ``PlatformEntry`` are accepted if they
provide a ``cron_deliver_env_var``.
"""
name = platform_name.lower()
if name in _KNOWN_DELIVERY_PLATFORMS:
return True
return bool(_plugin_cron_env_var(name))
def _resolve_home_env_var(platform_name: str) -> str:
"""Return the env var name for a platform's cron home channel.
Built-in platforms are in ``_HOME_TARGET_ENV_VARS``; plugin platforms are
resolved from the platform registry.
"""
name = platform_name.lower()
env_var = _HOME_TARGET_ENV_VARS.get(name)
if env_var:
return env_var
return _plugin_cron_env_var(name)
def _get_home_target_chat_id(platform_name: str) -> str:
"""Return the configured home target chat/room ID for a delivery platform."""
env_var = _HOME_TARGET_ENV_VARS.get(platform_name.lower())
env_var = _resolve_home_env_var(platform_name)
if not env_var:
return ""
value = os.getenv(env_var, "")
@ -167,7 +212,7 @@ def _get_home_target_chat_id(platform_name: str) -> str:
def _get_home_target_thread_id(platform_name: str) -> Optional[str]:
"""Return the optional thread/topic ID for a platform home target."""
env_var = _HOME_TARGET_ENV_VARS.get(platform_name.lower())
env_var = _resolve_home_env_var(platform_name)
if not env_var:
return None
value = os.getenv(f"{env_var}_THREAD_ID", "").strip()
@ -178,6 +223,24 @@ def _get_home_target_thread_id(platform_name: str) -> Optional[str]:
return value or None
def _iter_home_target_platforms():
"""Iterate built-in + plugin platform names that expose a home channel.
Used by the ``deliver=origin`` fallback when the job has no origin.
"""
for name in _HOME_TARGET_ENV_VARS:
yield name
try:
from hermes_cli.plugins import discover_plugins
discover_plugins() # idempotent
from gateway.platform_registry import platform_registry
for entry in platform_registry.plugin_entries():
if entry.cron_deliver_env_var and entry.name not in _HOME_TARGET_ENV_VARS:
yield entry.name
except Exception:
pass
def _resolve_single_delivery_target(job: dict, deliver_value: str) -> Optional[dict]:
"""Resolve one concrete auto-delivery target for a cron job."""
@ -195,7 +258,7 @@ def _resolve_single_delivery_target(job: dict, deliver_value: str) -> Optional[d
}
# Origin missing (e.g. job created via API/script) — try each
# platform's home channel as a fallback instead of silently dropping.
for platform_name in _HOME_TARGET_ENV_VARS:
for platform_name in _iter_home_target_platforms():
chat_id = _get_home_target_chat_id(platform_name)
if chat_id:
logger.info(
@ -251,7 +314,7 @@ def _resolve_single_delivery_target(job: dict, deliver_value: str) -> Optional[d
"thread_id": origin.get("thread_id"),
}
if platform_name.lower() not in _KNOWN_DELIVERY_PLATFORMS:
if not _is_known_delivery_platform(platform_name):
return None
chat_id = _get_home_target_chat_id(platform_name)
if not chat_id: