"""A resumed local session re-reads its config-derived settings (CFG-2); its MCP servers change the same way (CFG-3). Main's ``hermes -c`` was a new process: toolsets, MCP servers, ``terminal.backend``, ``max_turns``, checkpoints and the reasoning default came from the config it started with, while the stored session kept its model/provider. The owner keeps that line on ``session.resume``: it re-derives exactly those fields from the session profile's current config and commits them as a new policy generation. ``reload.mcp`` commits the MCP part alone for the calling session. The creation flags (request_json), the model route and a committed ``/reasoning`` or workspace pick stay; a session with a turn running or queued keeps the policy that turn was admitted under. A Bot Chat an earlier build committed frozen follows its profile from the open on (``follow_bot_chat``). """ import asyncio import json import logging from dataclasses import asdict, replace from functools import partial from pathlib import Path logger = logging.getLogger(__name__) def _follow(target, live, key): if key in live: target[key] = live[key] else: target.pop(key, None) def refreshed_policy(policy, live, terminal, *, picked=(), mcp_only=False): """``(policy, secrets, replaced)``: *policy* with its config-derived fields from *live* (the profile's config) and *terminal* (its terminal scope), or only its MCP servers (*mcp_only*); explicit picks (launch flags, the *picked* policy edits) stay. *secrets* are the refreshed sections' private values, *replaced* the sections (``None``: terminal) whose stored private values they supersede. *policy* itself when nothing moved; a rotated private value alone (its redacted tree unchanged) moves it.""" from gateway.session_policy import _extract_config_secrets, present_sections from gateway.session_policy_credentials import secrets_moved old, config = json.loads(policy.config_json), json.loads(policy.config_json) live, secrets, replaced = present_sections(live), {}, set() if mcp_only: toolsets, terminal = policy.toolsets, json.loads(policy.terminal_json) else: toolsets = _settings(policy, config, live, picked) terminal = _terminal(policy, terminal, picked) _extract_config_secrets(terminal, secrets, (None,)) replaced.add(None) toolsets = _mcp_servers(policy, config, live, toolsets, secrets, replaced) if (config == old and toolsets == policy.toolsets and terminal == json.loads(policy.terminal_json) and not secrets_moved(policy.config_secret_ref, secrets, replaced)): return policy, {}, set() policy = replace(policy, toolsets=toolsets, config_json=json.dumps(config), terminal_json=json.dumps(terminal)) return policy, secrets, replaced def _settings(policy, config, live, picked): """Follow the config-derived settings into *config*; the toolsets they select.""" from gateway.session_policy import _resolve_toolsets, session_pinned request = json.loads(policy.request_json) live_agent = live.get('agent') or {} agent = dict(config.get('agent') or {}) keys = [] if 'max_turns' in request else ['max_turns'] # The session's own record (a pick, or a reset back to the profile) wins over the receipt history. chosen = session_pinned(config, 'reasoning', 'reasoning' in request or 'reasoning' in picked) keys += [] if chosen else ['reasoning_effort', 'reasoning_overrides'] toolsets = policy.toolsets if 'toolsets' not in request and policy.editor_mcp_json is None: keys.append('disabled_toolsets') _follow(config, live, 'platform_toolsets') toolsets = tuple(sorted(_resolve_toolsets({}, live, policy.source, policy.safe_mode, policy.coding_posture))) for key in keys: _follow(agent, live_agent, key) if agent or 'agent' in config: config['agent'] = agent if 'max_turns' not in request: _follow(config, live, 'max_turns') _follow(config, live, 'checkpoints') if request.get('checkpoints') is True: section = config.get('checkpoints') section = dict(section) if isinstance(section, dict) else {'enabled': bool(section)} if section else {} config['checkpoints'] = {**section, 'enabled': True} return toolsets def _terminal(policy, terminal, picked): from gateway.session_policy import terminal_uses_host_cwd terminal, request = dict(terminal), json.loads(policy.request_json) # The session's own folder, where it now is, under build_policy's rule; a committed Move to project is # the user's pick on every backend (it rewrote the policy, never the launch request). if request.get('cwd_explicit') is True or 'workspace' in picked or terminal_uses_host_cwd(terminal): terminal['TERMINAL_CWD'] = policy.cwd return terminal def _mcp_servers(policy, config, live, toolsets, secrets, replaced): """The profile's MCP servers as this session's own selection takes them now (its explicit pick or platform allowlist, ``no_mcp`` and disabled entries respected): their definitions into *config*, private values split off as build_policy does (a managed worker binds this config, so it connects exactly these), and their names into the returned toolsets. An editor-MCP session keeps its frozen servers.""" from gateway.session_policy import _extract_config_secrets, _resolve_toolsets from hermes_cli.tools_config import enabled_mcp_server_names from hermes_state_runtime import RuntimeStoreError if policy.editor_mcp_json is not None: return toolsets request = json.loads(policy.request_json) sections = [section if isinstance(section, dict) else {} for section in (config.get('mcp_servers'), live.get('mcp_servers'))] pick, picked, enabled = request.get('toolsets'), set(), enabled_mcp_server_names(live) if pick is not None: # The launch pick's servers are an allowlist: each stays only while config enables it, and once all # are gone the chat has none, never every enabled server. A server that is now disabled or removed # leaves the pick before it is re-validated (it no longer validates, and keeping the frozen # definitions would start the server the user turned off). known = set(sections[0]) | set(sections[1]) server = partial(_server_name, known) picked = {server(name) for name in pick if isinstance(name, str) and server(name) in known} pick = [name for name in pick if not isinstance(name, str) or server(name) not in picked - enabled] try: selected = _resolve_toolsets({} if pick is None else {'toolsets': pick}, json.loads(json.dumps(live)), policy.source, policy.safe_mode, policy.coding_posture) except RuntimeStoreError: return toolsets # the rest of the launch pick no longer validates against the profile: keep the frozen servers # A picked server config removed keeps a disabled stub in the stored section, so every later refresh # (after an owner restart too) still knows that name as one of the pick's servers, not an unknown toolset. stubs = {name: {'enabled': False} for name in picked - set(sections[1])} if 'mcp_servers' in live or stubs: config['mcp_servers'] = json.loads(json.dumps({**sections[1], **stubs} if stubs else live['mcp_servers'])) _extract_config_secrets(config['mcp_servers'], secrets, ('mcp_servers',)) else: config.pop('mcp_servers', None) replaced.add('mcp_servers') servers = selected & enabled & picked if picked else selected & enabled return tuple(sorted((set(toolsets) - set(sections[0]) - set(sections[1])) | servers)) def _server_name(servers, name): """The server a pick name selects: ``mcp-`` is its bare alias unless a server has that name.""" return name[4:] if name.startswith('mcp-') and name not in servers else name def _prepare(authority, session_id, mcp_only=False, adopt_only=False): """Off the owner loop: the stored policy, its refresh from this profile home's files, and the generation it was derived at. None when the session takes no refresh or nothing moved. *adopt_only*: the adoption of a frozen Bot Chat alone, without the config-derived settings (a later open on the same attachment).""" from gateway.session_local import load_profile_config from gateway.session_policy import SURFACES, restore_policy from hermes_state_local import local_receipt from hermes_state_mutation_prepared import policy_picks from tools.terminal_scope import build_profile_terminal_scope generation = authority.db.get_session(session_id)['runtime_generation'] stored = local_receipt(authority.db, session_id)['policy'] old = restore_policy(stored) # A bypass launch never reads the profile; cron, Kanban and room routes are not resumed CLI sessions. if old.ignore_user_config or old.source not in SURFACES: return None home = Path(authority.db.db_path).resolve().parent terminal = {} if mcp_only or adopt_only else build_profile_terminal_scope(home) live, picked = load_profile_config(home), policy_picks(authority.db, session_id) base = old if not mcp_only: # Opening a Bot Chat an earlier build froze adopts it: it follows its profile from now on. from gateway.session_local_migration import follow_bot_chat base = follow_bot_chat(authority, session_id, old, live, picked) if adopt_only: return None if base is old else (stored, old, base, {}, set(), generation) policy, secrets, replaced = refreshed_policy(base, live, terminal, picked=picked, mcp_only=mcp_only) return None if policy is old else (stored, old, policy, secrets, replaced, generation) def _rebind(authority, session_id, old, policy, fresh, replaced): """Re-bind the private values like a policy mutation: policy identity covers config and terminal, and the refreshed sections' private values are the profile's current ones (the stored ones there are neither re-read nor checked: a rotated key is what the refresh picks up, not a revoked credential). A policy that follows its profile from this open on keeps none of its followed sections' frozen values.""" from gateway.session_policy import FOLLOW_SECTIONS, bind_launch_key, launch_key from gateway.session_policy_credentials import recover_config_secrets skip = (*(FOLLOW_SECTIONS if policy.follows_profile else ()), *replaced) secrets = recover_config_secrets(authority, old, skip) if old.config_secret_ref else {} secrets.update(fresh) return bind_launch_key(authority, session_id, policy, launch_key(authority, old), config_secrets=secrets) def _pending_adoptions(authority): """Frozen Bot Chats an open found to adopt but could not commit (a turn running or queued, a concurrent edit): the next open retries, whether or not that client is already attached.""" found = getattr(authority, '_pending_adoptions', None) if found is None: found = authority._pending_adoptions = set() return found def _in_flight(authority): found = getattr(authority, '_policy_refreshes', None) if found is None: found = authority._policy_refreshes = {} return found async def refresh_settled(authority, session_id): """Wait out a refresh of *session_id* in flight. Its commit lands before its terminal cleanup (a sandbox teardown can take 10-15 s) and its publication; an attach meanwhile would find the stored policy ahead of the live one, which restore_local_session refuses.""" refreshes = _in_flight(authority) while (running := refreshes.get(session_id)) is not None and not running.done(): logger.debug('Session %s waits for its policy refresh to publish', session_id) await asyncio.wait({running}) # its outcome is its caller's; a cancelled waiter leaves it running async def commit_refresh(authority, ref, *, mcp_only=False, adopt_only=False): """Commit an idle local session's refresh as its next policy generation: True when one was committed, False when nothing moved. Raises the store's refusal (``session_busy`` while a turn runs or waits). One refresh per session at a time, run to its publication even when the caller is cancelled: a second waits for the first, then usually finds nothing moved.""" from gateway.session_runtime_workers import track_mutation await refresh_settled(authority, ref.session_id) refreshes = _in_flight(authority) task = refreshes[ref.session_id] = track_mutation(authority, _commit_refresh(authority, ref, mcp_only, adopt_only)) task.add_done_callback(lambda done: refreshes.pop(ref.session_id, None) if refreshes.get(ref.session_id) is done else None) return await asyncio.shield(task) async def _commit_refresh(authority, ref, mcp_only, adopt_only=False): from gateway.session_runtime_workers import tracked_write from hermes_state_mutation_prepared import commit_refreshed_policy prepared = await asyncio.to_thread(_prepare, authority, ref.session_id, mcp_only, adopt_only) # An MCP-only refresh never runs follow_bot_chat: it neither settles nor commits an adoption, so it # leaves a pending one for the next open. pending = _pending_adoptions(authority) if not mcp_only else set() if prepared is None: pending.discard(ref.session_id) return False stored, old, policy, secrets, replaced, generation = prepared if policy.follows_profile and not old.follows_profile: pending.add(ref.session_id) # until this commit lands moved = json.loads(policy.terminal_json) != json.loads(old.terminal_json) policy = _rebind(authority, ref.session_id, old, policy, secrets, replaced) # Compare-and-swap against the receipt as stored (JSON lists), not its restored tuple form. The # publication is the commit's own shielded follow-up: a caller cancelled mid-commit cannot leave the # stored policy ahead of the live one (restore_local_session refuses that pair). await tracked_write(authority, partial(commit_refreshed_policy, authority.db, epoch=authority.epoch, session_id=ref.session_id, old=stored, new=asdict(policy), generation=generation), then=lambda _generation: _publish(authority, ref, moved)) pending.discard(ref.session_id) return True async def refresh_resumed_policy(authority, ref, *, attached=False): """Commit the config refresh of an idle local session before it is attached. Never fails the resume: a busy session, a revoked launch credential or an unreadable profile keeps the stored policy. Only a turn running or queued (or admitted during the commit) is expected; anything else is a WARNING. *attached*: this client already holds the session (Desktop's warm reopen). The settings refresh is once per attachment, but a frozen Bot Chat whose adoption a busy open refused is adopted on any later open.""" if attached and ref.session_id not in _pending_adoptions(authority): return try: await (commit_refresh(authority, ref, adopt_only=True) if attached else commit_refresh(authority, ref)) except Exception as exc: # health: allow BLE001 -- a refresh is best-effort; the resume itself must proceed reason = getattr(exc, 'reason', None) or type(exc).__name__ busy = reason in {'session_busy', 'unknown_execution', 'revision_conflict'} logger.log(logging.INFO if busy else logging.WARNING, 'Session %s keeps its stored policy on resume: %s', ref.session_id, reason) def drop_session_terminal(authority, ref): """The session's own cached terminal environments (keyed by its route, or its ids under per-session isolation): the terminal tool reuses one by key whatever backend built it. A profile-shared one stays. Its recorded cwd (keyed by its route or task id) goes too: it wins over the new binding's directory.""" from gateway.session_authorities import owner_scope from hermes_state_local import local_receipt from tools.terminal_tool import _qualify_task_key, clear_session_cwd from tools.terminal_tool_lifecycle import cleanup_vm ids = {ref.session_id, local_receipt(authority.db, ref.session_id)['entry']['session_id']} route = authority.sessions[ref.session_id].route from gateway.session_policy import unbind_turn_workspace with owner_scope(authority): keys = {_qualify_task_key(key) for key in (f'session:{route}', *ids)} for key in (route, *ids): # The turn's workspace binding goes with them: it wins over the new binding's cwd too. unbind_turn_workspace(key) clear_session_cwd(key) for key in keys: cleanup_vm(key) async def _publish(authority, ref, moved=False): from gateway.session_local import local_session_info, publish_local_policy if moved: # before the drain can run a turn on the new binding with the old environment await asyncio.to_thread(drop_session_terminal, authority, ref) publish_local_policy(authority, ref.session_id) # A drain that ran during the off-loop commit saw the new stored policy beside the old live one and # paused; with both equal again, anything admitted meanwhile runs. authority._schedule(ref) # Every viewer already attached adopts the new generation (its next fenced edit would otherwise be # refused as stale) and repaints from the refreshed policy, as a reasoning/workspace edit publishes. authority._publish_pending(ref) authority.sessions[ref.session_id].event_stream.publish( ref.session_id, local_session_info(authority, ref), event_type='session.info')