| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264 |
- """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()
|