| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625 |
- """Desktop/Ink projections of existing owner state, plus the session-scoped process verbs.
- No legacy server, manager construction, process recovery, or execution on reads. ``process.stop``
- and ``process.kill`` stop only processes ``process.list`` projects for the session; ``reload.mcp``
- reconciles only the requesting profile's MCP servers; ``file.attach`` stages for one owned session.
- """
- import asyncio
- from functools import partial
- from pathlib import Path
- import sys
- from gateway.session_busy_controls import authorize
- from hermes_state_runtime import RuntimeStoreError
- _SUBAGENT_FIELDS = (
- 'subagent_id', 'parent_id', 'depth', 'goal', 'delegation_id', 'model',
- 'started_at', 'status', 'tool_count', 'last_tool', 'accepting_steer',
- )
- _TAIL_BYTES = 16384
- _PROCESS_TAIL_CHARS = 32768 # main's dock tail view (cli_process_dock.process_tail)
- def handlers(connection):
- return {**{name: partial(read, connection, kind=kind) for name, kind in {
- 'session.control.read': 'control', 'process.list': 'processes',
- 'subagent.list': 'subagents', 'subagent.tail': 'tail',
- }.items()}, 'approval.pending': partial(approvals, connection),
- 'approval.received': partial(approvals, connection, ack=True),
- 'process.stop': partial(stop_processes, connection),
- 'process.kill': partial(kill_process, connection), 'reload.mcp': partial(reload_mcp, connection),
- 'file.attach': partial(attach_file, connection), 'tools.show': partial(show_tools, connection),
- 'skills.reload': partial(reload_skills, connection),
- **{name: partial(subagent_control, connection, steer=name == 'subagent.steer')
- for name in ('subagent.steer', 'subagent.interrupt')}}
- async def subagent_control(connection, ref, params, *, steer):
- """Desktop's per-child Steer / Stop: only a child of THIS session's live agent (the
- ``subagent.list`` rule). The sidecar handler never held an authority session."""
- fields = {'session_id', 'profile', 'subagent_id'} | ({'text'} if steer else set())
- if (set(params) - fields or not ref.session_id or any(not isinstance(params.get(k), str) or not params[k]
- for k in fields - {'profile'})):
- raise RuntimeStoreError('invalid_params')
- if ref.session_id not in connection.authority.sessions:
- raise RuntimeStoreError('not_found')
- authorize(connection, ref, params, 'session:control')
- live, sub = connection.authority.sessions[ref.session_id], params['subagent_id']
- with live.event_stream.lock:
- _require_current_route(connection.authority, ref)
- child = next((r['agent'] for r in _owner_objects(connection.authority, ref)[1] if r.get('subagent_id') == sub), None)
- if not steer:
- from agent.interrupt_compat import request_hard_interrupt
- return {'found': child is not None and bool(request_hard_interrupt(child, f'Interrupted via Desktop ({sub})')),
- 'subagent_id': sub}
- from tools import delegate_tool_registry as registry
- with registry._active_subagents_lock: # linearized with the child's final steer drain
- record = registry._active_subagents.get(sub)
- queued = bool(child is not None and record and record.get('agent') is child and record.get('accepting_steer')
- and child.steer(params['text']))
- return {'status': 'queued' if queued else 'rejected', 'subagent_id': sub, 'text': params['text']}
- async def show_tools(connection, ref, params):
- """``/tools``: the session's catalog as main's CLI listed it (``get_tool_definitions`` with the
- session's toolsets, pre tool_search assembly), resolved in the owner, where the MCP and plugin
- tools live. Rows carry the first description sentence, grouped by toolset."""
- if set(params) - {'session_id', 'profile'} or not isinstance(ref.session_id, str) or not ref.session_id:
- raise RuntimeStoreError('invalid_params')
- authority = connection.authority
- if ref.session_id not in authority.sessions:
- raise RuntimeStoreError('not_found')
- authorize(connection, ref, params, 'session:read')
- from gateway.session_authorities import owner_scope
- from gateway.session_policy import policy_for_source
- policy = policy_for_source(authority.runner, authority.sessions[ref.session_id].source)
- agent = authority.agent(ref)
- def build():
- import model_tools
- from agent.skill_utils import parse_config_string_list
- from toolsets import session_disabled_toolsets
- with owner_scope(authority):
- if agent is not None:
- enabled, disabled = getattr(agent, 'enabled_toolsets', None), getattr(agent, 'disabled_toolsets', None)
- else:
- config = policy.config(authority, secrets=False) if policy is not None else {}
- enabled = list(policy.current_toolsets(config)) if policy is not None else None
- disabled = session_disabled_toolsets(parse_config_string_list(
- (config.get('agent') or {}).get('disabled_toolsets')) or None,
- policy.platform if policy is not None else 'cli',
- oneshot=policy is not None and policy.source == 'oneshot')
- tools = model_tools.get_tool_definitions(enabled_toolsets=enabled, disabled_toolsets=disabled,
- quiet_mode=True, skip_tool_search_assembly=True)
- sections = {}
- for tool in sorted(tools or [], key=lambda item: item['function']['name']):
- name = tool['function']['name']
- desc = str(tool['function'].get('description', '') or '').split('\n')[0]
- if '. ' in desc:
- desc = desc[:desc.index('. ') + 1]
- sections.setdefault(model_tools.get_toolset_for_tool(name) or 'unknown', []).append(
- {'name': name, 'description': desc})
- return {'sections': [{'name': n, 'tools': rows} for n, rows in sorted(sections.items())],
- 'total': len(tools or [])}
- return await asyncio.to_thread(build)
- async def reload_skills(connection, ref, params):
- """``/reload-skills`` (and the CLI's ``/skills install``): rescan the skill dirs in the owner,
- whose skill-command map serves this session's skill and bundle invocations. The CLI renders
- main's lines from ``result`` and queues main's next-turn note itself."""
- if set(params) - {'session_id', 'profile'} or not isinstance(ref.session_id, str) or not ref.session_id:
- raise RuntimeStoreError('invalid_params')
- authority = connection.authority
- if ref.session_id not in authority.sessions:
- raise RuntimeStoreError('not_found')
- authorize(connection, ref, params, 'session:control')
- from gateway.session_authorities import owner_scope
- from gateway.session_policy import policy_for_source, policy_scope
- policy = policy_for_source(authority.runner, authority.sessions[ref.session_id].source)
- def rescan():
- from agent.skill_commands import reload_skills as rescan_skills
- with owner_scope(authority), policy_scope(policy, authority=authority):
- return rescan_skills()
- result = await asyncio.to_thread(rescan)
- added, removed = result.get('added') or [], result.get('removed') or []
- lines = ['Reloading skills...'] + ([] if added or removed else ['No new skills detected.'])
- for label, items in (('Added skills:', added), ('Removed skills:', removed)):
- if items:
- lines.append(label)
- lines.extend(f" - {item.get('name', '')}" for item in items)
- lines.append(f"{int(result.get('total') or 0)} skill(s) available")
- return {'output': '\n'.join(lines), 'result': result}
- async def attach_file(connection, ref, params):
- """Desktop's non-image attachment: stage the file for this session (its frozen launch cwd and
- the owner profile's ``attachments/``) and hand back the ``@file:`` ref its next submit carries.
- The sidecar handler looked the session up in its own table, which never holds an authority
- session, so every file drop failed with ``session not found``.
- A browser pick arrives as ``staged_upload`` (the Webapp upload route's receipt,
- ``hermes_cli/staged_uploads.py``): it is copied out of the profile it was uploaded to, which must
- be one this connection may reach."""
- staged_upload = params.get('staged_upload')
- if (set(params) - {'session_id', 'profile', 'path', 'data_url', 'name', 'staged_upload'} or not ref.session_id
- or any(not isinstance(value, str) for key, value in params.items() if key != 'staged_upload')
- or (staged_upload is not None and not isinstance(staged_upload, dict))):
- raise RuntimeStoreError('invalid_params')
- if ref.session_id not in connection.subscriptions:
- raise RuntimeStoreError('permission_denied')
- authorize(connection, ref, params, 'session:submit')
- if staged_upload is not None and not _reachable_upload_home(connection, staged_upload.get('profile_home')):
- raise RuntimeStoreError('permission_denied')
- from gateway.session_policy import policy_for_source
- authority = connection.authority
- policy = policy_for_source(authority.runner, authority.sessions[ref.session_id].source)
- if policy is None:
- raise RuntimeStoreError('permission_denied')
- # The staging helpers are bound onto the sidecar module's globals (method_ctx.bind_module).
- from tui_gateway import server
- session = {'cwd': policy.cwd, 'profile_home': authority.profile_id}
- def stage():
- if staged_upload is not None:
- # Only the receipt is read: a supplied path/data_url never stands in for a missing upload.
- return server._stage_browser_file_attachment(session, staged_upload, params.get('name', ''))
- return server._stage_session_file_attachment(
- session, raw_path=params.get('path', ''), data_url=params.get('data_url', ''),
- name=params.get('name', ''))
- try:
- stored, uploaded = await asyncio.to_thread(stage)
- except (ValueError, OverflowError) as exc:
- raise RuntimeStoreError('invalid_params') from exc
- except OSError as exc:
- raise RuntimeStoreError('storage_unavailable') from exc
- ref_path = server._attachment_ref_path(session, stored)
- return {'attached': True, 'name': stored.name, 'path': str(stored), 'ref_path': ref_path,
- 'ref_text': f'@file:{server._format_ref_value(ref_path)}', 'uploaded': uploaded}
- def _reachable_upload_home(connection, raw_home) -> bool:
- """A staged upload's source profile: this authority's own home or, for a host-scoped grant, a
- sibling this process serves (an owner-routed tile can receive a foreground browser pick). Never
- any other profile on disk, whatever its descriptor names."""
- from pathlib import Path
- if not isinstance(raw_home, str) or not raw_home:
- return False
- homes = {connection.authority.profile_id}
- if connection.host_scoped:
- registry = getattr(getattr(connection.authority, 'runner', None), 'session_authorities', None)
- homes |= {sibling.profile_id for sibling in (registry or ())}
- try:
- target = Path(raw_home).resolve()
- return any(Path(home).resolve() == target for home in homes)
- except (OSError, ValueError):
- return False
- async def approvals(connection, ref, params, *, ack=False):
- """The Desktop's approval replay (``approval.pending``) and card ack (``approval.received``)
- over the owner's generation-bound prompt projection. Left to the legacy sidecar they answered
- ``session not found`` for every authority session, which the renderer reads as a reaped
- runtime and answers with a mid-turn re-resume."""
- fields = {'session_id', 'profile'} | ({'request_id'} if ack else set())
- if (set(params) - fields or not isinstance(ref.session_id, str) or not ref.session_id
- or (ack and (not isinstance(params.get('request_id'), str) or not params['request_id']))):
- raise RuntimeStoreError('invalid_params')
- authority = connection.authority
- if ref.session_id not in authority.sessions:
- raise RuntimeStoreError('not_found')
- authorize(connection, ref, params, 'session:read')
- live = authority.sessions[ref.session_id]
- with live.event_stream.lock:
- pending = [(route, prompt) for route, prompt in live.controls.pending.values() if prompt['kind'] == 'approval']
- if ack:
- from tools.approval import ack_gateway_approval
- route = next((route for route, prompt in pending if prompt['prompt_id'] == params['request_id']), None)
- return {'acknowledged': route is not None and ack_gateway_approval(route, params['request_id'])}
- return {'approvals': [{'request_id': prompt['prompt_id'], 'command': prompt['command'],
- 'description': prompt['description'], 'choices': list(prompt['choices']),
- 'allow_permanent': 'always' in prompt['choices']} for _, prompt in pending]}
- async def read(connection, ref, params, *, kind):
- fields = {'session_id', 'profile'} | ({'subagent_id'} if kind == 'tail' else set())
- if (set(params) - fields or not isinstance(ref.session_id, str) or not ref.session_id
- or (kind == 'tail' and (not isinstance(params.get('subagent_id'), str)
- or not params['subagent_id']))):
- raise RuntimeStoreError('invalid_params')
- authority = connection.authority
- # Cold adoption belongs to session.resume, never an ancillary poll.
- if ref.session_id not in authority.sessions:
- raise RuntimeStoreError('not_found')
- authorize(connection, ref, params, 'session:read')
- # In a worker thread (it inherits the dispatch's owner scope): the projection takes the session's
- # event lock, which every streamed token takes too, reads state.db (compression lineage, local
- # receipt, control meta) and the process registry under its lock. Clients poll these every 1-5 s per
- # open session, so on the loop they were a large share of loop time with many sessions running.
- return await asyncio.to_thread(_read_projection, authority, authority.sessions[ref.session_id], ref, params, kind)
- def _read_projection(authority, live, ref, params, kind):
- with live.event_stream.lock:
- try:
- return _project(authority, ref, params, kind)
- except KeyError:
- # Popped from authority.sessions before or during the projection (retire_live_sessions runs
- # on the loop without this lock): the projection re-indexes the map, and a popped session is
- # not_found.
- if authority.sessions.get(ref.session_id) is not live:
- raise RuntimeStoreError('not_found') from None
- raise
- def _project(authority, ref, params, kind):
- if kind == 'control':
- # Persisted per session id, never the route's live objects: readable after a messaging
- # route moved on to another conversation.
- return {'control': control_snapshot(authority, ref)}
- _require_current_route(authority, ref)
- agent, records = _owner_objects(authority, ref, include_fallback_evicted=kind == 'subagents')
- if kind == 'subagents':
- return {'subagents': [{key: record.get(key) for key in _SUBAGENT_FIELDS}
- for record in records], 'delegations': []}
- if kind == 'tail':
- return subagent_tail(records, params['subagent_id'])
- return {'processes': process_snapshot(authority, ref, agent, records)}
- def _owned_targets(connection, ref, params, *, select):
- """``(registry, ids)``: the session's own processes (what ``process.list`` shows) that
- ``select(process)`` keeps; ``(None, [])`` when no process was ever registered here."""
- authority = connection.authority
- if ref.session_id not in authority.sessions:
- raise RuntimeStoreError('not_found')
- authorize(connection, ref, params, 'session:control')
- live = authority.sessions[ref.session_id]
- with live.event_stream.lock:
- _require_current_route(authority, ref)
- agent, records = _owner_objects(authority, ref)
- module = sys.modules.get('tools.process_registry')
- if module is None:
- return None, []
- registry = module.process_registry
- keys, owners = _ownership(authority, ref, agent, records)
- with registry._lock:
- return registry, [p.id for p in _owned_locked(registry, keys, owners) if select(p)]
- async def kill_process(connection, ref, params):
- """Desktop's per-process Stop: one process THIS session owns (the ``process.list`` rule); any
- other id, another chat's included, is ``process_not_found``. The legacy sidecar handler looked the
- session up in its own table, which never holds an authority session."""
- if (set(params) - {'session_id', 'process_id', 'profile'} or not ref.session_id
- or not isinstance(params.get('process_id'), str) or not params['process_id']):
- raise RuntimeStoreError('invalid_params')
- registry, ids = _owned_targets(connection, ref, params, select=lambda p: p.id == params['process_id'])
- if not ids:
- # Never ``not_found``: Desktop reads that reason as "this chat is gone" (dokterdok N64).
- raise RuntimeStoreError('process_not_found')
- return await asyncio.to_thread(registry.kill_process, ids[0])
- async def reload_mcp(connection, ref, params):
- """Desktop's MCP add / toggle / repair: bring THIS profile's live MCP servers in step with its
- config (the owner's housekeeping reconcile, run now) and refresh this profile's cached agents.
- Never the sidecar's teardown of every server, which cut every chat's in-flight MCP calls. The calling
- session's MCP servers then change as a new policy generation when it is idle (``session``: applied,
- unchanged or busy); other sessions take theirs when next attached. A configured server that did not
- connect is named: a refusal when nothing took effect (no server registered or removed, no session
- generation), else ``unavailable`` beside the success. A call naming ``rev``, the revision the session
- already holds, is that same nothing-left-to-load, answered as success with ``loaded_rev``."""
- if set(params) - {'session_id', 'confirm', 'rev', 'profile'}:
- raise RuntimeStoreError('invalid_params')
- if 'session:control' not in connection.actor.capabilities:
- raise RuntimeStoreError('permission_denied')
- if params.get('confirm') is not True:
- return {'status': 'confirm_required', 'message': 'Reloading MCP refreshes every chat of this profile.'}
- from tools.mcp_oauth import suppress_interactive_oauth
- from tools import mcp_tool_discovery as discovery
- def reconcile():
- with suppress_interactive_oauth():
- return (discovery.reconcile_mcp_servers_with_config(), discovery.mcp_servers_not_connected(),
- discovery.mcp_servers_ready())
- result, failed, ready = await asyncio.to_thread(reconcile)
- # ``added`` is what reconcile attempted: only those now registered (live or lazy) changed anything.
- result = {**result, 'added': [name for name in result.get('added', []) if name not in failed]}
- from gateway.session_authorities import served_profile_name
- runner = connection.authority.runner
- multiplex = bool(getattr(runner.config, 'multiplex_profiles', False))
- runner._mcp_reload_refresh_cached_agents(multiplex, served_profile_name(connection.authority.profile_id))
- session = await _commit_session_mcp(connection, ref, params)
- held_rev = await _held_mcp_rev(connection, ref) if params.get('rev') else ''
- # Refuse only a reload whose own work did not take effect: a call that names the revision the session
- # already holds has nothing left to load, and refusing it leaves a client that acknowledges on
- # ``reloaded`` retrying a parked server at poll rate with no way to close the handshake (#141769).
- if (failed and session != 'applied' and not (result.get('removed') or result['added'])
- and params.get('rev') != held_rev):
- raise RuntimeStoreError('mcp_servers_unavailable', field='mcp_servers',
- detail=f'did not connect: {", ".join(failed)}')
- changed = ', '.join(f'{k}: {", ".join(v)}' for k, v in result.items() if v) or 'no server changes'
- note = {'applied': '; this chat\'s tools changed for its next turn',
- 'busy': '; this chat is busy: its new tools apply once the turn finishes and reload runs again '
- 'or the chat is reopened'}.get(session or '', '')
- unavailable = f'; did not connect: {", ".join(failed)}' if failed else ''
- selected = {'session_servers': await asyncio.to_thread(_session_servers, connection.authority, ref.session_id,
- ready)} if session else {}
- return {'status': 'reloaded', 'message': f'MCP servers reconciled ({changed}){note}{unavailable}',
- **({'loaded_rev': held_rev} if held_rev else {}),
- **({'session': session} if session else {}), **({'unavailable': failed} if failed else {}), **selected}
- async def _held_mcp_rev(connection, ref):
- """The ``mcp_rev`` this session's committed policy already holds — the value ``config.get mtime`` shipped
- the client — or ``''`` when the call names no live local session. The policy is read on the loop (it
- walks ``authority.sessions`` and the adapter's maps, which only the loop mutates); only the config read
- and hash go to a worker thread."""
- sid = getattr(ref, 'session_id', None)
- live = connection.authority.sessions.get(sid) if sid else None
- if live is None or live.source is None:
- return ''
- from gateway.session_policy import policy_for_source
- policy = policy_for_source(connection.authority.runner, live.source)
- return await asyncio.to_thread(_mcp_revision_in_scope, Path(connection.authority.profile_id), policy)
- def _mcp_revision_in_scope(home, policy):
- from gateway.run import _profile_runtime_scope
- from gateway.session_config import mcp_revision
- from hermes_cli.config import load_config
- with _profile_runtime_scope(home):
- return mcp_revision(policy, load_config())
- def _session_servers(authority, sid, ready):
- """The profile MCP servers the session's committed policy runs (its toolsets name them) that are *ready*
- (live or lazy): a server connected for the profile is not one a chat with ``no_mcp``, an explicit pick or
- a platform allowlist enabled, and one the policy names but that parked serves the chat nothing."""
- import json
- from gateway.session_policy import restore_policy
- from hermes_cli.tools_config import enabled_mcp_server_names
- from hermes_state_local import local_receipt
- policy = restore_policy(local_receipt(authority.db, sid)['policy'])
- return sorted(set(policy.toolsets) & enabled_mcp_server_names(json.loads(policy.config_json)) & set(ready))
- async def _commit_session_mcp(connection, ref, params):
- """The calling local session's MCP servers as a gateway-committed generation (``commit_refresh``):
- never a running or queued turn's, never another session's."""
- from gateway.config import Platform
- authority, sid = connection.authority, getattr(ref, 'session_id', None)
- live = authority.sessions.get(sid) if sid else None
- if live is None or live.source is None or live.source.platform != Platform.LOCAL:
- return None
- authorize(connection, ref, params, 'session:control')
- from gateway.session_policy_refresh import commit_refresh
- try:
- return 'applied' if await commit_refresh(authority, ref, mcp_only=True) else 'unchanged'
- except RuntimeStoreError as exc:
- if exc.reason not in {'session_busy', 'unknown_execution', 'revision_conflict'}:
- raise
- return 'busy'
- async def stop_processes(connection, ref, params):
- """Ink ``/stop``: kill the background processes this session owns (what ``process.list``
- shows), never the registry-wide ``kill_all`` the legacy sidecar ran, which on the shared owner
- reached every chat, Desktop window and served profile (dokterdok N2). An explicit stop, so a
- ``persist_on_release`` job of THIS session is still reached (#41225)."""
- if set(params) - {'session_id', 'profile'} or not isinstance(ref.session_id, str) or not ref.session_id:
- raise RuntimeStoreError('invalid_params')
- registry, targets = _owned_targets(connection, ref, params,
- select=lambda p: not p.exited or p._scope_stop_pending)
- def kill():
- results = [registry.kill_process(pid, source='process.stop', consume_output=False) for pid in targets]
- return sum(r.get('status') in {'killed', 'already_exited'} and 'scope_stop_failed' not in r
- for r in results)
- killed = await asyncio.to_thread(kill) if targets else 0
- return {'killed': killed, 'delegations': await asyncio.to_thread(_interrupt_delegations, connection.authority, ref)}
- def _interrupt_delegations(authority, ref):
- """Main's ``/stop`` also interrupted the background (async) delegations; here only the ones this
- session dispatched (its route or its durable id), never another chat's."""
- module = sys.modules.get('tools.async_delegation')
- if module is None:
- return 0
- return module.interrupt_for_session(session_key=authority.sessions[ref.session_id].route,
- parent_session_id=physical_target(authority, ref), reason='/stop')
- def _require_current_route(authority, ref):
- """The route still serves this conversation (a reused route must not lend its objects)."""
- live = authority.sessions[ref.session_id]
- target = physical_target(authority, ref)
- store = authority.runner.session_store
- with store._lock:
- entry = store._entries.get(live.route)
- if entry is None or entry.session_id != target:
- raise RuntimeStoreError('stale_generation')
- def _owner_objects(authority, ref, *, include_fallback_evicted=False):
- """``(agent, subagent records)`` of this in-process session. Process-local registries cannot
- describe (or stop) another interpreter's live objects: a managed worker is refused rather than
- answered with an empty success."""
- from gateway.session_managed_worker import managed_policy
- if managed_policy(authority, ref) is not None:
- raise RuntimeStoreError('unsupported_projection')
- agent = authority.agent(ref)
- session_id = physical_target(authority, ref) if include_fallback_evicted else None
- route = authority.sessions[ref.session_id].route if include_fallback_evicted else None
- session_db = getattr(authority, 'db', None) if include_fallback_evicted else None
- return agent, subagent_records(
- agent, session_id=session_id, session_db=session_db, route=route,
- include_fallback_evicted=include_fallback_evicted)
- def physical_target(authority, ref):
- from gateway.config import Platform
- source = authority.sessions[ref.session_id].source # None: a history mount
- if source is not None and source.platform == Platform.LOCAL:
- from hermes_state_local import local_receipt
- return local_receipt(authority.db, ref.session_id)['entry']['session_id']
- return ref.session_id
- def control_snapshot(authority, ref):
- from hermes_cli.goals import GoalState
- from hermes_cli.loops import LoopState
- from hermes_cli.heartbeat import HeartbeatState
- # These pure serializers don't bind/import the legacy server. In particular
- # do not reuse _snapshot_control: its manager loader can write on a read.
- from tui_gateway.methods_session_control import (
- _safe_goal_snapshot, _safe_loop_snapshot, _safe_heartbeat_snapshot,
- _snapshot_revision, _snapshot_updated_at,
- )
- # Compression carries goal/loop/heartbeat to the continuation: read the current segment.
- target = physical_target(authority, ref)
- target = authority.db.get_compression_tip(target) or target
- states = []
- for kind, cls in [('goal', GoalState), ('loop', LoopState), ('heartbeat', HeartbeatState)]:
- raw = authority.db.get_meta(kind + ':' + target)
- try:
- states.append(cls.from_json(raw) if raw else None)
- except (ValueError, TypeError, AttributeError) as exc:
- raise RuntimeStoreError('storage_unavailable') from exc
- goal_state, loop_state, heartbeat_state = states
- goal = _safe_goal_snapshot(goal_state)
- # Project the persisted barrier, not GoalManager.is_waiting(), which clears
- # satisfied barriers and can query unrelated processes during a UI refresh.
- deferred = bool(goal and goal['status'] == 'active' and not goal.get('wait_barrier'))
- loop = _safe_loop_snapshot(loop_state, deferred_by_goal=bool(
- deferred and loop_state and loop_state.status == 'active'))
- heartbeat = _safe_heartbeat_snapshot(heartbeat_state)
- return {'goal': goal, 'loop': loop, 'heartbeat': heartbeat,
- 'revision': _snapshot_revision(goal, loop, heartbeat),
- 'updated_at': _snapshot_updated_at(*states)}
- def _has_fallback_evicted_ancestor(agent, target_sids, expected_db, route, registry):
- if not target_sids:
- return False
- current = agent
- for _ in range(getattr(registry, '_MAX_ANCESTOR_HOPS', 8)):
- ref = getattr(current, '_delegate_parent_ref', None) if current is not None else None
- current = ref() if callable(ref) else None
- if current is None:
- return False
- marker = getattr(current, '_evicted_on_fallback', False)
- if not (marker is True or (isinstance(marker, str) and bool(marker))):
- continue
- if getattr(current, 'session_id', None) not in target_sids:
- continue
- 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:
- continue
- if route is not None and marker != route:
- continue
- if route is None and isinstance(marker, str) and getattr(current, 'gateway_session_key', None) not in (None, marker):
- continue
- return True
- return False
- def subagent_records(parent, session_id=None, *, session_db=None, route=None, include_fallback_evicted=True):
- registry = sys.modules.get('tools.delegate_tool_registry')
- target_sid = (session_id or getattr(parent, 'session_id', None)) if include_fallback_evicted else None
- if registry is None or (parent is None and not target_sid):
- return []
- expected_db = session_db if session_db is not None else getattr(parent, '_session_db', None)
- effective_route = route if route is not None else getattr(parent, 'gateway_session_key', None)
- # A rotating /compress moves the conversation to a new stored id; an evicted parent keeps its earlier one.
- target_sids = _compression_lineage(expected_db, target_sid)
- with registry._active_subagents_lock:
- return [dict(record) for record in registry._active_subagents.values()
- if (parent is not None and registry._is_descendant_of(record.get('agent'), parent))
- or _has_fallback_evicted_ancestor(record.get('agent'), target_sids, expected_db, effective_route, registry)
- or _owned_by_lineage(record, target_sids, expected_db)]
- def _owned_by_lineage(record, target_sids, expected_db):
- """The read-only roster follows the conversation, as ``delegate_task(action="list")`` does: a
- child whose durable owner id is in this session's compression lineage, written to the same
- session database file. Without it every cached-agent rebuild (``/reasoning``, ``/model``, a
- policy refresh, idle eviction) hid still-running children from the dock while the status bar
- kept counting them. Control and tail stay pinned to the resident parent."""
- if not target_sids or record.get('owner_agent_session_id') not in target_sids:
- return False
- expected_path = getattr(expected_db, 'db_path', None)
- child_path = getattr(getattr(record.get('agent'), '_session_db', None), 'db_path', None)
- return expected_path is not None and child_path is not None and str(child_path) == str(expected_path)
- def _compression_lineage(db, session_id):
- """*session_id* plus the sessions it continues by compression, walked backward so a closed sibling under a compressed parent cannot divert the walk."""
- if not session_id:
- return frozenset()
- ids, current = {session_id}, session_id
- is_child, get = getattr(db, '_is_compression_child_row', None), getattr(db, 'get_session', None)
- if callable(is_child) and callable(get):
- row = get(current)
- while row and is_child(row) and row['parent_session_id'] not in ids and len(ids) < 200:
- current = row['parent_session_id']
- ids.add(current)
- row = get(current)
- return frozenset(ids)
- lineage = getattr(db, 'get_compression_lineage', None)
- found = lineage(session_id) if callable(lineage) else None
- return frozenset(found if isinstance(found, (list, tuple)) else ()) | ids
- def subagent_tail(records, subagent_id):
- result = {'subagent_id': subagent_id, 'available': False, 'text': '', 'truncated': False}
- record = next((r for r in records if r.get('subagent_id') == subagent_id), None)
- path = getattr(record.get('agent'), '_live_transcript_path', None) if record else None
- if not path:
- return result
- try:
- with open(path, 'rb') as stream:
- size = stream.seek(0, 2)
- stream.seek(max(0, size - _TAIL_BYTES))
- text = stream.read(_TAIL_BYTES).decode('utf-8', errors='ignore')
- except OSError:
- return result
- return {**result, 'available': True, 'text': text, 'truncated': size > _TAIL_BYTES}
- def _ownership(authority, ref, agent, records):
- """``(routing keys, owners)`` a registry process must match to belong to this session: its
- routing key AND an owner among the session, its agent and its subagents."""
- target = physical_target(authority, ref)
- keys, owners = {authority.sessions[ref.session_id].route, target}, {target}
- if agent is not None:
- owners.add(getattr(agent, 'session_id', None))
- owners.update(r.get('subagent_id') for r in records)
- owners.discard(None)
- owners.discard('')
- return keys, owners
- def _owned_locked(registry, keys, owners):
- """Matching process objects; the caller holds ``registry._lock``. Read directly:
- ``list_sessions`` refreshes recovered processes and writes checkpoints."""
- return [p for p in (*registry._running.values(), *registry._finished.values())
- if p.session_key in keys and (p.owner_task_id or p.task_id) in owners]
- def process_snapshot(authority, ref, agent, records):
- module = sys.modules.get('tools.process_registry')
- if module is None:
- return []
- registry = module.process_registry
- keys, owners = _ownership(authority, ref, agent, records)
- # Keep ownership and output together.
- with registry._lock:
- return [{'session_id': p.id, 'command': p.command[:200],
- 'status': 'exited' if p.exited else 'running', 'exit_code': p.exit_code,
- # The classic CLI dock's elapsed / exit-age / verdict and its 32k tail view.
- 'started_epoch': p.started_at, 'exited_at': p.exited_at or None,
- 'completion_reason': p.completion_reason if p.exited else None,
- 'output_tail': p.output_buffer[-_PROCESS_TAIL_CHARS:]} for p in _owned_locked(registry, keys, owners)]
|