"""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)]