refactor(agent): compact module docstrings (outbound_webhooks, otlp_exporter, emitter, gateway_health_export)

agent/monitoring/emitter.py

@@ -1,11 +1,9 @@
-"""Monitoring emitter: fire-and-forget queue + background dispatcher.
-
-The single seam between producers (gateway status hooks, diagnostic log handler)
-and consumers (OTLP streamers). Hot-path invariant: ``emit()`` MUST return in
-O(microseconds), MUST NOT block on disk/network, and MUST NEVER raise into the
-caller — a monitoring failure is logged locally and dropped. On a full queue the
-*oldest* event is dropped. A daemon thread fans batches out to fail-isolated
-subscribers. Nothing is persisted: monitoring is an egress path, not a store.
+"""Monitoring emitter: fire-and-forget queue + background dispatcher — the single seam between
+producers (gateway status hooks, diagnostic log handler) and consumers (OTLP streamers).
+Hot-path invariant: ``emit()`` MUST return in O(microseconds), MUST NOT block on disk/network, and
+MUST NEVER raise into the caller — a monitoring failure is logged locally and dropped.  On a full
+queue the *oldest* event is dropped.  A daemon thread fans batches out to fail-isolated
+subscribers.  Nothing is persisted: monitoring is an egress path, not a store.
 """
 
 from __future__ import annotations

agent/monitoring/gateway_health_export.py

@@ -171,11 +171,10 @@ def _count(failure_msg: str, module: str, read: Callable[[Any], Any]) -> int:
 
 
 def _read_background_work_count() -> int:
-    """Live background/subagent work that ``active_agents`` deliberately does NOT include
-    (``active_agents`` = foreground turns + in-flight cron + API runs; backgrounded
-    ``delegate_task`` subagents, ``terminal(background=true)`` processes and kanban workers are
-    tracked only by the scale-to-zero guard).  TASK-granular: a fan-out batch of N contributes N
-    (real concurrent load), unlike the pool's one-slot-per-batch accounting.  Content-free."""
+    """Live background/subagent work that ``active_agents`` (foreground turns + in-flight cron + API
+    runs) deliberately does NOT include: backgrounded ``delegate_task`` subagents,
+    ``terminal(background=true)`` processes, kanban workers.  TASK-granular: a fan-out batch of N
+    contributes N (real concurrent load), unlike the pool's one-slot-per-batch accounting."""
     return (
         _count("background-work async-delegation count failed", "tools.async_delegation", lambda m: m.active_task_count())
         + _count("background-work process-registry count failed", "tools.process_registry",
@@ -184,9 +183,8 @@ def _read_background_work_count() -> int:
 
 
 def _read_background_delegations_count() -> int:
-    """Live async delegation UNITS (dispatch/pool slots): a batch counts ONE regardless of fan-out
-    width, matching the pool's capacity accounting — slot pressure (alert vs
-    ``max_concurrent_children``) alongside ``background_work``'s real load.  Delegations only."""
+    """Live async delegation UNITS (pool slots): a batch counts ONE regardless of fan-out width, so
+    operators see slot pressure (vs ``max_concurrent_children``) alongside ``background_work``."""
     return _count("background-delegations count failed", "tools.async_delegation", lambda m: m.active_count())
 
 

agent/monitoring/otlp_exporter.py

@@ -1,12 +1,10 @@
 """Export monitoring events to an OpenTelemetry Collector over OTLP/HTTP.
 
-Maps gateway monitoring events to OTel spans for the operator-configured
-``monitoring.export.otlp`` endpoint (no default destination ships) and hosts the OTLP
-plumbing shared with ``gateway_health_export`` (SDK loading, header resolution, resource
-attributes, endpoint mapping).  The OTel SDK is an optional extra (``hermes-agent[otlp]``)
-imported lazily; ``headers_env`` values are read from the environment at export time and
-never logged or stored.  The continuous subscriber runs on the emitter's dispatcher thread,
-fail-isolated, and ``event_filter`` keeps other planes from riding along on this exporter.
+Maps gateway monitoring events to OTel spans for the operator-configured ``monitoring.export.otlp``
+endpoint (no default destination ships) and hosts the OTLP plumbing shared with
+``gateway_health_export``.  The OTel SDK is an optional extra (``hermes-agent[otlp]``) imported
+lazily; ``headers_env`` values are read at export time and never logged or stored.  The streaming
+subscriber runs fail-isolated on the emitter thread; ``event_filter`` keeps other planes off it.
 """
 
 from __future__ import annotations

agent/outbound_webhooks.py

@@ -1,14 +1,10 @@
-"""Outbound webhook notifications: ``hooks.outbound`` in config.yaml -> notify-only callbacks
-on the plugin hook manager, so every ``invoke_hook()`` site can push lifecycle events to
-external HTTP endpoints (outbound mirror of ``gateway/platforms/webhook.py``).
-
-* Fire-and-forget: callbacks serialize, enqueue on a bounded queue and return ``None``; one
-  daemon worker POSTs, so a target can never block a tool call or influence agent flow.
-* HMAC-SHA256 signed (``X-Hermes-Signature-256: sha256=<hex>`` over the raw body) when a
-  secret is configured.  ``HERMES_SAFE_MODE=1`` skips registration; registration is idempotent.
-* Entry keys: url, events, secret_env|secret, matcher (pre/post_tool_call only), timeout
-  (clamped to [1, 60]), name.  Body: ``{hook_event_name, profile, tool_name, tool_input,
-  session_id, cwd, extra, delivery_id, timestamp}``.
+"""Outbound webhooks: ``hooks.outbound`` entries (url, events, secret_env|secret, matcher for
+pre/post_tool_call, timeout clamped to [1, 60], name) -> notify-only callbacks on the plugin hook
+manager, so every ``invoke_hook()`` site can POST lifecycle events (mirror of
+``gateway/platforms/webhook.py``).  Fire-and-forget through a bounded queue + one daemon worker,
+so a target can never block a tool call or influence agent flow.  HMAC-SHA256 signed
+(``X-Hermes-Signature-256: sha256=<hex>`` over the raw body) when a secret is configured;
+``HERMES_SAFE_MODE=1`` skips registration; registration is idempotent.
 """
 
 from __future__ import annotations
@@ -76,11 +72,8 @@ class WebhookTarget(_ToolMatcherMixin):
 # --- Public API -----------------------------------------------------------------
 
 def register_from_config(cfg: Optional[Dict[str, Any]]) -> List[WebhookTarget]:
-    """Register every configured outbound webhook on the plugin manager.
-
-    Malformed ``hooks.outbound`` means zero targets — never raises. Returns the
-    targets that ended up wired (deduplicated across repeat calls).
-    """
+    """Register every configured outbound webhook on the plugin manager.  Malformed ``hooks.outbound``
+    means zero targets — never raises.  Returns the targets that ended up wired (deduplicated)."""
     if not isinstance(cfg, dict):
         return []
     from utils import env_var_enabled