"""Windows ConPTY bridge for the `hermes dashboard` chat tab.""" from __future__ import annotations import asyncio import logging import select import sys from typing import Optional, Sequence try: from winpty import PtyProcess # type: ignore _PTY_AVAILABLE = sys.platform.startswith("win") except ImportError: # pragma: no cover - non-Windows or pywinpty missing PtyProcess = None # type: ignore _PTY_AVAILABLE = False _log = logging.getLogger(__name__) __all__ = ["PtyUnavailableError", "WinPtyBridge"] # Same clamp ceiling as the POSIX bridge so a broken winsize probe never reaches the resize call. _MIN_DIMENSION = 1 _MAX_COLS = 2000 _MAX_ROWS = 1000 _WRITE_TIMEOUT = 10.0 _WRITE_SHUTDOWN_GRACE = 1.0 def _clamp(value: int, maximum: int) -> int: try: n = int(value) except (TypeError, ValueError, OverflowError): return _MIN_DIMENSION return max(_MIN_DIMENSION, min(n, maximum)) class PtyUnavailableError(RuntimeError): """Raised when a PTY cannot be created on this platform.""" class WinPtyBridge: """pywinpty-backed bridge with the same interface as ``PtyBridge``. ``read`` runs inside ``run_in_executor`` and, like the POSIX bridge, returns within its timeout; writes run in a worker thread to keep the same non-blocking event-loop contract as the POSIX bridge.""" def __init__(self, proc: PtyProcess) -> None: # type: ignore[name-defined] self._proc = proc self._closed = False # Deadline guards for writes whose caller left while they waited on a fence. self._late_writes: set[asyncio.Task] = set() @classmethod def is_available(cls) -> bool: return bool(_PTY_AVAILABLE) @classmethod def spawn( cls, argv: Sequence[str], *, cwd: Optional[str] = None, env: Optional[dict] = None, cols: int = 80, rows: int = 24) -> WinPtyBridge: if not _PTY_AVAILABLE: if PtyProcess is None: raise PtyUnavailableError("pywinpty is not installed. Run hermes pm repair, then restart Hermes.") raise PtyUnavailableError("ConPTY is unavailable on this platform.") # See pty_bridge.py: exact-preservation factory for the env=None fallback. from tools.environments.local import build_subprocess_env spawn_env = ( build_subprocess_env(scrub_secrets=False, inherit_profile_home=False) if env is None else dict(env)) spawn_env["TERM"] = spawn_env.get("TERM") or "xterm-256color" # pywinpty mirrors ptyprocess: dimensions=(rows, cols). return cls(PtyProcess.spawn(list(argv), cwd=cwd, env=spawn_env, dimensions=(rows, cols))) # type: ignore[union-attr] @property def pid(self) -> int: return int(self._proc.pid) def is_alive(self) -> bool: try: return not self._closed and bool(self._proc.isalive()) except Exception: return False def read(self, timeout: float = 0.2) -> Optional[bytes]: """Up to 64 KiB of child output, waiting at most ``timeout`` seconds for it. ``b""`` = nothing yet; ``None`` = EOF / closed (also after :meth:`close`). """ if self._closed: return None # pywinpty's read is a blocking recv on the loopback socket its reader thread # fills (``fileno()``). Unbounded, an idle shell would hold this executor # thread until it next printed, and a few quiet terminals would take every # default-executor thread (min(32, cpu count + 4)) from keystrokes and cleanup. try: readable, _, _ = select.select([self._proc], [], [], timeout) if not readable: return b"" data = self._proc.read(65536) # pywinpty returns str except Exception: return None if not data: return b"" # pywinpty's placeholder for an empty ConPTY read if isinstance(data, bytes): return data # pywinpty decodes internally, so a multibyte UTF-8 sequence can split across reads; # xterm.js tolerates the rare replacement char (the one fidelity tradeoff vs POSIX). return data.encode("utf-8", errors="replace") def _write_blocking(self, data: bytes) -> bool: if self._closed: return False if not data: return True try: self._proc.write(data.decode("utf-8", errors="replace")) # pywinpty wants text except Exception: return False return True async def write(self, data: bytes, *, timeout: Optional[float] = _WRITE_TIMEOUT, fence=None) -> bool: """Write off-loop and tear down ConPTY when its input pipe wedges. ``fence`` (see ``PtyBridge.write``) wraps the whole blocking write, and whatever it raises propagates. Waiting to enter the fence is not a stall: its profile lease can be held by other work (a cold SessionDB open, an attachment write) for longer than the deadline, so the deadline starts when the bytes reach ConPTY. ConPTY takes input whether or not the child reads it (conhost buffers it), so a write that misses the deadline means ConPTY itself is wedged: ``timeout=None``, which on POSIX waits for the child to read, still gets that deadline here and never holds the fence open-ended. ``wait_for(to_thread(...))`` alone only cancels the asyncio wrapper; the worker remains blocked inside pywinpty. Keep the worker future, force-close the ConPTY on timeout, and wait briefly for that close to release the blocked write before returning. Cancellation (the owning socket went away mid-write) is not evidence of a wedged child: the PTY outlives its socket by design, so give the in-flight write the grace window and only terminate if it never lands. A write cancelled while it still waits for its fence keeps waiting off the loop and gets the deadline once it reaches ConPTY. """ if self._closed: return False if not data: return True loop = asyncio.get_running_loop() entered = asyncio.Event() def enter_conpty(chunk: bytes) -> bool: loop.call_soon_threadsafe(entered.set) return self._write_blocking(chunk) if fence is None: entered.set() write = self._write_blocking else: def write(chunk: bytes): return fence(lambda: enter_conpty(chunk)) write_future = loop.run_in_executor(None, write, data) deadline = _WRITE_TIMEOUT if timeout is None else max(0.0, timeout) try: if not await self._entered_conpty(entered, write_future): return await write_future # the fence refused: its result, or what it raised except asyncio.CancelledError: if entered.is_set(): await asyncio.shield(self._settle_or_stop_write(write_future)) else: self._bound_late_write(entered, write_future, deadline) raise try: return await asyncio.wait_for(asyncio.shield(write_future), timeout=deadline) except TimeoutError: await self._stop_stalled_write(write_future) return False except asyncio.CancelledError: await asyncio.shield(self._settle_or_stop_write(write_future)) raise @staticmethod async def _entered_conpty(entered: asyncio.Event, write_future: asyncio.Future) -> bool: """Wait, with no deadline, until the write reaches ConPTY or the fence returns without it.""" if entered.is_set(): return True entering = asyncio.ensure_future(entered.wait()) try: await asyncio.wait({entering, write_future}, return_when=asyncio.FIRST_COMPLETED) finally: entering.cancel() return entered.is_set() def _bound_late_write(self, entered: asyncio.Event, write_future: asyncio.Future, deadline: float) -> None: """Hold a write cancelled before its fence admitted it to the deadline once it reaches ConPTY.""" async def bound() -> None: if await self._entered_conpty(entered, write_future): done, _ = await asyncio.wait({write_future}, timeout=deadline) if not done: await self._stop_stalled_write(write_future) return # Nobody awaits this write any more, so report what it raised here. if not write_future.cancelled() and (error := write_future.exception()) is not None: _log.debug("Host terminal write failed after its caller left", exc_info=error) task = asyncio.get_running_loop().create_task(bound()) self._late_writes.add(task) task.add_done_callback(self._late_writes.discard) async def _settle_or_stop_write(self, write_future: asyncio.Future) -> None: """Let a cancelled write finish within the grace window; terminate only if it stalls.""" try: await asyncio.wait_for(asyncio.shield(write_future), timeout=_WRITE_SHUTDOWN_GRACE) return except TimeoutError: pass except Exception: return await self._stop_stalled_write(write_future) async def _stop_stalled_write(self, write_future: asyncio.Future) -> None: """Close ConPTY and reap the worker that was blocked in ``write``.""" await asyncio.to_thread(self.close) try: await asyncio.wait_for( asyncio.shield(write_future), timeout=_WRITE_SHUTDOWN_GRACE, ) except TimeoutError: # The worker is still parked inside pywinpty after terminate(); it # now occupies a default-executor thread until the process exits. _log.warning( "ConPTY write worker did not exit within %.1fs of terminate(); thread leaked", _WRITE_SHUTDOWN_GRACE, ) except Exception: pass def resize(self, cols: int, rows: int) -> None: if self._closed: return cols = _clamp(cols, _MAX_COLS) rows = _clamp(rows, _MAX_ROWS) try: self._proc.setwinsize(rows, cols) # pywinpty: (rows, cols) except Exception: pass def close(self) -> None: if self._closed: return self._closed = True try: self._proc.terminate(force=True) except Exception: pass def __enter__(self) -> WinPtyBridge: return self def __exit__(self, *_exc) -> None: self.close()