session_activity.py 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149
  1. """Shared session activity observation contract: timestamp + bounded description/provenance, observation
  2. only (notification, timeout, kill and retry policy live elsewhere). Provenance is a small closed enum of
  3. *noun* sources; the default agent clock stamps ``unknown`` unless a writer passes ``provenance=``."""
  4. from __future__ import annotations
  5. import sys
  6. import time
  7. from contextlib import suppress
  8. from enum import Enum
  9. from typing import Any, Mapping, Optional
  10. from agent.i18n import t
  11. ACTIVITY_DESCRIPTION_MAX = 120
  12. # Durable SessionDB heartbeat cadence. Contract: MUST stay >= 30s — the SessionDB write path is contended and
  13. # this observation-only projection never justifies extra write pressure. A code constant on purpose (no config
  14. # can make it a high-frequency writer); matches the kanban auto-heartbeat. force_persist and terminal
  15. # compression stamps (see TERMINAL_COMPRESSION_PROVENANCES) are the only bypasses.
  16. SESSION_ACTIVITY_HEARTBEAT_MIN_INTERVAL_SECONDS = 60.0
  17. class ActivityProvenance(str, Enum):
  18. """Where a durable/in-memory activity stamp came from."""
  19. UNKNOWN = "unknown"
  20. # Compression writers: heartbeat, host timeout, cooldown, turn hold.
  21. # See #72424.
  22. AGENT_COMPRESSION = "agent.compression"
  23. AGENT_COMPRESSION_TIMEOUT = "agent.compression_timeout"
  24. AGENT_COMPRESSION_COOLDOWN = "agent.compression_cooldown"
  25. AGENT_COMPRESSION_TURNHOLD = "agent.compression_turnhold"
  26. # Provenances that END the user-visible "compressing" phase: the host's progress timeout, a cooldown/
  27. # backoff block, and the gateway's hygiene turn-hold. Each is written once, at a terminal edge, and must
  28. # reach the durable projection IMMEDIATELY — the heartbeat above wrote "context compression in progress"
  29. # moments earlier, so a rate-limited terminal stamp leaves `sessions.last_activity_description` advertising
  30. # a compression that has already stopped, with no later writer to correct it (the agent may be idle, the
  31. # process gone). That is the permanently "stuck / compressing" chat users see.
  32. #
  33. # Distinct from ``conversation_compression._TERMINAL_COMPRESSION_PROVENANCES``, which answers a different
  34. # question — "may a detached heartbeat still overwrite this stamp?" — and deliberately excludes TURNHOLD,
  35. # because after a turn-hold the worker may still be alive and adoptable.
  36. TERMINAL_COMPRESSION_PROVENANCES = frozenset(
  37. {
  38. ActivityProvenance.AGENT_COMPRESSION_TIMEOUT,
  39. ActivityProvenance.AGENT_COMPRESSION_COOLDOWN,
  40. ActivityProvenance.AGENT_COMPRESSION_TURNHOLD,
  41. }
  42. )
  43. def is_terminal_compression_provenance(provenance: Optional[ActivityProvenance | str]) -> bool:
  44. """True when this stamp ends a compression phase and must bypass the persist rate limit."""
  45. return normalize_activity_provenance(provenance) in TERMINAL_COMPRESSION_PROVENANCES
  46. def bound_activity_description(description: Optional[str]) -> str:
  47. """Clamp free-form activity text to the shared description budget."""
  48. text = (description or "").strip()
  49. return text if len(text) <= ACTIVITY_DESCRIPTION_MAX else text[: ACTIVITY_DESCRIPTION_MAX - 1] + "…"
  50. def normalize_activity_provenance(provenance: Optional[ActivityProvenance | str]) -> ActivityProvenance:
  51. """Return a known provenance, or ``UNKNOWN`` when unset/unrecognized."""
  52. if isinstance(provenance, ActivityProvenance):
  53. return provenance
  54. try:
  55. return ActivityProvenance((provenance or "").strip())
  56. except ValueError:
  57. return ActivityProvenance.UNKNOWN
  58. def format_iteration_progress(api_call_count: Any, max_iterations: Any) -> str:
  59. """``iteration N/M`` for user-facing status lines, or ``iteration N`` when the cap is unbounded.
  60. ``AIAgent.max_iterations`` defaults to ``sys.maxsize`` (unlimited), so printing the pair verbatim
  61. shows ``iteration 3/9223372036854775807`` in busy acks, heartbeats and timeout diagnostics (#102806).
  62. """
  63. try:
  64. cap = int(max_iterations)
  65. except (TypeError, ValueError):
  66. cap = sys.maxsize
  67. if cap >= sys.maxsize:
  68. return t("display.iteration_progress.unbounded", n=api_call_count)
  69. return t("display.iteration_progress.bounded", n=api_call_count, max=cap)
  70. def reset_session_activity_persist_window(agent: Any) -> None:
  71. """Clear the persist rate-limit so the next stamp writes through (terminal compression labels must not stick on mid-compress text)."""
  72. with suppress(Exception):
  73. agent._session_activity_last_persist_mono = 0.0
  74. def build_activity_snapshot(
  75. *,
  76. last_activity_at: Optional[float],
  77. last_activity_description: Optional[str],
  78. last_activity_provenance: Optional[ActivityProvenance | str] = None,
  79. now: Optional[float] = None,
  80. extra: Optional[Mapping[str, Any]] = None,
  81. ) -> dict[str, Any]:
  82. """Build the shared activity snapshot (plus optional caller extras)."""
  83. when = float(last_activity_at) if last_activity_at is not None else None
  84. clock = float(now if now is not None else time.time())
  85. desc = bound_activity_description(last_activity_description)
  86. prov = normalize_activity_provenance(last_activity_provenance).value
  87. return {
  88. "last_activity_at": when,
  89. "last_activity_description": desc,
  90. "last_activity_provenance": prov,
  91. "seconds_since_activity": round(clock - when, 1) if when is not None else None,
  92. # Short aliases used by existing gateway/delegate readers.
  93. "last_activity_ts": when, "last_activity_desc": desc, "description": desc, "provenance": prov,
  94. **(extra or {}),
  95. }
  96. class AwakeIdleMeter:
  97. """Removes host sleep from a polling watchdog's idle readings.
  98. Idle time is measured on the wall clock, which keeps running while the host sleeps, so a laptop
  99. that sleeps 15 minutes mid-turn wakes up "idle" for 15 minutes and the first poll after resume
  100. kills a turn that never had a chance to run. ``time.monotonic()`` pauses during sleep on macOS
  101. (``mach_absolute_time``) and Linux (``CLOCK_MONOTONIC``), so the two clocks drift apart by the
  102. time spent asleep. Call :meth:`measure` once per poll with the wall-clock idle seconds.
  103. """
  104. def __init__(self) -> None:
  105. self._wall, self._mono = time.time(), time.monotonic()
  106. self._asleep_s = 0.0
  107. def measure(self, idle_s: float) -> float:
  108. """Return *idle_s* minus the sleep observed since the agent's last activity."""
  109. wall, mono = time.time(), time.monotonic()
  110. slept_s = max(0.0, (wall - self._wall) - (mono - self._mono))
  111. # Activity since the previous sample (it is younger than the sampling interval) makes all
  112. # earlier credit predate it. A rarely sampled meter (stale-agent eviction samples only
  113. # when a message arrives) would otherwise keep charging old sleep against new idle time.
  114. if idle_s < wall - self._wall:
  115. self._asleep_s = 0.0
  116. self._asleep_s += slept_s
  117. self._wall, self._mono = wall, mono
  118. # The idle sample may predate sleep observed by these clock reads. Keep that new
  119. # credit until the next poll; only older credit can be trimmed by renewed activity.
  120. self._asleep_s = max(0.0, min(self._asleep_s, idle_s + slept_s))
  121. return max(0.0, idle_s - self._asleep_s)