j&" dZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl m Z mZ ddlZe jd Zn#e$rdZdZYnwxYwddgZGd deZGd dZdS) 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 PtyBridgePtyUnavailableErrorceZdZdZdS)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__4/usr/local/lib/hermes-agent/hermes_cli/pty_bridge.pyrr5srceZdZdZd&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__Is  rreturnboolc*ttS)z.True if a PTY can be spawned on this platform.)r_PTY_AVAILABLE)clss r is_availablezPtyBridge.is_availablePsN###rNP)cwdenvcolsrowsargv Sequence[str]r$ Optional[str]r%Optional[dict]r&intr' '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$r% dimensions) rsysplatform startswithr ptyprocessosenvironcopyget PtyProcessspawnlist)r r(r$r%r&r' spawn_envrs rr:zPtyBridge.spawnUs  K|&&u-- )B!)4 &&IJJ J +.+RZ__&&&388:: }}V$$ 1 0If $** JJd| +   s4yyrc4t|jjSN)r,rpidrs rr?z PtyBridge.pids4:>"""rc|jrdS t|jS#t$rYdSwxYwr)rrrisalive Exceptionr@s 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) rselectrOSError ValueErrorr5readerrnoEIOEBADF)rrFreadable_dataexcs rrMzPtyBridge.reads < 4 #]DH:r2wGGNHa$   44  3 748U++DD   yUY 444ttttt     4 s-!-AA A%% B/BBBrSbytesNonec(|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 memoryviewr5writerrKrNrOrPEPIPE)rrSviewnrTs rrYzPtyBridge.writes < t  F$  HTXt,,   9EK EEEFFFFF Avv8D     s9 A9*A43A44A9c|jrdStjdtd|td|dd} t j|jtj|dS#t$rYdSwxYw)z:Forward a terminal resize to the child via ``TIOCSWINSZ``.NHHHHr) rstructpackmaxfcntlioctlrtermios TIOCSWINSZrK)rr&r'winsizes rresizezPtyBridge.resizes~ <  F+fc!TllC4LL!QGG  K'"4g > > > > >    DD s%A&& A43A4cn|jrdSd|_tjtjtjfD]}|jsn |j|n#t$rYnwxYwtj dz}|jr[tj |krDtj d|jrtj |kD |j ddS#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) rsignalSIGHUPSIGTERMSIGKILLrrBkillrCtime monotonicsleepclose)rsigdeadlines rrszPtyBridge.closesJ <  F M6>6>B ! !C:%%''   $$$$    ~''#-H*$$&& !4>+;+;h+F+F 4   *$$&& !4>+;+;h+F+F  J  4  ( ( ( ( (    DD s$A-- A:9A: D&& D43D4c|Sr>rr@s r __enter__zPtyBridge.__enter__s rc.|dSr>)rs)r_excs r__exit__zPtyBridge.__exit__s r)rr)rr) r(r)r$r*r%r+r&r,r'r,rr-)rr,)rE)rFrGrrH)rSrUrrV)r&r,r'r,rrV)rrV)rr-)r r r r r classmethodr!r:propertyr?rDrMrYrhrsrwrzrrrrr>s<$$$[$ ""*****[*X###X#<"    :r)r __future__rrNrcr5rJrkr`r1rerptypingrrr4r2r3r ImportError__all__ RuntimeErrorrrrrrrsS8#"""""  %%%%%%%%00777NNJNNN - .,oooooooooosA A"!A"