gateway_server.py 73 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238
  1. """ACP projection of the profile gateway; never constructs an execution owner."""
  2. from __future__ import annotations
  3. import asyncio
  4. from contextlib import suppress
  5. import logging
  6. import os
  7. import uuid
  8. import acp
  9. from acp.schema import (
  10. AgentCapabilities, Implementation, InitializeResponse, LoadSessionResponse,
  11. NewSessionResponse, PromptCapabilities, PromptResponse, ResumeSessionResponse,
  12. SessionCapabilities, SessionForkCapabilities, SessionListCapabilities, SessionResumeCapabilities,
  13. )
  14. from hermes_cli.gateway_client import GatewayClientError, connect_gateway
  15. from hermes_constants import get_hermes_home
  16. from acp_adapter.gateway_reply import GatewayReplyMixin, _text
  17. from acp_adapter.session import _translate_acp_cwd, _normalize_cwd_for_compare
  18. logger = logging.getLogger(__name__)
  19. def _slash_command(text):
  20. """Canonical Hermes command name ``text`` invokes, or None for ordinary text.
  21. Only a registered command (or alias) is a command: ``/etc/hosts is wrong`` or ``/tmp/x``
  22. (a path, the same rule ``MessageEvent.get_command`` applies) and unknown ``/words`` are
  23. prompt text for the model. A registered command is never sent as prompt text: it is answered
  24. by a gateway verb or refused by name (``acp_adapter/gateway_commands.py``)."""
  25. stripped = text.lstrip()
  26. if not stripped.startswith('/'):
  27. return None
  28. name = stripped.split(None, 1)[0][1:]
  29. if not name or '/' in name:
  30. return None
  31. from hermes_cli.commands import resolve_command
  32. command = resolve_command(name)
  33. if command is not None:
  34. return command.name
  35. from acp_adapter.gateway_commands import ROUTES
  36. return name if name in ROUTES else None
  37. def _bypass_route():
  38. """--safe-mode / --ignore-user-config read no profile default route, so the session freezes the
  39. launch's explicit one (``hermes -m <model> --provider <name> --safe-mode acp``). Both, refused at
  40. session/new: a model alone is accepted by the owner, then its first turn cannot build the agent."""
  41. model = (os.environ.get("HERMES_MODEL") or os.environ.get("HERMES_INFERENCE_MODEL") or "").strip()
  42. if not model:
  43. raise GatewayClientError("--safe-mode / --ignore-user-config read no profile default model: launch "
  44. "with one, e.g. hermes -m <model> --provider <provider> --safe-mode acp")
  45. provider = os.environ.get("HERMES_INFERENCE_PROVIDER", "").strip()
  46. if not provider:
  47. raise GatewayClientError("--safe-mode / --ignore-user-config read no profile provider: launch with "
  48. "--provider too, e.g. hermes -m <model> --provider <provider> --safe-mode acp")
  49. return {"model": model, "provider": provider}
  50. def _tools_changed_notice(payload):
  51. """The owner re-froze this session's editor MCP tools (a changed config or changed schemas)."""
  52. servers = ", ".join(payload.get("mcp_servers") or []) or "none"
  53. return f"Editor MCP tools changed (servers: {servers}); the new tool list applies from the next turn.\n"
  54. class GatewayACPAgent(GatewayReplyMixin, acp.Agent):
  55. def __init__(self):
  56. self._conn = None
  57. self._gateway = None
  58. self._connection = None
  59. self._connect_lock = asyncio.Lock()
  60. # A per-task overlay HERMES_HOME attaches to the profile its symlinked lock names (#138949).
  61. from hermes_cli.gateway_runtime import gateway_profile_home
  62. self._home = gateway_profile_home(get_hermes_home())
  63. self._snapshots = {}
  64. self._event_task = None
  65. self._terminals = {}
  66. self._streamed = {}
  67. # Admission -> closed reply segments already shown (interim commentary, pre-tool deltas).
  68. self._segments = {}
  69. self._changed = asyncio.Condition()
  70. self._failure = None
  71. # Connection generation: a waiter whose transport was replaced reports that transport's
  72. # ambiguous failure (``_lost_failure``) instead of waiting on a connection it never used.
  73. self._link = 0
  74. self._lost_failure = None
  75. # Session -> editor MCP servers a replacement connection must re-attach.
  76. self._editor_mcp = {}
  77. self._permissions = {}
  78. self._admissions = {}
  79. self._submitting = set()
  80. # Session -> (content fingerprint, input_id, staged (text, attachments)) of a submit whose ack
  81. # never arrived. The editor's retry (that session's next prompt, same content) reuses it, so the authority
  82. # returns the same admission.
  83. self._unacked = {}
  84. # Admissions whose terminal reply one path (the pump's message.complete or a retry's
  85. # terminal receipt) is delivering right now; the other path yields to the claim.
  86. self._settling = set()
  87. # Admissions a terminal receipt already delivered: their late message.complete adds nothing.
  88. self._receipted = {}
  89. # ``gateway_replay_gap``: admission -> the reply segment shown when a gap cut it; own prompts awaiting
  90. # their terminal, in admission order; those whose reply the hole lost for good; per session, the gap
  91. # re-attaches sent and adopted (a snapshot covers the submits sent before its resume).
  92. self._cut, self._inflight, self._lost, self._resumes, self._adopted = {}, {}, {}, {}, {}
  93. self._pending_cancels = set()
  94. # (session, tool_call_id) -> (tool name, args, admission) of a call still open on the editor.
  95. self._tool_args = {}
  96. # Session -> AssistantMessageIdAllocator: the ``messageId`` of the assistant message being streamed.
  97. self._message_ids = {}
  98. # Editor-held compression-tip id -> logical session id (see ``_resume``).
  99. self._aliases = {}
  100. self._form_elicitation = False
  101. from hermes_cli.gateway_mutations import PreparedMutations
  102. self._mutations = PreparedMutations()
  103. # Session -> title the editor was last shown (``session_info_update`` fires on a change).
  104. self._titles = {}
  105. # Session -> the mode (edit approval policy) the editor was last shown (``current_mode_update``).
  106. self._modes = {}
  107. # Session -> the settings the editor's ``configOptions`` last showed (``config_option_update``).
  108. self._configs = {}
  109. # Session -> the owner's latest usage dict (``session.usage`` / ``session.stats``).
  110. self._usage = {}
  111. self._background = set()
  112. def on_connect(self, conn):
  113. self._conn = conn
  114. add_observer = getattr(getattr(conn, "_conn", None), "add_observer", None)
  115. if callable(add_observer):
  116. add_observer(self._observe_client_message)
  117. def _observe_client_message(self, event):
  118. """``initialize``'s raw capabilities (the SDK's typed model drops ``elicitation``)."""
  119. message = getattr(event, "message", None)
  120. if getattr(event, "direction", None) == "incoming" and isinstance(message, dict) \
  121. and message.get("method") == "initialize":
  122. from acp_adapter.elicitation import client_supports_form_elicitation
  123. self._form_elicitation = client_supports_form_elicitation(message.get("params"))
  124. async def initialize(self, **kwargs):
  125. from hermes_cli import __version__
  126. from acp_adapter.auth import build_auth_methods
  127. return InitializeResponse(protocol_version=acp.PROTOCOL_VERSION,
  128. agent_info=Implementation(name="hermes-agent", version=__version__),
  129. agent_capabilities=AgentCapabilities(load_session=True,
  130. prompt_capabilities=PromptCapabilities(image=True),
  131. session_capabilities=SessionCapabilities(fork=SessionForkCapabilities(), list=SessionListCapabilities(),
  132. resume=SessionResumeCapabilities())),
  133. auth_methods=build_auth_methods())
  134. async def authenticate(self, method_id, **kwargs):
  135. from acp_adapter.server import HermesACPAgent
  136. return await HermesACPAgent.authenticate(self, method_id, **kwargs)
  137. async def _client(self):
  138. async with self._connect_lock:
  139. if self._failure is not None or self._transport_closed():
  140. # The event pump died with this transport (gateway restart, socket loss, replay gap).
  141. # Its waiters hold the ambiguous failure; the next call gets a fresh, re-verified
  142. # connection instead of the stale error forever.
  143. await self._teardown()
  144. if self._gateway is None:
  145. connection = connect_gateway()
  146. gateway = await connection.__aenter__()
  147. try:
  148. descriptor = await gateway.rpc("runtime.describe")
  149. if descriptor.get("profile_id") != str(self._home):
  150. raise GatewayClientError("profile_mismatch")
  151. await self._reattach(gateway)
  152. except BaseException:
  153. await connection.__aexit__(None, None, None)
  154. raise
  155. self._connection, self._gateway = connection, gateway
  156. self._event_task = asyncio.create_task(self._events())
  157. if self._failure:
  158. raise self._failure
  159. return self._gateway
  160. async def _reattach(self, gateway):
  161. """Subscribe a replacement connection to every session this editor holds.
  162. The fresh snapshot carries the new replay epoch/sequence and the authority's current
  163. pending rows (a turn lost in the restart is ``unknown`` there, never resubmitted); the
  164. editor's borrowed MCP servers are re-attached because a restarted owner has none."""
  165. from hermes_cli.gateway_client import GatewayRPCError
  166. for session_id in list(self._snapshots):
  167. params = {"editor": self._editor_mcp[session_id]} if session_id in self._editor_mcp else {}
  168. try:
  169. snapshot = await gateway.rpc("session.resume", session_id=session_id, **params)
  170. except GatewayRPCError:
  171. # A definitive refusal for this session (deleted, retired) must not keep the
  172. # editor's other sessions offline; its next prompt reports not_found.
  173. logger.info("ACP session %s not re-attached after reconnect", session_id, exc_info=True)
  174. self._snapshots.pop(session_id, None)
  175. continue
  176. await self._adopt(session_id, snapshot, client=gateway)
  177. # Before this session's cards are offered again: until ``_client`` returns, ``self._gateway`` is
  178. # not this connection, so a card answered while the request is out would lose its answer.
  179. await self._request_live_reasoning(gateway, session_id)
  180. for pending in snapshot.get("prompts", []):
  181. self._permission(session_id, pending)
  182. await self._notify_unknown(session_id)
  183. async def _adopt(self, session_id, snapshot, resumes=None, client=None):
  184. """Install a fresh ``session.resume`` snapshot as a session's projection: every install (create, load,
  185. fork, a control's refresh, reconnect, replay gap) goes through here.
  186. Events before its watermark are skipped from here on, so the session state they would have carried
  187. is projected from the snapshot itself: the editor is never left showing Default while the owner
  188. enforces Accept Edits / Don't Ask (#141338 ACP-7)."""
  189. async with self._changed: # its pending rows and controls may settle or block a waiter
  190. self._snapshots[session_id] = snapshot
  191. if resumes is not None:
  192. self._adopted[session_id] = resumes
  193. self._changed.notify_all()
  194. await self._project_mode(session_id, self._editor_id(session_id), snapshot.get("info") or {}, client=client)
  195. async def _request_live_reasoning(self, client, session_id):
  196. """Ask the owner to stream this session's reasoning (``show_reasoning``), as the CLI does.
  197. The in-process server gave every editor turn a reasoning sink (``acp_adapter/server.py``). The
  198. owner publishes ``reasoning.delta`` only for a live session whose flag a viewer set, and a restarted
  199. owner's sessions start without it, so every attach and re-attach asks (#134889 ACP-4). The flag is
  200. the session's: a viewer that hides reasoning later turns it off until the editor attaches again."""
  201. try:
  202. await client.rpc("config.set", session_id=session_id, key="show_reasoning", value="1", _timeout=10)
  203. except Exception:
  204. # Boundary: a display flag must not fail the attach (a refusal, a lost connection, or no answer
  205. # within the CLI's 10 s). At worst the session runs without live reasoning; a reconnect's
  206. # re-attach asks again.
  207. logger.debug("ACP session %s keeps its reasoning hidden", session_id, exc_info=True)
  208. async def _notify_unknown(self, session_id):
  209. """The classic chat's resume notice: say why the next prompt will be refused and how to recover."""
  210. if self._has_unknown(session_id) and self._conn:
  211. await self._conn.session_update(session_id=self._editor_id(session_id), update=acp.update_agent_message_text(
  212. self._unknown_recovery(session_id, submitted=False).removeprefix("unknown_execution: ") + "\n"))
  213. def _transport_closed(self):
  214. # The socket reader settles every pending RPC before the pump sees its disconnect frame,
  215. # so an editor retry can arrive while ``_failure`` is still unset.
  216. reader = getattr(self._gateway, "reader", None)
  217. return isinstance(reader, asyncio.Future) and reader.done()
  218. async def _teardown(self):
  219. task, connection = self._event_task, self._connection
  220. self._event_task = self._connection = self._gateway = None
  221. if task is not None:
  222. task.cancel()
  223. with suppress(asyncio.CancelledError):
  224. await task
  225. if connection is not None:
  226. await connection.__aexit__(None, None, None)
  227. # Partial reply segments belonged to admissions whose waiters already failed. A reply cut off here
  228. # never gets its ``message.complete`` (re-attach starts at the owner's current sequence), so its
  229. # ``messageId`` closes too: the next reply must not reuse it.
  230. self._streamed.clear()
  231. self._segments.clear()
  232. self._message_ids.clear()
  233. self._cut.clear()
  234. async with self._changed:
  235. # Every waiter on the old transport wakes to its ambiguous failure, even one that had
  236. # not yet observed ``_failure`` before it is cleared here.
  237. self._link += 1
  238. self._lost_failure = self._failure or GatewayClientError(
  239. "Gateway disconnected; turn outcome is unknown. Resume the session to check whether "
  240. "it completed or was interrupted; do not resend the work.")
  241. self._failure = None
  242. self._changed.notify_all()
  243. async def new_session(self, cwd, mcp_servers=None, **kwargs):
  244. client = await self._client()
  245. descriptor = await client.rpc("runtime.describe")
  246. if ("acp" not in descriptor.get("session_create", {}).get("sources", [])
  247. or "acp-editor-policy-v1" not in descriptor.get("capabilities", [])):
  248. raise GatewayClientError("acp_policy_unavailable")
  249. from hermes_cli.gateway_chat import env_launch_flags
  250. # `hermes acp --yolo` / `--safe-mode` / ... reach this process as their env equivalents; the
  251. # owner does not inherit them, so they freeze into this session's policy or not at all.
  252. flags = env_launch_flags()
  253. if flags.get("safe_mode") or flags.get("ignore_user_config"):
  254. flags.update(_bypass_route())
  255. snapshot = await client.rpc("session.create", request_id=uuid.uuid4().hex,
  256. source="acp", cwd=_translate_acp_cwd(cwd),
  257. editor={"mcp_servers": [s.model_dump(by_alias=True) for s in mcp_servers or []],
  258. "edit_approval_policy": "ask"}, **flags)
  259. session_id = snapshot["session_id"]
  260. await self._adopt(session_id, snapshot)
  261. if mcp_servers:
  262. self._editor_mcp[session_id] = {
  263. "mcp_servers": [s.model_dump(by_alias=True) for s in mcp_servers]}
  264. info = snapshot.get("info") or await client.rpc("session.info", session_id=session_id)
  265. await self._request_live_reasoning(client, session_id)
  266. return NewSessionResponse(session_id=session_id, **await self._session_fields(session_id, info, session_id))
  267. def _editor_id(self, session_id):
  268. return next((held for held, sid in self._aliases.items() if sid == session_id), session_id)
  269. async def _session_fields(self, session_id, info, editor_id):
  270. """Main's new/load/resume/fork reply fields (model picker, modes, provenance ``_meta``); the
  271. command list and context indicator follow once the reply is queued, as main scheduled them."""
  272. from acp_adapter.gateway_session_meta import model_state, provenance_meta, session_config_options, session_modes
  273. from acp_adapter.modes import EDIT_APPROVAL_POLICY_CONFIG_ID, MODE_TO_EDIT_APPROVAL_POLICY
  274. title = info.get("title")
  275. if isinstance(title, str) and title.strip():
  276. self._titles[session_id] = title
  277. models = await asyncio.to_thread(model_state, info)
  278. meta = await asyncio.to_thread(provenance_meta, self._home / "state.db", editor_id, session_id)
  279. mode = self._modes.setdefault(session_id, session_modes(info).current_mode_id)
  280. options = await session_config_options(self._gateway, session_id, models, info, mode)
  281. # ``_adopt`` seeded the mode from the snapshot: a change the pump projected since is what the reply shows.
  282. policy = MODE_TO_EDIT_APPROVAL_POLICY[self._modes[session_id]]
  283. modes = session_modes({"edit_approval_policy": policy})
  284. for option in options:
  285. if option.id == EDIT_APPROVAL_POLICY_CONFIG_ID:
  286. option.current_value = policy
  287. if self._conn:
  288. task = asyncio.get_running_loop().create_task(self._after_attach(session_id, editor_id))
  289. self._background.add(task)
  290. task.add_done_callback(self._background.discard)
  291. return {"models": models, "modes": modes, "field_meta": meta,
  292. "config_options": options}
  293. async def _after_attach(self, session_id, editor_id):
  294. from acp_adapter.gateway_session_meta import available_commands_update
  295. await asyncio.sleep(0) # after the session reply: the editor routes updates by a known id
  296. try:
  297. await self._conn.session_update(session_id=editor_id, update=available_commands_update())
  298. await self._project_usage(session_id, editor_id,
  299. await (await self._client()).rpc("session.stats", session_id=session_id))
  300. except Exception:
  301. # Boundary: a detached editor or a refused read is not the attach's failure.
  302. logger.debug("ACP post-attach notices for %s not delivered", session_id, exc_info=True)
  303. async def _attach_info(self, client, session_id):
  304. """``session.info`` for a session to attach. A thread main's in-process server wrote has no
  305. gateway policy yet; ``session.resume`` is the verb that adopts it (``LEGACY_LOCAL_SOURCES``)."""
  306. from hermes_cli.gateway_client import GatewayRPCError
  307. try:
  308. return await client.rpc("session.info", session_id=session_id)
  309. except GatewayRPCError as exc:
  310. if str(exc) != "not_found":
  311. raise
  312. adopted = await client.rpc("session.resume", session_id=session_id)
  313. await client.rpc("session.detach", session_id=session_id, subscription_id=adopted["subscription_id"])
  314. return await client.rpc("session.info", session_id=session_id)
  315. async def _resume(self, cwd, held_id, mcp_servers):
  316. client = await self._client()
  317. from acp_adapter.catalog import logical_session_id
  318. from hermes_cli.gateway_client import GatewayRPCError
  319. session_id = await asyncio.to_thread(logical_session_id, self._home / "state.db", held_id)
  320. # The latest load names the id this editor addresses the conversation by.
  321. self._aliases = {held: sid for held, sid in self._aliases.items() if sid != session_id}
  322. if session_id != held_id:
  323. self._aliases[held_id] = session_id
  324. info = await self._attach_info(client, session_id)
  325. if self._moved(info, cwd):
  326. info = await self._move_workspace(client, session_id, cwd)
  327. if "cwd" not in info and self._conn:
  328. await self._conn.session_update(session_id=held_id, update=acp.update_agent_message_text(
  329. "Attached to the gateway's existing session policy; editor cwd is not applied.\n"))
  330. resume_params = {}
  331. if mcp_servers:
  332. # A non-empty list is the editor's selection. An empty one (load always carries a list)
  333. # keeps the session's servers, as fork does: a second editor without MCP config must not
  334. # strip the first one's tools. An owner without editor MCP bound none.
  335. descriptor = await client.rpc("runtime.describe")
  336. if "acp-session-mcp-v1" not in descriptor.get("capabilities", []):
  337. raise GatewayClientError("acp_mcp_policy_unavailable")
  338. resume_params['editor'] = {'mcp_servers': [s.model_dump(by_alias=True) for s in mcp_servers]}
  339. try:
  340. snapshot = await client.rpc("session.resume", session_id=session_id, **resume_params)
  341. except GatewayRPCError as exc:
  342. if str(exc) != "acp_mcp_policy_conflict":
  343. raise
  344. # The editor's MCP config changed: the owner re-binds the session's servers (control
  345. # capability, idle only), as the workspace move above, instead of refusing the thread.
  346. await self._rebind_editor_mcp(client, session_id, resume_params['editor'])
  347. snapshot = await client.rpc("session.resume", session_id=session_id, **resume_params)
  348. await self._adopt(session_id, snapshot)
  349. if 'editor' in resume_params:
  350. self._editor_mcp[session_id] = resume_params['editor']
  351. from acp_adapter.server import _history_replay_updates
  352. if self._conn:
  353. # The editor replays the live transcript in stored order, as main's ACP did; archived rows
  354. # (summarized away by a compression) are display-only.
  355. live = sorted((m for m in snapshot["messages"] if not m.get("archived")), key=lambda m: m.get("row_id") or 0)
  356. for update in _history_replay_updates(live):
  357. await self._conn.session_update(session_id=held_id, update=update)
  358. for pending in snapshot.get("prompts", []):
  359. self._permission(session_id, pending)
  360. await self._notify_unknown(session_id)
  361. await self._request_live_reasoning(client, session_id)
  362. return await self._session_fields(session_id, {**info, **(snapshot.get("info") or {})}, held_id)
  363. @staticmethod
  364. def _moved(info, cwd):
  365. return "cwd" in info and _normalize_cwd_for_compare(info["cwd"]) != _normalize_cwd_for_compare(_translate_acp_cwd(cwd))
  366. async def _move_workspace(self, client, session_id, cwd):
  367. """Main rebound a session opened from another folder to that folder; the owner's ``workspace``
  368. mutation (Move to project) moves execution cwd and TERMINAL_CWD together, idle sessions only."""
  369. payload = {'cwd': _translate_acp_cwd(cwd)}
  370. self._unacked.pop(session_id, None)
  371. await self._mutations.apply(client, session_id, 'workspace', payload)
  372. self._mutations.acknowledge(session_id, 'workspace', payload)
  373. return await client.rpc("session.info", session_id=session_id)
  374. async def _rebind_editor_mcp(self, client, session_id, editor):
  375. """The owner's ``editor_mcp`` mutation: rediscovers *editor*'s servers into the session's policy."""
  376. self._unacked.pop(session_id, None)
  377. await self._mutations.apply(client, session_id, 'editor_mcp', editor)
  378. self._mutations.acknowledge(session_id, 'editor_mcp', editor)
  379. async def load_session(self, cwd, session_id, mcp_servers=None, **kwargs):
  380. return LoadSessionResponse(**await self._resume(cwd, session_id, mcp_servers))
  381. async def resume_session(self, cwd, session_id, mcp_servers=None, **kwargs):
  382. return ResumeSessionResponse(**await self._resume(cwd, session_id, mcp_servers))
  383. async def _cancel_admission(self, session_id, admission_id):
  384. client = await self._client()
  385. # Cancel our own admission; another surface's running turn is not ours to
  386. # interrupt. Only when our admission is the one executing do we interrupt.
  387. try:
  388. await client.rpc("prompt.cancel", session_id=session_id, admission_id=admission_id)
  389. except GatewayClientError as exc:
  390. if str(exc) != "stale_generation":
  391. raise
  392. receipt = await client.rpc("prompt.receipt", session_id=session_id, admission_id=admission_id)
  393. if receipt["status"] != "started":
  394. return
  395. try:
  396. await client.rpc("session.interrupt", session_id=session_id,
  397. execution_generation=receipt["execution_generation"])
  398. except GatewayClientError as interrupt_exc:
  399. if str(interrupt_exc) != "stale_generation":
  400. raise
  401. # The exact admission may have settled between the receipt and interrupt.
  402. # Re-read that admission only; never substitute the session's current
  403. # generation, which could already belong to a successor.
  404. settled = await client.rpc(
  405. "prompt.receipt", session_id=session_id, admission_id=admission_id)
  406. if settled["status"] != "terminal":
  407. raise
  408. async def cancel(self, session_id, **kwargs):
  409. session_id = self._aliases.get(session_id, session_id)
  410. if session_id not in self._snapshots:
  411. raise GatewayClientError("not_found")
  412. admission_id = self._admissions.get(session_id)
  413. if admission_id is None:
  414. if session_id in self._submitting:
  415. self._pending_cancels.add(session_id)
  416. return
  417. await self._cancel_admission(session_id, admission_id)
  418. async def fork_session(self, cwd, session_id, mcp_servers=None, **kwargs):
  419. from acp.schema import ForkSessionResponse
  420. session_id = self._aliases.get(session_id, session_id)
  421. client = await self._client()
  422. info = await client.rpc('session.info', session_id=session_id)
  423. # The owner binds the child's editor servers under the child's own scope: these, or else a
  424. # copy of the parent's.
  425. payload = {'mcp_servers': [s.model_dump(by_alias=True) for s in mcp_servers]} if mcp_servers else {}
  426. self._unacked.pop(session_id, None)
  427. result = await self._mutations.apply(client, session_id, 'branch', payload)
  428. child = result['branched_session_id']
  429. if self._moved(info, cwd):
  430. await self._move_workspace(client, child, cwd)
  431. await self._adopt(child, await client.rpc('session.resume', session_id=child))
  432. if payload or session_id in self._editor_mcp:
  433. self._editor_mcp[child] = payload or self._editor_mcp[session_id]
  434. self._mutations.acknowledge(session_id, 'branch', payload)
  435. info = self._snapshots[child].get('info') or await client.rpc('session.info', session_id=child)
  436. await self._request_live_reasoning(client, child)
  437. return ForkSessionResponse(session_id=child, **await self._session_fields(child, info, child))
  438. async def set_session_model(self, model_id, session_id, **kwargs):
  439. from acp.schema import SetSessionModelResponse
  440. session_id = self._aliases.get(session_id, session_id)
  441. client = await self._client()
  442. from hermes_cli.models import parse_model_input
  443. # Picker IDs include the provider, as on the in-process ACP switch path.
  444. provider, model = await asyncio.to_thread(parse_model_input, model_id, '')
  445. payload = {'model': model, **({'provider': provider} if provider else {})}
  446. self._unacked.pop(session_id, None) # a control between a lost submit and its repeat retires it
  447. result = await self._mutations.apply(client, session_id, 'model', payload,
  448. confirm=self._model_confirmer(session_id))
  449. if result.get('status') == 'cancelled':
  450. # Declined: nothing was written; the editor's picker must not show the target as active.
  451. raise GatewayClientError('model_switch_cancelled')
  452. await self._adopt(session_id, await client.rpc('session.resume', session_id=session_id))
  453. self._mutations.acknowledge(session_id, 'model', payload)
  454. if result.get('status') == 'deferred' and self._conn:
  455. # A pick during a running turn lands for the next one (#139604); say so, as Desktop does.
  456. from acp_adapter.gateway_commands import deferred_pick_text
  457. await self._conn.session_update(session_id=self._editor_id(session_id),
  458. update=acp.update_agent_message_text(deferred_pick_text(result) + "\n"))
  459. return SetSessionModelResponse()
  460. async def _confirm_deferred_pick(self, session_id, editor_id, ask):
  461. """The owner's boundary ask for a guarded deferred pick (``confirmation_required``; nothing
  462. written, the pick stays pending): the same permission request as an idle pick. Yes re-sends
  463. the same selection once with the owner's token (as Ink/Desktop); no, or no editor, keeps the
  464. committed model, and the editor is told which outcome it got, never left on the promise."""
  465. from acp_adapter.gateway_commands import _model_text, deferred_pick_text, refused_pick_text
  466. from hermes_cli.gateway_mutations import model_refusal_text
  467. async def say(text):
  468. if self._conn:
  469. await self._conn.session_update(session_id=editor_id, update=acp.update_agent_message_text(text + "\n"))
  470. target = ask.get("target_model") or (ask.get("payload") or {}).get("model")
  471. committed = {"model": ask.get("committed_model"), "provider": ask.get("committed_provider"),
  472. "target_model": target}
  473. confirm = self._model_confirmer(session_id)
  474. try:
  475. if confirm is None or not await confirm(ask):
  476. await say(refused_pick_text({**committed, "reason": "not confirmed"}))
  477. return
  478. client = await self._client()
  479. snapshot = await client.rpc("session.resume", session_id=session_id)
  480. result = await client.rpc("session.mutate", session_id=session_id, operation="model",
  481. request_id=uuid.uuid4().hex, expected_revision=snapshot["revision"],
  482. expected_generation=snapshot["execution_generation"],
  483. payload={**(ask.get("payload") or {}), "confirm": ask["confirm"]})
  484. if result.get("status") == "confirmation_required":
  485. # Another pick or a turn moved the session first: said once, never re-asked in a loop.
  486. await say(model_refusal_text(result, confirmed=True))
  487. return
  488. if session_id in self._snapshots:
  489. await self._adopt(session_id, await client.rpc("session.resume", session_id=session_id))
  490. # Confirmed while a turn runs: stored again for the next boundary, said as such.
  491. await say(deferred_pick_text(result) if result.get("status") == "deferred"
  492. else _model_text("Model switched to", result))
  493. except GatewayClientError as exc:
  494. logger.info("Deferred model pick on %s not confirmed: %s", session_id, exc)
  495. await say(refused_pick_text({**committed, "reason": str(exc)}))
  496. def _model_confirmer(self, session_id):
  497. """The owner's guarded-model confirmation as an ACP permission request (the mechanism
  498. approvals use): "Switch anyway" re-sends the mutation once with the owner's token; deny,
  499. dismissal or a lost editor keeps the current model. None without an editor connection."""
  500. if self._conn is None:
  501. return None
  502. async def confirm(refusal):
  503. from acp.schema import AllowedOutcome, PermissionOption
  504. from agent.i18n import t
  505. from hermes_cli.gateway_mutations import confirmation_title
  506. title = confirmation_title(refusal)
  507. tool_call = acp.update_tool_call(
  508. f"model-confirm-{uuid.uuid4().hex[:12]}", title=f"{title}: {refusal.get('target_model', '')}",
  509. kind="other", status="pending",
  510. content=[acp.tool_content(acp.text_block(refusal['confirm_message']))],
  511. raw_input={'model': refusal.get('target_model'), 'provider': refusal.get('target_provider'),
  512. 'guards': [w.get('kind') for w in refusal.get('warnings') or []]})
  513. options = [PermissionOption(option_id="allow_once", kind="allow_once",
  514. name=t("cli.model.choice_switch_anyway")),
  515. PermissionOption(option_id="deny", kind="reject_once", name=t("cli.model.choice_cancel"))]
  516. response = await self._conn.request_permission(session_id=self._editor_id(session_id),
  517. tool_call=tool_call, options=options)
  518. return isinstance(response.outcome, AllowedOutcome) and response.outcome.option_id == "allow_once"
  519. return confirm
  520. def _held_session(self, session_id):
  521. session_id = self._aliases.get(session_id, session_id)
  522. if session_id not in self._snapshots:
  523. raise GatewayClientError("not_found")
  524. return session_id
  525. async def set_session_mode(self, mode_id, session_id, **kwargs):
  526. """Main's Default / Accept Edits / Don't Ask: the session's edit approval policy on the owner."""
  527. from acp.schema import SetSessionModeResponse
  528. from acp_adapter.modes import MODE_TO_EDIT_APPROVAL_POLICY
  529. if mode_id not in MODE_TO_EDIT_APPROVAL_POLICY:
  530. raise GatewayClientError("invalid_params")
  531. await self._set_edit_policy(self._held_session(session_id), MODE_TO_EDIT_APPROVAL_POLICY[mode_id])
  532. return SetSessionModeResponse()
  533. async def set_config_option(self, config_id, session_id, value=None, **kwargs):
  534. """The pickers ``config_options`` advertises: the edit mode is the modes select's owner setting,
  535. the model ``set_session_model``'s pick, the effort the owner's ``reasoning`` mutation (``default``
  536. = ``/reasoning reset``), and the tier its session-scoped speed setting.
  537. Another id is accepted so editors do not fail on their own config writes,
  538. as main did. The reply is the full list, read back from the owner."""
  539. from acp.schema import SetSessionConfigOptionResponse
  540. from acp_adapter.gateway_session_meta import (
  541. REASONING_CONFIG_ID, SERVICE_TIER_CONFIG_ID, SERVICE_TIER_LABELS, current_mode, model_state,
  542. reasoning_choices, session_config_options,
  543. )
  544. from acp_adapter.modes import EDIT_APPROVAL_POLICY_CONFIG_ID, EDIT_APPROVAL_POLICY_TO_MODE
  545. editor_id, session_id = session_id, self._held_session(session_id)
  546. if config_id == EDIT_APPROVAL_POLICY_CONFIG_ID:
  547. if value not in EDIT_APPROVAL_POLICY_TO_MODE:
  548. raise GatewayClientError("invalid_params")
  549. await self._set_edit_policy(session_id, value)
  550. elif config_id == "model":
  551. if not isinstance(value, str):
  552. raise GatewayClientError("invalid_params")
  553. await self.set_session_model(model_id=value, session_id=editor_id)
  554. elif config_id == REASONING_CONFIG_ID:
  555. if value not in reasoning_choices():
  556. raise GatewayClientError("invalid_params")
  557. await self._idle_control(session_id, "reasoning", {"effort": None if value == "default" else value},
  558. "Reasoning effort")
  559. elif config_id == SERVICE_TIER_CONFIG_ID:
  560. if not isinstance(value, str) or value not in SERVICE_TIER_LABELS:
  561. raise GatewayClientError('invalid_params')
  562. self._unacked.pop(session_id, None)
  563. await (await self._client()).rpc('config.set', session_id=session_id, key='fast', value=value)
  564. info = await (await self._client()).rpc("session.info", session_id=session_id)
  565. models = await asyncio.to_thread(model_state, info)
  566. return SetSessionConfigOptionResponse(config_options=await session_config_options(
  567. self._gateway, session_id, models, info, self._modes.get(session_id) or current_mode(info)))
  568. async def _set_edit_policy(self, session_id, policy):
  569. """The owner's ``edit_policy`` mutation; every surface attached to the session reads the
  570. committed policy from ``session.info``."""
  571. from acp_adapter.modes import EDIT_APPROVAL_POLICY_TO_MODE
  572. await self._idle_control(session_id, "edit_policy", {"policy": policy}, "Mode")
  573. self._modes[session_id] = EDIT_APPROVAL_POLICY_TO_MODE[policy]
  574. async def _idle_control(self, session_id, operation, payload, label):
  575. """A revision-fenced owner mutation that applies to idle sessions only, like a model pick."""
  576. client = await self._client()
  577. self._unacked.pop(session_id, None)
  578. try:
  579. await self._mutations.apply(client, session_id, operation, payload)
  580. except GatewayClientError as exc:
  581. if str(exc) not in {"session_busy", "unknown_execution"}:
  582. raise
  583. # Named in the transcript (as a deferred model pick is) and the reply: a running turn ends on its
  584. # own, a lost one (unknown_execution) blocks every control until it is resolved or discarded.
  585. text = (f"{label} changes apply when the session is idle; try again after this turn."
  586. if str(exc) == "session_busy" else f"{label} changes wait for the lost turn: "
  587. + self._unknown_recovery(session_id, submitted=False).removeprefix("unknown_execution: "))
  588. if self._conn:
  589. await self._conn.session_update(session_id=self._editor_id(session_id),
  590. update=acp.update_agent_message_text(text + "\n"))
  591. raise acp.RequestError(-32603, text) from exc
  592. self._mutations.acknowledge(session_id, operation, payload)
  593. async def list_sessions(self, cursor=None, cwd=None, **kwargs):
  594. from acp.schema import ListSessionsResponse, SessionInfo
  595. from acp_adapter.catalog import catalog_sessions
  596. rows = await asyncio.to_thread(catalog_sessions, self._home / "state.db", cwd)
  597. if cursor:
  598. index = next((i for i, row in enumerate(rows) if row["session_id"] == cursor), None)
  599. rows = [] if index is None else rows[index + 1:]
  600. page = [SessionInfo(session_id=row["session_id"], cwd=row["cwd"], title=row.get("title"),
  601. updated_at=row.get("updated_at")) for row in rows[:50]]
  602. return ListSessionsResponse(sessions=page, next_cursor=page[-1].session_id if len(rows) > 50 else None)
  603. async def prompt(self, prompt, session_id, **kwargs):
  604. held_id, session_id = session_id, self._aliases.get(session_id, session_id)
  605. if session_id not in self._snapshots:
  606. raise GatewayClientError("not_found")
  607. if self._has_unknown(session_id) and await self._refresh_unknown_for_prompt(session_id):
  608. return PromptResponse(stop_reason='cancelled')
  609. if self._has_unknown(session_id):
  610. # Only a text-only /discard passes a lost turn, recognised BEFORE staging: a refused
  611. # prompt must not write its media or retire the editor's retained retry identity.
  612. from acp_adapter.content import _content_blocks_to_openai_user_content
  613. content = _content_blocks_to_openai_user_content(prompt)
  614. if not isinstance(content, str) or _slash_command(content) != 'discard':
  615. raise GatewayClientError(self._unknown_recovery(session_id, submitted=False))
  616. prepared = await self._prepare_submit(session_id, prompt)
  617. if prepared is None:
  618. return PromptResponse(stop_reason='cancelled')
  619. retry_key, input_id, staged = prepared
  620. text, attachments = staged
  621. answered, text = await self._run_slash(held_id, session_id, text) if not attachments else (False, text)
  622. if answered:
  623. return PromptResponse(stop_reason='end_turn')
  624. # ... and every prepared control's (a slash keeps its own key: apply retires the rest).
  625. self._mutations.retire(session_id)
  626. submit = {'text': text}
  627. if attachments:
  628. submit['attachments'] = attachments
  629. self._submitting.add(session_id)
  630. try:
  631. # Inside the try: a failed reconnect is as ambiguous for a retained identity as a lost ack.
  632. client = await self._client()
  633. link, resumes = self._link, self._resumes.get(session_id, 0)
  634. receipt = await client.rpc("prompt.submit", session_id=session_id, input_id=input_id, **submit)
  635. except BaseException as exc:
  636. from hermes_cli.gateway_client import GatewayRPCError
  637. if not isinstance(exc, GatewayRPCError):
  638. # Transport loss, timeout or cancel before the ack: the owner may hold this admission.
  639. # Keep its identity for the editor's retry of the same prompt (latest 64 sessions).
  640. self._unacked[session_id] = (retry_key, input_id, staged)
  641. while len(self._unacked) > 64:
  642. self._unacked.pop(next(iter(self._unacked)))
  643. self._pending_cancels.discard(session_id)
  644. raise
  645. finally:
  646. self._submitting.discard(session_id)
  647. admission_id = await self._admission_from_receipt(client, held_id, session_id, receipt)
  648. if admission_id is None:
  649. return PromptResponse(stop_reason='end_turn')
  650. self._inflight[(session_id, admission_id)] = None
  651. try:
  652. await self._after_ack(session_id, admission_id, link, resumes)
  653. if session_id in self._pending_cancels:
  654. self._pending_cancels.discard(session_id)
  655. await self._cancel_admission(session_id, admission_id)
  656. async with self._changed:
  657. await self._changed.wait_for(lambda: admission_id in self._terminals or self._failure is not None
  658. or self._link != link or admission_id in self._lost
  659. or self._blocked_admission(session_id, admission_id))
  660. # A successor's unknown state cannot replace our committed terminal result.
  661. if admission_id not in self._terminals:
  662. if self._link != link:
  663. # Our transport died before this turn's outcome reached us: ambiguous,
  664. # never retried on the replacement connection.
  665. raise self._lost_failure
  666. if self._failure:
  667. raise self._failure
  668. raise self._lost.pop(admission_id, None) or GatewayClientError(
  669. self._unknown_recovery(session_id, admission_id))
  670. terminal = self._terminals.pop(admission_id)
  671. finally:
  672. # Do not let one prompt tear down a newer mapping if the session has
  673. # already advanced while this coroutine unwinds.
  674. if self._admissions.get(session_id) == admission_id:
  675. self._admissions.pop(session_id, None)
  676. self._inflight.pop((session_id, admission_id), None)
  677. outcome = terminal.get("outcome")
  678. if outcome == "unknown":
  679. # Our own lost turn: the same refusal whether session.info or this completion woke us.
  680. raise GatewayClientError(self._unknown_recovery(session_id, admission_id))
  681. if outcome == "failed":
  682. raise GatewayClientError("admitted_turn_failed")
  683. from acp_adapter.gateway_session_meta import turn_usage
  684. # The turn's last ``session.usage`` precedes its ``message.complete`` on the stream.
  685. return PromptResponse(stop_reason="cancelled" if outcome == "cancelled" else "end_turn",
  686. usage=turn_usage(self._usage.get(session_id)))
  687. async def _admission_from_receipt(self, client, held_id, session_id, receipt):
  688. """The admission a ``prompt.submit`` receipt names, or None when the owner admitted nothing."""
  689. if receipt.get("voice_stopped") is True:
  690. # TUI-26: a bare stop phrase typed into this LOCAL session's voice chat ended the chat on
  691. # the owner and admitted nothing, so no turn will settle: the prompt ends here.
  692. self._pending_cancels.discard(session_id)
  693. if self._conn:
  694. from agent.i18n import t
  695. await self._conn.session_update(session_id=held_id, update=acp.update_agent_message_text(
  696. t('cli.voice.stop_phrase_typed') + '\n'))
  697. return None
  698. admission_id = receipt["admission_id"]
  699. self._admissions[session_id] = admission_id
  700. if receipt.get("status") == "terminal":
  701. # A retry of an un-acked submit whose turn already settled: report that turn once.
  702. await self._settled_receipt(client, held_id, session_id, receipt)
  703. elif receipt.get("status") == "unknown":
  704. # A retry of an un-acked submit the owner lost in a restart: never a second turn.
  705. self._admissions.pop(session_id, None)
  706. raise GatewayClientError(self._unknown_recovery(session_id, admission_id))
  707. return admission_id
  708. async def _run_slash(self, held_id, session_id, text):
  709. """Run a slash command's local half: ``(answered, text to submit)``; answered ends the prompt."""
  710. command = _slash_command(text)
  711. if command is None:
  712. return False, text
  713. from acp_adapter.gateway_commands import CommandRefused, run_command
  714. parts = text.strip().split(None, 1)
  715. try:
  716. reply, text = await run_command(self, session_id, command, parts[1].strip() if len(parts) > 1 else '')
  717. except CommandRefused as exc:
  718. # A named refusal is the command's answer, shown to the user; never a failed prompt.
  719. reply = str(exc)
  720. if reply is None:
  721. return False, text
  722. if self._conn:
  723. await self._conn.session_update(session_id=held_id, update=acp.update_agent_message_text(reply + '\n'))
  724. return True, None
  725. async def _prepare_submit(self, session_id, prompt):
  726. """``(retry_key, input_id, (text, attachments))`` for one ACP prompt, or None when the editor's Stop
  727. arrived while it was staged."""
  728. from acp_adapter.content import _content_blocks_to_openai_user_content
  729. from acp_adapter.gateway_media import stage_user_content, submit_fingerprint
  730. content = _content_blocks_to_openai_user_content(prompt)
  731. retry_key = submit_fingerprint(session_id, content)
  732. # Only this session's very next prompt may be the editor's retry of an un-acked submit; any
  733. # prompt (slash work included) retires the retained identity, so a later repeat is new work.
  734. retained = self._unacked.pop(session_id, None)
  735. if retained is not None and retained[0] == retry_key:
  736. # The retry resends what the owner may already hold: the staged content and input_id are
  737. # reused, never prepared (a remote image fetched) a second time.
  738. return retained
  739. # The editor's Stop during staging (a remote image download) is held like one during the
  740. # submit itself, and the prompt then ends without being sent.
  741. self._submitting.add(session_id)
  742. try:
  743. staged = await stage_user_content(content, self._home)
  744. finally:
  745. self._submitting.discard(session_id)
  746. if session_id in self._pending_cancels:
  747. self._pending_cancels.discard(session_id)
  748. return None
  749. return retry_key, uuid.uuid4().hex, staged
  750. async def _after_ack(self, session_id, admission_id, link, resumes):
  751. """A gap re-attach whose resume left after this submit covers it. The pump owns recovery: it
  752. recovers this admission against that snapshot behind the ones it already holds (FIFO, once)."""
  753. if self._resumes.get(session_id, 0) == resumes:
  754. return
  755. async with self._changed:
  756. await self._changed.wait_for(lambda: self._adopted.get(session_id, 0) > resumes
  757. or self._failure is not None or self._link != link)
  758. if self._adopted.get(session_id, 0) > resumes:
  759. # Held behind a full queue, never dropped: a full queue parks the reader, not the link.
  760. from hermes_cli.gateway_client import put_behind
  761. put_behind(self._gateway.events, (session_id, admission_id))
  762. async def _recover(self, session_id, admission_id):
  763. """Queued: it lost nothing. Running: cut until its live completion. Unknown: the waiter refuses it.
  764. Unlisted: it ended in the hole and its receipt settles it (unreadable: that prompt alone fails).
  765. Terminal evidence received, being delivered or already delivered always wins."""
  766. from hermes_cli.gateway_replay_gap import pending_status, settled
  767. status = pending_status(self._snapshots[session_id].get("pending"), admission_id)
  768. if status in ("queued", "unknown") or {admission_id} & (
  769. self._terminals.keys() | self._settling | self._receipted.keys()):
  770. return
  771. self._cut.setdefault(admission_id, self._streamed.pop(admission_id, ""))
  772. if status:
  773. return
  774. try:
  775. receipt = await self._gateway.rpc("prompt.receipt", session_id=session_id, admission_id=admission_id,
  776. include_result=True)
  777. except (GatewayClientError, OSError, TimeoutError):
  778. receipt = {"status": "terminal"} # unreadable
  779. verdict = settled(receipt)
  780. if verdict is not False: # its one recovery read: a later entry (a post-ack request) joins it
  781. self._receipted.setdefault(admission_id, None)
  782. if verdict:
  783. await self._settled_receipt(self._gateway, self._editor_id(session_id), session_id, receipt, receipt)
  784. elif verdict is None and admission_id not in self._terminals and admission_id not in self._settling:
  785. async with self._changed:
  786. self._lost[admission_id] = GatewayClientError("session_replay_gap")
  787. self._changed.notify_all()
  788. async def _settled_receipt(self, client, held_id, session_id, receipt, saved=None):
  789. """``saved``: the receipt already fetched with its result (a replay gap's recovery read)."""
  790. admission_id = receipt["admission_id"]
  791. saved = saved or await client.rpc("prompt.receipt", session_id=session_id, admission_id=admission_id,
  792. include_result=True)
  793. if admission_id in self._terminals or admission_id in self._settling:
  794. return # this connection's pump carried the completion itself
  795. self._settling.add(admission_id) # claimed before the first await; the pump yields to it
  796. self._receipted[admission_id] = None
  797. while len(self._receipted) > 256:
  798. self._receipted.pop(next(iter(self._receipted)))
  799. try:
  800. outcome = {"interrupted": "cancelled"}.get(receipt.get("outcome"), receipt.get("outcome"))
  801. result = saved.get("result") or {}
  802. await self._finish_reply(session_id, held_id, admission_id, {
  803. "text": result.get("final_response") or "", "outcome": outcome,
  804. "response_reused": result.get("response_reused"), "receipt": True})
  805. async with self._changed:
  806. self._terminals[admission_id] = {"outcome": outcome}
  807. self._changed.notify_all()
  808. finally:
  809. self._settling.discard(admission_id)
  810. def _unknown_recovery(self, session_id, admission_id=None, *, submitted=True):
  811. """The refusal for a FIFO blocked by a lost turn, naming the existing recovery control.
  812. The editor's own ``/discard <id>`` (``acp_adapter.gateway_commands._discard_unknown``, the
  813. same fenced ``prompt.resolve_unknown`` the classic chat uses) acknowledges the exact lost
  814. admission without replaying it, and the queue then continues."""
  815. from hermes_constants import profile_name_for_home
  816. lost = [row["admission_id"] for row in self._snapshots.get(session_id, {}).get("pending", [])
  817. if row.get("status") == "unknown"] or [admission_id]
  818. profile = profile_name_for_home(self._home)
  819. command = "hermes" + (f" -p {profile}" if profile not in (None, "default") else "")
  820. state = ("your input is accepted and kept" if submitted else "nothing was submitted")
  821. return (f"unknown_execution: do not resend accepted input; a turn in this session was lost when the "
  822. f"gateway restarted and its outcome is unknown ({state}). Send "
  823. + " and ".join(f"`/discard {lost_id}`" for lost_id in lost)
  824. + f" here (or `{command} sessions discard {session_id}` in a terminal), then continue.")
  825. def _has_unknown(self, session_id):
  826. return any(row.get("status") == "unknown"
  827. for row in self._snapshots[session_id].get("pending", []))
  828. async def _refresh_unknown_for_prompt(self, session_id):
  829. # Stop during the owner's read must cancel the still-unsent editor input.
  830. self._submitting.add(session_id)
  831. try:
  832. await self._refresh_unknown(session_id)
  833. except BaseException:
  834. self._pending_cancels.discard(session_id)
  835. raise
  836. finally:
  837. self._submitting.discard(session_id)
  838. cancelled = session_id in self._pending_cancels
  839. self._pending_cancels.discard(session_id)
  840. return cancelled
  841. async def _refresh_unknown(self, session_id):
  842. """Ask the owner whether another viewer has acknowledged a cached lost turn."""
  843. client = await self._client() # A reconnect may already supply a fresh snapshot.
  844. cached = self._snapshots.get(session_id)
  845. if cached is None:
  846. raise GatewayClientError("not_found")
  847. if not self._has_unknown(session_id):
  848. return
  849. # Freeze the snapshot's pending watermark before the pump can advance its reply cursor.
  850. cached.setdefault("_pending_watermark", (cached.get("replay_epoch"), cached.get("last_sequence", 0)))
  851. fresh = await client.rpc("session.resume", session_id=session_id)
  852. cached = self._snapshots.get(session_id)
  853. if cached is None:
  854. raise GatewayClientError("not_found")
  855. # Only pending state received while the RPC was in flight can supersede its snapshot.
  856. epoch, sequence = cached.get("_pending_watermark",
  857. (cached.get("replay_epoch"), cached.get("last_sequence", 0)))
  858. if "pending" in fresh and (
  859. fresh.get("replay_epoch") != epoch or fresh.get("last_sequence", 0) >= sequence
  860. ):
  861. cached["pending"] = fresh["pending"]
  862. # The snapshot supplies only pending state here. Do not consume earlier message,
  863. # approval, or tool events that the editor's event pump has not projected yet.
  864. cached["_pending_watermark"] = (fresh.get("replay_epoch"), fresh.get("last_sequence", 0))
  865. def _pending_event_is_new(self, session_id, event):
  866. """Keep a pre-refresh pending event from restoring an already-discarded lost turn."""
  867. fence = self._snapshots.get(session_id, {}).get("_pending_watermark")
  868. sequence = event.get("seq")
  869. return (fence is None or sequence is None or event.get("replay_epoch") != fence[0]
  870. or sequence > fence[1])
  871. def _blocked_admission(self, session_id, admission_id):
  872. return self._has_unknown(session_id) and any(
  873. row.get("admission_id") == admission_id and row.get("status") in {"queued", "unknown"}
  874. for row in self._snapshots[session_id].get("pending", []))
  875. async def _events(self):
  876. gateway = self._gateway
  877. try:
  878. while True:
  879. frame = await gateway.events.get()
  880. if isinstance(frame, Exception):
  881. raise frame
  882. if isinstance(frame, tuple): # a post-ack recovery (``_after_ack``), behind every frame so far
  883. await self._recover(*frame)
  884. continue
  885. event = frame.get("params", {})
  886. sid = event.get("session_id")
  887. snapshot = self._snapshots.get(sid)
  888. if snapshot is None:
  889. continue
  890. epoch, seq = event.get("replay_epoch"), event.get("seq", 0)
  891. if epoch == snapshot.get("replay_epoch") and seq <= snapshot.get("last_sequence", 0):
  892. continue
  893. snapshot.update(replay_epoch=epoch, last_sequence=seq,
  894. execution_generation=event.get("execution_generation", snapshot.get("execution_generation")))
  895. await self._project(event)
  896. except asyncio.CancelledError:
  897. raise
  898. except Exception as exc:
  899. # Boundary: ANY projection failure must reach every waiter (prompt/load re-raise
  900. # ``_failure``), or they block forever on ``_changed``.
  901. logger.debug("ACP gateway event projection stopped", exc_info=True)
  902. async with self._changed:
  903. self._failure = exc
  904. self._changed.notify_all()
  905. async def _project(self, event):
  906. kind, payload = event.get("type"), event.get("payload", {})
  907. sid, editor_id = event["session_id"], self._editor_id(event["session_id"])
  908. aid = event.get("admission_id")
  909. if kind in {"session.info", "session.updated", "session.usage", "session.tools_changed"}:
  910. await self._project_session_state(kind, sid, editor_id, payload, event)
  911. return
  912. if await self._gap_guard(kind, sid, aid):
  913. return
  914. if kind in {"approval.request", "clarify.request"}:
  915. self._permission(sid, payload)
  916. return
  917. if kind in {"approval.settled", "clarify.settled"}:
  918. task = self._permissions.pop((sid, payload["prompt_id"], payload["execution_generation"]), None)
  919. if task:
  920. task.cancel()
  921. return
  922. if kind in {"reasoning.delta", "todo.updated"}:
  923. await self._project_side_update(kind, sid, editor_id, payload)
  924. return
  925. if kind in {"tool.start", "tool.complete"}:
  926. await self._project_tool(kind, sid, editor_id, aid, payload)
  927. return
  928. if kind == "message.delta":
  929. text = _text(payload)
  930. self._streamed[aid] = self._streamed.get(aid, "") + text
  931. if text and self._conn:
  932. await self._conn.session_update(session_id=editor_id, update=self._chunk(sid, text))
  933. elif kind == "message.interim":
  934. # Commentary the owner could not stream (``already_streamed`` false) reaches viewers
  935. # only here; streamed commentary is already on screen. Either way it is its own segment.
  936. self._close_segment(aid)
  937. text = _text(payload)
  938. self._end_message(sid)
  939. if not payload.get("already_streamed") and text.strip():
  940. self._segments.setdefault(aid, []).append(text)
  941. if self._conn:
  942. await self._conn.session_update(session_id=editor_id, update=self._chunk(sid, text + "\n\n"))
  943. self._end_message(sid)
  944. elif kind == "message.complete":
  945. if aid in self._settling or aid in self._receipted:
  946. # A retry's terminal receipt claimed this reply; it is shown once, from there.
  947. self._streamed.pop(aid, None)
  948. self._segments.pop(aid, None)
  949. return
  950. self._settling.add(aid)
  951. try:
  952. await self._finish_reply(sid, editor_id, aid, payload)
  953. async with self._changed:
  954. self._terminals[aid] = payload
  955. if len(self._terminals) > 256:
  956. self._terminals.pop(next(iter(self._terminals)))
  957. self._changed.notify_all()
  958. finally:
  959. self._settling.discard(aid)
  960. async def _gap_guard(self, kind, sid, aid):
  961. """What a replay gap changes in the projection; True when the frame is consumed here."""
  962. if kind == "session.replay_gap":
  963. # Re-attach that session alone (a refusal still fails the pump: the next call redials).
  964. params = {"editor": self._editor_mcp[sid]} if sid in self._editor_mcp else {}
  965. self._resumes[sid] = self._resumes.get(sid, 0) + 1
  966. snapshot = await self._gateway.rpc("session.resume", session_id=sid, **params)
  967. await self._adopt(sid, snapshot, self._resumes[sid])
  968. for prompt in snapshot.get("prompts", []):
  969. self._permission(sid, prompt)
  970. started = [row["admission_id"] for row in snapshot.get("pending", []) if row.get("status") == "started"]
  971. for admission_id in dict.fromkeys([*started, *(a for held, a in self._inflight if held == sid)]):
  972. await self._recover(sid, admission_id)
  973. return True
  974. if aid not in self._cut:
  975. return False
  976. if kind in {"tool.start", "message.interim"}: # a new segment: what was shown before it is closed
  977. if self._cut[aid].strip():
  978. self._segments.setdefault(aid, []).append(self._cut[aid])
  979. self._cut[aid] = ""
  980. self._end_message(sid)
  981. # Live deltas stopped at the gap; an interim is whole (it may be the only copy of the reply).
  982. return kind == "message.delta"
  983. async def _project_session_state(self, kind, sid, editor_id, payload, event):
  984. if kind == "session.usage":
  985. await self._project_usage(sid, editor_id, payload)
  986. return
  987. if kind == "session.tools_changed":
  988. if self._conn:
  989. await self._conn.session_update(session_id=editor_id, update=acp.update_agent_message_text(
  990. _tools_changed_notice(payload)))
  991. return
  992. if kind == "session.updated" and payload.get("operation") == "model" and payload.get("status") == "refused":
  993. # A deferred pick that no longer resolved at the turn boundary: dropped, named here.
  994. if self._conn:
  995. from acp_adapter.gateway_commands import refused_pick_text
  996. await self._conn.session_update(session_id=editor_id, update=acp.update_agent_message_text(
  997. refused_pick_text(payload) + "\n"))
  998. return
  999. if (kind == "session.updated" and payload.get("operation") == "model"
  1000. and payload.get("status") == "confirmation_required" and isinstance(payload.get("confirm"), str)):
  1001. # A deferred pick whose target needs consent at the turn boundary: asked like an idle
  1002. # pick (off the event pump: the answer may take as long as the user does).
  1003. task = asyncio.create_task(self._confirm_deferred_pick(sid, editor_id, payload))
  1004. self._background.add(task)
  1005. task.add_done_callback(self._background.discard)
  1006. return
  1007. if kind == "session.info" and sid in self._snapshots and "pending" in payload:
  1008. async with self._changed:
  1009. if self._pending_event_is_new(sid, event):
  1010. self._snapshots[sid]["pending"] = payload["pending"]
  1011. self._snapshots[sid]["_pending_watermark"] = (event.get("replay_epoch"), event.get("seq", 0))
  1012. self._changed.notify_all()
  1013. await self._project_title(sid, editor_id, payload.get("title"))
  1014. await self._project_mode(sid, editor_id, payload)
  1015. async def _project_mode(self, sid, editor_id, payload, client=None):
  1016. """Another surface's ``edit_policy`` change (its ``session.info``) as ``current_mode_update``."""
  1017. from acp_adapter.modes import EDIT_APPROVAL_POLICY_TO_MODE
  1018. mode = EDIT_APPROVAL_POLICY_TO_MODE.get(payload.get("edit_approval_policy"))
  1019. # A session's first (its attach's snapshot) seeds silently: the attach's reply shows it.
  1020. if mode is not None and self._modes.setdefault(sid, mode) != mode:
  1021. self._modes[sid] = mode
  1022. if self._conn:
  1023. from acp.schema import CurrentModeUpdate # ``acp`` does not re-export ``update_current_mode``
  1024. await self._conn.session_update(session_id=editor_id, update=CurrentModeUpdate(
  1025. session_update="current_mode_update", current_mode_id=mode))
  1026. await self._project_config(sid, editor_id, payload, client=client)
  1027. async def _project_config(self, sid, editor_id, payload, client=None):
  1028. """Zed draws its pickers only from ``configOptions`` once an agent sends them (it then ignores
  1029. ``current_mode_update``), so a mode, model, effort or tier change from another surface resends
  1030. the full list. A partial ``session.info`` keeps what it omits."""
  1031. from acp_adapter.gateway_session_meta import current_mode, model_state, session_config_options
  1032. fields = ("model", "provider", "reasoning_effort")
  1033. if not any(key in payload for key in (*fields, "edit_approval_policy", "service_tier")):
  1034. return
  1035. seen = self._configs.get(sid)
  1036. shown = {**(seen or {}), **{key: payload[key] for key in fields if key in payload},
  1037. "mode": self._modes.get(sid) or current_mode(payload)}
  1038. if seen == shown and "service_tier" not in payload:
  1039. return # an equal observation must not take over from a build still running for it
  1040. self._configs[sid] = shown
  1041. # Seeded silently like the mode: the attach's reply carries the options.
  1042. if seen is None or not self._conn:
  1043. return
  1044. from acp.schema import ConfigOptionUpdate
  1045. models = await asyncio.to_thread(model_state, shown)
  1046. options = await session_config_options(client or self._gateway, sid, models, shown, shown["mode"])
  1047. if self._configs.get(sid) is not shown:
  1048. return # a newer projection (an event or ``_adopt``) replaced it during the build and sends its own
  1049. await self._conn.session_update(session_id=editor_id, update=ConfigOptionUpdate(
  1050. session_update="config_option_update", config_options=options))
  1051. async def _project_usage(self, sid, editor_id, stats):
  1052. """The owner's usage dict: kept for the turn's ``PromptResponse.usage``, shown as ``usage_update``."""
  1053. from acp_adapter.gateway_session_meta import usage_update
  1054. self._usage[sid] = stats
  1055. if self._conn and (update := usage_update(stats)) is not None:
  1056. await self._conn.session_update(session_id=editor_id, update=update)
  1057. async def _project_title(self, sid, editor_id, title):
  1058. """A new title (auto-title's ``session.info``, a rename's ``session.updated``) as main's
  1059. ``session_info_update``; the owner republishes an unchanged one after every turn."""
  1060. if not isinstance(title, str) or not title.strip() or title == self._titles.get(sid):
  1061. return
  1062. self._titles[sid] = title
  1063. if self._conn:
  1064. from acp_adapter.gateway_session_meta import title_update
  1065. await self._conn.session_update(session_id=editor_id, update=title_update(title))
  1066. def _permission(self, session_id, prompt):
  1067. answer = {"approval": self._answer_permission, "clarify": self._answer_clarify}.get(prompt.get("kind"))
  1068. if answer is None or self._conn is None:
  1069. return
  1070. key = (session_id, prompt["prompt_id"], prompt["execution_generation"])
  1071. if key not in self._permissions:
  1072. task = asyncio.create_task(answer(session_id, prompt))
  1073. self._permissions[key] = task
  1074. task.add_done_callback(lambda done: self._retire_unanswered(key, done))
  1075. def _retire_unanswered(self, key, task):
  1076. """A card whose response the owner did not accept (editor cancel, transport loss, lost
  1077. respond RPC) gives up its key, so the next snapshot that still lists the prompt (reattach,
  1078. ``session/load``) shows a NEW card. An earlier answer is never replayed. An accepted one
  1079. keeps its key until ``*.settled``, so a replayed request raises no second card."""
  1080. if self._permissions.get(key) is task and (task.cancelled() or task.exception() is not None
  1081. or task.result() is not True):
  1082. del self._permissions[key]
  1083. async def _answer_clarify(self, session_id, prompt):
  1084. from acp.schema import AllowedOutcome
  1085. from acp_adapter.elicitation import (
  1086. ELICITATION_METHOD, SKIP_OPTION, build_clarify_elicitation, build_clarify_permission,
  1087. elicited_answer,
  1088. )
  1089. editor_id = self._editor_id(session_id)
  1090. try:
  1091. if self._form_elicitation:
  1092. answer = elicited_answer(await self._conn._conn.send_request(
  1093. ELICITATION_METHOD, build_clarify_elicitation(editor_id, prompt)))
  1094. else:
  1095. tool_call, options, answers = build_clarify_permission(prompt)
  1096. response = await self._conn.request_permission(
  1097. session_id=editor_id, tool_call=tool_call, options=options)
  1098. await self._close_card(editor_id, tool_call, options, response)
  1099. # A dismissed card (also what ACP answers for the editor's own Stop) is the Skip a
  1100. # form decline sends; only an unknown option id is no answer.
  1101. answer = (answers.get(response.outcome.option_id)
  1102. if isinstance(response.outcome, AllowedOutcome) else answers[SKIP_OPTION])
  1103. # No answer (editor transport loss) leaves the canonical waiter to other viewers.
  1104. if answer is None:
  1105. return False
  1106. await self._gateway.rpc("clarify.respond", session_id=session_id, prompt_id=prompt["prompt_id"],
  1107. execution_generation=prompt["execution_generation"], answer=answer)
  1108. return True
  1109. except Exception:
  1110. # Boundary: as for approvals, a detached editor or expired prompt is not an answer.
  1111. logger.info("ACP clarify viewer detached or control expired", exc_info=True)
  1112. return False
  1113. async def _answer_permission(self, session_id, prompt):
  1114. from acp.schema import AllowedOutcome
  1115. from acp_adapter.permissions import (
  1116. _build_permission_options, _build_permission_tool_call, _OPTION_ID_TO_HERMES,
  1117. )
  1118. choices = prompt["choices"]
  1119. options = [option for option in _build_permission_options(
  1120. allow_permanent="always" in choices, allow_session="session" in choices)
  1121. if _OPTION_ID_TO_HERMES[option.option_id] in choices]
  1122. try:
  1123. if 'edit' in prompt:
  1124. from acp_adapter.edit_approval import EditProposal, build_acp_edit_tool_call
  1125. tool_call = build_acp_edit_tool_call(EditProposal(**prompt['edit']))
  1126. else:
  1127. tool_call = _build_permission_tool_call(prompt.get('command', ''), prompt.get('description', ''))
  1128. response = await self._conn.request_permission(session_id=self._editor_id(session_id),
  1129. tool_call=tool_call, options=options)
  1130. await self._close_card(self._editor_id(session_id), tool_call, options, response)
  1131. # Transport loss/cancel is not a denial: the canonical waiter belongs
  1132. # to the execution and may still be answered by another viewer.
  1133. if not isinstance(response.outcome, AllowedOutcome):
  1134. return False
  1135. if response.outcome.option_id not in {option.option_id for option in options}:
  1136. return False
  1137. await self._gateway.rpc("approval.respond", session_id=session_id,
  1138. prompt_id=prompt["prompt_id"], execution_generation=prompt["execution_generation"],
  1139. choice=_OPTION_ID_TO_HERMES[response.outcome.option_id])
  1140. return True
  1141. except Exception:
  1142. # Boundary: a detached viewer or expired control is not a denial; the canonical
  1143. # waiter stays answerable by another viewer, so nothing propagates.
  1144. logger.info("ACP permission viewer detached or control expired", exc_info=True)
  1145. return False
  1146. async def aclose(self):
  1147. # Post-attach notices first: one paused mid-notice would otherwise resume after the
  1148. # teardown and open a fresh gateway connection through ``_client``.
  1149. background = list(self._background)
  1150. for task in background:
  1151. task.cancel()
  1152. if background:
  1153. await asyncio.gather(*background, return_exceptions=True)
  1154. for task in self._permissions.values():
  1155. task.cancel()
  1156. if self._permissions:
  1157. await asyncio.gather(*self._permissions.values(), return_exceptions=True)
  1158. self._permissions.clear()
  1159. await self._teardown()