pty_query_responder.py 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118
  1. """Answer a bounded set of blocking terminal queries from PTY subprocesses.
  2. Programs running inside a background PTY session (``terminal(background=true,
  3. pty=true)``) sometimes probe their "terminal" with ANSI queries — device
  4. status reports (``ESC[5n``), window-size queries (``ESC[18t``), cursor
  5. position reports (``ESC[6n``), or DEC private-mode queries
  6. (``ESC[?<mode>$p``). A real terminal emulator answers these on stdin; Hermes'
  7. PTY has no emulator on the master side, so the subprocess either blocks
  8. forever waiting for a reply or the raw query bytes leak into the captured
  9. output as garbage.
  10. This module ports openai/codex#41436 (``terminal_queries.rs``): a tiny
  11. byte-level state machine that scans PTY output for the handled queries,
  12. strips them from the output stream (queries split across read chunks
  13. included), and produces the bounded responses to write back to the
  14. subprocess. Everything else — colors, other escape sequences, partial
  15. UTF-8 — passes through untouched.
  16. Only the POSIX ``ptyprocess`` path uses this. On Windows, ConPTY is a real
  17. console host that answers queries itself.
  18. """
  19. from __future__ import annotations
  20. _ESC = 0x1B
  21. # DEC private-mode queries carry a numeric mode of bounded length; anything
  22. # longer is not a query we answer (and is passed through untouched).
  23. _MAX_MODE_DIGITS = 10
  24. # Longest handled sequence: ESC [ ? <digits> $ p
  25. _MAX_QUERY_BYTES = _MAX_MODE_DIGITS + 5
  26. class PtyQueryResponder:
  27. """Incremental scanner for terminal queries in a PTY output stream.
  28. Feed raw output chunks through :meth:`process`; it returns the chunk with
  29. any handled queries removed, plus the response bytes to write to the
  30. subprocess's stdin. Call :meth:`flush` at end-of-stream to recover any
  31. trailing partial escape sequence that never completed.
  32. """
  33. def __init__(self, rows: int = 24, cols: int = 80):
  34. # Exact-match queries and their responses. Window size reports the
  35. # PTY's actual spawn dimensions; cursor position reports home (1;1) —
  36. # we don't emulate a screen, a bounded answer just unblocks the
  37. # subprocess (same policy as openai/codex#41436).
  38. self._query_responses: tuple[tuple[bytes, bytes], ...] = (
  39. # Device status report: terminal operating normally.
  40. (b"\x1b[5n", b"\x1b[0n"),
  41. # Window-size query: report the PTY's row/col text area.
  42. (b"\x1b[18t", b"\x1b[8;%d;%dt" % (rows, cols)),
  43. # Cursor-position report: row 1, column 1.
  44. (b"\x1b[6n", b"\x1b[1;1R"),
  45. )
  46. self._pending = bytearray()
  47. def process(self, data: bytes) -> tuple[bytes, bytes]:
  48. """Scan ``data``; return ``(output_bytes, response_bytes)``."""
  49. if not self._pending and _ESC not in data:
  50. return data, b""
  51. output = bytearray()
  52. responses = bytearray()
  53. pending = self._pending
  54. for byte in data:
  55. if not pending and byte != _ESC:
  56. output.append(byte)
  57. continue
  58. if byte == _ESC:
  59. # A fresh ESC aborts any partial sequence — flush it through.
  60. output += pending
  61. pending.clear()
  62. pending.append(byte)
  63. if (
  64. len(pending) == 1
  65. or bytes(pending) == b"\x1b["
  66. or (
  67. pending[1] == ord("[")
  68. and not (0x40 <= byte <= 0x7E)
  69. and len(pending) < _MAX_QUERY_BYTES
  70. )
  71. ):
  72. # Still accumulating a possible query.
  73. continue
  74. seq = bytes(pending)
  75. matched = False
  76. for query, response in self._query_responses:
  77. if seq == query:
  78. responses += response
  79. matched = True
  80. break
  81. if not matched:
  82. mode = seq[3:-2]
  83. if (
  84. seq.startswith(b"\x1b[?")
  85. and seq.endswith(b"$p")
  86. and 0 < len(mode) <= _MAX_MODE_DIGITS
  87. and mode.isdigit()
  88. ):
  89. # DEC private-mode query: report mode as unrecognized.
  90. responses += b"\x1b[?" + mode + b";0$y"
  91. else:
  92. # Not a handled query — pass the sequence through.
  93. output += pending
  94. pending.clear()
  95. return bytes(output), bytes(responses)
  96. def flush(self) -> bytes:
  97. """Return any incomplete trailing sequence held back by the scanner."""
  98. tail = bytes(self._pending)
  99. self._pending.clear()
  100. return tail