win_pty_bridge.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264
  1. """Windows ConPTY bridge for the `hermes dashboard` chat tab."""
  2. from __future__ import annotations
  3. import asyncio
  4. import logging
  5. import select
  6. import sys
  7. from typing import Optional, Sequence
  8. try:
  9. from winpty import PtyProcess # type: ignore
  10. _PTY_AVAILABLE = sys.platform.startswith("win")
  11. except ImportError: # pragma: no cover - non-Windows or pywinpty missing
  12. PtyProcess = None # type: ignore
  13. _PTY_AVAILABLE = False
  14. _log = logging.getLogger(__name__)
  15. __all__ = ["PtyUnavailableError", "WinPtyBridge"]
  16. # Same clamp ceiling as the POSIX bridge so a broken winsize probe never reaches the resize call.
  17. _MIN_DIMENSION = 1
  18. _MAX_COLS = 2000
  19. _MAX_ROWS = 1000
  20. _WRITE_TIMEOUT = 10.0
  21. _WRITE_SHUTDOWN_GRACE = 1.0
  22. def _clamp(value: int, maximum: int) -> int:
  23. try:
  24. n = int(value)
  25. except (TypeError, ValueError, OverflowError):
  26. return _MIN_DIMENSION
  27. return max(_MIN_DIMENSION, min(n, maximum))
  28. class PtyUnavailableError(RuntimeError):
  29. """Raised when a PTY cannot be created on this platform."""
  30. class WinPtyBridge:
  31. """pywinpty-backed bridge with the same interface as ``PtyBridge``. ``read`` runs inside
  32. ``run_in_executor`` and, like the POSIX bridge, returns within its timeout; writes run in a
  33. worker thread to keep the same non-blocking event-loop contract as the POSIX bridge."""
  34. def __init__(self, proc: PtyProcess) -> None: # type: ignore[name-defined]
  35. self._proc = proc
  36. self._closed = False
  37. # Deadline guards for writes whose caller left while they waited on a fence.
  38. self._late_writes: set[asyncio.Task] = set()
  39. @classmethod
  40. def is_available(cls) -> bool:
  41. return bool(_PTY_AVAILABLE)
  42. @classmethod
  43. def spawn(
  44. cls, argv: Sequence[str], *, cwd: Optional[str] = None, env: Optional[dict] = None,
  45. cols: int = 80, rows: int = 24) -> WinPtyBridge:
  46. if not _PTY_AVAILABLE:
  47. if PtyProcess is None:
  48. raise PtyUnavailableError("pywinpty is not installed. Run hermes pm repair, then restart Hermes.")
  49. raise PtyUnavailableError("ConPTY is unavailable on this platform.")
  50. # See pty_bridge.py: exact-preservation factory for the env=None fallback.
  51. from tools.environments.local import build_subprocess_env
  52. spawn_env = (
  53. build_subprocess_env(scrub_secrets=False, inherit_profile_home=False)
  54. if env is None else dict(env))
  55. spawn_env["TERM"] = spawn_env.get("TERM") or "xterm-256color"
  56. # pywinpty mirrors ptyprocess: dimensions=(rows, cols).
  57. return cls(PtyProcess.spawn(list(argv), cwd=cwd, env=spawn_env, dimensions=(rows, cols))) # type: ignore[union-attr]
  58. @property
  59. def pid(self) -> int:
  60. return int(self._proc.pid)
  61. def is_alive(self) -> bool:
  62. try:
  63. return not self._closed and bool(self._proc.isalive())
  64. except Exception:
  65. return False
  66. def read(self, timeout: float = 0.2) -> Optional[bytes]:
  67. """Up to 64 KiB of child output, waiting at most ``timeout`` seconds for it.
  68. ``b""`` = nothing yet; ``None`` = EOF / closed (also after :meth:`close`).
  69. """
  70. if self._closed:
  71. return None
  72. # pywinpty's read is a blocking recv on the loopback socket its reader thread
  73. # fills (``fileno()``). Unbounded, an idle shell would hold this executor
  74. # thread until it next printed, and a few quiet terminals would take every
  75. # default-executor thread (min(32, cpu count + 4)) from keystrokes and cleanup.
  76. try:
  77. readable, _, _ = select.select([self._proc], [], [], timeout)
  78. if not readable:
  79. return b""
  80. data = self._proc.read(65536) # pywinpty returns str
  81. except Exception:
  82. return None
  83. if not data:
  84. return b"" # pywinpty's placeholder for an empty ConPTY read
  85. if isinstance(data, bytes):
  86. return data
  87. # pywinpty decodes internally, so a multibyte UTF-8 sequence can split across reads;
  88. # xterm.js tolerates the rare replacement char (the one fidelity tradeoff vs POSIX).
  89. return data.encode("utf-8", errors="replace")
  90. def _write_blocking(self, data: bytes) -> bool:
  91. if self._closed:
  92. return False
  93. if not data:
  94. return True
  95. try:
  96. self._proc.write(data.decode("utf-8", errors="replace")) # pywinpty wants text
  97. except Exception:
  98. return False
  99. return True
  100. async def write(self, data: bytes, *, timeout: Optional[float] = _WRITE_TIMEOUT, fence=None) -> bool:
  101. """Write off-loop and tear down ConPTY when its input pipe wedges.
  102. ``fence`` (see ``PtyBridge.write``) wraps the whole blocking write, and
  103. whatever it raises propagates. Waiting to enter the fence is not a stall:
  104. its profile lease can be held by other work (a cold SessionDB open, an
  105. attachment write) for longer than the deadline, so the deadline starts
  106. when the bytes reach ConPTY. ConPTY takes input whether or not the child
  107. reads it (conhost buffers it), so a write that misses the deadline means
  108. ConPTY itself is wedged: ``timeout=None``, which on POSIX waits for the
  109. child to read, still gets that deadline here and never holds the fence
  110. open-ended.
  111. ``wait_for(to_thread(...))`` alone only cancels the asyncio wrapper;
  112. the worker remains blocked inside pywinpty. Keep the worker future,
  113. force-close the ConPTY on timeout, and wait briefly for that close to
  114. release the blocked write before returning.
  115. Cancellation (the owning socket went away mid-write) is not evidence
  116. of a wedged child: the PTY outlives its socket by design, so give the
  117. in-flight write the grace window and only terminate if it never lands.
  118. A write cancelled while it still waits for its fence keeps waiting off
  119. the loop and gets the deadline once it reaches ConPTY.
  120. """
  121. if self._closed:
  122. return False
  123. if not data:
  124. return True
  125. loop = asyncio.get_running_loop()
  126. entered = asyncio.Event()
  127. def enter_conpty(chunk: bytes) -> bool:
  128. loop.call_soon_threadsafe(entered.set)
  129. return self._write_blocking(chunk)
  130. if fence is None:
  131. entered.set()
  132. write = self._write_blocking
  133. else:
  134. def write(chunk: bytes):
  135. return fence(lambda: enter_conpty(chunk))
  136. write_future = loop.run_in_executor(None, write, data)
  137. deadline = _WRITE_TIMEOUT if timeout is None else max(0.0, timeout)
  138. try:
  139. if not await self._entered_conpty(entered, write_future):
  140. return await write_future # the fence refused: its result, or what it raised
  141. except asyncio.CancelledError:
  142. if entered.is_set():
  143. await asyncio.shield(self._settle_or_stop_write(write_future))
  144. else:
  145. self._bound_late_write(entered, write_future, deadline)
  146. raise
  147. try:
  148. return await asyncio.wait_for(asyncio.shield(write_future), timeout=deadline)
  149. except TimeoutError:
  150. await self._stop_stalled_write(write_future)
  151. return False
  152. except asyncio.CancelledError:
  153. await asyncio.shield(self._settle_or_stop_write(write_future))
  154. raise
  155. @staticmethod
  156. async def _entered_conpty(entered: asyncio.Event, write_future: asyncio.Future) -> bool:
  157. """Wait, with no deadline, until the write reaches ConPTY or the fence returns without it."""
  158. if entered.is_set():
  159. return True
  160. entering = asyncio.ensure_future(entered.wait())
  161. try:
  162. await asyncio.wait({entering, write_future}, return_when=asyncio.FIRST_COMPLETED)
  163. finally:
  164. entering.cancel()
  165. return entered.is_set()
  166. def _bound_late_write(self, entered: asyncio.Event, write_future: asyncio.Future, deadline: float) -> None:
  167. """Hold a write cancelled before its fence admitted it to the deadline once it reaches ConPTY."""
  168. async def bound() -> None:
  169. if await self._entered_conpty(entered, write_future):
  170. done, _ = await asyncio.wait({write_future}, timeout=deadline)
  171. if not done:
  172. await self._stop_stalled_write(write_future)
  173. return
  174. # Nobody awaits this write any more, so report what it raised here.
  175. if not write_future.cancelled() and (error := write_future.exception()) is not None:
  176. _log.debug("Host terminal write failed after its caller left", exc_info=error)
  177. task = asyncio.get_running_loop().create_task(bound())
  178. self._late_writes.add(task)
  179. task.add_done_callback(self._late_writes.discard)
  180. async def _settle_or_stop_write(self, write_future: asyncio.Future) -> None:
  181. """Let a cancelled write finish within the grace window; terminate only if it stalls."""
  182. try:
  183. await asyncio.wait_for(asyncio.shield(write_future), timeout=_WRITE_SHUTDOWN_GRACE)
  184. return
  185. except TimeoutError:
  186. pass
  187. except Exception:
  188. return
  189. await self._stop_stalled_write(write_future)
  190. async def _stop_stalled_write(self, write_future: asyncio.Future) -> None:
  191. """Close ConPTY and reap the worker that was blocked in ``write``."""
  192. await asyncio.to_thread(self.close)
  193. try:
  194. await asyncio.wait_for(
  195. asyncio.shield(write_future),
  196. timeout=_WRITE_SHUTDOWN_GRACE,
  197. )
  198. except TimeoutError:
  199. # The worker is still parked inside pywinpty after terminate(); it
  200. # now occupies a default-executor thread until the process exits.
  201. _log.warning(
  202. "ConPTY write worker did not exit within %.1fs of terminate(); thread leaked",
  203. _WRITE_SHUTDOWN_GRACE,
  204. )
  205. except Exception:
  206. pass
  207. def resize(self, cols: int, rows: int) -> None:
  208. if self._closed:
  209. return
  210. cols = _clamp(cols, _MAX_COLS)
  211. rows = _clamp(rows, _MAX_ROWS)
  212. try:
  213. self._proc.setwinsize(rows, cols) # pywinpty: (rows, cols)
  214. except Exception:
  215. pass
  216. def close(self) -> None:
  217. if self._closed:
  218. return
  219. self._closed = True
  220. try:
  221. self._proc.terminate(force=True)
  222. except Exception:
  223. pass
  224. def __enter__(self) -> WinPtyBridge:
  225. return self
  226. def __exit__(self, *_exc) -> None:
  227. self.close()