| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118 |
- """Answer a bounded set of blocking terminal queries from PTY subprocesses.
- Programs running inside a background PTY session (``terminal(background=true,
- pty=true)``) sometimes probe their "terminal" with ANSI queries — device
- status reports (``ESC[5n``), window-size queries (``ESC[18t``), cursor
- position reports (``ESC[6n``), or DEC private-mode queries
- (``ESC[?<mode>$p``). A real terminal emulator answers these on stdin; Hermes'
- PTY has no emulator on the master side, so the subprocess either blocks
- forever waiting for a reply or the raw query bytes leak into the captured
- output as garbage.
- This module ports openai/codex#41436 (``terminal_queries.rs``): a tiny
- byte-level state machine that scans PTY output for the handled queries,
- strips them from the output stream (queries split across read chunks
- included), and produces the bounded responses to write back to the
- subprocess. Everything else — colors, other escape sequences, partial
- UTF-8 — passes through untouched.
- Only the POSIX ``ptyprocess`` path uses this. On Windows, ConPTY is a real
- console host that answers queries itself.
- """
- from __future__ import annotations
- _ESC = 0x1B
- # DEC private-mode queries carry a numeric mode of bounded length; anything
- # longer is not a query we answer (and is passed through untouched).
- _MAX_MODE_DIGITS = 10
- # Longest handled sequence: ESC [ ? <digits> $ p
- _MAX_QUERY_BYTES = _MAX_MODE_DIGITS + 5
- class PtyQueryResponder:
- """Incremental scanner for terminal queries in a PTY output stream.
- Feed raw output chunks through :meth:`process`; it returns the chunk with
- any handled queries removed, plus the response bytes to write to the
- subprocess's stdin. Call :meth:`flush` at end-of-stream to recover any
- trailing partial escape sequence that never completed.
- """
- def __init__(self, rows: int = 24, cols: int = 80):
- # Exact-match queries and their responses. Window size reports the
- # PTY's actual spawn dimensions; cursor position reports home (1;1) —
- # we don't emulate a screen, a bounded answer just unblocks the
- # subprocess (same policy as openai/codex#41436).
- self._query_responses: tuple[tuple[bytes, bytes], ...] = (
- # Device status report: terminal operating normally.
- (b"\x1b[5n", b"\x1b[0n"),
- # Window-size query: report the PTY's row/col text area.
- (b"\x1b[18t", b"\x1b[8;%d;%dt" % (rows, cols)),
- # Cursor-position report: row 1, column 1.
- (b"\x1b[6n", b"\x1b[1;1R"),
- )
- self._pending = bytearray()
- def process(self, data: bytes) -> tuple[bytes, bytes]:
- """Scan ``data``; return ``(output_bytes, response_bytes)``."""
- if not self._pending and _ESC not in data:
- return data, b""
- output = bytearray()
- responses = bytearray()
- pending = self._pending
- for byte in data:
- if not pending and byte != _ESC:
- output.append(byte)
- continue
- if byte == _ESC:
- # A fresh ESC aborts any partial sequence — flush it through.
- output += pending
- pending.clear()
- pending.append(byte)
- if (
- len(pending) == 1
- or bytes(pending) == b"\x1b["
- or (
- pending[1] == ord("[")
- and not (0x40 <= byte <= 0x7E)
- and len(pending) < _MAX_QUERY_BYTES
- )
- ):
- # Still accumulating a possible query.
- continue
- seq = bytes(pending)
- matched = False
- for query, response in self._query_responses:
- if seq == query:
- responses += response
- matched = True
- break
- if not matched:
- mode = seq[3:-2]
- if (
- seq.startswith(b"\x1b[?")
- and seq.endswith(b"$p")
- and 0 < len(mode) <= _MAX_MODE_DIGITS
- and mode.isdigit()
- ):
- # DEC private-mode query: report mode as unrecognized.
- responses += b"\x1b[?" + mode + b";0$y"
- else:
- # Not a handled query — pass the sequence through.
- output += pending
- pending.clear()
- return bytes(output), bytes(responses)
- def flush(self) -> bytes:
- """Return any incomplete trailing sequence held back by the scanner."""
- tail = bytes(self._pending)
- self._pending.clear()
- return tail
|