|+j* dZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl m Z mZ ddlZe jd Zn#e$rdZdZYnwxYwddgZd Zd Zd ZddZGddeZGddZdS)uPTY bridge for `hermes dashboard` chat tab. Wraps a child process behind a pseudo-terminal so its ANSI output can be streamed to a browser-side terminal emulator (xterm.js) and typed keystrokes can be fed back in. The only caller today is the ``/api/pty`` WebSocket endpoint in ``hermes_cli.web_server``. Design constraints: * **POSIX-only.** This module depends on ``fcntl``, ``termios``, and ``ptyprocess``, none of which exist on native Windows Python. Native Windows ConPTY is a different API (Windows 10 build 17763+) and would need a separate Windows implementation (``pywinpty``) — that's tracked as a future enhancement. On native Windows, importing this module raises :class:`ImportError` and the dashboard's ``/chat`` tab shows a WSL-recommended banner instead of crashing. Every other feature in the dashboard (sessions, jobs, metrics, config editor) works natively. * **Zero Node dependency on the server side.** We use :mod:`ptyprocess`, which is a pure-Python wrapper around the OS calls. The browser talks to the same ``hermes --tui`` binary it would launch from the CLI, so every TUI feature (slash popover, model picker, tool rows, markdown, skin engine, clarify/sudo/approval prompts) ships automatically. * **Byte-safe I/O.** Reads and writes go through the PTY master fd directly — we avoid :class:`ptyprocess.PtyProcessUnicode` because streaming ANSI is inherently byte-oriented and UTF-8 boundaries may land mid-read. ) annotationsN)OptionalSequencewinF PtyBridgePtyUnavailableErroriivalueintmaximumreturnc t|}n$#tttf$r tcYSwxYw|tkrtS||kr|S|S)zClamp a reported terminal dimension into ``[_MIN_DIMENSION, maximum]``. Non-integer / non-finite values fall back to ``_MIN_DIMENSION`` so a bad probe can never reach ``struct.pack`` and raise ``struct.error``. )r TypeError ValueError OverflowError_MIN_DIMENSION)r r ns 4/usr/local/lib/hermes-agent/hermes_cli/pty_bridge.py_clamp_dimensionr?sf  JJ z= 1>7{{ Hs 33ceZdZdZdS)rzRaised when a PTY cannot be created on this platform. Today this means native Windows (no ConPTY bindings) or a dev environment missing the ``ptyprocess`` dependency. The dashboard surfaces the message to the user as a chat-tab banner. N)__name__ __module__ __qualname____doc__rrrPsrceZdZdZd&dZed'dZeddd d d d(dZed)dZ d'dZ d*d+dZ d,d!Z d-d"Z d.d#Zd/d$Zd.d%ZdS)0ruThin wrapper around ``ptyprocess.PtyProcess`` for byte streaming. Not thread-safe. A single bridge is owned by the WebSocket handler that spawned it; the reader runs in an executor thread while writes happen on the event-loop thread. Both sides are OK because the kernel PTY is the actual synchronization point — we never call :mod:`ptyprocess` methods concurrently, we only call ``os.read`` and ``os.write`` on the master fd, which is safe. proc'ptyprocess.PtyProcess'c:||_|j|_d|_dSNF)_procfd_fd_closed)selfrs r__init__zPtyBridge.__init__ds  rr boolc*ttS)z.True if a PTY can be spawned on this platform.)r(_PTY_AVAILABLE)clss r is_availablezPtyBridge.is_availableksN###rNP)cwdenvcolsrowsargv Sequence[str]r/ Optional[str]r0Optional[dict]r1r r2 'PtyBridge'ctsStjdrt dt t dt d|t jn|}| dsd|d<t j t|||||f}||S) aSpawn ``argv`` behind a new PTY and return a bridge. Raises :class:`PtyUnavailableError` if the platform can't host a PTY. Raises :class:`FileNotFoundError` or :class:`OSError` for ordinary exec failures (missing binary, bad cwd, etc.). rz^Pseudo-terminals are unavailable on this platform. Hermes Agent supports Windows only via WSL.NzgThe `ptyprocess` package is missing. Install with: pip install ptyprocess (or pip install -e '.[pty]').z!Pseudo-terminals are unavailable.TERMzxterm-256color)r/r0 dimensions) r*sysplatform startswithr ptyprocessosenvironcopyget PtyProcessspawnlist)r+r3r/r0r1r2 spawn_envrs rrDzPtyBridge.spawnps  K|&&u-- )B!)4 &&IJJ J +.+RZ__&&&388:: }}V$$ 1 0If $** JJd| +   s4yyrc4t|jjSN)r r"pidr&s rrIz PtyBridge.pids4:>"""rc|jrdS t|jS#t$rYdSwxYwr!)r%r(r"isalive ExceptionrJs ris_alivezPtyBridge.is_alivesT < 5  **,,-- -   55 s %1 ??皙?timeoutfloatOptional[bytes]cF|jrdS tj|jggg|\}}}n#ttf$rYdSwxYw|sdS t j|jd}n8#t$r+}|jtjtj hvrYd}~dSd}~wwxYw|sdS|S)uRead up to 64 KiB of raw bytes from the PTY master. Returns: * bytes — zero or more bytes of child output * empty bytes (``b""``) — no data available within ``timeout`` * None — child has exited and the master fd is at EOF Never blocks longer than ``timeout`` seconds. Safe to call after :meth:`close`; returns ``None`` in that case. Nri) r%selectr$OSErrorrr?readerrnoEIOEBADF)r&rPreadable_dataexcs rrVzPtyBridge.reads < 4 #]DH:r2wGGNHa$   44  3 748U++DD   yUY 444ttttt     4 s-!-AA A%% B/BBBr\bytesNonec(|js|sdSt|}|ru tj|j|}nC#t $r6}|jt jt jt j hvrYd}~dSd}~wwxYw|dkrdS||d}|sdSdS)z;Write raw bytes to the PTY master (i.e. the child's stdin).Nr) r% memoryviewr?writer$rUrWrXrYEPIPE)r&r\viewrr]s rrbzPtyBridge.writes < t  F$  HTXt,,   9EK EEEFFFFF Avv8D     s9 A9*A43A44A9c |jrdSt|t}t|t}t jd||dd} t j|jtj |dS#t$rYdSwxYw)uForward a terminal resize to the child via ``TIOCSWINSZ``. Dimensions are clamped to a sane range first. Some hosts report garbage window sizes — the motivating case is WSL2, where xterm.js in the dashboard ``/chat`` tab can pick up ``columns=131072, rows=1`` from a broken winsize probe. ``struct winsize`` packs each field as an unsigned short (max 65535), so an unclamped 131072 would raise ``struct.error`` (not ``OSError``) and break the resize path, leaving the TUI laid out for a one-row / absurdly-wide screen — which is what shows up as blank / disappearing text. NHHHHr) r%r _MAX_COLS _MAX_ROWSstructpackfcntlioctlr$termios TIOCSWINSZrU)r&r1r2winsizes rresizezPtyBridge.resizes <  Fi00i00+fdD!Q77  K'"4g > > > > >    DD s %A44 BBc|jrdSd|_ tj|jj}n#t $rd}YnwxYwt jt jt j fD]}|j sn |tj ||n|j |n#t $rYnwxYwtjdz}|j r[tj|krDtjd|j rtj|kD |jddS#t $rYdSwxYw)uTerminate the child (SIGTERM → 0.5s grace → SIGKILL) and close fds. Idempotent. Reaping the child is important so we don't leak zombies across the lifetime of the dashboard process. NTg?g{Gz?)force)r%r?getpgidr"rIrMsignalSIGHUPSIGTERMSIGKILLrLkillpgkilltime monotonicsleepclose)r&pgidsigdeadlines rr}zPtyBridge.closes <  F  :djn--DD   DDD M6>6>B ! !C:%%''  #IdC((((JOOC(((    ~''#-H*$$&& !4>+;+;h+F+F 4   *$$&& !4>+;+;h+F+F  J  4  ( ( ( ( (    DD s21 AA2B77 CCE00 E>=E>c|SrHrrJs r __enter__zPtyBridge.__enter__s rc.|dSrH)r})r&_excs r__exit__zPtyBridge.__exit__s r)rr)r r() r3r4r/r5r0r6r1r r2r r r7)r r )rO)rPrQr rR)r\r^r r_)r1r r2r r r_)r r_)r r7)rrrrr' classmethodr,rDpropertyrIrNrVrbrpr}rrrrrrrYs=$$$[$ ""*****[*X###X#<"2$$$$Nr)r r r r r r )r __future__rrWrkr?rTrtrir;rmrztypingrrr>r<r=r* ImportError__all__rrgrhr RuntimeErrorrrrrrrsx8#"""""  %%%%%%%%00777NNJNNN - .       ",EEEEEEEEEEsA A"!A"