| 12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238 |
- """ACP projection of the profile gateway; never constructs an execution owner."""
- from __future__ import annotations
- import asyncio
- from contextlib import suppress
- import logging
- import os
- import uuid
- import acp
- from acp.schema import (
- AgentCapabilities, Implementation, InitializeResponse, LoadSessionResponse,
- NewSessionResponse, PromptCapabilities, PromptResponse, ResumeSessionResponse,
- SessionCapabilities, SessionForkCapabilities, SessionListCapabilities, SessionResumeCapabilities,
- )
- from hermes_cli.gateway_client import GatewayClientError, connect_gateway
- from hermes_constants import get_hermes_home
- from acp_adapter.gateway_reply import GatewayReplyMixin, _text
- from acp_adapter.session import _translate_acp_cwd, _normalize_cwd_for_compare
- logger = logging.getLogger(__name__)
- def _slash_command(text):
- """Canonical Hermes command name ``text`` invokes, or None for ordinary text.
- Only a registered command (or alias) is a command: ``/etc/hosts is wrong`` or ``/tmp/x``
- (a path, the same rule ``MessageEvent.get_command`` applies) and unknown ``/words`` are
- prompt text for the model. A registered command is never sent as prompt text: it is answered
- by a gateway verb or refused by name (``acp_adapter/gateway_commands.py``)."""
- stripped = text.lstrip()
- if not stripped.startswith('/'):
- return None
- name = stripped.split(None, 1)[0][1:]
- if not name or '/' in name:
- return None
- from hermes_cli.commands import resolve_command
- command = resolve_command(name)
- if command is not None:
- return command.name
- from acp_adapter.gateway_commands import ROUTES
- return name if name in ROUTES else None
- def _bypass_route():
- """--safe-mode / --ignore-user-config read no profile default route, so the session freezes the
- launch's explicit one (``hermes -m <model> --provider <name> --safe-mode acp``). Both, refused at
- session/new: a model alone is accepted by the owner, then its first turn cannot build the agent."""
- model = (os.environ.get("HERMES_MODEL") or os.environ.get("HERMES_INFERENCE_MODEL") or "").strip()
- if not model:
- raise GatewayClientError("--safe-mode / --ignore-user-config read no profile default model: launch "
- "with one, e.g. hermes -m <model> --provider <provider> --safe-mode acp")
- provider = os.environ.get("HERMES_INFERENCE_PROVIDER", "").strip()
- if not provider:
- raise GatewayClientError("--safe-mode / --ignore-user-config read no profile provider: launch with "
- "--provider too, e.g. hermes -m <model> --provider <provider> --safe-mode acp")
- return {"model": model, "provider": provider}
- def _tools_changed_notice(payload):
- """The owner re-froze this session's editor MCP tools (a changed config or changed schemas)."""
- servers = ", ".join(payload.get("mcp_servers") or []) or "none"
- return f"Editor MCP tools changed (servers: {servers}); the new tool list applies from the next turn.\n"
- class GatewayACPAgent(GatewayReplyMixin, acp.Agent):
- def __init__(self):
- self._conn = None
- self._gateway = None
- self._connection = None
- self._connect_lock = asyncio.Lock()
- # A per-task overlay HERMES_HOME attaches to the profile its symlinked lock names (#138949).
- from hermes_cli.gateway_runtime import gateway_profile_home
- self._home = gateway_profile_home(get_hermes_home())
- self._snapshots = {}
- self._event_task = None
- self._terminals = {}
- self._streamed = {}
- # Admission -> closed reply segments already shown (interim commentary, pre-tool deltas).
- self._segments = {}
- self._changed = asyncio.Condition()
- self._failure = None
- # Connection generation: a waiter whose transport was replaced reports that transport's
- # ambiguous failure (``_lost_failure``) instead of waiting on a connection it never used.
- self._link = 0
- self._lost_failure = None
- # Session -> editor MCP servers a replacement connection must re-attach.
- self._editor_mcp = {}
- self._permissions = {}
- self._admissions = {}
- self._submitting = set()
- # Session -> (content fingerprint, input_id, staged (text, attachments)) of a submit whose ack
- # never arrived. The editor's retry (that session's next prompt, same content) reuses it, so the authority
- # returns the same admission.
- self._unacked = {}
- # Admissions whose terminal reply one path (the pump's message.complete or a retry's
- # terminal receipt) is delivering right now; the other path yields to the claim.
- self._settling = set()
- # Admissions a terminal receipt already delivered: their late message.complete adds nothing.
- self._receipted = {}
- # ``gateway_replay_gap``: admission -> the reply segment shown when a gap cut it; own prompts awaiting
- # their terminal, in admission order; those whose reply the hole lost for good; per session, the gap
- # re-attaches sent and adopted (a snapshot covers the submits sent before its resume).
- self._cut, self._inflight, self._lost, self._resumes, self._adopted = {}, {}, {}, {}, {}
- self._pending_cancels = set()
- # (session, tool_call_id) -> (tool name, args, admission) of a call still open on the editor.
- self._tool_args = {}
- # Session -> AssistantMessageIdAllocator: the ``messageId`` of the assistant message being streamed.
- self._message_ids = {}
- # Editor-held compression-tip id -> logical session id (see ``_resume``).
- self._aliases = {}
- self._form_elicitation = False
- from hermes_cli.gateway_mutations import PreparedMutations
- self._mutations = PreparedMutations()
- # Session -> title the editor was last shown (``session_info_update`` fires on a change).
- self._titles = {}
- # Session -> the mode (edit approval policy) the editor was last shown (``current_mode_update``).
- self._modes = {}
- # Session -> the settings the editor's ``configOptions`` last showed (``config_option_update``).
- self._configs = {}
- # Session -> the owner's latest usage dict (``session.usage`` / ``session.stats``).
- self._usage = {}
- self._background = set()
- def on_connect(self, conn):
- self._conn = conn
- add_observer = getattr(getattr(conn, "_conn", None), "add_observer", None)
- if callable(add_observer):
- add_observer(self._observe_client_message)
- def _observe_client_message(self, event):
- """``initialize``'s raw capabilities (the SDK's typed model drops ``elicitation``)."""
- message = getattr(event, "message", None)
- if getattr(event, "direction", None) == "incoming" and isinstance(message, dict) \
- and message.get("method") == "initialize":
- from acp_adapter.elicitation import client_supports_form_elicitation
- self._form_elicitation = client_supports_form_elicitation(message.get("params"))
- async def initialize(self, **kwargs):
- from hermes_cli import __version__
- from acp_adapter.auth import build_auth_methods
- return InitializeResponse(protocol_version=acp.PROTOCOL_VERSION,
- agent_info=Implementation(name="hermes-agent", version=__version__),
- agent_capabilities=AgentCapabilities(load_session=True,
- prompt_capabilities=PromptCapabilities(image=True),
- session_capabilities=SessionCapabilities(fork=SessionForkCapabilities(), list=SessionListCapabilities(),
- resume=SessionResumeCapabilities())),
- auth_methods=build_auth_methods())
- async def authenticate(self, method_id, **kwargs):
- from acp_adapter.server import HermesACPAgent
- return await HermesACPAgent.authenticate(self, method_id, **kwargs)
- async def _client(self):
- async with self._connect_lock:
- if self._failure is not None or self._transport_closed():
- # The event pump died with this transport (gateway restart, socket loss, replay gap).
- # Its waiters hold the ambiguous failure; the next call gets a fresh, re-verified
- # connection instead of the stale error forever.
- await self._teardown()
- if self._gateway is None:
- connection = connect_gateway()
- gateway = await connection.__aenter__()
- try:
- descriptor = await gateway.rpc("runtime.describe")
- if descriptor.get("profile_id") != str(self._home):
- raise GatewayClientError("profile_mismatch")
- await self._reattach(gateway)
- except BaseException:
- await connection.__aexit__(None, None, None)
- raise
- self._connection, self._gateway = connection, gateway
- self._event_task = asyncio.create_task(self._events())
- if self._failure:
- raise self._failure
- return self._gateway
- async def _reattach(self, gateway):
- """Subscribe a replacement connection to every session this editor holds.
- The fresh snapshot carries the new replay epoch/sequence and the authority's current
- pending rows (a turn lost in the restart is ``unknown`` there, never resubmitted); the
- editor's borrowed MCP servers are re-attached because a restarted owner has none."""
- from hermes_cli.gateway_client import GatewayRPCError
- for session_id in list(self._snapshots):
- params = {"editor": self._editor_mcp[session_id]} if session_id in self._editor_mcp else {}
- try:
- snapshot = await gateway.rpc("session.resume", session_id=session_id, **params)
- except GatewayRPCError:
- # A definitive refusal for this session (deleted, retired) must not keep the
- # editor's other sessions offline; its next prompt reports not_found.
- logger.info("ACP session %s not re-attached after reconnect", session_id, exc_info=True)
- self._snapshots.pop(session_id, None)
- continue
- await self._adopt(session_id, snapshot, client=gateway)
- # Before this session's cards are offered again: until ``_client`` returns, ``self._gateway`` is
- # not this connection, so a card answered while the request is out would lose its answer.
- await self._request_live_reasoning(gateway, session_id)
- for pending in snapshot.get("prompts", []):
- self._permission(session_id, pending)
- await self._notify_unknown(session_id)
- async def _adopt(self, session_id, snapshot, resumes=None, client=None):
- """Install a fresh ``session.resume`` snapshot as a session's projection: every install (create, load,
- fork, a control's refresh, reconnect, replay gap) goes through here.
- Events before its watermark are skipped from here on, so the session state they would have carried
- is projected from the snapshot itself: the editor is never left showing Default while the owner
- enforces Accept Edits / Don't Ask (#141338 ACP-7)."""
- async with self._changed: # its pending rows and controls may settle or block a waiter
- self._snapshots[session_id] = snapshot
- if resumes is not None:
- self._adopted[session_id] = resumes
- self._changed.notify_all()
- await self._project_mode(session_id, self._editor_id(session_id), snapshot.get("info") or {}, client=client)
- async def _request_live_reasoning(self, client, session_id):
- """Ask the owner to stream this session's reasoning (``show_reasoning``), as the CLI does.
- The in-process server gave every editor turn a reasoning sink (``acp_adapter/server.py``). The
- owner publishes ``reasoning.delta`` only for a live session whose flag a viewer set, and a restarted
- owner's sessions start without it, so every attach and re-attach asks (#134889 ACP-4). The flag is
- the session's: a viewer that hides reasoning later turns it off until the editor attaches again."""
- try:
- await client.rpc("config.set", session_id=session_id, key="show_reasoning", value="1", _timeout=10)
- except Exception:
- # Boundary: a display flag must not fail the attach (a refusal, a lost connection, or no answer
- # within the CLI's 10 s). At worst the session runs without live reasoning; a reconnect's
- # re-attach asks again.
- logger.debug("ACP session %s keeps its reasoning hidden", session_id, exc_info=True)
- async def _notify_unknown(self, session_id):
- """The classic chat's resume notice: say why the next prompt will be refused and how to recover."""
- if self._has_unknown(session_id) and self._conn:
- await self._conn.session_update(session_id=self._editor_id(session_id), update=acp.update_agent_message_text(
- self._unknown_recovery(session_id, submitted=False).removeprefix("unknown_execution: ") + "\n"))
- def _transport_closed(self):
- # The socket reader settles every pending RPC before the pump sees its disconnect frame,
- # so an editor retry can arrive while ``_failure`` is still unset.
- reader = getattr(self._gateway, "reader", None)
- return isinstance(reader, asyncio.Future) and reader.done()
- async def _teardown(self):
- task, connection = self._event_task, self._connection
- self._event_task = self._connection = self._gateway = None
- if task is not None:
- task.cancel()
- with suppress(asyncio.CancelledError):
- await task
- if connection is not None:
- await connection.__aexit__(None, None, None)
- # Partial reply segments belonged to admissions whose waiters already failed. A reply cut off here
- # never gets its ``message.complete`` (re-attach starts at the owner's current sequence), so its
- # ``messageId`` closes too: the next reply must not reuse it.
- self._streamed.clear()
- self._segments.clear()
- self._message_ids.clear()
- self._cut.clear()
- async with self._changed:
- # Every waiter on the old transport wakes to its ambiguous failure, even one that had
- # not yet observed ``_failure`` before it is cleared here.
- self._link += 1
- self._lost_failure = self._failure or GatewayClientError(
- "Gateway disconnected; turn outcome is unknown. Resume the session to check whether "
- "it completed or was interrupted; do not resend the work.")
- self._failure = None
- self._changed.notify_all()
- async def new_session(self, cwd, mcp_servers=None, **kwargs):
- client = await self._client()
- descriptor = await client.rpc("runtime.describe")
- if ("acp" not in descriptor.get("session_create", {}).get("sources", [])
- or "acp-editor-policy-v1" not in descriptor.get("capabilities", [])):
- raise GatewayClientError("acp_policy_unavailable")
- from hermes_cli.gateway_chat import env_launch_flags
- # `hermes acp --yolo` / `--safe-mode` / ... reach this process as their env equivalents; the
- # owner does not inherit them, so they freeze into this session's policy or not at all.
- flags = env_launch_flags()
- if flags.get("safe_mode") or flags.get("ignore_user_config"):
- flags.update(_bypass_route())
- snapshot = await client.rpc("session.create", request_id=uuid.uuid4().hex,
- source="acp", cwd=_translate_acp_cwd(cwd),
- editor={"mcp_servers": [s.model_dump(by_alias=True) for s in mcp_servers or []],
- "edit_approval_policy": "ask"}, **flags)
- session_id = snapshot["session_id"]
- await self._adopt(session_id, snapshot)
- if mcp_servers:
- self._editor_mcp[session_id] = {
- "mcp_servers": [s.model_dump(by_alias=True) for s in mcp_servers]}
- info = snapshot.get("info") or await client.rpc("session.info", session_id=session_id)
- await self._request_live_reasoning(client, session_id)
- return NewSessionResponse(session_id=session_id, **await self._session_fields(session_id, info, session_id))
- def _editor_id(self, session_id):
- return next((held for held, sid in self._aliases.items() if sid == session_id), session_id)
- async def _session_fields(self, session_id, info, editor_id):
- """Main's new/load/resume/fork reply fields (model picker, modes, provenance ``_meta``); the
- command list and context indicator follow once the reply is queued, as main scheduled them."""
- from acp_adapter.gateway_session_meta import model_state, provenance_meta, session_config_options, session_modes
- from acp_adapter.modes import EDIT_APPROVAL_POLICY_CONFIG_ID, MODE_TO_EDIT_APPROVAL_POLICY
- title = info.get("title")
- if isinstance(title, str) and title.strip():
- self._titles[session_id] = title
- models = await asyncio.to_thread(model_state, info)
- meta = await asyncio.to_thread(provenance_meta, self._home / "state.db", editor_id, session_id)
- mode = self._modes.setdefault(session_id, session_modes(info).current_mode_id)
- options = await session_config_options(self._gateway, session_id, models, info, mode)
- # ``_adopt`` seeded the mode from the snapshot: a change the pump projected since is what the reply shows.
- policy = MODE_TO_EDIT_APPROVAL_POLICY[self._modes[session_id]]
- modes = session_modes({"edit_approval_policy": policy})
- for option in options:
- if option.id == EDIT_APPROVAL_POLICY_CONFIG_ID:
- option.current_value = policy
- if self._conn:
- task = asyncio.get_running_loop().create_task(self._after_attach(session_id, editor_id))
- self._background.add(task)
- task.add_done_callback(self._background.discard)
- return {"models": models, "modes": modes, "field_meta": meta,
- "config_options": options}
- async def _after_attach(self, session_id, editor_id):
- from acp_adapter.gateway_session_meta import available_commands_update
- await asyncio.sleep(0) # after the session reply: the editor routes updates by a known id
- try:
- await self._conn.session_update(session_id=editor_id, update=available_commands_update())
- await self._project_usage(session_id, editor_id,
- await (await self._client()).rpc("session.stats", session_id=session_id))
- except Exception:
- # Boundary: a detached editor or a refused read is not the attach's failure.
- logger.debug("ACP post-attach notices for %s not delivered", session_id, exc_info=True)
- async def _attach_info(self, client, session_id):
- """``session.info`` for a session to attach. A thread main's in-process server wrote has no
- gateway policy yet; ``session.resume`` is the verb that adopts it (``LEGACY_LOCAL_SOURCES``)."""
- from hermes_cli.gateway_client import GatewayRPCError
- try:
- return await client.rpc("session.info", session_id=session_id)
- except GatewayRPCError as exc:
- if str(exc) != "not_found":
- raise
- adopted = await client.rpc("session.resume", session_id=session_id)
- await client.rpc("session.detach", session_id=session_id, subscription_id=adopted["subscription_id"])
- return await client.rpc("session.info", session_id=session_id)
- async def _resume(self, cwd, held_id, mcp_servers):
- client = await self._client()
- from acp_adapter.catalog import logical_session_id
- from hermes_cli.gateway_client import GatewayRPCError
- session_id = await asyncio.to_thread(logical_session_id, self._home / "state.db", held_id)
- # The latest load names the id this editor addresses the conversation by.
- self._aliases = {held: sid for held, sid in self._aliases.items() if sid != session_id}
- if session_id != held_id:
- self._aliases[held_id] = session_id
- info = await self._attach_info(client, session_id)
- if self._moved(info, cwd):
- info = await self._move_workspace(client, session_id, cwd)
- if "cwd" not in info and self._conn:
- await self._conn.session_update(session_id=held_id, update=acp.update_agent_message_text(
- "Attached to the gateway's existing session policy; editor cwd is not applied.\n"))
- resume_params = {}
- if mcp_servers:
- # A non-empty list is the editor's selection. An empty one (load always carries a list)
- # keeps the session's servers, as fork does: a second editor without MCP config must not
- # strip the first one's tools. An owner without editor MCP bound none.
- descriptor = await client.rpc("runtime.describe")
- if "acp-session-mcp-v1" not in descriptor.get("capabilities", []):
- raise GatewayClientError("acp_mcp_policy_unavailable")
- resume_params['editor'] = {'mcp_servers': [s.model_dump(by_alias=True) for s in mcp_servers]}
- try:
- snapshot = await client.rpc("session.resume", session_id=session_id, **resume_params)
- except GatewayRPCError as exc:
- if str(exc) != "acp_mcp_policy_conflict":
- raise
- # The editor's MCP config changed: the owner re-binds the session's servers (control
- # capability, idle only), as the workspace move above, instead of refusing the thread.
- await self._rebind_editor_mcp(client, session_id, resume_params['editor'])
- snapshot = await client.rpc("session.resume", session_id=session_id, **resume_params)
- await self._adopt(session_id, snapshot)
- if 'editor' in resume_params:
- self._editor_mcp[session_id] = resume_params['editor']
- from acp_adapter.server import _history_replay_updates
- if self._conn:
- # The editor replays the live transcript in stored order, as main's ACP did; archived rows
- # (summarized away by a compression) are display-only.
- live = sorted((m for m in snapshot["messages"] if not m.get("archived")), key=lambda m: m.get("row_id") or 0)
- for update in _history_replay_updates(live):
- await self._conn.session_update(session_id=held_id, update=update)
- for pending in snapshot.get("prompts", []):
- self._permission(session_id, pending)
- await self._notify_unknown(session_id)
- await self._request_live_reasoning(client, session_id)
- return await self._session_fields(session_id, {**info, **(snapshot.get("info") or {})}, held_id)
- @staticmethod
- def _moved(info, cwd):
- return "cwd" in info and _normalize_cwd_for_compare(info["cwd"]) != _normalize_cwd_for_compare(_translate_acp_cwd(cwd))
- async def _move_workspace(self, client, session_id, cwd):
- """Main rebound a session opened from another folder to that folder; the owner's ``workspace``
- mutation (Move to project) moves execution cwd and TERMINAL_CWD together, idle sessions only."""
- payload = {'cwd': _translate_acp_cwd(cwd)}
- self._unacked.pop(session_id, None)
- await self._mutations.apply(client, session_id, 'workspace', payload)
- self._mutations.acknowledge(session_id, 'workspace', payload)
- return await client.rpc("session.info", session_id=session_id)
- async def _rebind_editor_mcp(self, client, session_id, editor):
- """The owner's ``editor_mcp`` mutation: rediscovers *editor*'s servers into the session's policy."""
- self._unacked.pop(session_id, None)
- await self._mutations.apply(client, session_id, 'editor_mcp', editor)
- self._mutations.acknowledge(session_id, 'editor_mcp', editor)
- async def load_session(self, cwd, session_id, mcp_servers=None, **kwargs):
- return LoadSessionResponse(**await self._resume(cwd, session_id, mcp_servers))
- async def resume_session(self, cwd, session_id, mcp_servers=None, **kwargs):
- return ResumeSessionResponse(**await self._resume(cwd, session_id, mcp_servers))
- async def _cancel_admission(self, session_id, admission_id):
- client = await self._client()
- # Cancel our own admission; another surface's running turn is not ours to
- # interrupt. Only when our admission is the one executing do we interrupt.
- try:
- await client.rpc("prompt.cancel", session_id=session_id, admission_id=admission_id)
- except GatewayClientError as exc:
- if str(exc) != "stale_generation":
- raise
- receipt = await client.rpc("prompt.receipt", session_id=session_id, admission_id=admission_id)
- if receipt["status"] != "started":
- return
- try:
- await client.rpc("session.interrupt", session_id=session_id,
- execution_generation=receipt["execution_generation"])
- except GatewayClientError as interrupt_exc:
- if str(interrupt_exc) != "stale_generation":
- raise
- # The exact admission may have settled between the receipt and interrupt.
- # Re-read that admission only; never substitute the session's current
- # generation, which could already belong to a successor.
- settled = await client.rpc(
- "prompt.receipt", session_id=session_id, admission_id=admission_id)
- if settled["status"] != "terminal":
- raise
- async def cancel(self, session_id, **kwargs):
- session_id = self._aliases.get(session_id, session_id)
- if session_id not in self._snapshots:
- raise GatewayClientError("not_found")
- admission_id = self._admissions.get(session_id)
- if admission_id is None:
- if session_id in self._submitting:
- self._pending_cancels.add(session_id)
- return
- await self._cancel_admission(session_id, admission_id)
- async def fork_session(self, cwd, session_id, mcp_servers=None, **kwargs):
- from acp.schema import ForkSessionResponse
- session_id = self._aliases.get(session_id, session_id)
- client = await self._client()
- info = await client.rpc('session.info', session_id=session_id)
- # The owner binds the child's editor servers under the child's own scope: these, or else a
- # copy of the parent's.
- payload = {'mcp_servers': [s.model_dump(by_alias=True) for s in mcp_servers]} if mcp_servers else {}
- self._unacked.pop(session_id, None)
- result = await self._mutations.apply(client, session_id, 'branch', payload)
- child = result['branched_session_id']
- if self._moved(info, cwd):
- await self._move_workspace(client, child, cwd)
- await self._adopt(child, await client.rpc('session.resume', session_id=child))
- if payload or session_id in self._editor_mcp:
- self._editor_mcp[child] = payload or self._editor_mcp[session_id]
- self._mutations.acknowledge(session_id, 'branch', payload)
- info = self._snapshots[child].get('info') or await client.rpc('session.info', session_id=child)
- await self._request_live_reasoning(client, child)
- return ForkSessionResponse(session_id=child, **await self._session_fields(child, info, child))
- async def set_session_model(self, model_id, session_id, **kwargs):
- from acp.schema import SetSessionModelResponse
- session_id = self._aliases.get(session_id, session_id)
- client = await self._client()
- from hermes_cli.models import parse_model_input
- # Picker IDs include the provider, as on the in-process ACP switch path.
- provider, model = await asyncio.to_thread(parse_model_input, model_id, '')
- payload = {'model': model, **({'provider': provider} if provider else {})}
- self._unacked.pop(session_id, None) # a control between a lost submit and its repeat retires it
- result = await self._mutations.apply(client, session_id, 'model', payload,
- confirm=self._model_confirmer(session_id))
- if result.get('status') == 'cancelled':
- # Declined: nothing was written; the editor's picker must not show the target as active.
- raise GatewayClientError('model_switch_cancelled')
- await self._adopt(session_id, await client.rpc('session.resume', session_id=session_id))
- self._mutations.acknowledge(session_id, 'model', payload)
- if result.get('status') == 'deferred' and self._conn:
- # A pick during a running turn lands for the next one (#139604); say so, as Desktop does.
- from acp_adapter.gateway_commands import deferred_pick_text
- await self._conn.session_update(session_id=self._editor_id(session_id),
- update=acp.update_agent_message_text(deferred_pick_text(result) + "\n"))
- return SetSessionModelResponse()
- async def _confirm_deferred_pick(self, session_id, editor_id, ask):
- """The owner's boundary ask for a guarded deferred pick (``confirmation_required``; nothing
- written, the pick stays pending): the same permission request as an idle pick. Yes re-sends
- the same selection once with the owner's token (as Ink/Desktop); no, or no editor, keeps the
- committed model, and the editor is told which outcome it got, never left on the promise."""
- from acp_adapter.gateway_commands import _model_text, deferred_pick_text, refused_pick_text
- from hermes_cli.gateway_mutations import model_refusal_text
- async def say(text):
- if self._conn:
- await self._conn.session_update(session_id=editor_id, update=acp.update_agent_message_text(text + "\n"))
- target = ask.get("target_model") or (ask.get("payload") or {}).get("model")
- committed = {"model": ask.get("committed_model"), "provider": ask.get("committed_provider"),
- "target_model": target}
- confirm = self._model_confirmer(session_id)
- try:
- if confirm is None or not await confirm(ask):
- await say(refused_pick_text({**committed, "reason": "not confirmed"}))
- return
- client = await self._client()
- snapshot = await client.rpc("session.resume", session_id=session_id)
- result = await client.rpc("session.mutate", session_id=session_id, operation="model",
- request_id=uuid.uuid4().hex, expected_revision=snapshot["revision"],
- expected_generation=snapshot["execution_generation"],
- payload={**(ask.get("payload") or {}), "confirm": ask["confirm"]})
- if result.get("status") == "confirmation_required":
- # Another pick or a turn moved the session first: said once, never re-asked in a loop.
- await say(model_refusal_text(result, confirmed=True))
- return
- if session_id in self._snapshots:
- await self._adopt(session_id, await client.rpc("session.resume", session_id=session_id))
- # Confirmed while a turn runs: stored again for the next boundary, said as such.
- await say(deferred_pick_text(result) if result.get("status") == "deferred"
- else _model_text("Model switched to", result))
- except GatewayClientError as exc:
- logger.info("Deferred model pick on %s not confirmed: %s", session_id, exc)
- await say(refused_pick_text({**committed, "reason": str(exc)}))
- def _model_confirmer(self, session_id):
- """The owner's guarded-model confirmation as an ACP permission request (the mechanism
- approvals use): "Switch anyway" re-sends the mutation once with the owner's token; deny,
- dismissal or a lost editor keeps the current model. None without an editor connection."""
- if self._conn is None:
- return None
- async def confirm(refusal):
- from acp.schema import AllowedOutcome, PermissionOption
- from agent.i18n import t
- from hermes_cli.gateway_mutations import confirmation_title
- title = confirmation_title(refusal)
- tool_call = acp.update_tool_call(
- f"model-confirm-{uuid.uuid4().hex[:12]}", title=f"{title}: {refusal.get('target_model', '')}",
- kind="other", status="pending",
- content=[acp.tool_content(acp.text_block(refusal['confirm_message']))],
- raw_input={'model': refusal.get('target_model'), 'provider': refusal.get('target_provider'),
- 'guards': [w.get('kind') for w in refusal.get('warnings') or []]})
- options = [PermissionOption(option_id="allow_once", kind="allow_once",
- name=t("cli.model.choice_switch_anyway")),
- PermissionOption(option_id="deny", kind="reject_once", name=t("cli.model.choice_cancel"))]
- response = await self._conn.request_permission(session_id=self._editor_id(session_id),
- tool_call=tool_call, options=options)
- return isinstance(response.outcome, AllowedOutcome) and response.outcome.option_id == "allow_once"
- return confirm
- def _held_session(self, session_id):
- session_id = self._aliases.get(session_id, session_id)
- if session_id not in self._snapshots:
- raise GatewayClientError("not_found")
- return session_id
- async def set_session_mode(self, mode_id, session_id, **kwargs):
- """Main's Default / Accept Edits / Don't Ask: the session's edit approval policy on the owner."""
- from acp.schema import SetSessionModeResponse
- from acp_adapter.modes import MODE_TO_EDIT_APPROVAL_POLICY
- if mode_id not in MODE_TO_EDIT_APPROVAL_POLICY:
- raise GatewayClientError("invalid_params")
- await self._set_edit_policy(self._held_session(session_id), MODE_TO_EDIT_APPROVAL_POLICY[mode_id])
- return SetSessionModeResponse()
- async def set_config_option(self, config_id, session_id, value=None, **kwargs):
- """The pickers ``config_options`` advertises: the edit mode is the modes select's owner setting,
- the model ``set_session_model``'s pick, the effort the owner's ``reasoning`` mutation (``default``
- = ``/reasoning reset``), and the tier its session-scoped speed setting.
- Another id is accepted so editors do not fail on their own config writes,
- as main did. The reply is the full list, read back from the owner."""
- from acp.schema import SetSessionConfigOptionResponse
- from acp_adapter.gateway_session_meta import (
- REASONING_CONFIG_ID, SERVICE_TIER_CONFIG_ID, SERVICE_TIER_LABELS, current_mode, model_state,
- reasoning_choices, session_config_options,
- )
- from acp_adapter.modes import EDIT_APPROVAL_POLICY_CONFIG_ID, EDIT_APPROVAL_POLICY_TO_MODE
- editor_id, session_id = session_id, self._held_session(session_id)
- if config_id == EDIT_APPROVAL_POLICY_CONFIG_ID:
- if value not in EDIT_APPROVAL_POLICY_TO_MODE:
- raise GatewayClientError("invalid_params")
- await self._set_edit_policy(session_id, value)
- elif config_id == "model":
- if not isinstance(value, str):
- raise GatewayClientError("invalid_params")
- await self.set_session_model(model_id=value, session_id=editor_id)
- elif config_id == REASONING_CONFIG_ID:
- if value not in reasoning_choices():
- raise GatewayClientError("invalid_params")
- await self._idle_control(session_id, "reasoning", {"effort": None if value == "default" else value},
- "Reasoning effort")
- elif config_id == SERVICE_TIER_CONFIG_ID:
- if not isinstance(value, str) or value not in SERVICE_TIER_LABELS:
- raise GatewayClientError('invalid_params')
- self._unacked.pop(session_id, None)
- await (await self._client()).rpc('config.set', session_id=session_id, key='fast', value=value)
- info = await (await self._client()).rpc("session.info", session_id=session_id)
- models = await asyncio.to_thread(model_state, info)
- return SetSessionConfigOptionResponse(config_options=await session_config_options(
- self._gateway, session_id, models, info, self._modes.get(session_id) or current_mode(info)))
- async def _set_edit_policy(self, session_id, policy):
- """The owner's ``edit_policy`` mutation; every surface attached to the session reads the
- committed policy from ``session.info``."""
- from acp_adapter.modes import EDIT_APPROVAL_POLICY_TO_MODE
- await self._idle_control(session_id, "edit_policy", {"policy": policy}, "Mode")
- self._modes[session_id] = EDIT_APPROVAL_POLICY_TO_MODE[policy]
- async def _idle_control(self, session_id, operation, payload, label):
- """A revision-fenced owner mutation that applies to idle sessions only, like a model pick."""
- client = await self._client()
- self._unacked.pop(session_id, None)
- try:
- await self._mutations.apply(client, session_id, operation, payload)
- except GatewayClientError as exc:
- if str(exc) not in {"session_busy", "unknown_execution"}:
- raise
- # Named in the transcript (as a deferred model pick is) and the reply: a running turn ends on its
- # own, a lost one (unknown_execution) blocks every control until it is resolved or discarded.
- text = (f"{label} changes apply when the session is idle; try again after this turn."
- if str(exc) == "session_busy" else f"{label} changes wait for the lost turn: "
- + self._unknown_recovery(session_id, submitted=False).removeprefix("unknown_execution: "))
- if self._conn:
- await self._conn.session_update(session_id=self._editor_id(session_id),
- update=acp.update_agent_message_text(text + "\n"))
- raise acp.RequestError(-32603, text) from exc
- self._mutations.acknowledge(session_id, operation, payload)
- async def list_sessions(self, cursor=None, cwd=None, **kwargs):
- from acp.schema import ListSessionsResponse, SessionInfo
- from acp_adapter.catalog import catalog_sessions
- rows = await asyncio.to_thread(catalog_sessions, self._home / "state.db", cwd)
- if cursor:
- index = next((i for i, row in enumerate(rows) if row["session_id"] == cursor), None)
- rows = [] if index is None else rows[index + 1:]
- page = [SessionInfo(session_id=row["session_id"], cwd=row["cwd"], title=row.get("title"),
- updated_at=row.get("updated_at")) for row in rows[:50]]
- return ListSessionsResponse(sessions=page, next_cursor=page[-1].session_id if len(rows) > 50 else None)
- async def prompt(self, prompt, session_id, **kwargs):
- held_id, session_id = session_id, self._aliases.get(session_id, session_id)
- if session_id not in self._snapshots:
- raise GatewayClientError("not_found")
- if self._has_unknown(session_id) and await self._refresh_unknown_for_prompt(session_id):
- return PromptResponse(stop_reason='cancelled')
- if self._has_unknown(session_id):
- # Only a text-only /discard passes a lost turn, recognised BEFORE staging: a refused
- # prompt must not write its media or retire the editor's retained retry identity.
- from acp_adapter.content import _content_blocks_to_openai_user_content
- content = _content_blocks_to_openai_user_content(prompt)
- if not isinstance(content, str) or _slash_command(content) != 'discard':
- raise GatewayClientError(self._unknown_recovery(session_id, submitted=False))
- prepared = await self._prepare_submit(session_id, prompt)
- if prepared is None:
- return PromptResponse(stop_reason='cancelled')
- retry_key, input_id, staged = prepared
- text, attachments = staged
- answered, text = await self._run_slash(held_id, session_id, text) if not attachments else (False, text)
- if answered:
- return PromptResponse(stop_reason='end_turn')
- # ... and every prepared control's (a slash keeps its own key: apply retires the rest).
- self._mutations.retire(session_id)
- submit = {'text': text}
- if attachments:
- submit['attachments'] = attachments
- self._submitting.add(session_id)
- try:
- # Inside the try: a failed reconnect is as ambiguous for a retained identity as a lost ack.
- client = await self._client()
- link, resumes = self._link, self._resumes.get(session_id, 0)
- receipt = await client.rpc("prompt.submit", session_id=session_id, input_id=input_id, **submit)
- except BaseException as exc:
- from hermes_cli.gateway_client import GatewayRPCError
- if not isinstance(exc, GatewayRPCError):
- # Transport loss, timeout or cancel before the ack: the owner may hold this admission.
- # Keep its identity for the editor's retry of the same prompt (latest 64 sessions).
- self._unacked[session_id] = (retry_key, input_id, staged)
- while len(self._unacked) > 64:
- self._unacked.pop(next(iter(self._unacked)))
- self._pending_cancels.discard(session_id)
- raise
- finally:
- self._submitting.discard(session_id)
- admission_id = await self._admission_from_receipt(client, held_id, session_id, receipt)
- if admission_id is None:
- return PromptResponse(stop_reason='end_turn')
- self._inflight[(session_id, admission_id)] = None
- try:
- await self._after_ack(session_id, admission_id, link, resumes)
- if session_id in self._pending_cancels:
- self._pending_cancels.discard(session_id)
- await self._cancel_admission(session_id, admission_id)
- async with self._changed:
- await self._changed.wait_for(lambda: admission_id in self._terminals or self._failure is not None
- or self._link != link or admission_id in self._lost
- or self._blocked_admission(session_id, admission_id))
- # A successor's unknown state cannot replace our committed terminal result.
- if admission_id not in self._terminals:
- if self._link != link:
- # Our transport died before this turn's outcome reached us: ambiguous,
- # never retried on the replacement connection.
- raise self._lost_failure
- if self._failure:
- raise self._failure
- raise self._lost.pop(admission_id, None) or GatewayClientError(
- self._unknown_recovery(session_id, admission_id))
- terminal = self._terminals.pop(admission_id)
- finally:
- # Do not let one prompt tear down a newer mapping if the session has
- # already advanced while this coroutine unwinds.
- if self._admissions.get(session_id) == admission_id:
- self._admissions.pop(session_id, None)
- self._inflight.pop((session_id, admission_id), None)
- outcome = terminal.get("outcome")
- if outcome == "unknown":
- # Our own lost turn: the same refusal whether session.info or this completion woke us.
- raise GatewayClientError(self._unknown_recovery(session_id, admission_id))
- if outcome == "failed":
- raise GatewayClientError("admitted_turn_failed")
- from acp_adapter.gateway_session_meta import turn_usage
- # The turn's last ``session.usage`` precedes its ``message.complete`` on the stream.
- return PromptResponse(stop_reason="cancelled" if outcome == "cancelled" else "end_turn",
- usage=turn_usage(self._usage.get(session_id)))
- async def _admission_from_receipt(self, client, held_id, session_id, receipt):
- """The admission a ``prompt.submit`` receipt names, or None when the owner admitted nothing."""
- if receipt.get("voice_stopped") is True:
- # TUI-26: a bare stop phrase typed into this LOCAL session's voice chat ended the chat on
- # the owner and admitted nothing, so no turn will settle: the prompt ends here.
- self._pending_cancels.discard(session_id)
- if self._conn:
- from agent.i18n import t
- await self._conn.session_update(session_id=held_id, update=acp.update_agent_message_text(
- t('cli.voice.stop_phrase_typed') + '\n'))
- return None
- admission_id = receipt["admission_id"]
- self._admissions[session_id] = admission_id
- if receipt.get("status") == "terminal":
- # A retry of an un-acked submit whose turn already settled: report that turn once.
- await self._settled_receipt(client, held_id, session_id, receipt)
- elif receipt.get("status") == "unknown":
- # A retry of an un-acked submit the owner lost in a restart: never a second turn.
- self._admissions.pop(session_id, None)
- raise GatewayClientError(self._unknown_recovery(session_id, admission_id))
- return admission_id
- async def _run_slash(self, held_id, session_id, text):
- """Run a slash command's local half: ``(answered, text to submit)``; answered ends the prompt."""
- command = _slash_command(text)
- if command is None:
- return False, text
- from acp_adapter.gateway_commands import CommandRefused, run_command
- parts = text.strip().split(None, 1)
- try:
- reply, text = await run_command(self, session_id, command, parts[1].strip() if len(parts) > 1 else '')
- except CommandRefused as exc:
- # A named refusal is the command's answer, shown to the user; never a failed prompt.
- reply = str(exc)
- if reply is None:
- return False, text
- if self._conn:
- await self._conn.session_update(session_id=held_id, update=acp.update_agent_message_text(reply + '\n'))
- return True, None
- async def _prepare_submit(self, session_id, prompt):
- """``(retry_key, input_id, (text, attachments))`` for one ACP prompt, or None when the editor's Stop
- arrived while it was staged."""
- from acp_adapter.content import _content_blocks_to_openai_user_content
- from acp_adapter.gateway_media import stage_user_content, submit_fingerprint
- content = _content_blocks_to_openai_user_content(prompt)
- retry_key = submit_fingerprint(session_id, content)
- # Only this session's very next prompt may be the editor's retry of an un-acked submit; any
- # prompt (slash work included) retires the retained identity, so a later repeat is new work.
- retained = self._unacked.pop(session_id, None)
- if retained is not None and retained[0] == retry_key:
- # The retry resends what the owner may already hold: the staged content and input_id are
- # reused, never prepared (a remote image fetched) a second time.
- return retained
- # The editor's Stop during staging (a remote image download) is held like one during the
- # submit itself, and the prompt then ends without being sent.
- self._submitting.add(session_id)
- try:
- staged = await stage_user_content(content, self._home)
- finally:
- self._submitting.discard(session_id)
- if session_id in self._pending_cancels:
- self._pending_cancels.discard(session_id)
- return None
- return retry_key, uuid.uuid4().hex, staged
- async def _after_ack(self, session_id, admission_id, link, resumes):
- """A gap re-attach whose resume left after this submit covers it. The pump owns recovery: it
- recovers this admission against that snapshot behind the ones it already holds (FIFO, once)."""
- if self._resumes.get(session_id, 0) == resumes:
- return
- async with self._changed:
- await self._changed.wait_for(lambda: self._adopted.get(session_id, 0) > resumes
- or self._failure is not None or self._link != link)
- if self._adopted.get(session_id, 0) > resumes:
- # Held behind a full queue, never dropped: a full queue parks the reader, not the link.
- from hermes_cli.gateway_client import put_behind
- put_behind(self._gateway.events, (session_id, admission_id))
- async def _recover(self, session_id, admission_id):
- """Queued: it lost nothing. Running: cut until its live completion. Unknown: the waiter refuses it.
- Unlisted: it ended in the hole and its receipt settles it (unreadable: that prompt alone fails).
- Terminal evidence received, being delivered or already delivered always wins."""
- from hermes_cli.gateway_replay_gap import pending_status, settled
- status = pending_status(self._snapshots[session_id].get("pending"), admission_id)
- if status in ("queued", "unknown") or {admission_id} & (
- self._terminals.keys() | self._settling | self._receipted.keys()):
- return
- self._cut.setdefault(admission_id, self._streamed.pop(admission_id, ""))
- if status:
- return
- try:
- receipt = await self._gateway.rpc("prompt.receipt", session_id=session_id, admission_id=admission_id,
- include_result=True)
- except (GatewayClientError, OSError, TimeoutError):
- receipt = {"status": "terminal"} # unreadable
- verdict = settled(receipt)
- if verdict is not False: # its one recovery read: a later entry (a post-ack request) joins it
- self._receipted.setdefault(admission_id, None)
- if verdict:
- await self._settled_receipt(self._gateway, self._editor_id(session_id), session_id, receipt, receipt)
- elif verdict is None and admission_id not in self._terminals and admission_id not in self._settling:
- async with self._changed:
- self._lost[admission_id] = GatewayClientError("session_replay_gap")
- self._changed.notify_all()
- async def _settled_receipt(self, client, held_id, session_id, receipt, saved=None):
- """``saved``: the receipt already fetched with its result (a replay gap's recovery read)."""
- admission_id = receipt["admission_id"]
- saved = saved or await client.rpc("prompt.receipt", session_id=session_id, admission_id=admission_id,
- include_result=True)
- if admission_id in self._terminals or admission_id in self._settling:
- return # this connection's pump carried the completion itself
- self._settling.add(admission_id) # claimed before the first await; the pump yields to it
- self._receipted[admission_id] = None
- while len(self._receipted) > 256:
- self._receipted.pop(next(iter(self._receipted)))
- try:
- outcome = {"interrupted": "cancelled"}.get(receipt.get("outcome"), receipt.get("outcome"))
- result = saved.get("result") or {}
- await self._finish_reply(session_id, held_id, admission_id, {
- "text": result.get("final_response") or "", "outcome": outcome,
- "response_reused": result.get("response_reused"), "receipt": True})
- async with self._changed:
- self._terminals[admission_id] = {"outcome": outcome}
- self._changed.notify_all()
- finally:
- self._settling.discard(admission_id)
- def _unknown_recovery(self, session_id, admission_id=None, *, submitted=True):
- """The refusal for a FIFO blocked by a lost turn, naming the existing recovery control.
- The editor's own ``/discard <id>`` (``acp_adapter.gateway_commands._discard_unknown``, the
- same fenced ``prompt.resolve_unknown`` the classic chat uses) acknowledges the exact lost
- admission without replaying it, and the queue then continues."""
- from hermes_constants import profile_name_for_home
- lost = [row["admission_id"] for row in self._snapshots.get(session_id, {}).get("pending", [])
- if row.get("status") == "unknown"] or [admission_id]
- profile = profile_name_for_home(self._home)
- command = "hermes" + (f" -p {profile}" if profile not in (None, "default") else "")
- state = ("your input is accepted and kept" if submitted else "nothing was submitted")
- return (f"unknown_execution: do not resend accepted input; a turn in this session was lost when the "
- f"gateway restarted and its outcome is unknown ({state}). Send "
- + " and ".join(f"`/discard {lost_id}`" for lost_id in lost)
- + f" here (or `{command} sessions discard {session_id}` in a terminal), then continue.")
- def _has_unknown(self, session_id):
- return any(row.get("status") == "unknown"
- for row in self._snapshots[session_id].get("pending", []))
- async def _refresh_unknown_for_prompt(self, session_id):
- # Stop during the owner's read must cancel the still-unsent editor input.
- self._submitting.add(session_id)
- try:
- await self._refresh_unknown(session_id)
- except BaseException:
- self._pending_cancels.discard(session_id)
- raise
- finally:
- self._submitting.discard(session_id)
- cancelled = session_id in self._pending_cancels
- self._pending_cancels.discard(session_id)
- return cancelled
- async def _refresh_unknown(self, session_id):
- """Ask the owner whether another viewer has acknowledged a cached lost turn."""
- client = await self._client() # A reconnect may already supply a fresh snapshot.
- cached = self._snapshots.get(session_id)
- if cached is None:
- raise GatewayClientError("not_found")
- if not self._has_unknown(session_id):
- return
- # Freeze the snapshot's pending watermark before the pump can advance its reply cursor.
- cached.setdefault("_pending_watermark", (cached.get("replay_epoch"), cached.get("last_sequence", 0)))
- fresh = await client.rpc("session.resume", session_id=session_id)
- cached = self._snapshots.get(session_id)
- if cached is None:
- raise GatewayClientError("not_found")
- # Only pending state received while the RPC was in flight can supersede its snapshot.
- epoch, sequence = cached.get("_pending_watermark",
- (cached.get("replay_epoch"), cached.get("last_sequence", 0)))
- if "pending" in fresh and (
- fresh.get("replay_epoch") != epoch or fresh.get("last_sequence", 0) >= sequence
- ):
- cached["pending"] = fresh["pending"]
- # The snapshot supplies only pending state here. Do not consume earlier message,
- # approval, or tool events that the editor's event pump has not projected yet.
- cached["_pending_watermark"] = (fresh.get("replay_epoch"), fresh.get("last_sequence", 0))
- def _pending_event_is_new(self, session_id, event):
- """Keep a pre-refresh pending event from restoring an already-discarded lost turn."""
- fence = self._snapshots.get(session_id, {}).get("_pending_watermark")
- sequence = event.get("seq")
- return (fence is None or sequence is None or event.get("replay_epoch") != fence[0]
- or sequence > fence[1])
- def _blocked_admission(self, session_id, admission_id):
- return self._has_unknown(session_id) and any(
- row.get("admission_id") == admission_id and row.get("status") in {"queued", "unknown"}
- for row in self._snapshots[session_id].get("pending", []))
- async def _events(self):
- gateway = self._gateway
- try:
- while True:
- frame = await gateway.events.get()
- if isinstance(frame, Exception):
- raise frame
- if isinstance(frame, tuple): # a post-ack recovery (``_after_ack``), behind every frame so far
- await self._recover(*frame)
- continue
- event = frame.get("params", {})
- sid = event.get("session_id")
- snapshot = self._snapshots.get(sid)
- if snapshot is None:
- continue
- epoch, seq = event.get("replay_epoch"), event.get("seq", 0)
- if epoch == snapshot.get("replay_epoch") and seq <= snapshot.get("last_sequence", 0):
- continue
- snapshot.update(replay_epoch=epoch, last_sequence=seq,
- execution_generation=event.get("execution_generation", snapshot.get("execution_generation")))
- await self._project(event)
- except asyncio.CancelledError:
- raise
- except Exception as exc:
- # Boundary: ANY projection failure must reach every waiter (prompt/load re-raise
- # ``_failure``), or they block forever on ``_changed``.
- logger.debug("ACP gateway event projection stopped", exc_info=True)
- async with self._changed:
- self._failure = exc
- self._changed.notify_all()
- async def _project(self, event):
- kind, payload = event.get("type"), event.get("payload", {})
- sid, editor_id = event["session_id"], self._editor_id(event["session_id"])
- aid = event.get("admission_id")
- if kind in {"session.info", "session.updated", "session.usage", "session.tools_changed"}:
- await self._project_session_state(kind, sid, editor_id, payload, event)
- return
- if await self._gap_guard(kind, sid, aid):
- return
- if kind in {"approval.request", "clarify.request"}:
- self._permission(sid, payload)
- return
- if kind in {"approval.settled", "clarify.settled"}:
- task = self._permissions.pop((sid, payload["prompt_id"], payload["execution_generation"]), None)
- if task:
- task.cancel()
- return
- if kind in {"reasoning.delta", "todo.updated"}:
- await self._project_side_update(kind, sid, editor_id, payload)
- return
- if kind in {"tool.start", "tool.complete"}:
- await self._project_tool(kind, sid, editor_id, aid, payload)
- return
- if kind == "message.delta":
- text = _text(payload)
- self._streamed[aid] = self._streamed.get(aid, "") + text
- if text and self._conn:
- await self._conn.session_update(session_id=editor_id, update=self._chunk(sid, text))
- elif kind == "message.interim":
- # Commentary the owner could not stream (``already_streamed`` false) reaches viewers
- # only here; streamed commentary is already on screen. Either way it is its own segment.
- self._close_segment(aid)
- text = _text(payload)
- self._end_message(sid)
- if not payload.get("already_streamed") and text.strip():
- self._segments.setdefault(aid, []).append(text)
- if self._conn:
- await self._conn.session_update(session_id=editor_id, update=self._chunk(sid, text + "\n\n"))
- self._end_message(sid)
- elif kind == "message.complete":
- if aid in self._settling or aid in self._receipted:
- # A retry's terminal receipt claimed this reply; it is shown once, from there.
- self._streamed.pop(aid, None)
- self._segments.pop(aid, None)
- return
- self._settling.add(aid)
- try:
- await self._finish_reply(sid, editor_id, aid, payload)
- async with self._changed:
- self._terminals[aid] = payload
- if len(self._terminals) > 256:
- self._terminals.pop(next(iter(self._terminals)))
- self._changed.notify_all()
- finally:
- self._settling.discard(aid)
- async def _gap_guard(self, kind, sid, aid):
- """What a replay gap changes in the projection; True when the frame is consumed here."""
- if kind == "session.replay_gap":
- # Re-attach that session alone (a refusal still fails the pump: the next call redials).
- params = {"editor": self._editor_mcp[sid]} if sid in self._editor_mcp else {}
- self._resumes[sid] = self._resumes.get(sid, 0) + 1
- snapshot = await self._gateway.rpc("session.resume", session_id=sid, **params)
- await self._adopt(sid, snapshot, self._resumes[sid])
- for prompt in snapshot.get("prompts", []):
- self._permission(sid, prompt)
- started = [row["admission_id"] for row in snapshot.get("pending", []) if row.get("status") == "started"]
- for admission_id in dict.fromkeys([*started, *(a for held, a in self._inflight if held == sid)]):
- await self._recover(sid, admission_id)
- return True
- if aid not in self._cut:
- return False
- if kind in {"tool.start", "message.interim"}: # a new segment: what was shown before it is closed
- if self._cut[aid].strip():
- self._segments.setdefault(aid, []).append(self._cut[aid])
- self._cut[aid] = ""
- self._end_message(sid)
- # Live deltas stopped at the gap; an interim is whole (it may be the only copy of the reply).
- return kind == "message.delta"
- async def _project_session_state(self, kind, sid, editor_id, payload, event):
- if kind == "session.usage":
- await self._project_usage(sid, editor_id, payload)
- return
- if kind == "session.tools_changed":
- if self._conn:
- await self._conn.session_update(session_id=editor_id, update=acp.update_agent_message_text(
- _tools_changed_notice(payload)))
- return
- if kind == "session.updated" and payload.get("operation") == "model" and payload.get("status") == "refused":
- # A deferred pick that no longer resolved at the turn boundary: dropped, named here.
- if self._conn:
- from acp_adapter.gateway_commands import refused_pick_text
- await self._conn.session_update(session_id=editor_id, update=acp.update_agent_message_text(
- refused_pick_text(payload) + "\n"))
- return
- if (kind == "session.updated" and payload.get("operation") == "model"
- and payload.get("status") == "confirmation_required" and isinstance(payload.get("confirm"), str)):
- # A deferred pick whose target needs consent at the turn boundary: asked like an idle
- # pick (off the event pump: the answer may take as long as the user does).
- task = asyncio.create_task(self._confirm_deferred_pick(sid, editor_id, payload))
- self._background.add(task)
- task.add_done_callback(self._background.discard)
- return
- if kind == "session.info" and sid in self._snapshots and "pending" in payload:
- async with self._changed:
- if self._pending_event_is_new(sid, event):
- self._snapshots[sid]["pending"] = payload["pending"]
- self._snapshots[sid]["_pending_watermark"] = (event.get("replay_epoch"), event.get("seq", 0))
- self._changed.notify_all()
- await self._project_title(sid, editor_id, payload.get("title"))
- await self._project_mode(sid, editor_id, payload)
- async def _project_mode(self, sid, editor_id, payload, client=None):
- """Another surface's ``edit_policy`` change (its ``session.info``) as ``current_mode_update``."""
- from acp_adapter.modes import EDIT_APPROVAL_POLICY_TO_MODE
- mode = EDIT_APPROVAL_POLICY_TO_MODE.get(payload.get("edit_approval_policy"))
- # A session's first (its attach's snapshot) seeds silently: the attach's reply shows it.
- if mode is not None and self._modes.setdefault(sid, mode) != mode:
- self._modes[sid] = mode
- if self._conn:
- from acp.schema import CurrentModeUpdate # ``acp`` does not re-export ``update_current_mode``
- await self._conn.session_update(session_id=editor_id, update=CurrentModeUpdate(
- session_update="current_mode_update", current_mode_id=mode))
- await self._project_config(sid, editor_id, payload, client=client)
- async def _project_config(self, sid, editor_id, payload, client=None):
- """Zed draws its pickers only from ``configOptions`` once an agent sends them (it then ignores
- ``current_mode_update``), so a mode, model, effort or tier change from another surface resends
- the full list. A partial ``session.info`` keeps what it omits."""
- from acp_adapter.gateway_session_meta import current_mode, model_state, session_config_options
- fields = ("model", "provider", "reasoning_effort")
- if not any(key in payload for key in (*fields, "edit_approval_policy", "service_tier")):
- return
- seen = self._configs.get(sid)
- shown = {**(seen or {}), **{key: payload[key] for key in fields if key in payload},
- "mode": self._modes.get(sid) or current_mode(payload)}
- if seen == shown and "service_tier" not in payload:
- return # an equal observation must not take over from a build still running for it
- self._configs[sid] = shown
- # Seeded silently like the mode: the attach's reply carries the options.
- if seen is None or not self._conn:
- return
- from acp.schema import ConfigOptionUpdate
- models = await asyncio.to_thread(model_state, shown)
- options = await session_config_options(client or self._gateway, sid, models, shown, shown["mode"])
- if self._configs.get(sid) is not shown:
- return # a newer projection (an event or ``_adopt``) replaced it during the build and sends its own
- await self._conn.session_update(session_id=editor_id, update=ConfigOptionUpdate(
- session_update="config_option_update", config_options=options))
- async def _project_usage(self, sid, editor_id, stats):
- """The owner's usage dict: kept for the turn's ``PromptResponse.usage``, shown as ``usage_update``."""
- from acp_adapter.gateway_session_meta import usage_update
- self._usage[sid] = stats
- if self._conn and (update := usage_update(stats)) is not None:
- await self._conn.session_update(session_id=editor_id, update=update)
- async def _project_title(self, sid, editor_id, title):
- """A new title (auto-title's ``session.info``, a rename's ``session.updated``) as main's
- ``session_info_update``; the owner republishes an unchanged one after every turn."""
- if not isinstance(title, str) or not title.strip() or title == self._titles.get(sid):
- return
- self._titles[sid] = title
- if self._conn:
- from acp_adapter.gateway_session_meta import title_update
- await self._conn.session_update(session_id=editor_id, update=title_update(title))
- def _permission(self, session_id, prompt):
- answer = {"approval": self._answer_permission, "clarify": self._answer_clarify}.get(prompt.get("kind"))
- if answer is None or self._conn is None:
- return
- key = (session_id, prompt["prompt_id"], prompt["execution_generation"])
- if key not in self._permissions:
- task = asyncio.create_task(answer(session_id, prompt))
- self._permissions[key] = task
- task.add_done_callback(lambda done: self._retire_unanswered(key, done))
- def _retire_unanswered(self, key, task):
- """A card whose response the owner did not accept (editor cancel, transport loss, lost
- respond RPC) gives up its key, so the next snapshot that still lists the prompt (reattach,
- ``session/load``) shows a NEW card. An earlier answer is never replayed. An accepted one
- keeps its key until ``*.settled``, so a replayed request raises no second card."""
- if self._permissions.get(key) is task and (task.cancelled() or task.exception() is not None
- or task.result() is not True):
- del self._permissions[key]
- async def _answer_clarify(self, session_id, prompt):
- from acp.schema import AllowedOutcome
- from acp_adapter.elicitation import (
- ELICITATION_METHOD, SKIP_OPTION, build_clarify_elicitation, build_clarify_permission,
- elicited_answer,
- )
- editor_id = self._editor_id(session_id)
- try:
- if self._form_elicitation:
- answer = elicited_answer(await self._conn._conn.send_request(
- ELICITATION_METHOD, build_clarify_elicitation(editor_id, prompt)))
- else:
- tool_call, options, answers = build_clarify_permission(prompt)
- response = await self._conn.request_permission(
- session_id=editor_id, tool_call=tool_call, options=options)
- await self._close_card(editor_id, tool_call, options, response)
- # A dismissed card (also what ACP answers for the editor's own Stop) is the Skip a
- # form decline sends; only an unknown option id is no answer.
- answer = (answers.get(response.outcome.option_id)
- if isinstance(response.outcome, AllowedOutcome) else answers[SKIP_OPTION])
- # No answer (editor transport loss) leaves the canonical waiter to other viewers.
- if answer is None:
- return False
- await self._gateway.rpc("clarify.respond", session_id=session_id, prompt_id=prompt["prompt_id"],
- execution_generation=prompt["execution_generation"], answer=answer)
- return True
- except Exception:
- # Boundary: as for approvals, a detached editor or expired prompt is not an answer.
- logger.info("ACP clarify viewer detached or control expired", exc_info=True)
- return False
- async def _answer_permission(self, session_id, prompt):
- from acp.schema import AllowedOutcome
- from acp_adapter.permissions import (
- _build_permission_options, _build_permission_tool_call, _OPTION_ID_TO_HERMES,
- )
- choices = prompt["choices"]
- options = [option for option in _build_permission_options(
- allow_permanent="always" in choices, allow_session="session" in choices)
- if _OPTION_ID_TO_HERMES[option.option_id] in choices]
- try:
- if 'edit' in prompt:
- from acp_adapter.edit_approval import EditProposal, build_acp_edit_tool_call
- tool_call = build_acp_edit_tool_call(EditProposal(**prompt['edit']))
- else:
- tool_call = _build_permission_tool_call(prompt.get('command', ''), prompt.get('description', ''))
- response = await self._conn.request_permission(session_id=self._editor_id(session_id),
- tool_call=tool_call, options=options)
- await self._close_card(self._editor_id(session_id), tool_call, options, response)
- # Transport loss/cancel is not a denial: the canonical waiter belongs
- # to the execution and may still be answered by another viewer.
- if not isinstance(response.outcome, AllowedOutcome):
- return False
- if response.outcome.option_id not in {option.option_id for option in options}:
- return False
- await self._gateway.rpc("approval.respond", session_id=session_id,
- prompt_id=prompt["prompt_id"], execution_generation=prompt["execution_generation"],
- choice=_OPTION_ID_TO_HERMES[response.outcome.option_id])
- return True
- except Exception:
- # Boundary: a detached viewer or expired control is not a denial; the canonical
- # waiter stays answerable by another viewer, so nothing propagates.
- logger.info("ACP permission viewer detached or control expired", exc_info=True)
- return False
- async def aclose(self):
- # Post-attach notices first: one paused mid-notice would otherwise resume after the
- # teardown and open a fresh gateway connection through ``_client``.
- background = list(self._background)
- for task in background:
- task.cancel()
- if background:
- await asyncio.gather(*background, return_exceptions=True)
- for task in self._permissions.values():
- task.cancel()
- if self._permissions:
- await asyncio.gather(*self._permissions.values(), return_exceptions=True)
- self._permissions.clear()
- await self._teardown()
|