cli_inline_images.py 4.3 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495
  1. """Inline images in the classic CLI scrollback: the user's attachments and image tool results.
  2. Images print as ordinary text rows (kitty Unicode placeholders, half-blocks, or blank rows an
  3. iTerm2 image is drawn over) so the scrollback replay and its row accounting keep working. The
  4. transmit itself goes out once, raw, beside its row (``_cprint(raw=...)``) and never enters the
  5. output history: a resize replay repaints the rows alone, so it can't crop a 1 MB escape into
  6. text or re-send it. kitty keeps the image by id, so replayed placeholders still show it. An
  7. iTerm2 image is pixels drawn over its reserved rows; a replay repaints those rows blank, so the
  8. picture is lost in the redrawn viewport (scrollback above keeps it) rather than painted over
  9. whatever text the replay put above a partly kept image.
  10. The kitty id color rides in prompt_toolkit's zero-width ``\\001…\\002`` brackets: its ANSI
  11. printer would otherwise quantize the truecolor that carries the image id to the output's color
  12. depth (256 by default). Half-block colors go through that quantization on purpose, like the rest
  13. of the scrollback.
  14. """
  15. from __future__ import annotations
  16. import os
  17. import random
  18. import sys
  19. from collections.abc import Iterable
  20. from agent.terminal_image import (
  21. InlineImage,
  22. half_block,
  23. local_image_path,
  24. probe_vscode_images,
  25. render_inline_image,
  26. resolve_inline_mode,
  27. )
  28. _INDENT = " "
  29. # Mirrors ui-tui/src/config/limits.ts INLINE_IMAGE_MAX_COLS/ROWS (the TUI's budget); keep them equal.
  30. _MAX_COLS = 64
  31. _MAX_ROWS = 16
  32. # Odds per launch of the "VS Code can show full images" hint: occasional, never every start.
  33. _VSCODE_HINT_ODDS = 0.2
  34. def _zero_width(seq: str) -> str:
  35. return f"\001{seq}\002"
  36. def _passthrough(seq: str) -> str:
  37. from hermes_cli.cli_terminal_mixin import _tmux_passthrough
  38. return _tmux_passthrough(seq) if os.environ.get("TMUX") else seq
  39. def image_rows(image: InlineImage) -> list[tuple[str, str]]:
  40. """*image* as ``(row, raw)`` pairs: ``row`` is history-safe scrollback text, ``raw`` the
  41. escape written verbatim right after it (the transmit: first kitty row, last iTerm2 row)."""
  42. if image.mode == "kitty":
  43. r, g, b = bytes.fromhex(image.color[1:])
  44. color, reset = _zero_width(f"\x1b[38;2;{r};{g};{b}m"), _zero_width("\x1b[39m")
  45. rows = [(_INDENT + color + row + reset, "") for row in image.placeholder]
  46. rows[0] = (rows[0][0], _passthrough(image.transmit))
  47. return rows
  48. if image.mode == "iterm":
  49. # Reserve the rows as empty lines (text written over an image cell erases it), then from
  50. # the start of the last one jump to the first, past the indent, draw, and restore.
  51. up = f"\x1b[{image.rows - 1}A" if image.rows > 1 else ""
  52. draw = f"\x1b7{up}\x1b[{len(_INDENT)}C{_passthrough(image.transmit)}\x1b8"
  53. return [("", "")] * (image.rows - 1) + [("", draw)]
  54. return [(_INDENT + "".join(half_block(t, b) for t, b in row) + "\x1b[0m", "") for row in image.cells]
  55. def vscode_images_hint(configured) -> bool:
  56. """Probe VS Code's image support before prompt_toolkit owns the tty; True when the
  57. occasional "turn on VS Code images" hint should print this launch.
  58. Only ``auto`` probes and hints: a pinned mode is the user's own choice.
  59. """
  60. if str(configured).strip().lower() != "auto" and configured not in (None, True):
  61. return False
  62. return probe_vscode_images() is False and random.random() < _VSCODE_HINT_ODDS
  63. def print_inline_images(cli, paths: Iterable) -> None:
  64. """Print each image in *paths* under the current scrollback line, per ``display.inline_images``."""
  65. from cli import _cprint, _terminal_columns
  66. stdout = sys.__stdout__
  67. if stdout is None or not stdout.isatty():
  68. return
  69. mode = resolve_inline_mode(getattr(cli, "_inline_images_mode", "auto"), overlays=True)
  70. if mode == "off":
  71. return
  72. max_cols = min(_MAX_COLS, _terminal_columns() - len(_INDENT) - 1)
  73. for path in filter(None, map(local_image_path, map(str, paths))): # the same files the TUI draws
  74. image = render_inline_image(path, mode=mode, max_cols=max_cols, max_rows=_MAX_ROWS)
  75. # One print per row, like the diff printer: a whole truecolor image in a single write
  76. # overruns the Windows console write and the tail rows are lost.
  77. for row, raw in image_rows(image) if image is not None else ():
  78. _cprint(row, raw=raw)