read_terminal_tool.py 3.0 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283
  1. #!/usr/bin/env python3
  2. """Read the in-app terminal pane in the Hermes desktop GUI.
  3. The buffer lives in the desktop renderer (xterm.js), so this round-trips through the
  4. gateway's blocking-prompt bridge (as `clarify` does): tui_gateway emits
  5. ``terminal.read.request``, the renderer answers ``terminal.read.respond``. Lives in the
  6. ``desktop_ui`` toolset, enabled only for desktop-sourced sessions.
  7. """
  8. from typing import Callable, Optional
  9. from tools.desktop_ui import passthrough_json
  10. from tools.registry import registry, tool_error
  11. def read_pane(callback: Optional[Callable], window, errors: tuple) -> str:
  12. """Shared body of the read_terminal / read_preview / read_window bridges. ``window`` is
  13. ``((key, value, floor), ...)`` (None omitted, else int-coerced and floored); ``errors`` =
  14. (not_desktop, not_integers, fail_prefix, empty)."""
  15. if callback is None:
  16. return tool_error(errors[0])
  17. try:
  18. kwargs = {key: max(floor, int(val)) for key, val, floor in window if val is not None}
  19. except (TypeError, ValueError):
  20. return tool_error(errors[1])
  21. try:
  22. raw = callback(**kwargs)
  23. except Exception as exc:
  24. return tool_error(f"{errors[2]}{exc}")
  25. if not raw:
  26. return tool_error(errors[3])
  27. return passthrough_json(raw)
  28. def read_terminal_tool(
  29. start_line: Optional[int] = None,
  30. count: Optional[int] = None,
  31. callback: Optional[Callable] = None,
  32. ) -> str:
  33. """Return the in-app terminal's contents (+ line metadata) as a JSON string."""
  34. return read_pane(callback, (("start", start_line, 0), ("count", count, 1)), (
  35. "read_terminal is only available in the Hermes desktop app.",
  36. "start_line and count must be integers.",
  37. "Failed to read terminal: ",
  38. "No in-app terminal answered: nothing is open, or the bridge timed out. "
  39. "If the terminal pane IS open, the desktop app may be older than this "
  40. "backend — update it and retry.",
  41. ))
  42. READ_TERMINAL_SCHEMA = {
  43. "name": "read_terminal",
  44. "description": (
  45. "Read the in-app terminal pane beside this chat. No args = visible "
  46. "screen + total_lines; page scrollback with start_line (0 = oldest) "
  47. "+ count. JSON: {total_lines, start, end, viewport_rows, cursor_row, "
  48. "text}."
  49. ),
  50. "parameters": {
  51. "type": "object",
  52. "properties": {
  53. "start_line": {
  54. "type": "integer",
  55. "description": "0-indexed first line (0 = oldest). Omit for the visible screen.",
  56. },
  57. "count": {
  58. "type": "integer",
  59. "description": "Lines to read from start_line. Defaults to the visible row count.",
  60. },
  61. },
  62. },
  63. }
  64. registry.register(
  65. name="read_terminal",
  66. toolset="desktop_ui",
  67. schema=READ_TERMINAL_SCHEMA,
  68. handler=lambda args, **kw: read_terminal_tool(
  69. start_line=args.get("start_line"), count=args.get("count"), callback=kw.get("callback")
  70. ),
  71. emoji="🖥️",
  72. )