feat(gateway): make still-working heartbeats configurable

gateway/run.py

@@ -29,6 +29,7 @@
 import inspect
 import json
 import logging
+import math
 import os
 import re
 import shlex
@@ -3275,6 +3276,94 @@ def _load_background_notifications_mode() -> str:
             return "all"
         return mode
 
+    @staticmethod
+    def _load_still_working_interval(platform_key: str | None = None) -> float | None:
+        """Load per-platform still-working heartbeat interval from config.
+
+        Returns seconds as a float, or ``None`` when disabled.
+        Config keys:
+          - ``display.still_working_interval`` (global default, seconds)
+          - ``display.still_working_overrides.<platform>`` (per-platform override)
+
+        Values of ``0``, ``false``, or ``off`` disable the heartbeat.
+        Invalid global values fall back to the default 600 seconds. Invalid
+        per-platform overrides are ignored so they inherit the global setting.
+        """
+
+        def _coerce_interval(raw, *, key_name: str, invalid_fallback) -> float | None | object:
+            if raw is None or raw == "":
+                return _MISSING
+            if raw is False:
+                return None
+            if raw is True:
+                return invalid_fallback
+            text = str(raw).strip().lower()
+            if text in {"off", "false", "none"}:
+                return None
+            if text in {"on", "true"}:
+                return invalid_fallback
+            try:
+                value = float(raw)
+            except (TypeError, ValueError):
+                logger.warning(
+                    "Unknown %s '%s', defaulting to %s",
+                    key_name,
+                    raw,
+                    "inherit" if invalid_fallback is _MISSING else f"{invalid_fallback}s",
+                )
+                return invalid_fallback
+            if math.isnan(value) or math.isinf(value):
+                logger.warning(
+                    "Unknown %s '%s', defaulting to %s",
+                    key_name,
+                    raw,
+                    "inherit" if invalid_fallback is _MISSING else f"{invalid_fallback}s",
+                )
+                return invalid_fallback
+            if value <= 0:
+                return None
+            return value
+
+        _MISSING = object()
+        try:
+            import yaml as _y
+            cfg_path = _hermes_home / "config.yaml"
+            if cfg_path.exists():
+                with open(cfg_path, encoding="utf-8") as _f:
+                    cfg = _y.safe_load(_f) or {}
+                display_cfg = cfg.get("display", {}) if isinstance(cfg, dict) else {}
+            else:
+                display_cfg = {}
+        except Exception:
+            display_cfg = {}
+
+        raw_value = _coerce_interval(
+            display_cfg.get("still_working_interval"),
+            key_name="still_working_interval",
+            invalid_fallback=600.0,
+        )
+        if raw_value is _MISSING:
+            raw_value = _coerce_interval(
+                os.getenv("HERMES_AGENT_NOTIFY_INTERVAL"),
+                key_name="HERMES_AGENT_NOTIFY_INTERVAL",
+                invalid_fallback=600.0,
+            )
+        interval = 600.0 if raw_value is _MISSING else raw_value
+
+        overrides = display_cfg.get("still_working_overrides", {})
+        if not isinstance(overrides, dict):
+            overrides = {}
+        if platform_key:
+            override_value = _coerce_interval(
+                overrides.get(platform_key),
+                key_name=f"still_working_overrides.{platform_key}",
+                invalid_fallback=_MISSING,
+            )
+            if override_value is not _MISSING:
+                interval = override_value
+
+        return interval
+
     @staticmethod
     def _load_provider_routing() -> dict:
         """Load OpenRouter provider routing preferences from config.yaml."""
@@ -18625,12 +18714,11 @@ async def monitor_for_interrupt():
         interrupt_monitor = asyncio.create_task(monitor_for_interrupt())
 
         # Periodic "still working" notifications for long-running tasks.
-        # Fires every N seconds so the user knows the agent hasn't died.
-        # Config: agent.gateway_notify_interval in config.yaml, or
-        # HERMES_AGENT_NOTIFY_INTERVAL env var.  Default 180s (3 min).
-        # 0 = disable notifications.
-        _NOTIFY_INTERVAL_RAW = _float_env("HERMES_AGENT_NOTIFY_INTERVAL", 180)
-        _NOTIFY_INTERVAL = _NOTIFY_INTERVAL_RAW if _NOTIFY_INTERVAL_RAW > 0 else None
+        # Default every 10 minutes, configurable via display.still_working_interval
+        # with optional per-platform overrides in display.still_working_overrides.
+        # Backward compat: if the new display keys are unset, honor the older
+        # agent.gateway_notify_interval / HERMES_AGENT_NOTIFY_INTERVAL setting.
+        _notify_interval = self._load_still_working_interval(platform_key)
         if not bool(
             resolve_display_setting(
                 user_config,
@@ -18639,12 +18727,12 @@ async def monitor_for_interrupt():
                 True,
             )
         ):
-            _NOTIFY_INTERVAL = None
+            _notify_interval = None
         _notify_start = time.time()
 
         async def _notify_long_running():
-            if _NOTIFY_INTERVAL is None:
-                return  # Notifications disabled (gateway_notify_interval: 0)
+            if _notify_interval is None:
+                return  # Notifications disabled
             _notify_adapter = self.adapters.get(source.platform)
             if not _notify_adapter:
                 return
@@ -18655,7 +18743,7 @@ async def _notify_long_running():
             # supported by the adapter.
             _heartbeat_msg_id: Optional[str] = None
             while True:
