session_tui_side.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300
  1. """Ink's ``/bg`` (``prompt.background``) and ``/btw`` (``prompt.btw``) on the shared owner.
  2. Each verb replies ``{task_id}`` at once and the answer lands later on the parent session's event
  3. stream as ``background.complete`` ``{task_id, text}`` / ``btw.complete`` ``{task_id, question,
  4. text}`` (``error: <exc>`` on failure) — the sidecar's contract (``tui_gateway/methods_prompt.py``).
  5. The side agent is detached: never an admission, never a FIFO turn, never a row in the parent
  6. transcript. It runs on a daemon thread
  7. under the owning profile's scope and the session's frozen launch policy (cwd, terminal, model
  8. route, toolsets), so a session that never ran a turn (no resident agent) works the same.
  9. """
  10. from functools import partial
  11. import asyncio
  12. import contextlib
  13. import logging
  14. import threading
  15. import uuid
  16. from gateway.session_busy_controls import authorize
  17. from hermes_state_runtime import RuntimeStoreError
  18. logger = logging.getLogger(__name__)
  19. _RUNTIME_KEYS = ('api_key', 'base_url', 'provider', 'requested_provider', 'api_mode', 'command', 'args',
  20. 'credential_pool', 'max_tokens', 'capabilities')
  21. def handlers(connection):
  22. return {'prompt.background': partial(background, connection), 'prompt.btw': partial(btw, connection),
  23. 'preview.restart': partial(preview_restart, connection)}
  24. def _admit(connection, ref, params, prefix, required='text', optional=()):
  25. """Shared admission: ``(live, policy, text, task_id)`` or a refusal before any work starts."""
  26. text = params.get(required)
  27. if (set(params) - {'session_id', 'profile', required, *optional} or not isinstance(ref.session_id, str)
  28. or not ref.session_id or not isinstance(text, str) or not text.strip()
  29. or any(params.get(key) is not None and not isinstance(params[key], str) for key in optional)):
  30. raise RuntimeStoreError('invalid_params')
  31. authority = connection.authority
  32. if ref.session_id not in authority.sessions:
  33. raise RuntimeStoreError('not_found')
  34. authorize(connection, ref, params, 'session:submit')
  35. # The answer rides this connection's event subscription, like a submit's reply.
  36. if ref.session_id not in connection.subscriptions:
  37. raise RuntimeStoreError('permission_denied')
  38. authority._require_admission_open()
  39. from gateway.session_policy import policy_for_source
  40. live = authority.sessions[ref.session_id]
  41. policy = policy_for_source(authority.runner, live.source)
  42. if policy is None:
  43. raise RuntimeStoreError('permission_denied')
  44. return live, policy, text, f'{prefix}_{uuid.uuid4().hex[:6]}'
  45. @contextlib.contextmanager
  46. def _side_scope(authority, policy, task_id):
  47. """The owning profile's home/secrets, the session's frozen policy, and the task's own session
  48. identity (approval key, HERMES_SESSION_ID) for the side agent's thread."""
  49. from gateway.session_authorities import owner_scope, served_profile_name
  50. from gateway.session_context import clear_session_vars, set_session_vars
  51. from gateway.session_policy import bind_turn_workspace, policy_scope, unbind_turn_workspace
  52. from tools.environments.local import _is_routed_home
  53. # The owning profile, as its own turns bind it: a served secondary by its name, so persistent
  54. # Docker keys ITS workspace container (never the launch profile's live one for the same folder);
  55. # the launch home binds none, like its ``agent:main`` turns.
  56. home = authority.profile_id
  57. profile = served_profile_name(home) if _is_routed_home(home) else ''
  58. with owner_scope(authority, hydrate_secrets=True), policy_scope(policy, authority=authority):
  59. # async_delivery=False: the side agent's answer is one ``*.complete`` event, and its bg_* session
  60. # has no later turn to wake, so a background delegate_task joins in this run (#140569).
  61. tokens = set_session_vars(session_key=task_id, session_id=task_id, cwd=policy.cwd, profile=profile,
  62. async_delivery=False)
  63. try:
  64. # The session's workspace, as its own turns get it (#140665): mounted at /workspace in a
  65. # per-task container, or the session's own persistent workspace container (same digest).
  66. bind_turn_workspace(policy, task_id)
  67. yield
  68. finally:
  69. unbind_turn_workspace(task_id)
  70. clear_session_vars(tokens)
  71. def _resolve_runtime(authority, policy):
  72. """``(model, runtime)`` the session's next turn would use: its frozen policy route."""
  73. from gateway.run_turn_prepare import _resolve_policy_agent_runtime
  74. return _resolve_policy_agent_runtime(authority.runner, policy)
  75. def _side_agent(authority, policy, live, task_id, **overrides):
  76. """A fresh ``AIAgent`` on the session's frozen route (call inside ``_side_scope``)."""
  77. from agent.skill_utils import parse_config_string_list
  78. from gateway.run import _checkpoint_agent_kwargs
  79. from run_agent import AIAgent
  80. runner = authority.runner
  81. model, runtime = _resolve_runtime(authority, policy)
  82. config = policy.config(authority)
  83. from gateway.session_worker_construct import session_routing
  84. pr = session_routing(authority, policy)
  85. refresh_fallback = getattr(runner, '_refresh_fallback_model', None)
  86. kwargs = dict(
  87. model=model, **{key: runtime.get(key) for key in _RUNTIME_KEYS if key in runtime},
  88. **_checkpoint_agent_kwargs(config),
  89. max_iterations=policy.max_turns, quiet_mode=True, verbose_logging=False,
  90. enabled_toolsets=list(policy.current_toolsets(config)),
  91. disabled_toolsets=parse_config_string_list((config.get('agent') or {}).get('disabled_toolsets')) or None,
  92. reasoning_config=policy.current_reasoning_config(runner, live.route),
  93. service_tier=policy.current_service_tier(runner, live.route),
  94. request_overrides=dict(runtime.get('request_overrides') or {}),
  95. providers_allowed=pr.get('only'), providers_ignored=pr.get('ignore'), providers_order=pr.get('order'),
  96. provider_sort=pr.get('sort'), provider_require_parameters=pr.get('require_parameters', False),
  97. provider_data_collection=pr.get('data_collection'),
  98. # Its own session in the owning profile's store, like the sidecar's ``bg_*`` rows.
  99. session_id=task_id, platform=policy.platform, session_db=authority.db,
  100. fallback_model=refresh_fallback() if callable(refresh_fallback) else None,
  101. load_soul_identity=not policy.ignore_rules, skip_memory=policy.ignore_rules,
  102. side_agent=True)
  103. kwargs.update(overrides)
  104. return AIAgent(**kwargs)
  105. def _abandoned(holder):
  106. abandoned = getattr(holder[0], 'abandoned', None) if holder else None
  107. return bool(abandoned and abandoned())
  108. def _spawn(authority, ref, task_id, event_type, body, extra=None, holder=None):
  109. """Run ``body()`` on a daemon thread; publish its text (or ``error: <exc>``) on the session.
  110. The thread is owner work until it unwinds: the authority's ``_side_agents`` ledger is counted by
  111. the restart wait, the shutdown drain, the SessionDB close gate and idle exit
  112. (``session_runtime_workers.uncounted_runtime_work``), and profile retirement interrupts
  113. ``holder[0]`` (the side agent, once built) and joins the thread."""
  114. from gateway.session_runtime_workers import persist_work_count
  115. extra = extra or {}
  116. ledger = getattr(authority, '_side_agents', None)
  117. if ledger is None:
  118. ledger = authority._side_agents = {}
  119. try:
  120. loop = asyncio.get_running_loop()
  121. except RuntimeError:
  122. loop = None
  123. def run():
  124. # The whole target: a BaseException the agent re-raises (cancellation, exit) must not
  125. # leave a dead thread counted as owner work.
  126. try:
  127. try:
  128. text = body()
  129. except Exception as exc:
  130. logger.warning('Side agent %s failed', task_id, exc_info=True)
  131. # A refusal names the check that fired (``workspace_unavailable (cwd: <path>)``).
  132. field, detail = getattr(exc, 'field', None), getattr(exc, 'detail', None)
  133. named = f' ({field}: {detail})' if field and detail else ''
  134. text = f'error: {getattr(exc, "reason", None) or exc}{named}'
  135. live = authority.sessions.get(ref.session_id)
  136. if live is not None and not _abandoned(holder):
  137. live.event_stream.publish(ref.session_id, {'task_id': task_id, **extra, 'text': str(text or '')},
  138. event_type=event_type)
  139. finally:
  140. ledger.pop(thread, None)
  141. if loop is not None:
  142. # gateway_state.json's active_agents drops back, recounted on the owner loop.
  143. with contextlib.suppress(RuntimeError): # the loop already closed
  144. loop.call_soon_threadsafe(persist_work_count, authority)
  145. thread = threading.Thread(target=run, name=f'side-agent-{task_id}', daemon=True)
  146. ledger[thread] = holder
  147. try:
  148. thread.start()
  149. except BaseException:
  150. ledger.pop(thread, None)
  151. raise
  152. persist_work_count(authority)
  153. return {'task_id': task_id}
  154. async def background(connection, ref, params):
  155. """``/bg <prompt>``: a fresh agent on the session's route runs the prompt to completion."""
  156. live, policy, text, task_id = _admit(connection, ref, params, 'bg')
  157. authority = connection.authority
  158. holder = [None]
  159. def body():
  160. from tui_gateway.methods_prompt import _final_response_text
  161. with _side_scope(authority, policy, task_id):
  162. agent = holder[0] = _side_agent(authority, policy, live, task_id)
  163. try:
  164. result = agent.run_conversation(user_message=text, task_id=task_id)
  165. finally:
  166. # AIAgent.close() is the owner boundary (memory, tool subprocesses, clients).
  167. with contextlib.suppress(Exception):
  168. agent.close()
  169. return _final_response_text(result)
  170. return _spawn(authority, ref, task_id, 'background.complete', body, holder=holder)
  171. async def btw(connection, ref, params):
  172. """``/btw <question>``: a side question over a snapshot of the conversation
  173. (``agent/side_question.py``); the live history, FIFO and prompt cache stay untouched."""
  174. _live, policy, text, task_id = _admit(connection, ref, params, 'btw')
  175. authority = connection.authority
  176. # The resident agent's conversation (a cache-parity fork replays it); a session with no
  177. # resident agent (never ran a turn here, or evicted) answers from its stored transcript.
  178. agent = authority.agent(ref)
  179. snapshot = list(getattr(agent, '_session_messages', None) or [])
  180. from gateway.session_local_recovery import transcript_target
  181. target = None if snapshot else transcript_target(authority, ref)
  182. handle = _SideQuestionStop()
  183. def body():
  184. from agent.side_question import answer_side_question
  185. history = snapshot or authority.db.get_messages_as_conversation(target)
  186. with _side_scope(authority, policy, task_id):
  187. model, runtime = _resolve_runtime(authority, policy)
  188. main_runtime = {'model': model, 'session_id': ref.session_id,
  189. **{key: runtime.get(key) for key in ('provider', 'base_url', 'api_key', 'api_mode')}}
  190. return answer_side_question(text, history, parent_agent=agent, main_runtime=main_runtime,
  191. on_fork=handle.set_fork, should_stop=handle.stopped.is_set) or ''
  192. return _spawn(authority, ref, task_id, 'btw.complete', body, extra={'question': text}, holder=[handle])
  193. class _SideQuestionStop:
  194. """``/btw``'s holder: retirement and shutdown interrupt its cache-parity fork, and once stopped
  195. the read-only one-shot fallback (an uncancellable aux call of up to 180 s that writes nothing)
  196. no longer holds owner work, so it cannot keep a retiring profile's reservation."""
  197. def __init__(self):
  198. self.stopped = threading.Event()
  199. self._lock = threading.Lock()
  200. self._fork = None
  201. def set_fork(self, fork):
  202. with self._lock:
  203. self._fork = fork
  204. if fork is not None and self.stopped.is_set():
  205. self.hard_interrupt('Profile runtime is stopping')
  206. def hard_interrupt(self, message=None):
  207. self.stopped.set()
  208. with self._lock:
  209. fork = self._fork
  210. if fork is not None:
  211. from agent.interrupt_compat import request_hard_interrupt
  212. request_hard_interrupt(fork, message)
  213. def abandoned(self):
  214. """Stopped with no fork running: what is left publishes nothing and writes nothing."""
  215. with self._lock:
  216. return self.stopped.is_set() and self._fork is None
  217. async def preview_restart(connection, ref, params):
  218. """Desktop preview pane "restart dev server": a hidden terminal+file agent brings the preview
  219. URL's server back up (rules: ``tui_gateway/methods_prompt.py`` ``_PREVIEW_RESTART_RULES``).
  220. Detached like ``/bg``; progress rides ``preview.restart.progress``, the answer
  221. ``preview.restart.complete`` ``{task_id, text}``. Context is the session's stored transcript."""
  222. live, policy, url, task_id = _admit(connection, ref, params, 'preview', required='url',
  223. optional=('cwd', 'context'))
  224. authority = connection.authority
  225. cwd, context = (str(params.get(key) or '').strip() for key in ('cwd', 'context'))
  226. from gateway.session_local_recovery import transcript_target
  227. target = transcript_target(authority, ref)
  228. holder = [None]
  229. def progress(text):
  230. if (text := str(text or '').strip()) and (stream := authority.sessions.get(ref.session_id)) is not None:
  231. stream.event_stream.publish(ref.session_id, {'task_id': task_id, 'text': text},
  232. event_type='preview.restart.progress')
  233. def body():
  234. from tui_gateway.agent_callbacks import _preview_restart_history
  235. from tui_gateway.methods_prompt import (_final_response_text, _preview_restart_prompt,
  236. _validated_preview_cwd)
  237. preview_cwd = _validated_preview_cwd(cwd)
  238. history = _preview_restart_history(authority.db.get_messages_as_conversation(target) if target else [])
  239. prompt = _preview_restart_prompt(url, cwd, context, bool(history))
  240. with _side_scope(authority, policy, task_id):
  241. if preview_cwd:
  242. from tools.terminal_tool import register_task_env_overrides
  243. register_task_env_overrides(task_id, {'cwd': preview_cwd})
  244. try:
  245. progress('Starting hidden restart agent')
  246. # Deliberately NOT closed via AIAgent.close(): it would kill the background
  247. # server this task exists to leave running.
  248. agent = _side_agent(authority, policy, live, task_id, enabled_toolsets=['terminal', 'file'],
  249. disabled_toolsets=None, session_db=None, skip_memory=True,
  250. tool_start_callback=lambda _id, name, _args: progress(f'Running {name}'))
  251. holder[0] = agent
  252. result = agent.run_conversation(user_message=prompt, task_id=task_id,
  253. conversation_history=history or None)
  254. finally:
  255. with contextlib.suppress(Exception):
  256. from tools.terminal_tool import clear_task_env_overrides
  257. clear_task_env_overrides(task_id)
  258. return _final_response_text(result)
  259. return _spawn(authority, ref, task_id, 'preview.restart.complete', body, holder=holder)