session_tui_ops.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341
  1. """Ink's session utilities on the shared owner: ``/save`` (``session.save``), ``/reload``
  2. (``reload.env``), ``/agents pause|resume`` (``delegation.pause``) and ``/rollback``
  3. (``rollback.list`` / ``rollback.diff`` / ``rollback.restore``), plus the classic CLI's ``/diff session``
  4. (``rollback.session_diff``).
  5. Main's per-TUI sidecar served these from its own session table, which never holds a shared-gateway
  6. session, so the canonical TUI refused them. Each verb reuses main's helpers rather than re-deriving
  7. them. ``dispatch`` already runs every handler under the owning profile's scope (``owner_scope``) and
  8. ``asyncio.to_thread`` carries that context into the worker thread.
  9. """
  10. import asyncio
  11. from datetime import datetime
  12. import json
  13. import re
  14. import uuid
  15. from functools import partial
  16. from pathlib import Path
  17. from gateway.session_busy_controls import authorize
  18. from gateway.session_tui_reads import context_breakdown
  19. from hermes_state_runtime import RuntimeStoreError
  20. def handlers(connection):
  21. return {'session.save': partial(save_session, connection),
  22. 'session.export': partial(export_session, connection),
  23. 'reload.env': partial(reload_env, connection),
  24. 'delegation.pause': partial(pause_delegation, connection),
  25. 'rollback.list': partial(rollback, connection, kind='list'),
  26. 'rollback.diff': partial(rollback, connection, kind='diff'),
  27. 'rollback.restore': partial(rollback, connection, kind='restore'),
  28. 'rollback.session_diff': partial(rollback, connection, kind='session_diff'),
  29. 'session.context_breakdown': partial(context_breakdown, connection),
  30. 'session.history': partial(session_history, connection)}
  31. def _profile_home(authority):
  32. """The owning profile's home (a symbolic test-peer id falls back to the scoped home)."""
  33. home = Path(str(authority.profile_id))
  34. if home.is_absolute() and home.is_dir():
  35. return home
  36. from hermes_constants import get_hermes_home
  37. return get_hermes_home()
  38. def _multiplexed(authority):
  39. """Every turn runs under a per-profile secret scope (``owner_scope``'s own predicate)."""
  40. return bool(getattr(getattr(authority.runner, 'config', None), 'multiplex_profiles', False))
  41. def _live_ref(connection, ref, params, fields, capability):
  42. if set(params) - fields or not isinstance(ref.session_id, str) or not ref.session_id:
  43. raise RuntimeStoreError('invalid_params')
  44. authorize(connection, ref, params, capability)
  45. return connection.authority.sessions[ref.session_id]
  46. async def save_session(connection, ref, params):
  47. """``/save``: main's ``session.save`` — the stored transcript as a ``/save json`` snapshot in the
  48. profile's ``sessions/saved/``. Reads the conversation's CURRENT physical row (a local session's
  49. reset/compression child), like main's ``_submit_row_target_key``."""
  50. _live_ref(connection, ref, params, {'session_id', 'profile'}, 'session:read')
  51. authority = connection.authority
  52. from gateway.session_ancillary import physical_target
  53. target = physical_target(authority, ref)
  54. def write():
  55. from hermes_cli.session_export import load_save_snapshot, render_session_for_save
  56. from hermes_state import SessionExportTooLargeError
  57. try:
  58. data = load_save_snapshot(authority.db, target, 'json')
  59. except SessionExportTooLargeError as exc:
  60. raise RuntimeStoreError('export_too_large') from exc
  61. if not data:
  62. raise RuntimeStoreError('not_found')
  63. path = (_profile_home(authority) / 'sessions' / 'saved'
  64. / f'hermes_conversation_{datetime.now():%Y%m%d_%H%M%S}.json')
  65. try:
  66. path.parent.mkdir(parents=True, exist_ok=True)
  67. path.write_text(render_session_for_save(data, 'json'), encoding='utf-8')
  68. except OSError as exc:
  69. raise RuntimeStoreError('storage_unavailable') from exc
  70. return {'file': str(path)}
  71. return await asyncio.to_thread(write)
  72. async def export_session(connection, ref, params):
  73. """``session.export``: the ``/save`` transcript rendered for the CLIENT to write (json/md/html,
  74. optional force-redaction). Nothing is written on the gateway host, so a remote Desktop and a
  75. local Ink both save to the user's own disk (T10/T11)."""
  76. _live_ref(connection, ref, params, {'session_id', 'profile', 'format', 'redact'}, 'session:read')
  77. fmt, redact = params.get('format', 'json'), params.get('redact', False)
  78. if not isinstance(fmt, str) or not isinstance(redact, bool):
  79. raise RuntimeStoreError('invalid_params')
  80. from hermes_cli.session_export import default_save_filename, normalize_save_format
  81. try:
  82. fmt = normalize_save_format(fmt)
  83. except ValueError:
  84. raise RuntimeStoreError('invalid_params') from None
  85. authority = connection.authority
  86. from gateway.session_ancillary import physical_target
  87. target = physical_target(authority, ref)
  88. def render():
  89. from hermes_cli.session_export import load_save_snapshot, render_session_for_save
  90. from hermes_state import SessionExportTooLargeError
  91. try:
  92. data = load_save_snapshot(authority.db, target, fmt)
  93. except SessionExportTooLargeError as exc:
  94. raise RuntimeStoreError('export_too_large') from exc
  95. if not data:
  96. raise RuntimeStoreError('not_found')
  97. if redact:
  98. from hermes_cli.session_export_md import redact_session_data
  99. data = redact_session_data(data)
  100. return render_session_for_save(data, fmt)
  101. content = await asyncio.to_thread(render)
  102. return {'format': fmt, 'filename': default_save_filename(target, fmt), 'content': content}
  103. async def session_history(connection, ref, params):
  104. """Main's ``session.history``: the display transcript of the conversation's current physical row (compression tip or local receipt entry), ancestors included, each row with its durable ``row_id``; Desktop's edit resolves its turn by it."""
  105. _live_ref(connection, ref, params, {'session_id', 'profile'}, 'session:read')
  106. authority = connection.authority
  107. from gateway.session_local_recovery import transcript_target
  108. # On the loop, as ``attach`` resolves it: a local restore publishes the live entry.
  109. target = transcript_target(authority, ref)
  110. def read():
  111. from gateway.session_controls import display_projection
  112. rows = authority.db.get_messages_as_conversation(target, include_ancestors=True, include_row_ids=True)
  113. return {'count': len(rows), 'messages': display_projection(rows, authority.profile_id)}
  114. return await asyncio.to_thread(read)
  115. async def reload_env(connection, ref, params):
  116. """``/reload``: re-read the profile's ``.env`` (main's ``reload.env`` / CLI ``/reload``).
  117. Single-profile owner: main's ``hermes_cli.config.reload_env()`` verbatim — the owner's
  118. ``os.environ`` is what its turns read, exactly as the TUI's own sidecar process was. Built agents
  119. keep their credential pool until ``/new`` (main's documented behaviour).
  120. Multiplexed owner: ``os.environ`` is shared by every served profile and turns never read profile
  121. secrets from it, so it is left alone. Each turn already re-reads ``.env`` into its own scope; what
  122. can be stale is the profile's external secret-source snapshot, which is re-pulled here. The count
  123. is the number of keys whose value in this profile's secret scope changed.
  124. """
  125. # Addressed at one session the caller controls: a sessionless frame stays refused, as it was
  126. # before this verb existed (a bare grant must not rewrite the owner's environment).
  127. _live_ref(connection, ref, params, {'session_id', 'profile'}, 'session:control')
  128. authority = connection.authority
  129. def reload():
  130. if not _multiplexed(authority):
  131. from hermes_cli.config import reload_env as reload_process_env
  132. return reload_process_env()
  133. from agent.secret_scope import build_profile_secret_scope, invalidate_env_file_cache
  134. from hermes_cli.env_loader import hydrate_profile_secret_sources, reset_secret_source_cache
  135. home = _profile_home(authority)
  136. before = build_profile_secret_scope(home)
  137. invalidate_env_file_cache(home / '.env')
  138. reset_secret_source_cache(home)
  139. hydrate_profile_secret_sources(home)
  140. after = build_profile_secret_scope(home)
  141. return sum(before.get(key) != after.get(key) for key in before.keys() | after.keys())
  142. return {'updated': int(await asyncio.to_thread(reload))}
  143. async def pause_delegation(connection, ref, params):
  144. """``/agents pause|resume`` and the overlay's ``p``: main's ``delegation.pause`` — block or
  145. unblock NEW ``delegate_task`` spawns; running children keep going.
  146. The gate (``tools.delegate_tool_registry``) is process-wide, as it was in main's sidecar (a
  147. TUI's sidecar served one TUI, but its gate covered every agent in that process). On the shared
  148. owner it therefore covers every chat this gateway runs, which is what an operator's kill switch
  149. is for; ``delegation.status`` reports the same flag to every client."""
  150. paused = params.get('paused', True)
  151. if set(params) - {'paused', 'profile', 'session_id'} or type(paused) is not bool:
  152. raise RuntimeStoreError('invalid_params')
  153. if ref.session_id:
  154. authorize(connection, ref, params, 'session:control')
  155. else:
  156. if 'session:control' not in connection.actor.capabilities:
  157. raise RuntimeStoreError('permission_denied')
  158. profile = params.get('profile')
  159. if profile is not None and not isinstance(profile, str):
  160. raise RuntimeStoreError('invalid_params')
  161. if profile:
  162. from hermes_cli.profiles import profile_matches_home
  163. if not profile_matches_home(profile, Path(connection.authority.profile_id)):
  164. raise RuntimeStoreError('profile_mismatch')
  165. from tools.delegate_tool_registry import set_spawn_paused
  166. return {'paused': set_spawn_paused(paused)}
  167. _ROLLBACK_FIELDS = {'list': {'session_id', 'profile'}, 'diff': {'session_id', 'profile', 'hash'},
  168. 'restore': {'session_id', 'profile', 'hash', 'file_path', 'all'},
  169. 'session_diff': {'session_id', 'profile'}}
  170. # ``rollback.session_diff`` stat + body bound, in bytes on the wire: half the 8 MiB frame every client
  171. # accepts (``hermes_cli/gateway_client.py``). Counted JSON-escaped, since a control character is one
  172. # character but six bytes (``\u0001``); the classic CLI shows 400 lines either way.
  173. _SESSION_DIFF_BYTES = 4 * 1024 * 1024
  174. async def rollback(connection, ref, params, *, kind):
  175. """``/rollback [list] | diff <n|hash> | <n|hash> [file]`` and ``/diff session``: main's ``rollback.*`` over this
  176. session's checkpoints (the shared ``<profile>/checkpoints`` store, keyed by the frozen launch cwd).
  177. The manager is built from the session's frozen ``checkpoints`` policy rather than read off the
  178. resident agent (main's ``agent._checkpoint_mgr``, built from the same config): it carries no
  179. per-session state these reads need, and a restarted owner or a just-rewound session has no
  180. resident agent. A whole-tree restore also rewinds the transcript to before the newest user turn
  181. (main's ``_rewind_active_session_history``) through the owner's fenced ``rewind`` mutation."""
  182. fields = _ROLLBACK_FIELDS[kind]
  183. if any(key in params and (not isinstance(params[key], str) or (key == 'hash' and not params[key]))
  184. for key in ('hash', 'file_path')) or (kind in ('diff', 'restore') and 'hash' not in params) or (
  185. params.get('all') is not None and not isinstance(params['all'], bool)): # nullable: null is omitted
  186. raise RuntimeStoreError('invalid_params')
  187. live = _live_ref(connection, ref, params, fields, 'session:read' if kind != 'restore' else 'session:control')
  188. authority = connection.authority
  189. from gateway.session_policy import policy_for_source
  190. policy = policy_for_source(authority.runner, live.source)
  191. if policy is None:
  192. raise RuntimeStoreError('permission_denied')
  193. file_path = params.get('file_path') or ''
  194. if kind == 'restore' and not file_path and authority._handle(ref).execution_state != 'idle':
  195. # Main refuses a full-history rollback mid-turn; a file-scoped restore only touches disk.
  196. raise RuntimeStoreError('session_busy')
  197. from gateway.session_ancillary import physical_target
  198. task_id = physical_target(authority, ref)
  199. from gateway.run import _checkpoint_agent_kwargs
  200. kwargs = _checkpoint_agent_kwargs(policy.config(authority, secrets=False))
  201. terminal = json.loads(policy.terminal_json)
  202. def run() -> dict:
  203. from tools.checkpoint_manager import CheckpointManager
  204. from tui_gateway.checkpoints import _resolve_checkpoint_hash
  205. mgr = CheckpointManager(enabled=bool(kwargs['checkpoints_enabled']), **{
  206. key[len('checkpoint_'):]: value for key, value in kwargs.items() if key.startswith('checkpoint_')})
  207. cwd = policy.cwd
  208. if not mgr.enabled and kind in ('list', 'session_diff'):
  209. return {'enabled': False, 'checkpoints': []} if kind == 'list' else {'enabled': False}
  210. if kind == 'list':
  211. # The TUI renders ``message``; the manager calls it ``reason``.
  212. return {'enabled': True, 'checkpoints': [
  213. {'hash': c.get('hash', ''), 'timestamp': c.get('timestamp', ''), 'message': c.get('reason', '')}
  214. for c in mgr.list_checkpoints(cwd)]}
  215. # Host checkpoints are not a container-backed session's tree (main's _container_checkpoint_refusal),
  216. # classified under the session's frozen terminal policy, not the owner's ambient one.
  217. from tools.terminal_scope import reset_terminal_scope, set_terminal_scope
  218. token = set_terminal_scope(terminal)
  219. try:
  220. refusal = mgr.unsupported_backend_reason(task_id)
  221. finally:
  222. reset_terminal_scope(token)
  223. if kind == 'session_diff':
  224. return _session_diff(mgr, cwd, refusal)
  225. try:
  226. target = _resolve_checkpoint_hash(mgr, cwd, params['hash'])
  227. except ValueError as exc:
  228. if kind == 'diff':
  229. raise RuntimeStoreError('invalid_checkpoint') from exc
  230. return {'success': False, 'error': str(exc)}
  231. if kind == 'diff':
  232. if refusal:
  233. raise RuntimeStoreError('unsupported_terminal_backend')
  234. from tui_gateway.render import render_diff
  235. result = mgr.diff(cwd, target)
  236. raw = result.get('diff', '')[:4000]
  237. payload = {'stat': result.get('stat', ''), 'diff': raw}
  238. if rendered := render_diff(raw, 80):
  239. payload['rendered'] = rendered
  240. return payload
  241. if refusal:
  242. return {'success': False, 'error': refusal}
  243. # Main's whole-tree /rollback keeps the user's hand-edits unless ``--all`` (``all``) says otherwise.
  244. return mgr.restore(cwd, target, file_path=file_path or None,
  245. safe=not file_path and not params.get('all'))
  246. result = await asyncio.to_thread(run)
  247. if kind == 'restore' and result.get('success') and not file_path:
  248. result['history_removed'] = await _rewind_last_turn(connection, ref)
  249. return result
  250. def _session_diff(mgr, cwd, refusal):
  251. """``/diff session``: main's ``session_diff`` (earliest retained checkpoint vs the tree) as data,
  252. so the classic CLI renders it with its own terminal renderer instead of chat-sized text."""
  253. if refusal:
  254. return {'enabled': True, 'success': False, 'error': refusal}
  255. result = mgr.session_diff(cwd)
  256. if not result.get('success'):
  257. return {'enabled': True, 'success': False, 'error': str(result.get('error') or '')}
  258. diff = result.get('diff', '')
  259. stat = _fit_frame(result.get('stat', ''), _SESSION_DIFF_BYTES)
  260. body = _fit_frame(diff, _SESSION_DIFF_BYTES - _wire_bytes(stat))
  261. return {'enabled': True, 'success': True, 'stat': stat, 'diff': body,
  262. 'diff_lines': len(diff.splitlines()), 'empty': bool(result.get('empty'))}
  263. def _wire_bytes(text):
  264. """Bytes ``text`` takes inside a frame: JSON-escaped as ``serialize_frame`` writes it, then UTF-8."""
  265. return len(json.dumps(text, ensure_ascii=False).encode('utf-8', 'surrogatepass')) - 2
  266. def _fit_frame(text, budget):
  267. """The longest whole-line prefix of ``text`` whose wire size fits ``budget`` bytes. The caller
  268. reports the uncut line count, so the client names the cut instead of the frame dropping the socket."""
  269. if len(text) * 6 <= budget or (len(text) <= budget and _wire_bytes(text) <= budget):
  270. return text
  271. kept, used = [], 0
  272. # Lines end at ``\n`` only (``splitlines`` would also cut at ``\r``, ``\f``, U+2028 inside a diff line).
  273. for line in re.split(r'(?<=\n)', text[:budget + 1]): # chars cost >= 1 byte; +1 keeps a cut line over
  274. used += _wire_bytes(line)
  275. if used > budget:
  276. break
  277. kept.append(line)
  278. return ''.join(kept).removesuffix('\n')
  279. async def _rewind_last_turn(connection, ref):
  280. """Drop the newest user turn and everything after it (main's full ``/rollback`` restore) via the
  281. owner's revision-fenced ``rewind`` mutation; 0 when the transcript has no user turn."""
  282. authority = connection.authority
  283. from agent.context_compressor import user_originated_turn_view
  284. from gateway.session_local_recovery import local_history
  285. rows = await asyncio.to_thread(local_history, authority, ref)
  286. target = next((row['row_id'] for row in reversed(rows) if isinstance(row.get('row_id'), int)
  287. and not row.get('archived') and user_originated_turn_view(row) is not None), None)
  288. if target is None:
  289. return 0
  290. from gateway.session_mutations import mutate_session
  291. from hermes_state_mutation_guards import MUTATION_GUARD_REFUSALS
  292. handle = authority._handle(ref)
  293. try:
  294. result = await mutate_session(authority, connection.actor, ref, {
  295. 'session_id': ref.session_id, 'request_id': f'rollback:{uuid.uuid4().hex}',
  296. 'expected_revision': handle.revision, 'expected_generation': handle.execution_generation,
  297. 'operation': 'rewind', 'payload': {'target_message_id': target}})
  298. except MUTATION_GUARD_REFUSALS as exc:
  299. raise RuntimeStoreError('session_busy') from exc
  300. return int(result.get('rewound_count') or 0)