`gj*dZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl m Z mZ ddlZe j j#d ZddgZd Zd Zd Zdd ZGd deZGddZy#e$rdZdZY/wxYw)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 PtyBridgePtyUnavailableErroriic t|}|tkrtS||kDr|S|S#tttf$r tcYSwxYw)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``. )int TypeError ValueError OverflowError_MIN_DIMENSION)valuemaximumns H/root/.hermes/venv/lib/python3.12/site-packages/hermes_cli/pty_bridge.py_clamp_dimensionr?sO  J >7{ H z= 1s %AAceZdZdZy)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__rrrPsrceZdZdZddZeddZeddddd ddZedd Z dd Z ddd Z dd Z dd Z ddZddZddZy)ruThin 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. cB||_|j|_d|_yNF)_procfd_fd_closed)selfprocs r__init__zPtyBridge.__init__ds  rc ttS)z.True if a PTY can be spawned on this platform.)bool_PTY_AVAILABLE)clss r is_availablezPtyBridge.is_availableksN##rNP)cwdenvcolsrowsctsFtjjdr t dt t dt d|t jjn|j}|jdsd|d<t jjt|||||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.zgThe `ptyprocess` package is missing. Install with: pip install ptyprocess (or pip install -e '.[pty]').z!Pseudo-terminals are unavailable.TERMzxterm-256color)r-r. dimensions) r(sysplatform startswithr ptyprocessosenvironcopyget PtyProcessspawnlist)r)argvr-r.r/r0 spawn_envr$s rr=zPtyBridge.spawnps ||&&u-)B!)4 &&IJ J +.+RZZ__&388: }}V$ 0If $$** Jd| +  4yrc@t|jjSN)r rpidr#s rrCz PtyBridge.pids4::>>""rc|jry t|jjS#t$rYywxYwr)r"r'risalive ExceptionrDs ris_alivezPtyBridge.is_alives; <<  **,- -  s "2 >>cn|jry tj|jggg|\}}}|sy t j |jd}|sy|S#ttf$rYywxYw#t$r7}|jtjtjhvrYd}~yd}~wwxYw)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!OSErrorr r8readerrnoEIOEBADF)r#timeoutreadable_dataexcs rrLzPtyBridge.reads << #]]DHH:r2wGNHa 77488U+D  $    yyUYY 44   s.'A A4A10A14 B4=,B/.B//B4c@|js|syt|}|r0 tj|j|}|dkry||d}|r/yy#t $rF}|j t jt jt jhvrYd}~yd}~wwxYw)z;Write raw bytes to the PTY master (i.e. the child's stdin).Nr) r" memoryviewr8writer!rKrMrNrOEPIPE)r#rSviewrrTs rrWzPtyBridge.writes <   s/A88 BBcH|jryd|_ tj|jj}t jt jt jfD]}|jjsn |tj||n|jj|tjdz}|jjstj|kstjd|jjstj|krH |jj!dy#t $rd}YCwxYw#t $rYwxYw#t $rYywxYw)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"r8getpgidrrCrGsignalSIGHUPSIGTERMSIGKILLrFkillpgkilltime monotonicsleepclose)r#pgidsigdeadlines rrrzPtyBridge.closesC <<   ::djjnn-DMM6>>6>>B !C::%%' #IIdC(JJOOC(~~'#-H**$$&4>>+;h+F 4 **$$&4>>+;h+F !  JJ  4  (- D      s5)E44FF4 FF FF F! F!c|SrBrrDs r __enter__zPtyBridge.__enter__s rc$|jyrB)rr)r#_excs r__exit__zPtyBridge.__exit__s  r)r$z'ptyprocess.PtyProcess')returnr') r?z Sequence[str]r-z Optional[str]r.zOptional[dict]r/r r0r r{ 'PtyBridge')r{r )g?)rPfloatr{zOptional[bytes])rSbytesr{None)r/r r0r r{r)r{r)r{r|)rrrrr% classmethodr*r=propertyrCrHrLrWrerrrwrzrrrrrYs$$ ""** *  *  ** **X##<"2$Nr)rr rr r{r )r __future__rrMr`r8rJrir^r4rbrotypingrrr7r5r6r( ImportError__all__rr\r]r RuntimeErrorrrrrrrs8#  %0077N - .    ",EEYJNs A:: BB