Running itHost protocol
Host protocol
A host gives Vendetta a terminal or multiplexer. This page is the wire contract a host serves, so one can be written in any language. Writing a host covers the plugin side: naming, config, and keys.
Socket
Section titled “Socket”The host serves a Unix socket at
$XDG_RUNTIME_DIR/vendetta/hosts/<control socket's stem>-<KIND>.sockwhere the control socket is the worker’s ($XDG_RUNTIME_DIR/vendetta/control/<hash>.sock,
named to the plugin as VENDETTA_CONTROL_SOCKET), and KIND is the host’s kind, such as tmux
or kitty. The directory is mode 0700 and the socket 0600. Every Vendetta process of the
user finds hosts by listing that directory and sending hello to each socket with the
right stem; a socket that does not answer is a host that is not running. A host refuses to
start while another of its kind answers there, and removes a stale file.
Each connection carries any number of requests, one at a time: one JSON object per line each way, a line at most 64 MiB. Serve each connection on its own thread or task, so a popup that waits for the owner holds up nothing else.
{"method":"capture","params":{"pane":{"server":"kitty:/tmp/k.sock,4242,1731400000,b1","target":"s:w.p"},"lines":200}}
{"ok":"…text…"}
{"error":"That terminal has closed"}A request is {"method": NAME} or {"method": NAME, "params": {...}}. The answer is
{"ok": VALUE} (null for methods that return nothing) or {"error": MESSAGE}. An
unknown method or malformed line answers an error and keeps the connection open.
Callers wait 10 seconds for an answer, 30 for place and create_session, and as long
as it takes for popup. A connection that drops after a request was written is
uncertain: the host may have acted, and nothing retries it. Refuse before acting when
you can, so an error means nothing happened.
Identities
Section titled “Identities”- A server identity names one lifetime of what the host serves:
KIND:ADDRESS,PID,START,BOOT, wherePIDis the serving process,STARTits start time as/procgives it, andBOOTthe kernel’s boot id. A host with nothing running answersKIND:alone. tmux identities have no prefix and start with the socket’s absolute path. Vendetta routes on theKIND:prefix and treats an identity of an ended lifetime as gone. - A target names a session, tab, or pane within one lifetime:
session,session:window, orsession:window.pane. A location is{server, target}. - A viewport is where the owner can look: a tmux client, a Kitty window. Its
idstarts withKIND:(tmux’s are client names). - A location of an ended lifetime, or a pane whose root process changed, is refused, never reinterpreted.
| Type | Shape |
|---|---|
| Location | {server, target} |
| Pane | {server, session, session_name, managed_project, attached, activity, window, window_index, window_name, window_active, id, index, active, pid, command, title, cwd, dead}. managed_project names the project when the pane sits in the Agents tab the host keeps for it, else null; pid is the pane’s root process; activity grows with use. Hosts send agents as [] or leave it out. |
| Session | {server, id, name, cwd, attached_clients, activity}; server may be empty, as callers fill it in. |
| Viewport | {id, pid, pane, session, session_name, window, activity, width, height, terminal, pane_tty, zoomed, hidden?}. pid is the terminal process behind it, which places it inside another host’s window; pane is the pane it shows; pane_tty that pane’s terminal; hidden that its terminal shows another tab now, as a Kitty window in a tab its OS window does not show. |
| Screen | {text, width, height, cursor_x, cursor_y, cursor_visible}; text is the visible screen, lines joined by \n, with SGR escapes for colors and attributes. |
| Root | {target, server, pane_pid, pane_start} |
| Pin | {location, pid, start}: a pane pinned to the process it started with. |
| Input | {"key": KeyPress}, {"paste": TEXT} (bracketed if the pane asked), or {"submit": TEXT} (pasted, then Enter in the same burst). |
| KeyPress | {key, ctrl, alt, shift}; key is one character or enter, backspace, left, right, up, down, home, end, page_up, page_down, tab, backtab, delete, insert, escape, null, f1–f63. |
| Destination | {"existing": {server, session_id}} or {"new": {name}} |
| LaunchReceipt | {target, server_key, launch_token}; launch_token may be null. |
| Scope | "session", "window", or "pane" |
| Placement | {server, session, pane, project, tab, managed}; managed is whether Vendetta launched the process, when the pane’s root is exactly it, else null. |
Methods
Section titled “Methods”| Method and params | Answer |
|---|---|
hello |
{kind, persistent}: persistent when panes outlive the terminal the owner closes, so a launch with no viewport makes sense. |
server_key |
The current server identity. |
panes |
Every pane. |
sessions |
[server identity, [Session]], read in that lifetime. |
capture {pane, lines} |
The last lines lines of the pane’s screen and scrollback, as text. |
screen {pane, viewer_tty} |
Its Screen. Refuse when viewer_tty is that pane’s own terminal. |
pane_viewers {pane} |
An opaque string naming who shows the pane; empty when none does. |
input_revision {server, pane} |
An opaque string that changes whenever someone types into the pane. |
input_revisions |
An opaque fingerprint of every pane’s input revision. |
input {pin, input} |
Type into the pane. Refuse unless its root is still the pinned pid and start, checked where nothing can replace it before the write. |
launch_project {destination} |
The project the destination names, checked against the live host. |
place {cwd, destination, command} |
Start the argv command in a fresh pane of the project’s Agents tab; answer a LaunchReceipt. |
root {location} |
The Root of the pane there. |
viewports |
Every viewport, most recently used first when the host can say. |
current_viewport {viewport, pid} |
The viewport process pid runs in, or viewport checked; null when none of this host’s. Find it from the process’s ancestry, never from inherited environment alone. |
current_pane {pid} |
The pane id process pid runs in, or null. |
graphics_pass |
Whether graphics drawn in a pane reach the terminal. |
open {viewport, location} |
Show the location in the viewport; with null, make it what the host shows next. |
zoom {viewport, location, zoomed} |
Show the pane with its tab zoomed on it (true), or with every pane laid out and it in focus. |
fit {location, width, height} |
Size the pane alone in its tab, for a preview of that size; only a tab the host keeps for agents and no viewport shows. Hosts that cannot answer null. |
create_session {name, cwd} |
A new project session with a shell in cwd; answer its Location. |
rename {scope, location, name} |
Rename a session, tab, or pane title. |
close {scope, location} |
Close a session, tab, or pane. |
popup {viewport, title, command} |
Run the argv command floating over the viewport; answer when it exits. |
native_chooser {viewport} |
Show the host’s own chooser. |
recent_panes |
Pane ids the owner focused, newest first. |
attach_command {location} |
An argv showing the location from inside another terminal, or null when panes cannot be shown elsewhere. |
placement {pid, start} |
Where that exact process is shown, as a Placement, or null. |
shortcut {window, key, action, program} |
A desktop-wide key for action (chooser, history, overview, master, previous, agents, layout) pressed while the desktop window of process window has focus: handle it there as the host’s own key, running the argv program, and answer true; false when that window is not the host’s. |
float {command} |
Run the argv command floating over whatever window has focus and answer true, or false when the host cannot. |
A host that cannot do something answers an error saying so, except where the table says
false or null.
The chooser’s command line
Section titled “The chooser’s command line”A host’s chooser, history, and overview keys run vendetta [--config FILE] tui, then
the chooser’s own flags, in any order: --socket TMUX (the tmux server whose host it
uses), --client VIEWPORT (the viewport it opens for, which it navigates), --config FILE, and --focus history (history key) or --overview (overview key). Each host
builds it with vendetta_host::keys::chooser_command, and adds only what it alone knows,
such as tmux’s #{q:client_name} or the Kitty window the key was pressed in.
Lifecycle
Section titled “Lifecycle”The worker starts the host as a plugin with the usual environment
(Writing a plugin). The host opens its socket, then reports
report_health {"state": "running"}, and serves until the worker goes away. It exits on
any panic and when a main loop stops beating, so the worker restarts it; a restart must
not read as panes moving or ending, so identities stay the same while the terminal does.