session_detached.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303
  1. """A messaging conversation its chat moved past stays usable from the apps (Teknium's ruling).
  2. When a messaging chat names another conversation (``/new``, ``/resume``, ``/branch``, a handoff,
  3. its next inbound naming another one), a Desktop / Webapp / mobile view still open on the previous
  4. conversation keeps working: its turns, Stop and controls act on that conversation alone, and its
  5. replies reach its viewers only, never the chat, which now gets only its new conversation's replies.
  6. ``detach`` moves the live session off the chat's route onto a key that names the conversation
  7. (``agent:<ns>:detached:<session id>``) and pins that key on a copy of its source
  8. (``SessionSource.detached_route``). From there the turn runs on the ordinary messaging path:
  9. * ``build_session_key`` answers the pinned key, so the runner's per-route state (running slot,
  10. agent cache, busy guard, the agent a Stop reaches) is the conversation's own, never the chat's;
  11. * ``SessionStore.get_or_create_session`` resolves the key to the conversation itself
  12. (``detached_entry``), and never creates or persists a route for it;
  13. * delivery goes through the profile's ``LocalSessionAdapter`` (gateway/session_local.py), as a local
  14. session's does: its sends publish nothing, viewers read the canonical event stream.
  15. The key carries no platform slot, so a reader that parses a chat out of a session key
  16. (``gateway.run._parse_session_key``) finds none and delivers nowhere. Its turns bind the session
  17. variables a Desktop session's turn binds (``session_env_source``), so a reminder, a kanban subscription
  18. or a ``send_message`` it starts names the app, never the chat. The chat naming the conversation again
  19. (``/resume``) moves it back onto the chat's route (``SessionAuthority.name_lane``).
  20. Every route change reaches ``name_lane`` from one place: the session store announces each conversation a
  21. route comes to name (``SessionStore.route_named``: ``/new``, ``/resume``, ``/branch``, ``/handoff``,
  22. the context-exhaustion auto-reset, a reset policy, a topic binding heal), wired by ``watch_routes``.
  23. """
  24. from __future__ import annotations
  25. import asyncio
  26. from datetime import datetime, timedelta
  27. _SLOT = 'detached'
  28. def detached_route_of(source) -> str | None:
  29. """*source*'s pinned detached key; None for any other source (duck-typed test sources too)."""
  30. route = getattr(source, 'detached_route', None)
  31. return route if isinstance(route, str) else None
  32. def detached_key(route: str, session_id: str) -> str:
  33. """The detached key of *session_id*, in the profile namespace of its chat's *route*."""
  34. parts = route.split(':')
  35. namespace = ':'.join(parts[:2]) if len(parts) > 1 and parts[0] == 'agent' else 'agent:main'
  36. return f'{namespace}:{_SLOT}:{session_id}'
  37. def detached_session_id(key: str) -> str | None:
  38. parts = key.split(':')
  39. return parts[3] if len(parts) == 4 and parts[0] == 'agent' and parts[2] == _SLOT else None
  40. def detach(authority, live, session_id) -> None:
  41. """Move *live* (a messaging conversation its chat no longer names) off the chat's route. A
  42. history mount (no source) has no route to leave, and a detached one has left it already."""
  43. if live.source is None or detached_route_of(live.source):
  44. return
  45. from gateway.session_identity import replace_source
  46. from gateway.session_local_recovery import local_adapter
  47. adapter = local_adapter(authority) # its delivery; a messaging-only gateway has none yet
  48. live.route = detached_key(live.route, session_id)
  49. # No reply anchor: its replies reach the apps, and a background result's event is this very source.
  50. live.source = replace_source(live.source, detached_route=live.route, message_id=None)
  51. adapter.register_source(live.source) # what admits its background results (``authorize_source``)
  52. def lane_source(source):
  53. """*source* as its chat's own, a detached copy's pin dropped: what a conversation that takes the
  54. chat's route over starts from (the route moved first, so the one it replaced is detached by now)."""
  55. if detached_route_of(source) is None:
  56. return source
  57. from gateway.session_identity import replace_source
  58. return replace_source(source, detached_route=None)
  59. def forget_detached(authority, key) -> None:
  60. """*key* names no live conversation any more (it came back onto its chat, or retired): its
  61. cached agent commits and goes, as at any boundary (a later idle eviction would commit it while the
  62. conversation runs elsewhere), and the store forgets the ids it owned (``detached_entry``)."""
  63. runner = authority.runner
  64. evict = getattr(runner, '_evict_cached_agent_at_boundary', None)
  65. if evict is not None:
  66. evict(key)
  67. drop_owner_hints(runner.session_store, key)
  68. from gateway.config import Platform
  69. from gateway.session_local_recovery import local_adapter_map
  70. local = local_adapter_map(authority).get(Platform.LOCAL)
  71. if local is not None:
  72. local.sources.pop(key, None) # what admitted the detached copy's background results
  73. def drop_owner_hints(store, key) -> None:
  74. hints = getattr(store, '_session_owner_hints', None) or {}
  75. for session_id in [sid for sid, owner in list(hints.items()) if owner == key]:
  76. hints.pop(session_id, None)
  77. def running_key(runner, route, session_id) -> str:
  78. """The key a turn of *session_id* runs under: its detached key while a turn that started there
  79. still runs (the chat took the conversation back meanwhile), so a Stop from the chat or the app
  80. reaches it; else *route*."""
  81. key = detached_key(route, session_id)
  82. return key if key in (getattr(runner, '_running_agents', None) or {}) else route
  83. def chat_running_key(runner, route, entry) -> str:
  84. """``running_key`` for the conversation the chat's *route* names (*entry*, its routing entry)."""
  85. from gateway.session_authorities import active_authority
  86. authority = active_authority(runner)
  87. return route if authority is None else running_key(runner, route, authority.logical_owner(entry.session_id))
  88. def session_env_source(runner, source):
  89. """The source a turn's session variables (``HERMES_SESSION_PLATFORM``, ``_CHAT_ID``, ...) name.
  90. A conversation its chat moved past binds the local view a Desktop session's turn binds
  91. (``local_source``): whatever it schedules for "here" reaches the apps, never the chat."""
  92. key = detached_route_of(source)
  93. if key is None:
  94. return source
  95. from gateway.session_authorities import active_authority
  96. from gateway.session_local_recovery import local_source
  97. return local_source(active_authority(runner), detached_session_id(key), source.user_id)
  98. def _route_authority(runner, store, route):
  99. """The authority owning *route*: its key names the profile, whatever scope the writer runs in."""
  100. from gateway.session_authorities import authority_for_home
  101. from hermes_constants import hermes_home_key
  102. registry = getattr(runner, 'session_authorities', None)
  103. if store._named_profile_for_key(route) is None: # the launch profile's own key
  104. if registry is None:
  105. return getattr(runner, 'session_authority', None)
  106. return next((a for a in registry.serving() if hermes_home_key(a.profile_id) == registry.launch_key), None)
  107. home = store._profile_home_for_key(route)
  108. return authority_for_home(runner, home) if home is not None else None
  109. def watch_routes(runner, store) -> None:
  110. """Wire *store*'s route announcements to the owning authority's ``name_lane``. A store write off
  111. the owner loop (a worker thread) hands the move to the loop, ahead of the writer's own resumption,
  112. so nothing on the loop sees the new route before the conversation it replaced has left it."""
  113. loop = asyncio.get_running_loop()
  114. def route_named(route, session_id, origin):
  115. authority = _route_authority(runner, store, route)
  116. if authority is None or origin is None:
  117. return
  118. def name():
  119. # Writers announce outside the store lock, so announcements can land out of order: one
  120. # the store has since moved past (a worker's /resume overtaken by a /new) would hand the
  121. # chat back a conversation it left; the newer write announces itself. Compared by logical
  122. # owner: a compression repoint since (unannounced) is still the same conversation.
  123. current = store.lookup_by_session_key(route)
  124. owner = authority.logical_owner(session_id)
  125. if current is None or authority.logical_owner(current.session_id) != owner:
  126. return
  127. authority.name_lane(route, owner, origin)
  128. try:
  129. on_loop = asyncio.get_running_loop() is loop
  130. except RuntimeError:
  131. on_loop = False
  132. if on_loop:
  133. name()
  134. elif not loop.is_closed():
  135. loop.call_soon_threadsafe(name)
  136. store.route_named = route_named
  137. def recover_detached_sessions(authority, pending):
  138. """Boot: schedule the queued input of conversations their chats moved past (an app prompt
  139. accepted during a restart's after-turn wait). The routing index names only each chat's current
  140. conversation, so native recovery never binds these, and no chat message will wake them."""
  141. from gateway.session_contract import SessionRef
  142. from gateway.session_route_recovery import restore_routed_session
  143. scheduled = []
  144. from hermes_state_runtime import list_session_admissions
  145. for session_id in sorted(pending):
  146. if session_id in authority.sessions or not any( # a lost (unknown) turn waits for /discard
  147. row['status'] == 'queued' for row in list_session_admissions(authority.db, session_id=session_id)):
  148. continue
  149. if restore_routed_session(authority, session_id) is None:
  150. continue
  151. if authority.sessions[session_id].detached:
  152. authority._schedule(SessionRef(authority.profile_id, session_id))
  153. scheduled.append(session_id)
  154. return scheduled
  155. def detached_live(authority, route):
  156. """``(ref, live)`` of the conversation still live on detached key *route*, else None."""
  157. from gateway.session_contract import SessionRef
  158. session_id = detached_session_id(route)
  159. live = authority.sessions.get(session_id) if session_id else None
  160. if live is None or live.route != route:
  161. return None
  162. return SessionRef(authority.profile_id, session_id), live
  163. def own_detached_key(key, session_id) -> bool:
  164. """*key* is *session_id*'s own detached key (the route it was on while its chat was elsewhere)."""
  165. return isinstance(key, str) and detached_session_id(key) == session_id
  166. async def follow_detached_pin(runner, evt):
  167. """*evt* (a background result) on its pinned conversation's detached key, else *evt* itself.
  168. The chat's turn on a conversation started it, and the chat has moved on since, but the
  169. conversation is still open: the app used it after the chat's ``/new`` (a row the ``/new`` left
  170. ended stays a boundary, and its result is dropped once). The result lands in that conversation,
  171. for its app viewers, never in the chat's current one, and is never refused there on every retry
  172. (#141562). A conversation not mounted (a restart) mounts off the chat first."""
  173. key = str(evt.get('session_key') or '')
  174. pinned = str(evt.get('parent_session_id') or '').strip()
  175. from gateway.session_authorities import all_authorities
  176. if not key or not all_authorities(runner):
  177. return evt
  178. if (detached := detached_session_id(key)) is not None:
  179. return _follow_detached_key(runner, evt, key, detached)
  180. if not pinned:
  181. return evt
  182. store = runner.session_store
  183. authority = _route_authority(runner, store, key)
  184. entry = store.lookup_by_session_key(key) if authority is not None else None
  185. if authority is None or entry is None:
  186. return evt
  187. verdict, _owner, target = await runner._classify_completion_owner(pinned, key)
  188. session_id = authority.logical_owner(target) if verdict == 'deliver' else None
  189. if session_id is None or session_id == authority.logical_owner(entry.session_id):
  190. return evt
  191. row = authority.db.get_session(target)
  192. if row is None or row.get('ended_at'):
  193. return evt
  194. live = _mounted(authority, session_id)
  195. if live is None or live.route != detached_key(key, session_id):
  196. return evt
  197. return {**evt, 'session_key': live.route}
  198. def _follow_detached_key(runner, evt, key, session_id):
  199. """A result of a turn that ran on detached *key*: on the chat's route once the chat names the
  200. conversation again (its ``/resume``), as that conversation's own result there."""
  201. authority = _route_authority(runner, runner.session_store, key)
  202. live = _mounted(authority, session_id) if authority is not None else None
  203. if live is None or live.route == key:
  204. return evt
  205. return {**evt, 'session_key': live.route}
  206. def _mounted(authority, session_id):
  207. """*session_id*'s live session, mounted as its route would after a restart (off the chat when the
  208. chat names another conversation); None when it cannot be mounted now."""
  209. if session_id not in authority.sessions:
  210. from gateway.session_authorities import owner_scope
  211. from gateway.session_route_recovery import restore_routed_session
  212. from hermes_state_runtime import RuntimeStoreError
  213. try:
  214. with owner_scope(authority):
  215. restore_routed_session(authority, session_id)
  216. except RuntimeStoreError: # draining: the drain retries it
  217. return None
  218. return authority.sessions.get(session_id)
  219. def detached_live_source(runner, key):
  220. """The source of the conversation still live on detached key *key*, else None. The key's
  221. namespace names the owning profile: this runs before any profile scope is bound
  222. (``_completion_event_scope`` derives the scope from it)."""
  223. authority = _route_authority(runner, runner.session_store, key) if detached_session_id(key) else None
  224. found = detached_live(authority, key) if authority is not None else None
  225. return found[1].source if found is not None else None
  226. def route_entry(authority, route):
  227. """The routing entry *route* names: the store's, or a detached key's live conversation (a
  228. background result it started finds it there, never on the chat's route)."""
  229. store = authority.runner.session_store
  230. entry = store.lookup_by_session_key(route)
  231. if entry is None and (found := detached_live(authority, route)) is not None:
  232. return detached_entry(store, found[1].source)
  233. return entry
  234. def detached_entry(store, source):
  235. """The routing entry a detached *source* resolves to: its own conversation, at the compression
  236. tip a turn writes to. Never stored: the chat's route stays the only one this conversation has."""
  237. from gateway.session import SessionEntry
  238. key = source.detached_route
  239. session_id = str(detached_session_id(key))
  240. db = store._db_for_key(key)
  241. row = db.get_session(session_id) if db is not None else None
  242. tip = (db.get_compression_tip(session_id) if db is not None else None) or session_id
  243. # No route names it, so its by-id reads and writes (history, transcript, compression) find their
  244. # profile's store through the key; ``forget_detached`` drops these.
  245. hints = store._lazy('_session_owner_hints', dict)
  246. hints[session_id] = hints[tip] = key
  247. now = datetime.now()
  248. # Never a new conversation (that would fire session:start and first-contact notes).
  249. started = datetime.fromtimestamp(row['started_at']) if row and row.get('started_at') else now - timedelta(seconds=1)
  250. return SessionEntry(session_key=key, session_id=tip, created_at=started, updated_at=now, origin=source,
  251. platform=source.platform, chat_type=source.chat_type)