session_ancillary.py 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625
  1. """Desktop/Ink projections of existing owner state, plus the session-scoped process verbs.
  2. No legacy server, manager construction, process recovery, or execution on reads. ``process.stop``
  3. and ``process.kill`` stop only processes ``process.list`` projects for the session; ``reload.mcp``
  4. reconciles only the requesting profile's MCP servers; ``file.attach`` stages for one owned session.
  5. """
  6. import asyncio
  7. from functools import partial
  8. from pathlib import Path
  9. import sys
  10. from gateway.session_busy_controls import authorize
  11. from hermes_state_runtime import RuntimeStoreError
  12. _SUBAGENT_FIELDS = (
  13. 'subagent_id', 'parent_id', 'depth', 'goal', 'delegation_id', 'model',
  14. 'started_at', 'status', 'tool_count', 'last_tool', 'accepting_steer',
  15. )
  16. _TAIL_BYTES = 16384
  17. _PROCESS_TAIL_CHARS = 32768 # main's dock tail view (cli_process_dock.process_tail)
  18. def handlers(connection):
  19. return {**{name: partial(read, connection, kind=kind) for name, kind in {
  20. 'session.control.read': 'control', 'process.list': 'processes',
  21. 'subagent.list': 'subagents', 'subagent.tail': 'tail',
  22. }.items()}, 'approval.pending': partial(approvals, connection),
  23. 'approval.received': partial(approvals, connection, ack=True),
  24. 'process.stop': partial(stop_processes, connection),
  25. 'process.kill': partial(kill_process, connection), 'reload.mcp': partial(reload_mcp, connection),
  26. 'file.attach': partial(attach_file, connection), 'tools.show': partial(show_tools, connection),
  27. 'skills.reload': partial(reload_skills, connection),
  28. **{name: partial(subagent_control, connection, steer=name == 'subagent.steer')
  29. for name in ('subagent.steer', 'subagent.interrupt')}}
  30. async def subagent_control(connection, ref, params, *, steer):
  31. """Desktop's per-child Steer / Stop: only a child of THIS session's live agent (the
  32. ``subagent.list`` rule). The sidecar handler never held an authority session."""
  33. fields = {'session_id', 'profile', 'subagent_id'} | ({'text'} if steer else set())
  34. if (set(params) - fields or not ref.session_id or any(not isinstance(params.get(k), str) or not params[k]
  35. for k in fields - {'profile'})):
  36. raise RuntimeStoreError('invalid_params')
  37. if ref.session_id not in connection.authority.sessions:
  38. raise RuntimeStoreError('not_found')
  39. authorize(connection, ref, params, 'session:control')
  40. live, sub = connection.authority.sessions[ref.session_id], params['subagent_id']
  41. with live.event_stream.lock:
  42. _require_current_route(connection.authority, ref)
  43. child = next((r['agent'] for r in _owner_objects(connection.authority, ref)[1] if r.get('subagent_id') == sub), None)
  44. if not steer:
  45. from agent.interrupt_compat import request_hard_interrupt
  46. return {'found': child is not None and bool(request_hard_interrupt(child, f'Interrupted via Desktop ({sub})')),
  47. 'subagent_id': sub}
  48. from tools import delegate_tool_registry as registry
  49. with registry._active_subagents_lock: # linearized with the child's final steer drain
  50. record = registry._active_subagents.get(sub)
  51. queued = bool(child is not None and record and record.get('agent') is child and record.get('accepting_steer')
  52. and child.steer(params['text']))
  53. return {'status': 'queued' if queued else 'rejected', 'subagent_id': sub, 'text': params['text']}
  54. async def show_tools(connection, ref, params):
  55. """``/tools``: the session's catalog as main's CLI listed it (``get_tool_definitions`` with the
  56. session's toolsets, pre tool_search assembly), resolved in the owner, where the MCP and plugin
  57. tools live. Rows carry the first description sentence, grouped by toolset."""
  58. if set(params) - {'session_id', 'profile'} or not isinstance(ref.session_id, str) or not ref.session_id:
  59. raise RuntimeStoreError('invalid_params')
  60. authority = connection.authority
  61. if ref.session_id not in authority.sessions:
  62. raise RuntimeStoreError('not_found')
  63. authorize(connection, ref, params, 'session:read')
  64. from gateway.session_authorities import owner_scope
  65. from gateway.session_policy import policy_for_source
  66. policy = policy_for_source(authority.runner, authority.sessions[ref.session_id].source)
  67. agent = authority.agent(ref)
  68. def build():
  69. import model_tools
  70. from agent.skill_utils import parse_config_string_list
  71. from toolsets import session_disabled_toolsets
  72. with owner_scope(authority):
  73. if agent is not None:
  74. enabled, disabled = getattr(agent, 'enabled_toolsets', None), getattr(agent, 'disabled_toolsets', None)
  75. else:
  76. config = policy.config(authority, secrets=False) if policy is not None else {}
  77. enabled = list(policy.current_toolsets(config)) if policy is not None else None
  78. disabled = session_disabled_toolsets(parse_config_string_list(
  79. (config.get('agent') or {}).get('disabled_toolsets')) or None,
  80. policy.platform if policy is not None else 'cli',
  81. oneshot=policy is not None and policy.source == 'oneshot')
  82. tools = model_tools.get_tool_definitions(enabled_toolsets=enabled, disabled_toolsets=disabled,
  83. quiet_mode=True, skip_tool_search_assembly=True)
  84. sections = {}
  85. for tool in sorted(tools or [], key=lambda item: item['function']['name']):
  86. name = tool['function']['name']
  87. desc = str(tool['function'].get('description', '') or '').split('\n')[0]
  88. if '. ' in desc:
  89. desc = desc[:desc.index('. ') + 1]
  90. sections.setdefault(model_tools.get_toolset_for_tool(name) or 'unknown', []).append(
  91. {'name': name, 'description': desc})
  92. return {'sections': [{'name': n, 'tools': rows} for n, rows in sorted(sections.items())],
  93. 'total': len(tools or [])}
  94. return await asyncio.to_thread(build)
  95. async def reload_skills(connection, ref, params):
  96. """``/reload-skills`` (and the CLI's ``/skills install``): rescan the skill dirs in the owner,
  97. whose skill-command map serves this session's skill and bundle invocations. The CLI renders
  98. main's lines from ``result`` and queues main's next-turn note itself."""
  99. if set(params) - {'session_id', 'profile'} or not isinstance(ref.session_id, str) or not ref.session_id:
  100. raise RuntimeStoreError('invalid_params')
  101. authority = connection.authority
  102. if ref.session_id not in authority.sessions:
  103. raise RuntimeStoreError('not_found')
  104. authorize(connection, ref, params, 'session:control')
  105. from gateway.session_authorities import owner_scope
  106. from gateway.session_policy import policy_for_source, policy_scope
  107. policy = policy_for_source(authority.runner, authority.sessions[ref.session_id].source)
  108. def rescan():
  109. from agent.skill_commands import reload_skills as rescan_skills
  110. with owner_scope(authority), policy_scope(policy, authority=authority):
  111. return rescan_skills()
  112. result = await asyncio.to_thread(rescan)
  113. added, removed = result.get('added') or [], result.get('removed') or []
  114. lines = ['Reloading skills...'] + ([] if added or removed else ['No new skills detected.'])
  115. for label, items in (('Added skills:', added), ('Removed skills:', removed)):
  116. if items:
  117. lines.append(label)
  118. lines.extend(f" - {item.get('name', '')}" for item in items)
  119. lines.append(f"{int(result.get('total') or 0)} skill(s) available")
  120. return {'output': '\n'.join(lines), 'result': result}
  121. async def attach_file(connection, ref, params):
  122. """Desktop's non-image attachment: stage the file for this session (its frozen launch cwd and
  123. the owner profile's ``attachments/``) and hand back the ``@file:`` ref its next submit carries.
  124. The sidecar handler looked the session up in its own table, which never holds an authority
  125. session, so every file drop failed with ``session not found``.
  126. A browser pick arrives as ``staged_upload`` (the Webapp upload route's receipt,
  127. ``hermes_cli/staged_uploads.py``): it is copied out of the profile it was uploaded to, which must
  128. be one this connection may reach."""
  129. staged_upload = params.get('staged_upload')
  130. if (set(params) - {'session_id', 'profile', 'path', 'data_url', 'name', 'staged_upload'} or not ref.session_id
  131. or any(not isinstance(value, str) for key, value in params.items() if key != 'staged_upload')
  132. or (staged_upload is not None and not isinstance(staged_upload, dict))):
  133. raise RuntimeStoreError('invalid_params')
  134. if ref.session_id not in connection.subscriptions:
  135. raise RuntimeStoreError('permission_denied')
  136. authorize(connection, ref, params, 'session:submit')
  137. if staged_upload is not None and not _reachable_upload_home(connection, staged_upload.get('profile_home')):
  138. raise RuntimeStoreError('permission_denied')
  139. from gateway.session_policy import policy_for_source
  140. authority = connection.authority
  141. policy = policy_for_source(authority.runner, authority.sessions[ref.session_id].source)
  142. if policy is None:
  143. raise RuntimeStoreError('permission_denied')
  144. # The staging helpers are bound onto the sidecar module's globals (method_ctx.bind_module).
  145. from tui_gateway import server
  146. session = {'cwd': policy.cwd, 'profile_home': authority.profile_id}
  147. def stage():
  148. if staged_upload is not None:
  149. # Only the receipt is read: a supplied path/data_url never stands in for a missing upload.
  150. return server._stage_browser_file_attachment(session, staged_upload, params.get('name', ''))
  151. return server._stage_session_file_attachment(
  152. session, raw_path=params.get('path', ''), data_url=params.get('data_url', ''),
  153. name=params.get('name', ''))
  154. try:
  155. stored, uploaded = await asyncio.to_thread(stage)
  156. except (ValueError, OverflowError) as exc:
  157. raise RuntimeStoreError('invalid_params') from exc
  158. except OSError as exc:
  159. raise RuntimeStoreError('storage_unavailable') from exc
  160. ref_path = server._attachment_ref_path(session, stored)
  161. return {'attached': True, 'name': stored.name, 'path': str(stored), 'ref_path': ref_path,
  162. 'ref_text': f'@file:{server._format_ref_value(ref_path)}', 'uploaded': uploaded}
  163. def _reachable_upload_home(connection, raw_home) -> bool:
  164. """A staged upload's source profile: this authority's own home or, for a host-scoped grant, a
  165. sibling this process serves (an owner-routed tile can receive a foreground browser pick). Never
  166. any other profile on disk, whatever its descriptor names."""
  167. from pathlib import Path
  168. if not isinstance(raw_home, str) or not raw_home:
  169. return False
  170. homes = {connection.authority.profile_id}
  171. if connection.host_scoped:
  172. registry = getattr(getattr(connection.authority, 'runner', None), 'session_authorities', None)
  173. homes |= {sibling.profile_id for sibling in (registry or ())}
  174. try:
  175. target = Path(raw_home).resolve()
  176. return any(Path(home).resolve() == target for home in homes)
  177. except (OSError, ValueError):
  178. return False
  179. async def approvals(connection, ref, params, *, ack=False):
  180. """The Desktop's approval replay (``approval.pending``) and card ack (``approval.received``)
  181. over the owner's generation-bound prompt projection. Left to the legacy sidecar they answered
  182. ``session not found`` for every authority session, which the renderer reads as a reaped
  183. runtime and answers with a mid-turn re-resume."""
  184. fields = {'session_id', 'profile'} | ({'request_id'} if ack else set())
  185. if (set(params) - fields or not isinstance(ref.session_id, str) or not ref.session_id
  186. or (ack and (not isinstance(params.get('request_id'), str) or not params['request_id']))):
  187. raise RuntimeStoreError('invalid_params')
  188. authority = connection.authority
  189. if ref.session_id not in authority.sessions:
  190. raise RuntimeStoreError('not_found')
  191. authorize(connection, ref, params, 'session:read')
  192. live = authority.sessions[ref.session_id]
  193. with live.event_stream.lock:
  194. pending = [(route, prompt) for route, prompt in live.controls.pending.values() if prompt['kind'] == 'approval']
  195. if ack:
  196. from tools.approval import ack_gateway_approval
  197. route = next((route for route, prompt in pending if prompt['prompt_id'] == params['request_id']), None)
  198. return {'acknowledged': route is not None and ack_gateway_approval(route, params['request_id'])}
  199. return {'approvals': [{'request_id': prompt['prompt_id'], 'command': prompt['command'],
  200. 'description': prompt['description'], 'choices': list(prompt['choices']),
  201. 'allow_permanent': 'always' in prompt['choices']} for _, prompt in pending]}
  202. async def read(connection, ref, params, *, kind):
  203. fields = {'session_id', 'profile'} | ({'subagent_id'} if kind == 'tail' else set())
  204. if (set(params) - fields or not isinstance(ref.session_id, str) or not ref.session_id
  205. or (kind == 'tail' and (not isinstance(params.get('subagent_id'), str)
  206. or not params['subagent_id']))):
  207. raise RuntimeStoreError('invalid_params')
  208. authority = connection.authority
  209. # Cold adoption belongs to session.resume, never an ancillary poll.
  210. if ref.session_id not in authority.sessions:
  211. raise RuntimeStoreError('not_found')
  212. authorize(connection, ref, params, 'session:read')
  213. # In a worker thread (it inherits the dispatch's owner scope): the projection takes the session's
  214. # event lock, which every streamed token takes too, reads state.db (compression lineage, local
  215. # receipt, control meta) and the process registry under its lock. Clients poll these every 1-5 s per
  216. # open session, so on the loop they were a large share of loop time with many sessions running.
  217. return await asyncio.to_thread(_read_projection, authority, authority.sessions[ref.session_id], ref, params, kind)
  218. def _read_projection(authority, live, ref, params, kind):
  219. with live.event_stream.lock:
  220. try:
  221. return _project(authority, ref, params, kind)
  222. except KeyError:
  223. # Popped from authority.sessions before or during the projection (retire_live_sessions runs
  224. # on the loop without this lock): the projection re-indexes the map, and a popped session is
  225. # not_found.
  226. if authority.sessions.get(ref.session_id) is not live:
  227. raise RuntimeStoreError('not_found') from None
  228. raise
  229. def _project(authority, ref, params, kind):
  230. if kind == 'control':
  231. # Persisted per session id, never the route's live objects: readable after a messaging
  232. # route moved on to another conversation.
  233. return {'control': control_snapshot(authority, ref)}
  234. _require_current_route(authority, ref)
  235. agent, records = _owner_objects(authority, ref, include_fallback_evicted=kind == 'subagents')
  236. if kind == 'subagents':
  237. return {'subagents': [{key: record.get(key) for key in _SUBAGENT_FIELDS}
  238. for record in records], 'delegations': []}
  239. if kind == 'tail':
  240. return subagent_tail(records, params['subagent_id'])
  241. return {'processes': process_snapshot(authority, ref, agent, records)}
  242. def _owned_targets(connection, ref, params, *, select):
  243. """``(registry, ids)``: the session's own processes (what ``process.list`` shows) that
  244. ``select(process)`` keeps; ``(None, [])`` when no process was ever registered here."""
  245. authority = connection.authority
  246. if ref.session_id not in authority.sessions:
  247. raise RuntimeStoreError('not_found')
  248. authorize(connection, ref, params, 'session:control')
  249. live = authority.sessions[ref.session_id]
  250. with live.event_stream.lock:
  251. _require_current_route(authority, ref)
  252. agent, records = _owner_objects(authority, ref)
  253. module = sys.modules.get('tools.process_registry')
  254. if module is None:
  255. return None, []
  256. registry = module.process_registry
  257. keys, owners = _ownership(authority, ref, agent, records)
  258. with registry._lock:
  259. return registry, [p.id for p in _owned_locked(registry, keys, owners) if select(p)]
  260. async def kill_process(connection, ref, params):
  261. """Desktop's per-process Stop: one process THIS session owns (the ``process.list`` rule); any
  262. other id, another chat's included, is ``process_not_found``. The legacy sidecar handler looked the
  263. session up in its own table, which never holds an authority session."""
  264. if (set(params) - {'session_id', 'process_id', 'profile'} or not ref.session_id
  265. or not isinstance(params.get('process_id'), str) or not params['process_id']):
  266. raise RuntimeStoreError('invalid_params')
  267. registry, ids = _owned_targets(connection, ref, params, select=lambda p: p.id == params['process_id'])
  268. if not ids:
  269. # Never ``not_found``: Desktop reads that reason as "this chat is gone" (dokterdok N64).
  270. raise RuntimeStoreError('process_not_found')
  271. return await asyncio.to_thread(registry.kill_process, ids[0])
  272. async def reload_mcp(connection, ref, params):
  273. """Desktop's MCP add / toggle / repair: bring THIS profile's live MCP servers in step with its
  274. config (the owner's housekeeping reconcile, run now) and refresh this profile's cached agents.
  275. Never the sidecar's teardown of every server, which cut every chat's in-flight MCP calls. The calling
  276. session's MCP servers then change as a new policy generation when it is idle (``session``: applied,
  277. unchanged or busy); other sessions take theirs when next attached. A configured server that did not
  278. connect is named: a refusal when nothing took effect (no server registered or removed, no session
  279. generation), else ``unavailable`` beside the success. A call naming ``rev``, the revision the session
  280. already holds, is that same nothing-left-to-load, answered as success with ``loaded_rev``."""
  281. if set(params) - {'session_id', 'confirm', 'rev', 'profile'}:
  282. raise RuntimeStoreError('invalid_params')
  283. if 'session:control' not in connection.actor.capabilities:
  284. raise RuntimeStoreError('permission_denied')
  285. if params.get('confirm') is not True:
  286. return {'status': 'confirm_required', 'message': 'Reloading MCP refreshes every chat of this profile.'}
  287. from tools.mcp_oauth import suppress_interactive_oauth
  288. from tools import mcp_tool_discovery as discovery
  289. def reconcile():
  290. with suppress_interactive_oauth():
  291. return (discovery.reconcile_mcp_servers_with_config(), discovery.mcp_servers_not_connected(),
  292. discovery.mcp_servers_ready())
  293. result, failed, ready = await asyncio.to_thread(reconcile)
  294. # ``added`` is what reconcile attempted: only those now registered (live or lazy) changed anything.
  295. result = {**result, 'added': [name for name in result.get('added', []) if name not in failed]}
  296. from gateway.session_authorities import served_profile_name
  297. runner = connection.authority.runner
  298. multiplex = bool(getattr(runner.config, 'multiplex_profiles', False))
  299. runner._mcp_reload_refresh_cached_agents(multiplex, served_profile_name(connection.authority.profile_id))
  300. session = await _commit_session_mcp(connection, ref, params)
  301. held_rev = await _held_mcp_rev(connection, ref) if params.get('rev') else ''
  302. # Refuse only a reload whose own work did not take effect: a call that names the revision the session
  303. # already holds has nothing left to load, and refusing it leaves a client that acknowledges on
  304. # ``reloaded`` retrying a parked server at poll rate with no way to close the handshake (#141769).
  305. if (failed and session != 'applied' and not (result.get('removed') or result['added'])
  306. and params.get('rev') != held_rev):
  307. raise RuntimeStoreError('mcp_servers_unavailable', field='mcp_servers',
  308. detail=f'did not connect: {", ".join(failed)}')
  309. changed = ', '.join(f'{k}: {", ".join(v)}' for k, v in result.items() if v) or 'no server changes'
  310. note = {'applied': '; this chat\'s tools changed for its next turn',
  311. 'busy': '; this chat is busy: its new tools apply once the turn finishes and reload runs again '
  312. 'or the chat is reopened'}.get(session or '', '')
  313. unavailable = f'; did not connect: {", ".join(failed)}' if failed else ''
  314. selected = {'session_servers': await asyncio.to_thread(_session_servers, connection.authority, ref.session_id,
  315. ready)} if session else {}
  316. return {'status': 'reloaded', 'message': f'MCP servers reconciled ({changed}){note}{unavailable}',
  317. **({'loaded_rev': held_rev} if held_rev else {}),
  318. **({'session': session} if session else {}), **({'unavailable': failed} if failed else {}), **selected}
  319. async def _held_mcp_rev(connection, ref):
  320. """The ``mcp_rev`` this session's committed policy already holds — the value ``config.get mtime`` shipped
  321. the client — or ``''`` when the call names no live local session. The policy is read on the loop (it
  322. walks ``authority.sessions`` and the adapter's maps, which only the loop mutates); only the config read
  323. and hash go to a worker thread."""
  324. sid = getattr(ref, 'session_id', None)
  325. live = connection.authority.sessions.get(sid) if sid else None
  326. if live is None or live.source is None:
  327. return ''
  328. from gateway.session_policy import policy_for_source
  329. policy = policy_for_source(connection.authority.runner, live.source)
  330. return await asyncio.to_thread(_mcp_revision_in_scope, Path(connection.authority.profile_id), policy)
  331. def _mcp_revision_in_scope(home, policy):
  332. from gateway.run import _profile_runtime_scope
  333. from gateway.session_config import mcp_revision
  334. from hermes_cli.config import load_config
  335. with _profile_runtime_scope(home):
  336. return mcp_revision(policy, load_config())
  337. def _session_servers(authority, sid, ready):
  338. """The profile MCP servers the session's committed policy runs (its toolsets name them) that are *ready*
  339. (live or lazy): a server connected for the profile is not one a chat with ``no_mcp``, an explicit pick or
  340. a platform allowlist enabled, and one the policy names but that parked serves the chat nothing."""
  341. import json
  342. from gateway.session_policy import restore_policy
  343. from hermes_cli.tools_config import enabled_mcp_server_names
  344. from hermes_state_local import local_receipt
  345. policy = restore_policy(local_receipt(authority.db, sid)['policy'])
  346. return sorted(set(policy.toolsets) & enabled_mcp_server_names(json.loads(policy.config_json)) & set(ready))
  347. async def _commit_session_mcp(connection, ref, params):
  348. """The calling local session's MCP servers as a gateway-committed generation (``commit_refresh``):
  349. never a running or queued turn's, never another session's."""
  350. from gateway.config import Platform
  351. authority, sid = connection.authority, getattr(ref, 'session_id', None)
  352. live = authority.sessions.get(sid) if sid else None
  353. if live is None or live.source is None or live.source.platform != Platform.LOCAL:
  354. return None
  355. authorize(connection, ref, params, 'session:control')
  356. from gateway.session_policy_refresh import commit_refresh
  357. try:
  358. return 'applied' if await commit_refresh(authority, ref, mcp_only=True) else 'unchanged'
  359. except RuntimeStoreError as exc:
  360. if exc.reason not in {'session_busy', 'unknown_execution', 'revision_conflict'}:
  361. raise
  362. return 'busy'
  363. async def stop_processes(connection, ref, params):
  364. """Ink ``/stop``: kill the background processes this session owns (what ``process.list``
  365. shows), never the registry-wide ``kill_all`` the legacy sidecar ran, which on the shared owner
  366. reached every chat, Desktop window and served profile (dokterdok N2). An explicit stop, so a
  367. ``persist_on_release`` job of THIS session is still reached (#41225)."""
  368. if set(params) - {'session_id', 'profile'} or not isinstance(ref.session_id, str) or not ref.session_id:
  369. raise RuntimeStoreError('invalid_params')
  370. registry, targets = _owned_targets(connection, ref, params,
  371. select=lambda p: not p.exited or p._scope_stop_pending)
  372. def kill():
  373. results = [registry.kill_process(pid, source='process.stop', consume_output=False) for pid in targets]
  374. return sum(r.get('status') in {'killed', 'already_exited'} and 'scope_stop_failed' not in r
  375. for r in results)
  376. killed = await asyncio.to_thread(kill) if targets else 0
  377. return {'killed': killed, 'delegations': await asyncio.to_thread(_interrupt_delegations, connection.authority, ref)}
  378. def _interrupt_delegations(authority, ref):
  379. """Main's ``/stop`` also interrupted the background (async) delegations; here only the ones this
  380. session dispatched (its route or its durable id), never another chat's."""
  381. module = sys.modules.get('tools.async_delegation')
  382. if module is None:
  383. return 0
  384. return module.interrupt_for_session(session_key=authority.sessions[ref.session_id].route,
  385. parent_session_id=physical_target(authority, ref), reason='/stop')
  386. def _require_current_route(authority, ref):
  387. """The route still serves this conversation (a reused route must not lend its objects)."""
  388. live = authority.sessions[ref.session_id]
  389. target = physical_target(authority, ref)
  390. store = authority.runner.session_store
  391. with store._lock:
  392. entry = store._entries.get(live.route)
  393. if entry is None or entry.session_id != target:
  394. raise RuntimeStoreError('stale_generation')
  395. def _owner_objects(authority, ref, *, include_fallback_evicted=False):
  396. """``(agent, subagent records)`` of this in-process session. Process-local registries cannot
  397. describe (or stop) another interpreter's live objects: a managed worker is refused rather than
  398. answered with an empty success."""
  399. from gateway.session_managed_worker import managed_policy
  400. if managed_policy(authority, ref) is not None:
  401. raise RuntimeStoreError('unsupported_projection')
  402. agent = authority.agent(ref)
  403. session_id = physical_target(authority, ref) if include_fallback_evicted else None
  404. route = authority.sessions[ref.session_id].route if include_fallback_evicted else None
  405. session_db = getattr(authority, 'db', None) if include_fallback_evicted else None
  406. return agent, subagent_records(
  407. agent, session_id=session_id, session_db=session_db, route=route,
  408. include_fallback_evicted=include_fallback_evicted)
  409. def physical_target(authority, ref):
  410. from gateway.config import Platform
  411. source = authority.sessions[ref.session_id].source # None: a history mount
  412. if source is not None and source.platform == Platform.LOCAL:
  413. from hermes_state_local import local_receipt
  414. return local_receipt(authority.db, ref.session_id)['entry']['session_id']
  415. return ref.session_id
  416. def control_snapshot(authority, ref):
  417. from hermes_cli.goals import GoalState
  418. from hermes_cli.loops import LoopState
  419. from hermes_cli.heartbeat import HeartbeatState
  420. # These pure serializers don't bind/import the legacy server. In particular
  421. # do not reuse _snapshot_control: its manager loader can write on a read.
  422. from tui_gateway.methods_session_control import (
  423. _safe_goal_snapshot, _safe_loop_snapshot, _safe_heartbeat_snapshot,
  424. _snapshot_revision, _snapshot_updated_at,
  425. )
  426. # Compression carries goal/loop/heartbeat to the continuation: read the current segment.
  427. target = physical_target(authority, ref)
  428. target = authority.db.get_compression_tip(target) or target
  429. states = []
  430. for kind, cls in [('goal', GoalState), ('loop', LoopState), ('heartbeat', HeartbeatState)]:
  431. raw = authority.db.get_meta(kind + ':' + target)
  432. try:
  433. states.append(cls.from_json(raw) if raw else None)
  434. except (ValueError, TypeError, AttributeError) as exc:
  435. raise RuntimeStoreError('storage_unavailable') from exc
  436. goal_state, loop_state, heartbeat_state = states
  437. goal = _safe_goal_snapshot(goal_state)
  438. # Project the persisted barrier, not GoalManager.is_waiting(), which clears
  439. # satisfied barriers and can query unrelated processes during a UI refresh.
  440. deferred = bool(goal and goal['status'] == 'active' and not goal.get('wait_barrier'))
  441. loop = _safe_loop_snapshot(loop_state, deferred_by_goal=bool(
  442. deferred and loop_state and loop_state.status == 'active'))
  443. heartbeat = _safe_heartbeat_snapshot(heartbeat_state)
  444. return {'goal': goal, 'loop': loop, 'heartbeat': heartbeat,
  445. 'revision': _snapshot_revision(goal, loop, heartbeat),
  446. 'updated_at': _snapshot_updated_at(*states)}
  447. def _has_fallback_evicted_ancestor(agent, target_sids, expected_db, route, registry):
  448. if not target_sids:
  449. return False
  450. current = agent
  451. for _ in range(getattr(registry, '_MAX_ANCESTOR_HOPS', 8)):
  452. ref = getattr(current, '_delegate_parent_ref', None) if current is not None else None
  453. current = ref() if callable(ref) else None
  454. if current is None:
  455. return False
  456. marker = getattr(current, '_evicted_on_fallback', False)
  457. if not (marker is True or (isinstance(marker, str) and bool(marker))):
  458. continue
  459. if getattr(current, 'session_id', None) not in target_sids:
  460. continue
  461. if (expected_db is not None or getattr(current, '_session_db', None) is not None) and getattr(current, '_session_db', None) is not expected_db:
  462. continue
  463. if route is not None and marker != route:
  464. continue
  465. if route is None and isinstance(marker, str) and getattr(current, 'gateway_session_key', None) not in (None, marker):
  466. continue
  467. return True
  468. return False
  469. def subagent_records(parent, session_id=None, *, session_db=None, route=None, include_fallback_evicted=True):
  470. registry = sys.modules.get('tools.delegate_tool_registry')
  471. target_sid = (session_id or getattr(parent, 'session_id', None)) if include_fallback_evicted else None
  472. if registry is None or (parent is None and not target_sid):
  473. return []
  474. expected_db = session_db if session_db is not None else getattr(parent, '_session_db', None)
  475. effective_route = route if route is not None else getattr(parent, 'gateway_session_key', None)
  476. # A rotating /compress moves the conversation to a new stored id; an evicted parent keeps its earlier one.
  477. target_sids = _compression_lineage(expected_db, target_sid)
  478. with registry._active_subagents_lock:
  479. return [dict(record) for record in registry._active_subagents.values()
  480. if (parent is not None and registry._is_descendant_of(record.get('agent'), parent))
  481. or _has_fallback_evicted_ancestor(record.get('agent'), target_sids, expected_db, effective_route, registry)
  482. or _owned_by_lineage(record, target_sids, expected_db)]
  483. def _owned_by_lineage(record, target_sids, expected_db):
  484. """The read-only roster follows the conversation, as ``delegate_task(action="list")`` does: a
  485. child whose durable owner id is in this session's compression lineage, written to the same
  486. session database file. Without it every cached-agent rebuild (``/reasoning``, ``/model``, a
  487. policy refresh, idle eviction) hid still-running children from the dock while the status bar
  488. kept counting them. Control and tail stay pinned to the resident parent."""
  489. if not target_sids or record.get('owner_agent_session_id') not in target_sids:
  490. return False
  491. expected_path = getattr(expected_db, 'db_path', None)
  492. child_path = getattr(getattr(record.get('agent'), '_session_db', None), 'db_path', None)
  493. return expected_path is not None and child_path is not None and str(child_path) == str(expected_path)
  494. def _compression_lineage(db, session_id):
  495. """*session_id* plus the sessions it continues by compression, walked backward so a closed sibling under a compressed parent cannot divert the walk."""
  496. if not session_id:
  497. return frozenset()
  498. ids, current = {session_id}, session_id
  499. is_child, get = getattr(db, '_is_compression_child_row', None), getattr(db, 'get_session', None)
  500. if callable(is_child) and callable(get):
  501. row = get(current)
  502. while row and is_child(row) and row['parent_session_id'] not in ids and len(ids) < 200:
  503. current = row['parent_session_id']
  504. ids.add(current)
  505. row = get(current)
  506. return frozenset(ids)
  507. lineage = getattr(db, 'get_compression_lineage', None)
  508. found = lineage(session_id) if callable(lineage) else None
  509. return frozenset(found if isinstance(found, (list, tuple)) else ()) | ids
  510. def subagent_tail(records, subagent_id):
  511. result = {'subagent_id': subagent_id, 'available': False, 'text': '', 'truncated': False}
  512. record = next((r for r in records if r.get('subagent_id') == subagent_id), None)
  513. path = getattr(record.get('agent'), '_live_transcript_path', None) if record else None
  514. if not path:
  515. return result
  516. try:
  517. with open(path, 'rb') as stream:
  518. size = stream.seek(0, 2)
  519. stream.seek(max(0, size - _TAIL_BYTES))
  520. text = stream.read(_TAIL_BYTES).decode('utf-8', errors='ignore')
  521. except OSError:
  522. return result
  523. return {**result, 'available': True, 'text': text, 'truncated': size > _TAIL_BYTES}
  524. def _ownership(authority, ref, agent, records):
  525. """``(routing keys, owners)`` a registry process must match to belong to this session: its
  526. routing key AND an owner among the session, its agent and its subagents."""
  527. target = physical_target(authority, ref)
  528. keys, owners = {authority.sessions[ref.session_id].route, target}, {target}
  529. if agent is not None:
  530. owners.add(getattr(agent, 'session_id', None))
  531. owners.update(r.get('subagent_id') for r in records)
  532. owners.discard(None)
  533. owners.discard('')
  534. return keys, owners
  535. def _owned_locked(registry, keys, owners):
  536. """Matching process objects; the caller holds ``registry._lock``. Read directly:
  537. ``list_sessions`` refreshes recovered processes and writes checkpoints."""
  538. return [p for p in (*registry._running.values(), *registry._finished.values())
  539. if p.session_key in keys and (p.owner_task_id or p.task_id) in owners]
  540. def process_snapshot(authority, ref, agent, records):
  541. module = sys.modules.get('tools.process_registry')
  542. if module is None:
  543. return []
  544. registry = module.process_registry
  545. keys, owners = _ownership(authority, ref, agent, records)
  546. # Keep ownership and output together.
  547. with registry._lock:
  548. return [{'session_id': p.id, 'command': p.command[:200],
  549. 'status': 'exited' if p.exited else 'running', 'exit_code': p.exit_code,
  550. # The classic CLI dock's elapsed / exit-age / verdict and its 32k tail view.
  551. 'started_epoch': p.started_at, 'exited_at': p.exited_at or None,
  552. 'completion_reason': p.completion_reason if p.exited else None,
  553. 'output_tail': p.output_buffer[-_PROCESS_TAIL_CHARS:]} for p in _owned_locked(registry, keys, owners)]