kitty/docs/misc-protocol.rst
ttyS3 00f7a0abd5
feat: support the Program Status Protocol (OSC 7501)
Implement revision 0.4 of the Program Status Protocol, which lets a
program report whether it is idle, working, done, blocked on the user
or failed, and why.

- Parse and validate reports per the spec: limits, base64 text without
  control characters, malformed ids discard the report instead of
  falling back to the root record, unknown states are ignored
- Keep up to 256 records per window (LRU eviction), with clear removing
  a record and its descendants and app inherited from ancestors
- Reply to the feature detection query with supported states and kinds
- Lifetime: working/blocked/idle records are dropped at a new shell
  prompt (OSC 133;A), done/error are dropped when the window gets focus,
  a full reset (RIS) removes every record
- Expose records via tab.program_status in tab_title_template, the
  output of kitten @ ls and a new on_program_status_change watcher

Spec: https://www.superlogical.com/rex/docs/build/program-status
Ref: ghostty-org/ghostty#14560, ghostty-org/ghostty#14630

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 22:31:38 +08:00

83 lines
3.7 KiB
ReStructuredText

Miscellaneous protocol extensions
==============================================
These are a few small protocol extensions kitty implements, primarily for use
by its own kitten, they are documented here for completeness.
Simple save/restore of all terminal modes
--------------------------------------------
XTerm has the XTSAVE/XTRESTORE escape codes to save and restore terminal
private modes. However, they require specifying an explicit list of modes to
save/restore. kitty extends this protocol to specify that when no modes are
specified, all side-effect free modes should be saved/restored. By side-effects
we mean things that can affect other terminal state such as cursor position or
screen contents. Examples of modes that have side effects are: `DECOM
<https://vt100.net/docs/vt510-rm/DECOM.html>`__ and `DECCOLM
<https://vt100.net/docs/vt510-rm/DECCOLM.html>`__.
This allows TUI applications to easily save and restore emulator state without
needing to maintain lists of modes.
Independent control of bold and faint SGR properties
-------------------------------------------------------
In common terminal usage, bold is set via SGR 1 and faint by SGR 2. However,
there is only one number to reset these attributes, SGR 22, which resets both.
There is no way to reset one and not the other. kitty uses 221 and 222 to reset
bold and faint independently.
.. _mouse_leave_window:
Reporting when the mouse leaves the window
----------------------------------------------
kitty extends the SGR Pixel mouse reporting protocol created by xterm to
also report when the mouse leaves the window. This event is delivered
encoded as a normal SGR pixel event except that the eight bit is set on the
first number. Additionally, bit 5 is set to indicate this is a motion related event.
The remaining bits 1-7 (except 5) are used to encode button and modifier information.
When bit 8 is set it means the event is a mouse has left the window event,
and all other bits should be ignored. The pixel position values must also
be ignored as they may not be accurate.
An escape code to move the contents of the screen into the scrollback
-------------------------------------------------------------------------------------
The escape code is ``\x1b [ 22 J`` (ignoring spaces present for clarity). It
moves all screen contents (text and images) into the scrollback leaving the
screen in the same state as it would be if the standard screen clear escape
code had been used ``\x1b [ 2 J``.
.. _program_status:
Reporting the status of a program
-------------------------------------
kitty supports the `Program Status Protocol (OSC 7501)
<https://www.superlogical.com/rex/docs/build/program-status>`__, revision 0.4,
which lets a program tell the terminal what it is doing: idle, working,
finished, blocked waiting on the user or failed, and why. For example::
printf '\e]7501;state=working:app=rsync:progress=40\e\\'
kitty keeps the records reported by programs per window and applies the
lifetime rules of the specification: :code:`working`, :code:`blocked` and
:code:`idle` records are dropped when a new shell prompt starts (needs
:ref:`shell_integration`), :code:`done` and :code:`error` records are kept until
the window is focused, and a full reset removes every record. The status is
shown in the tab bar via the :code:`tab.program_status` field of
:opt:`tab_title_template`, is reported in the output of ``kitten @ ls``, and
:ref:`watchers <watchers>` can react to it via
:code:`on_program_status_change`.
kitty specific private escape codes
---------------------------------------
These are a family of escape codes used by kitty for various things including
remote control. They are all DCS (Device Control String) escape codes starting
with ``\x1b P @ kitty-`` (ignoring spaces present for clarity).