session_stall.py 2.8 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576
  1. """Gateway session stall notification policy.
  2. Consumes ``AIAgent.get_activity_summary()`` as the **single progress source** and owns
  3. only the notify-once policy for "pending inbound + stale progress"; it never derives a
  4. parallel progress clock from turn-start or inbound timestamps. Pending inbound is a
  5. stall *policy gate*, not a delivery obligation and not process liveness.
  6. """
  7. from __future__ import annotations
  8. import math
  9. import time
  10. from typing import Any, Mapping, Optional
  11. def should_emit_session_stall_notification(
  12. *, timeout_seconds: float, idle_seconds: Optional[float], has_pending_inbound: bool,
  13. already_notified: bool,
  14. ) -> bool:
  15. """Return True when a stall warning should be sent for this session."""
  16. return (
  17. timeout_seconds > 0 and has_pending_inbound and not already_notified
  18. and idle_seconds is not None and idle_seconds >= timeout_seconds
  19. )
  20. def should_clear_session_stall_notification(
  21. *, timeout_seconds: float, idle_seconds: Optional[float], has_pending_inbound: bool,
  22. ) -> bool:
  23. """Return True when a prior stall notice may be cleared (episode ended)."""
  24. if not has_pending_inbound or timeout_seconds <= 0:
  25. return True
  26. # Unknown progress holds the latch: observation gaps are not recovery.
  27. return idle_seconds is not None and idle_seconds < timeout_seconds
  28. def format_session_stall_notification(idle_seconds: float) -> str:
  29. """User-facing stall warning (ASCII minutes).
  30. See #72016.
  31. """
  32. mins = max(1, int(idle_seconds // 60))
  33. return (f"⚠️ I seem to be stuck (no activity for {mins} min). Send /stop to cancel the current "
  34. "task, or /new to start a fresh conversation.")
  35. def _finite_float(value: Any) -> Optional[float]:
  36. """``value`` as a finite float, or None (bools are rejected as non-numeric)."""
  37. if value is None or isinstance(value, bool):
  38. return None
  39. try:
  40. result = float(value)
  41. except (TypeError, ValueError):
  42. return None
  43. return result if math.isfinite(result) else None
  44. def resolve_session_idle_seconds_from_activity(
  45. activity: Optional[Mapping[str, Any]], *, now: Optional[float] = None,
  46. ) -> Optional[float]:
  47. """Idle seconds from a shared activity snapshot: a finite ``seconds_since_activity``, else
  48. derived from ``last_activity_at`` / ``last_activity_ts``. None when there is no usable
  49. progress timestamp — callers must not fall back to turn-start or inbound clocks.
  50. See #72039.
  51. """
  52. if not activity:
  53. return None
  54. idle = _finite_float(activity.get("seconds_since_activity"))
  55. if idle is not None:
  56. return max(0.0, idle)
  57. ts = activity.get("last_activity_at")
  58. when = _finite_float(activity.get("last_activity_ts") if ts is None else ts)
  59. if when is None:
  60. return None
  61. return max(0.0, float(time.time() if now is None else now) - when)