-                await asyncio.sleep(_NOTIFY_INTERVAL)
+                await asyncio.sleep(_notify_interval)
                 _elapsed_mins = int((time.time() - _notify_start) // 60)
                 # Include agent activity context if available. Default
                 # heartbeat is terse: elapsed + current tool. Verbose
@@ -18673,15 +18761,19 @@ async def _notify_long_running():
                 )
                 if _agent_ref and hasattr(_agent_ref, "get_activity_summary"):
                     try:
-                        _a = _agent_ref.get_activity_summary()
+                        _act = _agent_ref.get_activity_summary()
                         _parts = []
                         if _want_iteration_detail:
-                            _parts.append(
-                                f"iteration {_a['api_call_count']}/{_a['max_iterations']}"
-                            )
-                        _action = _a.get("current_tool") or _a.get("last_activity_desc")
-                        if _action:
-                            _parts.append(str(_action))
+                            _iter_n = _act.get("api_call_count", 0)
+                            _iter_max = _act.get("max_iterations", 0)
+                            _parts.append(f"iteration {_iter_n}/{_iter_max}")
+                        _cur_tool = _act.get("current_tool")
+                        if _cur_tool:
+                            _parts.append(f"running: {_cur_tool}")
+                        else:
+                            _last_desc = _act.get("last_activity_desc")
+                            if _last_desc:
+                                _parts.append(str(_last_desc))
                         if _parts:
                             _status_detail = " — " + ", ".join(_parts)
                     except Exception:
@@ -18714,7 +18806,8 @@ async def _notify_long_running():
                 except Exception as _ne:
                     logger.debug("Long-running notification error: %s", _ne)
 
-        _notify_task = asyncio.create_task(_notify_long_running())
+        _notify_task = asyncio.create_task(_notify_long_running()) if _notify_interval is not None else None
+
 
         try:
             # Run in thread pool to not block.  Use an *inactivity*-based
@@ -19130,7 +19223,8 @@ async def _notify_long_running():
             if progress_task:
                 progress_task.cancel()
             interrupt_monitor.cancel()
-            _notify_task.cancel()
+            if _notify_task:
+                _notify_task.cancel()
 
             # Wait for stream consumer to finish its final edit
             if stream_task:

hermes_cli/config.py

@@ -1406,6 +1406,8 @@ def _ensure_hermes_home_managed(home: Path):
         "interim_assistant_messages": True,  # Gateway: show natural mid-turn assistant status messages
         "tool_progress_command": False,  # Enable /verbose command in messaging gateway
         "tool_progress_overrides": {},  # DEPRECATED — use display.platforms instead
+        "still_working_interval": 600,  # Seconds between long-running task heartbeats in the gateway (0/false/off disables)
+        "still_working_overrides": {},  # Per-platform interval overrides: {"signal": "off", "telegram": 300}
         "tool_preview_length": 0,  # Max chars for tool call previews (0 = no limit, show full paths/commands)
         # Auto-delete system-notice replies (e.g. "✨ New session started!",
         # "♻ Restarting gateway…", "⚡ Stopped…") after N seconds on platforms
@@ -4452,9 +4454,30 @@ def migrate_config(interactive: bool = True, quiet: bool = False) -> Dict[str, A
                 print(f"  ✓ Migrated tool_progress_overrides → display.platforms: {migrated}")
             results["config_added"].append("display.platforms (migrated from tool_progress_overrides)")
 
-    # ── Version 16 → 17: remove legacy compression.summary_* keys ──
+    # ── Version 16 → 17: add still-working heartbeat display settings and remove
+    # legacy compression.summary_* keys ──
     if current_ver < 17:
         config = read_raw_config()
+        changed = False
+
+        display = config.get("display", {})
+        if not isinstance(display, dict):
+            display = {}
+        if "still_working_interval" not in display:
+            display["still_working_interval"] = 600
+            results["config_added"].append("display.still_working_interval=600 (default)")
+            changed = True
+            if not quiet:
+                print("  ✓ Added display.still_working_interval=600")
+        if "still_working_overrides" not in display:
+            display["still_working_overrides"] = {}
+            results["config_added"].append("display.still_working_overrides={} (default)")
+            changed = True
+            if not quiet:
+                print("  ✓ Added display.still_working_overrides={}")
+        if changed:
+            config["display"] = display
+
         comp = config.get("compression", {})
         if isinstance(comp, dict):
             s_model = comp.pop("summary_model", None)
@@ -4482,13 +4505,16 @@ def migrate_config(interactive: bool = True, quiet: bool = False) -> Dict[str, A
                     migrated_keys.append(f"base_url={s_base_url}")
             if migrated_keys or s_model is not None or s_provider is not None or s_base_url is not None:
                 config["compression"] = comp
-                save_config(config)
+                changed = True
                 if not quiet:
                     if migrated_keys:
                         print(f"  ✓ Migrated compression.summary_* → auxiliary.compression: {', '.join(migrated_keys)}")
                     else:
                         print("  ✓ Removed unused compression.summary_* keys")
 
+        if changed:
+            save_config(config)
+
     # ── Version 20 → 21: plugins are now opt-in; grandfather existing user plugins ──
     # The loader now requires plugins to appear in ``plugins.enabled`` before
     # loading. Existing installs had all discovered plugins loading by default