Module clipboard_5522 

Kitty OSC 5522 rich-clipboard protocol: request builders, reply parsing, capability hint.

Spec: https://sw.kovidgoyal.net/kitty/clipboard/

VT Code implements the read path only: the TUI falls back to it when a local OS-clipboard image read fails (SSH, containers, headless sessions). The write path (type=write/wdata/walias) and paste-event mode (CSI ? 5522 h) are deliberately out of scope — terminal copy stays on plain OSC 52 and paste stays on bracketed paste plus this read fallback.

Two consumers share this module:

• the startup color probe (crate::utils callers in vtcode-core) folds a DECRQM 5522 query into its existing OSC batch and caches the result with set_clipboard_5522_hint;
• the TUI session (Phase 1) sends read_request on image-paste fallback, receives one reply packet per fork-parser event, and feeds them to ReadAssembler.

All parsing is fail-closed: malformed packets, id mismatches, oversized payloads, and terminal error statuses abort the read instead of yielding partial data.

Structs

MimeData

One fully assembled MIME payload from a 5522 read.

ReadAssembler

Incremental assembler for one 5522 read: OK (DATA*) DONE.

ReadOptions

Shared options for 5522 read requests.

ReadPacket

One parsed 5522 read-reply packet (OSC framing already stripped).

Enums

AssembleError

A 5522 read failed while assembling packets.

AssembleOutcome

Outcome of feeding one packet to ReadAssembler::push.

PacketError

A single packet failed to parse.

ReadErrorCode

Terminal error status for a 5522 read.

ReadStatus

Status of one parsed 5522 read-reply packet.

Constants

DECRPM_5522_PREFIX

Prefix of a DECRPM reply to DECRQM_5522_QUERY: CSI ? 5522 ; Ps $ y.

DECRQM_5522_QUERY

Query for 5522 support: CSI ? 5522 $ p (DECRQM).

MAX_PACKET_BYTES

Upper bound for one 5522 reply packet (base64 payload plus metadata).

MAX_READ_BYTES

Upper bound for the total decoded bytes of one clipboard read.

Functions

clipboard_5522_available

Whether the session may attempt 5522 clipboard reads.

clipboard_5522_hint

Cached startup-probe verdict, if the probe produced one.

generate_request_id

Generate a random correlation id inside the spec’s charset.

mime_list_request

Build a MIME-list request: payload is base64(.).

parse_decrpm_5522

Parse a DECRPM 5522 reply out of a mixed probe buffer.

parse_read_packet

Parse one 5522 reply packet with OSC framing already stripped.

read_request

Build a typed read request for space-separated mimes.

sanitize_request_id

Strip characters outside the spec’s request-id charset.

set_clipboard_5522_hint

Cache the startup probe’s 5522 verdict (None clears the hint).