Protocol Verbs

Other machines

Other machines: part of the Protocol Verbs of TUIOS.

This page is one part of docs/protocol-verbs.md of the tuios repository. The Protocol Verbs page lists every part.

attach-presence Added in v0.9.3

Hold the person's nonce on this connection without a screen. The reply carries human_nonce, which respond, reply-approval, answer-ask and dismiss-attention take as the person's, by the same rules as an attach nonce: only from outside every pane, over a link only on a stream the hub vouched for, and only from the process that holds it. The presence does not attach: it does not change the session size, focus or view a pane, or receive broadcasts. The connection serves other verbs as before, and the presence ends when it closes.

ParamTypeRequiredDefaultDescription
sessionstringThe session the nonce is for. The nonce then acts only in that session. Omit it for every session.
Result fieldTypeDescription
human_noncestringThe nonce. Send it from this process, as human_nonce.
client_idstringThis connection's client id, which answered_by reports.
sessionstringThe session, when one was named.
{"id":1,"verb":"attach-presence"}

list-host-agents Added in v0.8.0

List the agent panes of every session on this machine and on every configured host. Hosts are asked at once, so a slow one costs only its own entry.

ParamTypeRequiredDefaultDescription
hoststringOne host by name, or "local" for this machine. Omit for every host.
allboolList every window on each host, not just the panes identified as agents.
selectstringA selector: space-separated key:value terms, all of which must match, each with comma-separated alternatives. Keys: harness (id or program name), state, needs:you, session (glob), group (fan-out group, glob), host (local or a host name, glob), name (window name, glob), cwd (the directory or under it; ~ is home), task (a task card the pane holds, by id, glob), stage (the stage of a card the pane holds), parent and root (the parent agent pane, or the first of its chain, by window id or a start of it). Keeps only the rows it matches, on every host; a host term matches the entry's host. A host from before selectors sends no group, so a group term matches none of its rows.
Result fieldTypeDescription
hosts[]stringOne entry per host, local first, carrying the agent rows of every session on it, each row naming its session. session is set only when every row is in one session. An entry that failed carries an error and a code; when the host answered before, it also carries the rows it last gave, with stale true and fetched_at in unix seconds. events says how this daemon follows the host: live, polling, or empty while the link is down.
selectstringThe selector as parsed, when one was given.
{"id":1,"verb":"list-host-agents"}
{"id":1,"verb":"list-host-agents","params":{"host":"build"}}
{"id":1,"verb":"list-host-agents","params":{"select":"harness:codex state:idle"}}

list-host-sessions Added in v0.8.0

List sessions on this machine and on every configured host. Hosts that do not answer are listed with their status.

ParamTypeRequiredDefaultDescription
hoststringOne host by name, or "local" for this machine. Omit for every host.
Result fieldTypeDescription
hosts[]stringOne entry per host, local first, carrying that host's status and its sessions. An entry that failed carries an error and a code; when the host answered before, it also carries the sessions it last gave, with stale true and fetched_at in unix seconds. Each session carries agent_state, the most urgent agent state among its panes, so a listing can say which sessions want a person without a second call, and space when it is filed under one on its host. events says how this daemon follows the host.
{"id":1,"verb":"list-host-sessions"}
{"id":1,"verb":"list-host-sessions","params":{"host":"build"}}

list-hosts Added in v0.8.0

List the machines named in the [hosts] config table, with the state of each link.

No params.

Result fieldTypeDescription
hosts[]stringOne entry per configured host, carrying its name, address, status, plain reason, remote daemon version, control protocol range, the last time it answered, and events: live when this daemon streams the host's agents and Inbox, polling when the host's tuios is too old to (events_note says what to update), empty while the link is not up. queued is how many messages this daemon holds for the host until its link is back. cores, load1, mem_pct and agents_working are the host's load from the last hello on the link, at load_at (Unix seconds), and rtt_ms is that hello's round trip in milliseconds; all are absent until a hello from the host carried a load.
totalintHow many hosts are configured.
events_pushboolAlways true from a daemon that pushes host changes: host-changed on subscribe, and a hosts-changed push to attached clients.
config_problems[]stringConfig entries that were dropped, with the reason for each. Omitted when there are none.
{"id":1,"verb":"list-hosts"}

open-host-connection Added in v0.8.0

Turn this connection into a connection to the daemon on one host. After the reply, every byte written here reaches that daemon and every byte it writes comes back. Send nothing until the reply has arrived.

The connection stays open after the reply.

ParamTypeRequiredDefaultDescription
hoststringA host by name from the [hosts] config table.
ssh_auth_sockstringThe caller's SSH_AUTH_SOCK. With [daemon] ssh_agent = "follow", the agent link the link's ssh forwards points at it while this caller is the newest person attached.
Result fieldTypeDescription
hoststringThe host the connection reaches.
daemon_versionstringThe version the host's daemon reported when the link came up. It is what the host said, not a fact this daemon checked.
protocolintThe control protocol version the host's daemon reported.
{"id":1,"verb":"open-host-connection","params":{"host":"build"}}

