session_authorities.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346
  1. """One SessionAuthority per reserved profile home; resolved by the active runtime scope.
  2. A multiplexing gateway owns every profile under ``profiles/`` plus the default home. Each
  3. home has its own ``state.db``, admission ledger, runtime epoch and control identity, so each
  4. gets its own authority. Every consumer already runs inside the routed profile's
  5. ``_profile_runtime_scope`` (that is what the multiplex fixes on main established), so the
  6. authority for "the profile this code is acting for" is the one keyed by the active home.
  7. A single-profile gateway is a map of one: the launch home's authority answers every lookup,
  8. scoped or not, exactly as before.
  9. """
  10. from __future__ import annotations
  11. import asyncio
  12. from contextlib import asynccontextmanager
  13. from dataclasses import dataclass
  14. from pathlib import Path
  15. from typing import Any
  16. from hermes_constants import get_hermes_home, get_hermes_home_override, hermes_home_key
  17. from hermes_state_runtime import RuntimeStoreError
  18. class SessionAuthorities:
  19. """Registry of authorities keyed by ``hermes_home_key(home)``."""
  20. def __init__(self, launch_home, *, multiplexed=False):
  21. self.launch_key = hermes_home_key(launch_home)
  22. self._by_key: dict[str, object] = {}
  23. self._names: dict[str, str | None] = {}
  24. # One event per slot reserved by ``add(home, None)`` while its authority is being built: set
  25. # when ``replace`` fills the slot or ``remove`` drops it (the build failed).
  26. self._starting: dict[str, asyncio.Event] = {}
  27. # A multiplexing runtime (configured, or one that ever served a second home) keeps the
  28. # scoped-lookup contract after its secondaries are removed: an unserved home is None.
  29. self.multiplexed = bool(multiplexed)
  30. def add(self, home, authority, name=None) -> None:
  31. key = hermes_home_key(home)
  32. if key in self._by_key:
  33. raise RuntimeError(f'duplicate session authority for {home}')
  34. self._by_key[key] = authority
  35. self._names[key] = name
  36. if authority is None:
  37. self._starting[key] = asyncio.Event()
  38. if key != self.launch_key:
  39. self.multiplexed = True
  40. def replace(self, home, authority) -> None:
  41. """Fill the slot reserved by ``add(home, None, name=...)`` once the authority exists."""
  42. key = hermes_home_key(home)
  43. if key not in self._by_key or self._by_key[key] is not None:
  44. raise RuntimeError(f'no reserved session authority slot for {home}')
  45. self._by_key[key] = authority
  46. self._end_start(key)
  47. def remove(self, home):
  48. """Drop *home*'s slot (a parked boot, a hot-unserved profile); returns the authority or None.
  49. The launch slot is never removed."""
  50. key = hermes_home_key(home)
  51. if key == self.launch_key:
  52. raise RuntimeError('the launch session authority cannot be removed')
  53. self._names.pop(key, None)
  54. self._end_start(key)
  55. return self._by_key.pop(key, None)
  56. def _end_start(self, key) -> None:
  57. started = self._starting.pop(key, None)
  58. if started is not None:
  59. started.set()
  60. def starting(self, profile):
  61. """``(key, started)`` for the reserved slot *profile* names while its authority is still being
  62. built, else None. ``started`` is set once the build ends: filled, or dropped because it failed."""
  63. from hermes_cli.profiles import profile_matches_home
  64. return next(((key, started) for key, started in list(self._starting.items())
  65. if profile_matches_home(profile, Path(key))), None)
  66. def starting_homes(self) -> list[str]:
  67. """Keys of every slot whose authority is still being built (a snapshot, as in ``serving``)."""
  68. return list(self._starting)
  69. def profile_name(self, authority):
  70. """Served profile name for *authority*; None for the launch profile (its adapters are
  71. ``runner.adapters``, its session keys the historical ``agent:main`` namespace)."""
  72. key = hermes_home_key(authority.profile_id)
  73. return None if key == self.launch_key else self._names.get(key)
  74. def __len__(self) -> int:
  75. return sum(authority is not None for authority in self._by_key.values())
  76. def __iter__(self):
  77. """The built authorities, retiring ones included. A slot still being built is no authority
  78. yet, so iteration and ``len`` skip it (``starting`` names it); membership (``in``) still sees
  79. it, so ``add`` refuses a second build of that profile."""
  80. # A snapshot, as in ``serving``: other threads walk the set while the loop hot-serves.
  81. return (authority for authority in list(self._by_key.values()) if authority is not None)
  82. def __contains__(self, home) -> bool:
  83. return hermes_home_key(home) in self._by_key
  84. @property
  85. def launch(self):
  86. return self._by_key[self.launch_key]
  87. def for_home(self, home):
  88. """Authority owning *home*, or None when this process does not serve it."""
  89. return self._by_key.get(hermes_home_key(home))
  90. def require(self, home):
  91. authority = self.for_home(home)
  92. if authority is None:
  93. raise RuntimeStoreError('profile_mismatch')
  94. return authority
  95. def active(self):
  96. """Authority for the active runtime scope.
  97. Unscoped code (startup, shutdown, background watchers) belongs to the launch profile.
  98. Scoped code that names a home this process does not serve gets ``None``: a routed
  99. profile must never fall back to the launch profile's ledger — including once a removed
  100. secondary leaves only the launch slot (a late callback of that profile). Only a runtime
  101. that never multiplexed is a map of one that answers every scope with the launch authority.
  102. """
  103. if not self.multiplexed or get_hermes_home_override() is None:
  104. return self._by_key[self.launch_key]
  105. return self._by_key.get(hermes_home_key(get_hermes_home()))
  106. def serving(self) -> list:
  107. """Authorities that accept work: not a reserved-but-unbuilt slot, not one retiring (a
  108. failed serve or an unserve whose turn outlived Stop keeps its slot but refuses admissions)."""
  109. # A snapshot: hosted-room coordinator threads read the served set while the loop hot-serves.
  110. return [a for a in list(self._by_key.values()) if a is not None and not getattr(a, 'retiring', False)]
  111. def served_profiles(self) -> list[dict]:
  112. return [{'profile_id': a.profile_id, 'home': a.profile_id} for a in self.serving()]
  113. def profile_ids(self) -> frozenset[str]:
  114. return frozenset(a.profile_id for a in self.serving())
  115. @dataclass(frozen=True)
  116. class LocalBot:
  117. """One local bot this process serves: its profile ``name``, ``home`` and owning ``authority``.
  118. ``problem`` says why a client cannot address it by that name (None when it can); ``retiring``
  119. marks one being unserved, which still owns its rooms but takes no new work."""
  120. name: str
  121. home: Path
  122. authority: Any
  123. problem: str | None = None
  124. retiring: bool = False
  125. def local_bots(runner) -> list[LocalBot]:
  126. """The local bots this gateway serves, one per built authority, by the name the registry
  127. reserved each under (the launch profile keeps ``served_profile_name``). The one answer to
  128. "which bots are local here" for both the Bots roster (``profiles.list``) and group seating
  129. (``session_hosted_members``). A name two homes answer to, or one that is not its home's own
  130. name (a linked ``profiles/<name>`` resolves outside ``profiles/`` and reads as ``default``), is
  131. flagged rather than bound: a client routes, and the member transport names, a bot by name."""
  132. from collections import Counter
  133. registry = getattr(runner, 'session_authorities', None)
  134. if registry is None:
  135. authority = getattr(runner, 'session_authority', None)
  136. pairs = [(served_profile_name(authority.profile_id), authority)] if authority is not None else []
  137. else:
  138. # A snapshot: hosted-room coordinator threads read the served set while the loop hot-serves.
  139. pairs = [(registry.profile_name(a) or served_profile_name(a.profile_id), a)
  140. for a in list(registry._by_key.values()) if a is not None]
  141. counts = Counter(name for name, _ in pairs)
  142. bots = []
  143. for name, authority in pairs:
  144. problem = None
  145. if counts[name] > 1:
  146. problem = 'two served homes answer to that name'
  147. elif name != served_profile_name(authority.profile_id):
  148. problem = 'a linked profile home is not supported yet'
  149. bots.append(LocalBot(name, Path(authority.profile_id), authority, problem,
  150. bool(getattr(authority, 'retiring', False))))
  151. return bots
  152. def served_profile_name(home) -> str:
  153. """Canonical profile id of a served home: ``default`` for the root, the directory name for
  154. ``profiles/<name>`` (via ``hermes_constants.profile_name_for_home``, the resolver main uses).
  155. Any other custom HERMES_HOME is the process's own single profile and keeps the ``default``
  156. label the CLI reports for it (``hermes -p`` never targets such a home by name)."""
  157. from hermes_constants import profile_name_for_home
  158. return profile_name_for_home(home) or 'default'
  159. def authority_for_home(runner, home):
  160. """Explicit per-home lookup for callers that already know the routed home."""
  161. registry = getattr(runner, 'session_authorities', None)
  162. if registry is None:
  163. authority = getattr(runner, 'session_authority', None)
  164. if authority is not None and Path(authority.db.db_path).resolve().parent == Path(home).resolve():
  165. return authority
  166. return None
  167. return registry.for_home(home)
  168. def authority_for_profile_id(runner, profile_id):
  169. return authority_for_home(runner, Path(profile_id))
  170. def active_authority(runner):
  171. """Authority for the active runtime scope (see ``SessionAuthorities.active``); the single
  172. launch authority when the runner predates the registry (bare test runners)."""
  173. registry = getattr(runner, 'session_authorities', None)
  174. if registry is None:
  175. return getattr(runner, 'session_authority', None)
  176. return registry.active()
  177. def require_active_authority(runner, store=None):
  178. """The active scope's authority, or a refusal: retryable (``runtime_draining``) while its
  179. profile is parked, else ``profile_mismatch``. With *store* (a callable returning the caller's
  180. SessionDB, called only once an authority exists), that store must be the authority's: an API
  181. adapter bound to another profile's SessionDB never admits here."""
  182. authority = active_authority(runner)
  183. if authority is None:
  184. from gateway.run_runtime import refuse_parked_scope
  185. refuse_parked_scope(runner) # retryable while its profile is parked
  186. if authority is None or (store is not None and store() is not authority.db):
  187. from hermes_state_runtime import RuntimeStoreError
  188. raise RuntimeStoreError('profile_mismatch')
  189. return authority
  190. def all_authorities(runner):
  191. registry = getattr(runner, 'session_authorities', None)
  192. if registry is not None:
  193. return list(registry)
  194. authority = getattr(runner, 'session_authority', None)
  195. return [authority] if authority is not None else []
  196. def serving_authorities(runner):
  197. """The authorities that accept work (``SessionAuthorities.serving``: no reserved-but-unbuilt slot,
  198. none retiring): what startup recovery, service creation and cross-ledger reads cover. Shutdown
  199. keeps ``all_authorities``, so a retained authority's live writer is still settled."""
  200. registry = getattr(runner, 'session_authorities', None)
  201. if registry is not None:
  202. return registry.serving()
  203. authority = getattr(runner, 'session_authority', None)
  204. return [authority] if authority is not None and not getattr(authority, 'retiring', False) else []
  205. def require_serving(authority):
  206. """Refuse a verb reached through a stale connection to a retired authority: its ownership is
  207. released, and until a successor bumps the epoch its own epoch still passes the store fence."""
  208. if getattr(authority, 'retired', False):
  209. raise RuntimeStoreError('runtime_retired')
  210. def admission_owner(authority, session_id):
  211. """The admission identity a physical store row answers to: its compression root, then the
  212. local creation id a canonical reset forks under (a reset child is not a compression child, so
  213. ``logical_owner`` alone stops at the child and misses the conversation's admissions)."""
  214. from hermes_state_local import local_lineage_owner
  215. sid = authority.logical_owner(session_id)
  216. if not sid:
  217. return sid
  218. with authority.db._read_ctx() as conn:
  219. return local_lineage_owner(conn, sid)
  220. def holds_admission(authority, session_id) -> bool:
  221. """Whether *authority*'s store holds a canonical admission for *session_id*. A parked profile's
  222. retained (retiring) store that cannot answer counts as holding one: startup auto-resume fails
  223. closed for that entry instead of stopping the boot or resuming a turn that FIFO may own."""
  224. try:
  225. return bool(authority.db._read_one(
  226. 'SELECT 1 FROM session_admissions WHERE target_session_id IN (?,?) LIMIT 1',
  227. (session_id, admission_owner(authority, session_id))))
  228. except Exception as exc:
  229. if not getattr(authority, 'retiring', False):
  230. raise
  231. import logging
  232. logging.getLogger('gateway.run').warning("Skipping auto-resume of %s: retained store %s cannot answer: %s",
  233. session_id, getattr(authority, 'profile_id', '?'), exc)
  234. return True
  235. def _prepare_owner_scope(home: Path):
  236. """Enter ``owner_scope``'s profile scope in this (worker) thread and return what it bound:
  237. ``(secrets, terminal scope)``, or ``None`` when *home* is not a directory (``owner_scope`` binds
  238. nothing then). Entering the real scope keeps one definition of how it is built."""
  239. if not home.is_dir():
  240. return None
  241. from agent.secret_scope import current_secret_scope
  242. from gateway.run import _profile_runtime_scope
  243. from tools.terminal_scope import get_terminal_scope
  244. with _profile_runtime_scope(home, hydrate_secrets=False):
  245. return current_secret_scope(), get_terminal_scope()
  246. @asynccontextmanager
  247. async def async_owner_scope(authority):
  248. """``owner_scope`` for a coroutine on the gateway loop: the profile's ``.env``, ``config.yaml`` and
  249. terminal policy are read in a worker thread, then only the context variables are set here.
  250. Every RPC a client sends enters its owner's scope, and the classic CLI, Ink and Desktop poll
  251. ``subagent.list`` / ``process.list`` every 1-5 s per session: built on the loop, that scope was the
  252. largest single cost of RPC dispatch on a multiplexed gateway with many sessions open."""
  253. runner = getattr(authority, 'runner', None)
  254. home = Path(str(authority.profile_id))
  255. if not getattr(getattr(runner, 'config', None), 'multiplex_profiles', False) or not home.is_absolute():
  256. with owner_scope(authority): # the launch scope (frozen sources) or nullcontext: no profile files
  257. yield
  258. return
  259. prepared = await asyncio.to_thread(_prepare_owner_scope, home)
  260. if prepared is None:
  261. yield
  262. return
  263. from gateway.run import _profile_runtime_scope
  264. secrets, terminal = prepared
  265. with _profile_runtime_scope(home, secrets, prepared_terminal_scope=terminal):
  266. yield
  267. def owner_scope(authority, *, hydrate_secrets=False):
  268. """Runtime scope of the profile that owns *authority* — under multiplex only.
  269. Owner-side handlers (RPC dispatch, cron submit, admitted execution) must read config, jobs
  270. and policy for the OWNING profile, never the launch profile's ambient scope. A
  271. single-profile gateway keeps its ambient scope byte-for-byte: entering a scope there
  272. would read the profile's config/.env for every handler, including bypass (--safe-mode)
  273. launches that must never touch the profile YAML. Test peers with symbolic ids ('fixture')
  274. likewise keep the ambient scope.
  275. A standalone gateway that already hosts a second home (a profile created over the wire froze
  276. the launch env and made unscoped secret reads fail closed) binds the launch profile's own scope
  277. instead: unbound, every launch-profile session.create raised UnscopedSecretError (#141623).
  278. """
  279. from contextlib import nullcontext
  280. runner = getattr(authority, 'runner', None)
  281. if not getattr(getattr(runner, 'config', None), 'multiplex_profiles', False):
  282. from tui_gateway.launch_profile_policy import launch_profile_scope_if_multiplexed
  283. return launch_profile_scope_if_multiplexed()
  284. home = Path(str(authority.profile_id))
  285. if not home.is_absolute() or not home.is_dir():
  286. return nullcontext()
  287. from gateway.run import _profile_runtime_scope
  288. return _profile_runtime_scope(home, hydrate_secrets=hydrate_secrets)