session_state.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272
  1. """Per-session gateway state in one container (replaces ~19 session_key-keyed dicts on
  2. GatewayRunner that bred boundary drift and wholesale-reset races). Scopes follow where each dict
  3. was CLEARED: ``turn`` at the end of every turn; ``conversation`` at conversation boundaries (/new,
  4. /resume, auto-reset, expiry); ``persistent`` fields have their own lifecycles."""
  5. from __future__ import annotations
  6. from collections.abc import MutableMapping
  7. from dataclasses import dataclass, field
  8. from typing import Any, Callable, Dict, Iterator, List, NamedTuple, Optional, Tuple
  9. # /fast stores "priority" or None (explicit normal), so key PRESENCE decides, not truthiness.
  10. _UNSET_TIER = object()
  11. SERVICE_TIER_UNSET = _UNSET_TIER # public alias
  12. @dataclass
  13. class TurnState:
  14. """State scoped to one running gateway turn. ``lease_tokens`` is NOT touched by
  15. ``clear()``: ``_release_turn_lease`` owns it (release exactly once)."""
  16. agent: Any = None # running AIAgent (or _AGENT_PENDING_SENTINEL); None = idle
  17. # The MessageEvent that opened the running turn and the live TurnContext: a successful busy
  18. # redirect re-anchors both to the redirecting message (#115001).
  19. event: Any = None
  20. ctx: Any = None
  21. started_ts: float = 0.0 # 0.0 = not running
  22. lease: Any = None # cross-process active-session slot lease
  23. busy_ack_ts: float = 0.0 # debounce; 0.0 = never acked
  24. # Held turn-lease tokens keyed by acquiring run generation: release/rebind resolve the
  25. # token for their own generation, so a displaced turn's unwind frees only its own lease and
  26. # never a successor's (an evicted turn and its replacement may both hold one briefly).
  27. lease_tokens: dict[int, Any] = field(default_factory=dict)
  28. # Agents taken out of the cache while this turn still ran them (a one-turn ``model_override``
  29. # agent): ``_release_running_agent_state`` releases them once the slot clears.
  30. retired_agents: list[Any] = field(default_factory=list)
  31. def clear(self) -> None:
  32. """Reset the per-turn slot. The caller pops ``lease`` first to release it."""
  33. self.agent = self.lease = self.event = self.ctx = None
  34. self.started_ts = self.busy_ack_ts = 0.0
  35. @dataclass
  36. class ConversationState:
  37. """State scoped to one conversation (survives turns, not boundaries)."""
  38. model_override: Optional[dict[str, Any]] = None # /model per-session override
  39. one_turn_restore: Optional[dict[str, Any]] = None # /model --once snapshot
  40. reasoning_override: Optional[dict[str, Any]] = None # /reasoning override
  41. service_tier_override: Any = _UNSET_TIER # /fast: "priority" or None; _UNSET_TIER = absent
  42. last_resolved_model: str = "" # last successfully-resolved non-empty model
  43. queued_events: list[Any] = field(default_factory=list) # /queue overflow FIFO (head in adapter)
  44. sidecar_notes: list[str] = field(default_factory=list) # one-shot must-deliver notes
  45. ephemeral_pin: Optional[tuple[Any, ...]] = None # pinned session-context (change_key, text, redact_pii)
  46. # (channel_prompt, parent_chat_id) of the last non-internal turn; internal events reuse it
  47. channel_pin: Optional[tuple[Optional[str], Optional[str]]] = None
  48. vc_last: Optional[str] = None # last voice-channel context delivered
  49. def clear(self) -> None:
  50. """Reset every field to its default, so new fields are cleared automatically."""
  51. self.__dict__.update(ConversationState().__dict__)
  52. @dataclass
  53. class PersistentState:
  54. """State with its own lifecycle — NOT cleared wholesale by turn or boundary resets
  55. (approvals/update prompts ARE cleared, individually, by the boundary security funnel)."""
  56. approvals: Optional[dict[str, Any]] = None # {"command": ..., "pattern_key": ...}
  57. update_prompt_pending: bool = False # /update prompt awaiting a reply
  58. native_image_paths: list[str] = field(default_factory=list) # consumed one-shot
  59. # Legacy runner-level pending text (flushed on shutdown); not the adapter-level one.
  60. pending_command_text: Optional[str] = None
  61. run_generation: int = 0 # monotonic; NEVER reset (stale-run detection depends on it)
  62. # Consecutive hygiene compression failures (the in-agent ladder is unreachable: hygiene builds
  63. # a FRESH AIAgent per run). Reset on success; process-local, mirrored to the DB by run.py.
  64. # Monotonic run-generation counter (#28686). NEVER reset: clearing it would break stale-run detection.
  65. # The in-agent compressor escalates repeat timeouts via ContextCompressor._consecutive_timeout_failures,
  66. # but hygiene builds a FRESH AIAgent per run and bind_session_state() zeroes that counter, so the
  67. # in-agent ladder is structurally unreachable from the gateway. Tracking the streak here — outside the
  68. # per-run agent — lets hygiene escalate its cooldown instead of retrying on a flat interval forever.
  69. # Reset on a successful compression, not by turn/boundary resets. PROCESS-LOCAL, deliberately:
  70. # `PersistentState` means "survives turn and boundary resets", NOT "survives a restart" — this field has
  71. # no disk flush (unlike `pending_command_text` above, #72680), so a gateway restart drops escalation
  72. # back to rung 1 while the DB-backed deadline itself survives (#74136). Keying on `session_key` rather
  73. # than `session_id` is what buys correctness across compaction ROTATION (the sid changes, the chat does
  74. # not). gateway.run mirrors this value to the DB keyed by session_key so the same semantics also survive
  75. # gateway restarts.
  76. hygiene_failure_streak: int = 0
  77. @dataclass
  78. class SessionState:
  79. """All per-session gateway state, grouped by lifecycle scope."""
  80. turn: TurnState = field(default_factory=TurnState)
  81. conversation: ConversationState = field(default_factory=ConversationState)
  82. persistent: PersistentState = field(default_factory=PersistentState)
  83. # --- Legacy dict-view adapters: tests read/write the old dict attributes directly
  84. # (``runner._running_agents = {}``); each view is a LIVE MutableMapping over one field.
  85. class _FieldSpec(NamedTuple):
  86. """One legacy dict: scope attr, field name, default factory, presence test."""
  87. scope: str
  88. name: str
  89. default: Callable[[], Any]
  90. is_present: Callable[[Any], bool]
  91. def _spec(scope: str, name: str, default: Any) -> _FieldSpec:
  92. """``default`` is a type (presence = truthiness) or a sentinel (presence = ``is not``)."""
  93. if isinstance(default, type):
  94. return _FieldSpec(scope, name, default, bool)
  95. return _FieldSpec(scope, name, lambda: default, lambda v: v is not default)
  96. class _RunnerView(MutableMapping):
  97. """Shared plumbing: live view over ``runner._sessions``, dict-comparable."""
  98. __slots__ = ("_runner",)
  99. def __init__(self, runner: Any) -> None:
  100. self._runner = runner
  101. def _sessions(self) -> dict[str, SessionState]:
  102. return self._runner.__dict__.get("_sessions") or {}
  103. def __len__(self) -> int:
  104. return sum(1 for _ in self)
  105. def __eq__(self, other: object) -> bool: # Mapping has no __eq__; tests compare to dicts
  106. if isinstance(other, (dict, MutableMapping)):
  107. return dict(self.items()) == dict(other)
  108. return NotImplemented
  109. class SessionFieldView(_RunnerView):
  110. """Live dict-like view of one SessionState field across sessions."""
  111. __slots__ = ("_spec",)
  112. def __init__(self, runner: Any, spec: _FieldSpec) -> None:
  113. super().__init__(runner)
  114. self._spec = spec
  115. def _value(self, state: SessionState) -> Any:
  116. return getattr(getattr(state, self._spec.scope), self._spec.name)
  117. def _set(self, state: SessionState, value: Any) -> None:
  118. setattr(getattr(state, self._spec.scope), self._spec.name, value)
  119. def _present(self, key: Any) -> Optional[SessionState]:
  120. """The session state for ``key`` if its field is present, else None."""
  121. state = self._sessions().get(key)
  122. return state if state is not None and self._spec.is_present(self._value(state)) else None
  123. def _held(self, key: str) -> SessionState:
  124. state = self._present(key)
  125. if state is None:
  126. raise KeyError(key)
  127. return state
  128. def __getitem__(self, key: str) -> Any:
  129. return self._value(self._held(key))
  130. def __setitem__(self, key: str, value: Any) -> None:
  131. self._set(self._runner._session_state(key), value)
  132. def __delitem__(self, key: str) -> None:
  133. self._set(self._held(key), self._spec.default())
  134. def __iter__(self) -> Iterator[str]:
  135. return (k for k in list(self._sessions()) if self._present(k) is not None)
  136. def __contains__(self, key: object) -> bool:
  137. return self._present(key) is not None
  138. def clear(self) -> None: # avoid MutableMapping's popitem loop
  139. for state in list(self._sessions().values()):
  140. self._set(state, self._spec.default())
  141. def __repr__(self) -> str: # pragma: no cover - debug aid
  142. return f"SessionFieldView({self._spec.scope}.{self._spec.name}, {dict(self.items())!r})"
  143. class TurnLeaseTokenView(_RunnerView):
  144. """Legacy (session_key, generation)-keyed view of ``_turn_lease_tokens``; the lease registry
  145. serializes acquisition per session, so one ``TurnState`` slot per key equals the old dict."""
  146. __slots__ = ()
  147. def _held(self, key: Any) -> TurnState:
  148. """TurnState for a currently-held (session_key, generation) or raise KeyError."""
  149. if not isinstance(key, tuple) or len(key) != 2:
  150. raise KeyError(key)
  151. state = self._sessions().get(key[0])
  152. if state is None or key[1] not in state.turn.lease_tokens:
  153. raise KeyError(key)
  154. return state.turn
  155. def __getitem__(self, key: Any) -> Any:
  156. return self._held(key).lease_tokens[key[1]]
  157. def __setitem__(self, key: Any, value: Any) -> None:
  158. if not isinstance(key, tuple) or len(key) != 2:
  159. raise KeyError(key)
  160. self._runner._session_state(key[0]).turn.lease_tokens[key[1]] = value
  161. def __delitem__(self, key: Any) -> None:
  162. del self._held(key).lease_tokens[key[1]]
  163. def __iter__(self) -> Iterator[tuple[str, Any]]:
  164. return ((k, gen) for k, s in list(self._sessions().items()) for gen in list(s.turn.lease_tokens))
  165. def clear(self) -> None: # avoid MutableMapping's popitem loop
  166. for key in list(self):
  167. del self[key]
  168. # One spec per legacy dict attribute.
  169. LEGACY_FIELD_SPECS: dict[str, _FieldSpec] = {
  170. "_running_agents": _spec("turn", "agent", None),
  171. "_running_agents_ts": _spec("turn", "started_ts", float),
  172. "_active_session_leases": _spec("turn", "lease", None),
  173. "_busy_ack_ts": _spec("turn", "busy_ack_ts", float),
  174. "_session_model_overrides": _spec("conversation", "model_override", None),
  175. "_pending_one_turn_model_restores": _spec("conversation", "one_turn_restore", None),
  176. "_session_reasoning_overrides": _spec("conversation", "reasoning_override", None),
  177. "_session_service_tier_overrides": _spec("conversation", "service_tier_override", _UNSET_TIER),
  178. "_last_resolved_model": _spec("conversation", "last_resolved_model", str),
  179. "_queued_events": _spec("conversation", "queued_events", list),
  180. "_pending_turn_sidecar_notes": _spec("conversation", "sidecar_notes", list),
  181. "_session_ephemeral_pin": _spec("conversation", "ephemeral_pin", None),
  182. "_session_vc_last": _spec("conversation", "vc_last", None),
  183. "_pending_approvals": _spec("persistent", "approvals", None),
  184. "_update_prompt_pending": _spec("persistent", "update_prompt_pending", bool),
  185. "_pending_native_image_paths_by_session": _spec("persistent", "native_image_paths", list),
  186. "_pending_messages": _spec("persistent", "pending_command_text", None),
  187. "_session_run_generation": _spec("persistent", "run_generation", int),
  188. }
  189. def _legacy_property(make_view: Callable[[Any], MutableMapping], doc: str) -> property:
  190. """Dict-shaped @property over a live view; the setter takes a plain dict (test pattern
  191. ``runner._X = {...}``): reset the field on every session, then apply the entries."""
  192. def fset(self: Any, mapping: Optional[dict[Any, Any]]) -> None:
  193. view = make_view(self)
  194. view.clear()
  195. view.update(mapping or {})
  196. return property(make_view, fset, lambda self: make_view(self).clear(), doc=doc)
  197. def legacy_dict_property(attr_name: str) -> property:
  198. """Legacy dict-shaped @property for one migrated attribute."""
  199. spec = LEGACY_FIELD_SPECS[attr_name]
  200. return _legacy_property(
  201. lambda self: SessionFieldView(self, spec),
  202. f"Legacy dict view over SessionState.{spec.scope}.{spec.name} (for pre-SessionState tests).",
  203. )
  204. def legacy_lease_token_property() -> property:
  205. """Legacy (session_key, generation)-keyed view of held turn-lease tokens."""
  206. return _legacy_property(
  207. TurnLeaseTokenView, "Legacy (session_key, generation)-keyed turn-lease token view."
  208. )