register-push Added in v0.9.3

Register a phone's Web Push subscription, so the phone gets Inbox items while it sleeps. When an item of a kind the phone asked for opens, the daemon posts a payload encrypted for the phone (RFC 8291, aes128gcm) to its push service, signed with the daemon's VAPID key (RFC 8292), and posts a close when the item closes. The same device name replaces the phone it names, but not over a link. Each registration opens an Inbox item named phone NAME. Only the person: a live human_nonce from an attach or a presence with no session (a phone gets the Inbox of every session), and over a link the respond capability. At most 16 phones.

ParamTypeRequiredDefaultDescription
endpointstringThe push service's address for the phone. https, or http on a loopback or private IP address when [notify.webpush] allow_insecure is true. A loopback or private address needs allow_insecure also with https, and the daemon checks the address a name resolves to when it connects.
p256dhstringThe phone's public key: the uncompressed P-256 point (65 bytes), base64url.
authstringThe phone's authentication secret: 16 bytes, base64url.
devicestringA name for the phone, 1 to 64 bytes. remove-push takes it. Over a link, the name of a registered phone is refused.
kindsstring[]The Inbox kinds to push. Default: approval, plan, ask and question.
human_noncestringThe nonce of an attach, or of an attach-presence made with no session, from the same process.
Result fieldTypeDescription
devicestringThe phone's name.
kindsstring[]The kinds it gets.
replacedboolTrue when a phone of that name was registered before.
vapid_public_keystringThe daemon's VAPID public key, the uncompressed point, base64url: the applicationServerKey to subscribe with.
machinestringThis machine's name, as the payload carries it.
{"id":1,"verb":"register-push","params":{"endpoint":"https://push.example.net/s/abc","p256dh":"BNc...","auth":"tBH...","device":"pixel","human_nonce":"<from attach-presence>"}}

stream-pane Added in v0.9.3

Stream one pane as bytes, for a client that is not tuios. The reply is one JSON line, and after it the connection carries binary frames both ways: a type byte, a 4-byte big-endian length, then the payload. From the daemon: S snapshot (u64 seq, u16 cols, u16 rows, then bytes that paint the pane on a fresh emulator of that size), O output (u64 seq after the frame's last byte, then the pane's bytes), R resize (u64 seq, u16 cols, u16 rows), E error (JSON code and message, for a refused frame or a lease that was not renewed; the stream goes on), X exit (the reason: exited N when the pane's program exited with status N, killed N when signal N ended it, closed when its window closed first, or refused: … when the caller may no longer read it; the connection then closes). From the client: I input (at most 64 KiB of bytes typed into the pane, checked as send-text is), L lease (u16 cols, u16 rows, 0 0 to release; send it again every 10 seconds, or the lease ends after 30). Skip a frame type you do not know: read its length and drop that many bytes. At most 4 I frames wait for a pane that does not read, and the next gets E busy. The stream never changes the pane's size or the session's. A lease holds the pane at most at its size while the stream is open, and the pane goes back to the size its clients asked for when the lease ends.

The connection stays open after the reply.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringThe pane to stream: a window id or name.
from_seqintThe seq the client reached on an earlier stream of this pane. With boot_id, the stream resumes there when the daemon still holds the bytes after it.
boot_idstringThe boot_id of the stream from_seq came from. A different one means the daemon restarted, and the stream starts with a snapshot.
lease_colsintHold the pane at most this many columns wide while the stream is open. Needs lease_rows. It needs what resize needs.
lease_rowsintHold the pane at most this many rows high while the stream is open. Needs lease_cols.
session_idstringThe session by its id, which a rename does not change. It wins over session. The reply carries it.
fitboolMake the lease a viewer's: while no TUI client shows the session, the pane takes the size of the largest fit lease held, and goes back to its own size when the last one ends. While a client shows the session, a fit lease only holds the pane smaller.
viewerobjectThe terminal the stream shows the pane in: bg, fg (#rrggbb), palette (sixteen comma-separated #rrggbb), kitty and sixel (bool). While no TUI client shows the session, the daemon answers the pane's OSC 10, 11 and 4, DA1 and kitty graphics queries from the newest viewer's report.
Result fieldTypeDescription
modestringresume: the first frames are output from from_seq. snapshot: the first frame is S. One of resume or snapshot.
seqintThe stream position the first frame starts at.
colsintThe pane's width at seq.
rowsintThe pane's height at seq.
boot_idstringThis daemon start. Send it back with from_seq to resume.
sessionstringThe pane's session.
session_idstringThe pane's session id, which a rename does not change.
windowstringThe pane's window id.
titlestringThe pane's title.
{"id":1,"verb":"stream-pane","params":{"session":"work","window":"build"}}
{"id":1,"verb":"stream-pane","params":{"session":"work","window":"build","from_seq":48211,"boot_id":"<from the last reply>","lease_cols":45,"lease_rows":20}}

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page