acp_client.py 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562
  1. """Generic ACP (Agent Client Protocol) stdio client behind a minimal OpenAI-client facade.
  2. The public base for ``external_process`` model providers: a provider profile's
  3. ``create_client`` returns an :class:`ACPClient` (or a subclass). Each request starts a
  4. short-lived ACP session with the agent CLI, sends the formatted conversation as one prompt,
  5. collects text chunks, and returns the minimal OpenAI-client shape.
  6. Subclasses customise the launch defaults and vendor quirks through class attributes
  7. (``default_command``, ``default_args``, ``command_env_vars``, ``args_env_var``,
  8. ``marker_base_url``, ``placeholder_model``, ``label``, ``missing_command_hint``,
  9. ``unsupported_transport_hint``) and two hooks (:meth:`ACPClient.model_entry_disabled`,
  10. :meth:`ACPClient.early_exit_error`).
  11. """
  12. from __future__ import annotations
  13. import contextlib
  14. import errno
  15. import json
  16. import logging
  17. import os
  18. import queue
  19. import re
  20. import shlex
  21. import subprocess
  22. import tempfile
  23. import threading
  24. import time
  25. from collections import deque
  26. from collections.abc import Callable, Iterator
  27. from pathlib import Path
  28. from types import SimpleNamespace
  29. from typing import Any
  30. from agent.acp_openai_bridge import (
  31. completion_to_stream_chunks as _completion_to_stream_chunks,
  32. extract_tool_calls_from_text as _extract_tool_calls_from_text,
  33. render_tool_bridge_sections as _render_tool_bridge_sections,
  34. )
  35. from agent.file_safety import (
  36. get_nt_namespace_error, get_read_block_error, get_write_denied_error, is_write_approval_required)
  37. from agent.redact import redact_sensitive_text
  38. from agent.runtime_cwd import resolve_agent_cwd
  39. logger = logging.getLogger(__name__)
  40. _DEFAULT_TIMEOUT_SECONDS = 900.0
  41. # ACP JSON-RPC error code meaning "authentication required" (the agent CLI is not signed in).
  42. _ACP_AUTH_REQUIRED = -32000
  43. _ROLE_LABELS = {"system": "System", "user": "User", "assistant": "Assistant", "tool": "Tool", "context": "Context"}
  44. # Probe verdicts per binary path (~50ms --help paid once per process). Only definitive
  45. # True/False is cached, so a CLI installed mid-session is picked up.
  46. _ACP_PROBE_CACHE: dict[str, bool] = {}
  47. _PROMPT_PREAMBLE = (
  48. "You are being used as the active ACP agent backend for Hermes.",
  49. "Use ACP capabilities to complete tasks.",
  50. "IMPORTANT: If you take an action with a tool, you MUST output tool calls using <tool_call>{...}</tool_call> blocks with JSON exactly in OpenAI function-call shape.",
  51. "If no tool is needed, answer normally.",
  52. )
  53. _INITIALIZE_PARAMS = {
  54. "protocolVersion": 1,
  55. "clientCapabilities": {"fs": {"readTextFile": True, "writeTextFile": True}},
  56. "clientInfo": {"name": "hermes-agent", "title": "Hermes Agent", "version": "0.0.0"},
  57. }
  58. def _acp_supported(command: str, args: list[str]) -> bool | None:
  59. """Tri-state ``--acp`` probe (a CLI without the flag exits 1 and the parent would wait the
  60. full child timeout for stdout that never arrives). True = help advertises --acp; False =
  61. help ran cleanly without it (caller fast-fails); None = inconclusive (binary missing /
  62. --help failed → normal spawn error). Skipped when ``--acp`` is not in ``args`` (custom transport)."""
  63. if "--acp" not in args:
  64. return True
  65. if (cached := _ACP_PROBE_CACHE.get(command)) is not None:
  66. return cached
  67. try:
  68. probe = subprocess.run(
  69. [command, "--help"],
  70. # Explicit codec because text=True alone decodes with the
  71. # locale default and crashes on non-ASCII help text under
  72. # GBK/CP932 locales.
  73. capture_output=True, text=True, encoding="utf-8",
  74. errors="replace", timeout=5,
  75. stdin=subprocess.DEVNULL,
  76. check=False,
  77. )
  78. except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
  79. return None
  80. if probe.returncode != 0:
  81. return None
  82. # ``--acp`` as a flag token; tolerate spacing and ``[--acp]`` variants.
  83. verdict = _ACP_PROBE_CACHE[command] = bool(re.search(r"(?:^|[\s\[])--acp(?:[\s=\],]|$)", probe.stdout, re.MULTILINE))
  84. return verdict
  85. def _resolve_home_dir() -> str:
  86. """Stable HOME for child ACP processes; the temp dir as a last resort so the child never starts HOME-less."""
  87. if home := os.environ.get("HOME", "").strip():
  88. return home
  89. if (expanded := os.path.expanduser("~")) and expanded != "~":
  90. return expanded
  91. try:
  92. import pwd
  93. return pwd.getpwuid(os.getuid()).pw_dir.strip() or tempfile.gettempdir() # windows-footgun: ok — POSIX fallback inside try/except (pwd import fails on Windows)
  94. except Exception:
  95. return tempfile.gettempdir()
  96. def _build_subprocess_env() -> dict[str, str]:
  97. # Lazy: the env policy imports hermes_cli.config, and provider plugins import this module
  98. # while hermes_cli.config is still initializing (discovery runs from it).
  99. from hermes_constants import apply_subprocess_home_env
  100. from tools.environments.local import hermes_subprocess_env
  101. # An ACP agent drives a model and needs LLM provider credentials; the central helper still
  102. # strips Tier-1 secrets (bot tokens, GitHub auth, infra).
  103. # See #29157.
  104. env = hermes_subprocess_env(inherit_credentials=True)
  105. env["HOME"] = _resolve_home_dir()
  106. apply_subprocess_home_env(env)
  107. return env
  108. def _jsonrpc_result(message_id: Any, result: Any) -> dict[str, Any]:
  109. return {"jsonrpc": "2.0", "id": message_id, "result": result}
  110. def _jsonrpc_error(message_id: Any, code: int, message: str) -> dict[str, Any]:
  111. return {"jsonrpc": "2.0", "id": message_id, "error": {"code": code, "message": message}}
  112. def _never_disabled(entry: dict[str, Any]) -> bool:
  113. return False
  114. def _enabled_id_list(entries: Any, key: str, disabled: Callable[[dict[str, Any]], bool] = _never_disabled) -> list[str]:
  115. """Ordered unique ids of the entries ``disabled`` does not reject."""
  116. seen: set[str] = set()
  117. result: list[str] = []
  118. for entry in entries or []:
  119. if not isinstance(entry, dict):
  120. continue
  121. value = str(entry.get(key) or "").strip()
  122. if not value or value in seen or disabled(entry):
  123. continue
  124. seen.add(value)
  125. result.append(value)
  126. return result
  127. def _model_config_option(session: dict[str, Any]) -> dict[str, Any] | None:
  128. return next((option for option in (session.get("configOptions") or []) if isinstance(option, dict)
  129. and "model" in (option.get("category"), option.get("id"))), None)
  130. def _session_model_ids(session: dict[str, Any], disabled: Callable[[dict[str, Any]], bool] = _never_disabled) -> list[str]:
  131. """Account-authorized model ids advertised by ``session/new`` in ACP v1 or its legacy extension."""
  132. if option := _model_config_option(session):
  133. return _enabled_id_list(option.get("options"), "value", disabled)
  134. return _legacy_session_model_ids(session, disabled)
  135. def _legacy_session_model_ids(session: dict[str, Any], disabled: Callable[[dict[str, Any]], bool] = _never_disabled) -> list[str]:
  136. return _enabled_id_list((session.get("models") or {}).get("availableModels"), "modelId", disabled)
  137. def _model_selection_request(
  138. session: dict[str, Any], requested_model: str, *, placeholder: str = "",
  139. disabled: Callable[[dict[str, Any]], bool] = _never_disabled,
  140. ) -> tuple[str, dict[str, str]] | None:
  141. """ACP request selecting ``requested_model`` for ``session``: stable v1
  142. ``session/set_config_option``, else the pre-stabilization ``session/set_model`` when no
  143. model config option is advertised. A reported model list is authoritative: unknown and
  144. ``disabled`` ids return None instead of being sent, as does the provider's ``placeholder``
  145. id (meaning "the session default")."""
  146. session_id = str(session.get("sessionId") or "").strip()
  147. requested_model = str(requested_model or "").strip()
  148. if not session_id or not requested_model or requested_model == placeholder:
  149. return None
  150. option = _model_config_option(session)
  151. if option:
  152. if requested_model not in _enabled_id_list(option.get("options"), "value", disabled):
  153. return None
  154. return "session/set_config_option", {"sessionId": session_id, "configId": str(option.get("id") or "model"), "value": requested_model}
  155. available = _legacy_session_model_ids(session, disabled)
  156. return None if available and requested_model not in available else ("session/set_model", {"sessionId": session_id, "modelId": requested_model})
  157. def _format_messages_as_prompt(
  158. messages: list[dict[str, Any]], model: str | None = None, tools: list[dict[str, Any]] | None = None, tool_choice: Any = None,
  159. ) -> str:
  160. # Deliberately no "requested model" line: the model is applied for real via ACP session/set_model;
  161. # a prompt-text mention makes a substituted backend model FALSELY self-identify as the requested
  162. # one. The whole Hermes toolset is forwarded; the agent's own tools run inside the agent.
  163. sections: list[str] = [*_PROMPT_PREAMBLE, *_render_tool_bridge_sections(tools, tool_choice)]
  164. transcript: list[str] = []
  165. for message in (m for m in messages if isinstance(m, dict)):
  166. role = str(message.get("role") or "unknown").strip().lower()
  167. if rendered := _render_message_content(message.get("content")):
  168. transcript.append(f"{_ROLE_LABELS.get(role, 'Context')}:\n{rendered}")
  169. if transcript:
  170. sections.append("Conversation transcript:\n\n" + "\n\n".join(transcript))
  171. sections.append("Continue the conversation from the latest user request.")
  172. return "\n\n".join(section.strip() for section in sections if section and section.strip())
  173. def _render_message_content(content: Any) -> str:
  174. if content is None:
  175. return ""
  176. if isinstance(content, dict):
  177. if "text" in content:
  178. return str(content.get("text") or "").strip()
  179. return content["content"].strip() if isinstance(content.get("content"), str) else json.dumps(content, ensure_ascii=True)
  180. if isinstance(content, list):
  181. parts = [item if isinstance(item, str) else item["text"].strip() for item in content if isinstance(item, str)
  182. or (isinstance(item, dict) and isinstance(item.get("text"), str) and item["text"].strip())]
  183. return "\n".join(parts).strip()
  184. return str(content).strip()
  185. def _ensure_path_within_cwd(path_text: str, cwd: str, *, verb: str) -> Path:
  186. # Raw-string check BEFORE resolve(): resolving an NT-namespace path is the NTLM-leak trigger.
  187. if nt_error := get_nt_namespace_error(path_text, verb=verb):
  188. raise PermissionError(nt_error)
  189. if not Path(path_text).is_absolute():
  190. raise PermissionError("ACP file-system paths must be absolute.")
  191. resolved, root = Path(path_text).resolve(), Path(cwd).resolve()
  192. try:
  193. resolved.relative_to(root)
  194. except ValueError as exc:
  195. raise PermissionError(f"Path '{resolved}' is outside the session cwd '{root}'.") from exc
  196. return resolved
  197. def _effective_timeout(timeout: Any) -> float:
  198. """Normalise a float or httpx.Timeout-like object to wall-clock seconds (largest component wins)."""
  199. if isinstance(timeout, (int, float)):
  200. return float(timeout)
  201. candidates = [getattr(timeout, attr, None) for attr in ("read", "write", "connect", "pool", "timeout")]
  202. return max((float(v) for v in candidates if isinstance(v, (int, float))), default=_DEFAULT_TIMEOUT_SECONDS)
  203. def _fs_read_text_file(params: dict[str, Any], cwd: str) -> Any:
  204. path = _ensure_path_within_cwd(str(params.get("path") or ""), cwd, verb="Read")
  205. if block_error := get_read_block_error(str(path)):
  206. raise PermissionError(block_error)
  207. try:
  208. content = path.read_text(encoding="utf-8-sig")
  209. except FileNotFoundError:
  210. content = ""
  211. line, limit = params.get("line"), params.get("limit")
  212. if isinstance(line, int) and line > 1:
  213. end = line - 1 + limit if isinstance(limit, int) and limit > 0 else None
  214. content = "".join(content.splitlines(keepends=True)[line - 1:end])
  215. return {"content": redact_sensitive_text(content, force=True) if content else content}
  216. def _fs_write_text_file(params: dict[str, Any], cwd: str) -> Any:
  217. path = _ensure_path_within_cwd(str(params.get("path") or ""), cwd, verb="Write")
  218. if denied := get_write_denied_error(str(path)):
  219. raise PermissionError(denied)
  220. if is_write_approval_required(str(path)): # soft-gated for interactive tools; the ACP shim has no human channel → fail closed
  221. raise PermissionError(f"Write denied: '{path}' requires interactive approval and cannot be written through the ACP file bridge.")
  222. path.parent.mkdir(parents=True, exist_ok=True)
  223. path.write_text(str(params.get("content") or ""), encoding="utf-8")
  224. return None
  225. _FS_HANDLERS = {"fs/read_text_file": _fs_read_text_file, "fs/write_text_file": _fs_write_text_file}
  226. class ACPClient:
  227. """Minimal OpenAI-client-compatible facade over one ACP agent CLI spoken to on stdio.
  228. Construct it with the resolved ``command``/``args`` (what
  229. ``resolve_external_process_provider_credentials`` returns for the provider); the class
  230. attributes below are only the fallback when a caller passes neither.
  231. """
  232. # Declared for agent/auxiliary_client.py: this shim drives an ACP subprocess over stdio, so it is
  233. # already a complete client (never re-dispatch through a wire adapter) and async-safe as-is.
  234. HERMES_SKIP_TRANSPORT_WRAP = True
  235. HERMES_SKIP_ASYNC_WRAP = True
  236. #: Binary and argv tail used when the caller passes no command/args; env vars win, in order.
  237. default_command: str = ""
  238. default_args: tuple[str, ...] = ()
  239. command_env_vars: tuple[str, ...] = ()
  240. args_env_var: str = ""
  241. #: ``base_url`` reported when none is passed (an ``acp://`` marker, never dialled).
  242. marker_base_url: str = "acp://agent"
  243. #: Model id meaning "the session default": never sent as a model selection.
  244. placeholder_model: str = "acp"
  245. #: Product name in errors and log lines.
  246. label: str = "ACP"
  247. #: Error text after "Could not start <label> command '<cmd>'." (default names ``command_env_vars``).
  248. missing_command_hint: str = ""
  249. #: Sentence appended when the agent answers a request with ACP's auth-required error (code -32000),
  250. #: e.g. the CLI's own login command; None = the agent's message alone.
  251. auth_required_hint: str | None = None
  252. #: Error text after the ``--acp`` probe rejects the CLI.
  253. unsupported_transport_hint: str = (
  254. "Either install a CLI release that supports --acp, or point the provider at a working command/args pair.")
  255. def model_entry_disabled(self, entry: dict[str, Any]) -> bool:
  256. """True when an advertised model entry is unavailable to this account (vendor ``_meta``)."""
  257. return False
  258. def early_exit_error(self, stderr_text: str) -> str | None:
  259. """Error message for a CLI that exited before answering, or None for the generic one."""
  260. return None
  261. def _resolve_command(self) -> str:
  262. return next((v for name in self.command_env_vars if (v := os.getenv(name, "").strip())), "") or self.default_command
  263. def _resolve_args(self) -> list[str]:
  264. override = os.getenv(self.args_env_var, "").strip() if self.args_env_var else ""
  265. return shlex.split(override) or list(self.default_args)
  266. def _request_error(self, method: str, err: Any) -> str:
  267. text = f"{self.label} {method} failed: {(err.get('message') if isinstance(err, dict) else None) or err}"
  268. auth_required = isinstance(err, dict) and err.get("code") == _ACP_AUTH_REQUIRED
  269. return f"{text} {self.auth_required_hint}" if auth_required and self.auth_required_hint else text
  270. def _missing_command_hint(self) -> str:
  271. if self.missing_command_hint:
  272. return self.missing_command_hint
  273. return f"Install the agent CLI or set {'/'.join(self.command_env_vars)}." if self.command_env_vars else "Install the agent CLI."
  274. def __init__(
  275. self, *, api_key: str | None = None, base_url: str | None = None, default_headers: dict[str, str] | None = None,
  276. acp_command: str | None = None, acp_args: list[str] | None = None, acp_cwd: str | None = None, command: str | None = None,
  277. args: list[str] | None = None, **_: Any,
  278. ):
  279. self.api_key, self.base_url = api_key or self.placeholder_model, base_url or self.marker_base_url
  280. self._default_headers = dict(default_headers or {})
  281. self._acp_command = acp_command or command or self._resolve_command()
  282. self._acp_args = list(acp_args or args or self._resolve_args())
  283. # The session's workspace, not the process cwd: under the gateway every turn runs in
  284. # the daemon (or a managed worker) whose own cwd is unrelated to the client's.
  285. self._acp_cwd = str(Path(acp_cwd or resolve_agent_cwd()).resolve())
  286. self.chat = SimpleNamespace(completions=SimpleNamespace(create=self._create_chat_completion))
  287. self.is_closed = False
  288. # Clients are cached and shared across concurrent callers (auxiliary tasks, async
  289. # dispatch), so several ACP sessions can be live on one instance. Track every live
  290. # child — a single slot would let one session's teardown kill a sibling's process
  291. # while its own leaked.
  292. self._active_processes: set[subprocess.Popen[str]] = set()
  293. self._active_process_lock = threading.Lock()
  294. @staticmethod
  295. def _terminate_process(proc: subprocess.Popen[str]) -> None:
  296. try:
  297. proc.terminate()
  298. proc.wait(timeout=2)
  299. except Exception:
  300. with contextlib.suppress(Exception):
  301. proc.kill()
  302. def _release_process(self, proc: subprocess.Popen[str]) -> None:
  303. """Reap one session's own child. ``is_closed`` flips only when the last live
  304. session drains — marking it while siblings still run would tell lifecycle code
  305. to rebuild a client that is mid-request."""
  306. with self._active_process_lock:
  307. self._active_processes.discard(proc)
  308. if not self._active_processes:
  309. self.is_closed = True
  310. self._terminate_process(proc)
  311. def close(self) -> None:
  312. with self._active_process_lock:
  313. procs, self._active_processes = tuple(self._active_processes), set()
  314. self.is_closed = True
  315. for proc in procs:
  316. self._terminate_process(proc)
  317. def _create_chat_completion(
  318. self, *, model: str | None = None, messages: list[dict[str, Any]] | None = None, timeout: float | None = None,
  319. tools: list[dict[str, Any]] | None = None, tool_choice: Any = None, stream: bool = False, **_: Any,
  320. ) -> Any:
  321. prompt_text = _format_messages_as_prompt(messages or [], model=model, tools=tools, tool_choice=tool_choice)
  322. response_text, reasoning = self._run_prompt(prompt_text, timeout_seconds=_effective_timeout(timeout), model=model)
  323. tool_calls, cleaned_text = _extract_tool_calls_from_text(response_text)
  324. message = SimpleNamespace(
  325. content=cleaned_text, tool_calls=tool_calls, reasoning=reasoning or None, reasoning_content=reasoning or None,
  326. reasoning_details=None,
  327. )
  328. completion = SimpleNamespace(
  329. choices=[SimpleNamespace(message=message, finish_reason="tool_calls" if tool_calls else "stop")],
  330. usage=SimpleNamespace(prompt_tokens=0, completion_tokens=0, total_tokens=0, prompt_tokens_details=SimpleNamespace(cached_tokens=0)),
  331. model=model or self.placeholder_model,
  332. )
  333. return _completion_to_stream_chunks(completion) if stream else completion
  334. def _spawn(self) -> subprocess.Popen[str]:
  335. # Fast-fail when the CLI rejects --acp (else the parent waits the full child timeout for stdout that
  336. # never arrives). ``None`` falls through to the spawn's established start error.
  337. if _acp_supported(self._acp_command, self._acp_args) is False:
  338. preview = " ".join(self._acp_args[:3]) if self._acp_args else "(none)"
  339. raise RuntimeError(
  340. f"ACP transport not supported by '{self._acp_command}': `{preview}` is rejected as an unknown option. This "
  341. "usually means the CLI is an older release (e.g. Claude Code v2.x) or a different tool than expected. "
  342. + self.unsupported_transport_hint
  343. )
  344. try:
  345. from hermes_cli._subprocess_compat import windows_hide_flags # hide the Windows console flash (#56747); pipes intact for the ACP wire
  346. # Hide the console the CLI child would otherwise flash on Windows (#56747). Hide-only — stdio
  347. # pipes stay intact for the ACP wire.
  348. proc = subprocess.Popen(
  349. [self._acp_command] + self._acp_args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
  350. text=True, encoding='utf-8', errors='replace', bufsize=1, cwd=self._acp_cwd, env=_build_subprocess_env(),
  351. creationflags=windows_hide_flags(),
  352. )
  353. except FileNotFoundError as exc:
  354. raise RuntimeError(
  355. f"Could not start {self.label} command '{self._acp_command}'. {self._missing_command_hint()}") from exc
  356. if proc.stdin is None or proc.stdout is None:
  357. proc.kill()
  358. raise RuntimeError(f"{self.label} process did not expose stdin/stdout pipes.")
  359. with self._active_process_lock:
  360. self._active_processes.add(proc)
  361. self.is_closed = False
  362. return proc
  363. @contextlib.contextmanager
  364. def _session(
  365. self, timeout_seconds: float, *, allow_file_requests: bool = True
  366. ) -> Iterator[tuple[dict[str, Any], Callable[..., Any]]]:
  367. """Start one ACP process and yield its ``session/new`` result plus request callable."""
  368. proc = self._spawn()
  369. inbox: queue.Queue[dict[str, Any]] = queue.Queue()
  370. stderr_tail: deque[str] = deque(maxlen=40)
  371. def _decode(line: str) -> dict[str, Any]:
  372. try:
  373. return json.loads(line)
  374. except Exception:
  375. return {"raw": line.rstrip("\n")}
  376. def _pump(stream, sink) -> None:
  377. for line in stream or ():
  378. sink(line)
  379. threading.Thread(target=_pump, args=(proc.stdout, lambda line: inbox.put(_decode(line))), daemon=True).start()
  380. stderr_pump = threading.Thread(
  381. target=_pump, args=(proc.stderr, lambda line: stderr_tail.append(line.rstrip("\n"))), daemon=True)
  382. stderr_pump.start()
  383. request_ids = iter(range(1, 1 << 62))
  384. # One budget for the WHOLE session (initialize + session/new + any prompt), not per
  385. # request: a hung CLI must not get 2x the caller's timeout on the foreground /model path.
  386. session_deadline = time.monotonic() + timeout_seconds
  387. def _request(method: str, params: dict[str, Any], *, text_parts: list[str] | None = None,
  388. reasoning_parts: list[str] | None = None) -> Any:
  389. request_id = next(request_ids)
  390. try:
  391. proc.stdin.write(json.dumps({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params}) + "\n")
  392. proc.stdin.flush()
  393. except OSError as exc: # the CLI stopped reading: EPIPE, or EINVAL on a Windows pipe
  394. if not isinstance(exc, BrokenPipeError) and exc.errno != errno.EINVAL:
  395. raise
  396. with contextlib.suppress(subprocess.TimeoutExpired):
  397. proc.wait(timeout=5) # dying: report its exit text below, not a bare EPIPE
  398. if proc.poll() is None: # alive but deaf: fail now, not after the whole request timeout
  399. raise
  400. deadline = session_deadline
  401. while time.monotonic() < deadline and proc.poll() is None:
  402. try:
  403. msg = inbox.get(timeout=0.1)
  404. except queue.Empty:
  405. continue
  406. if self._handle_server_message(
  407. msg, process=proc, cwd=self._acp_cwd, text_parts=text_parts,
  408. reasoning_parts=reasoning_parts, allow_file_requests=allow_file_requests,
  409. ) or msg.get("id") != request_id:
  410. continue
  411. if "error" in msg:
  412. raise RuntimeError(self._request_error(method, msg.get("error") or {}))
  413. return msg.get("result")
  414. if proc.poll() is not None:
  415. # The pump can still hold the crash text when poll() first sees the exit; reading
  416. # it too early turned a dead CLI into a TimeoutError, which retries differently.
  417. stderr_pump.join(timeout=1.0)
  418. stderr_text = "\n".join(stderr_tail).strip()
  419. if (vendor_error := self.early_exit_error(stderr_text)) is not None:
  420. raise RuntimeError(vendor_error)
  421. raise RuntimeError(f"{self.label} process exited early: {stderr_text or f'exit code {proc.returncode}'}")
  422. raise TimeoutError(f"Timed out waiting for {self.label} response to {method}.")
  423. try:
  424. _request("initialize", _INITIALIZE_PARAMS)
  425. session = _request("session/new", {"cwd": self._acp_cwd, "mcpServers": []}) or {}
  426. if not str(session.get("sessionId") or "").strip():
  427. raise RuntimeError(f"{self.label} did not return a sessionId.")
  428. yield session, _request
  429. finally:
  430. self._release_process(proc)
  431. def list_models(self, *, timeout_seconds: float = 15.0) -> list[str]:
  432. """Return the enabled models advertised by a short-lived authenticated ACP session."""
  433. with self._session(timeout_seconds, allow_file_requests=False) as (session, _):
  434. return _session_model_ids(session, self.model_entry_disabled)
  435. def _run_prompt(self, prompt_text: str, *, timeout_seconds: float, model: str | None = None) -> tuple[str, str]:
  436. # No `--model` spawn flag: agent CLIs may validate it (an unknown id aborts the spawn) yet ignore it
  437. # for the session, so the model is applied over ACP after session/new instead.
  438. requested_model = str(model or "").strip()
  439. with self._session(timeout_seconds) as (session, _request):
  440. session_id = str(session.get("sessionId") or "").strip()
  441. if requested_model and requested_model != self.placeholder_model:
  442. try:
  443. selection = _model_selection_request(
  444. session, requested_model, placeholder=self.placeholder_model, disabled=self.model_entry_disabled)
  445. if selection is not None:
  446. _request(*selection)
  447. else:
  448. logger.warning("%s does not offer model %r; using the session default.", self.label, requested_model)
  449. # _request raises RuntimeError/TimeoutError/OSError (broken pipe); vendor ``session/new`` payload
  450. # drift (e.g. a non-list ``configOptions``) raises TypeError/AttributeError in the parsers.
  451. # Either way model choice degrades to the session default instead of failing the turn.
  452. except (RuntimeError, TimeoutError, OSError, TypeError, AttributeError) as exc:
  453. logger.warning("%s model selection for %r failed; continuing with the session default: %s",
  454. self.label, requested_model, exc)
  455. text_parts: list[str] = []
  456. reasoning_parts: list[str] = []
  457. prompt = {"sessionId": session_id, "prompt": [{"type": "text", "text": prompt_text}]}
  458. _request("session/prompt", prompt, text_parts=text_parts, reasoning_parts=reasoning_parts)
  459. return "".join(text_parts), "".join(reasoning_parts)
  460. def _handle_server_message(
  461. self, msg: dict[str, Any], *, process: subprocess.Popen[str], cwd: str, text_parts: list[str] | None, reasoning_parts: list[str] | None,
  462. allow_file_requests: bool = True,
  463. ) -> bool:
  464. """Consume a server->client message; True when handled (notification or request answered)."""
  465. method = msg.get("method")
  466. if not isinstance(method, str):
  467. return False
  468. if method == "session/update":
  469. update = (msg.get("params") or {}).get("update") or {}
  470. content = update.get("content") or {}
  471. chunk_text = str(content.get("text") or "") if isinstance(content, dict) else ""
  472. sinks = {"agent_message_chunk": text_parts, "agent_thought_chunk": reasoning_parts}
  473. if chunk_text and (sink := sinks.get(str(update.get("sessionUpdate") or "").strip())) is not None:
  474. sink.append(chunk_text)
  475. return True
  476. if process.stdin is None:
  477. return True
  478. message_id = msg.get("id")
  479. if method == "session/request_permission":
  480. response = _jsonrpc_result(message_id, {"outcome": {"outcome": "cancelled"}})
  481. elif method in _FS_HANDLERS:
  482. if not allow_file_requests:
  483. response = _jsonrpc_error(message_id, -32601, "File access is unavailable during model discovery.")
  484. else:
  485. try:
  486. response = _jsonrpc_result(message_id, _FS_HANDLERS[method](msg.get("params") or {}, cwd))
  487. except Exception as exc:
  488. response = _jsonrpc_error(message_id, -32602, str(exc))
  489. else:
  490. response = _jsonrpc_error(message_id, -32601, f"ACP client method '{method}' is not supported by Hermes yet.")
  491. process.stdin.write(json.dumps(response) + "\n")
  492. process.stdin.flush()
  493. return True