From eea8e8060eeb7db049cbce7f79a4d9d4b2df7bcb Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 18:53:00 -0700 Subject: [PATCH] refactor(agent): compact module docstrings (outbound_webhooks, otlp_exporter, emitter, gateway_health_export) --- agent/monitoring/emitter.py | 14 ++++++------- agent/monitoring/gateway_health_export.py | 14 ++++++------- agent/monitoring/otlp_exporter.py | 12 +++++------ agent/outbound_webhooks.py | 25 ++++++++--------------- 4 files changed, 26 insertions(+), 39 deletions(-) diff --git a/agent/monitoring/emitter.py b/agent/monitoring/emitter.py index 2858d257c6..b54ac54918 100644 --- a/agent/monitoring/emitter.py +++ b/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 diff --git a/agent/monitoring/gateway_health_export.py b/agent/monitoring/gateway_health_export.py index 643298be61..68f69bccc9 100644 --- a/agent/monitoring/gateway_health_export.py +++ b/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()) diff --git a/agent/monitoring/otlp_exporter.py b/agent/monitoring/otlp_exporter.py index 2f845569ff..e5f054db5c 100644 --- a/agent/monitoring/otlp_exporter.py +++ b/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 diff --git a/agent/outbound_webhooks.py b/agent/outbound_webhooks.py index 4504838888..91d430060b 100644 --- a/agent/outbound_webhooks.py +++ b/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=`` 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=`` 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