Control Protocol

Verbs: Sessions

Verbs: Sessions: part of the Control Protocol of TUIOS.

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

list-sessions

List all sessions the daemon holds. No params.

Request:

{"verb": "list-sessions"}

Response:

{"result": {"type": "session_list", "sessions": [
  {"name": "work", "id": "5f...", "window_count": 3, "attached": true, "width": 120, "height": 40}
]}}

A session filed under a space also carries space. See set-session-space.

list-clients

List every connection to the daemon. No params. Each row carries the daemon's client id, the peer pid recorded by the kernel, and the current session name. The session is empty while the connection is detached. The pid is zero on Windows and the BSDs. For SSH and web clients it names the local server process, not the remote SSH process or browser.

Request:

{"verb": "list-clients"}

Response:

{"result": {"type": "client_list", "clients": [
  {"client_id": "client-1790941960197517900", "pid": 4242, "session": "work"}
]}}

client-session-changed carries the session a client entered or left and sets attached to true or false. A session rename sends one with the new name and attached: true for each client in the session.

switch-session

Switch an attached client to a different session, in place, as the session switcher does.

Params: name (required), host, create, cwd, session, client.

  • name is the session to show. host is a machine from the client's [hosts] table. Omit it, or pass local, for this daemon.
  • create makes the session when it is missing. On this daemon it is made as new-session makes one, with cwd as its directory. On a host, the client makes it there and opens its first window. cwd needs create.
  • The client to switch is the one client names, else the one that shows session, else the one that shows the caller's session when the caller runs in a pane, else the only TUI client attached. With more than one attached and nothing to choose by, the call fails with invalid_params.

Request:

{"verb": "switch-session", "params": {"name": "api", "create": true, "cwd": "/src/api", "session": "work"}}

Response:

{"result": {"type": "session_switched", "session": "api", "client_id": "client-1790941960197517900", "created": true}}

On this daemon the answer comes when the client shows the session. A missing session without create fails with session_not_found. No client to switch fails with needs_client. already: true says the client showed the session already. A pane needs the admin grant. Over a link the verb needs write.

detach-client

Detach attached clients from their sessions, as tmux detach-client does. The sessions continue to run.

Params: client, session, all_other.

  • client names one client from list-clients. session names a session, and every client of it detaches. Give one of the two, or neither.
  • With neither, the verb acts on the client used last in the caller's pane's session, else in the only session with a client.
  • all_other keeps the named client, or the client used last, and detaches every other client of its session.

Each detached client gets MsgSessionEnded with detached set and a reason, and exits with status 0. An attach with detach_others set (tuios attach -d), or any attach while [daemon] single_client is on, detaches the other clients of the session in the same way.

Request:

{"verb": "detach-client", "params": {"session": "work", "all_other": true}}

Response:

{"result": {"type": "clients_detached", "detached": ["client-1790941960197517900"]}}

An unknown client fails with invalid_params. A pane needs the admin grant. Over a link the verb needs write.

ssh-agent-path

Report the ssh agent link of a session. With [daemon] ssh_agent = "follow", the link points at the agent socket of the client that attached to the session or used it last, and new panes get SSH_AUTH_SOCK set to it.

Params: session (required).

The client sends its socket as ssh_auth_sock in its hello. Only tuios attach and tuios new send it. The daemon follows it only for a client that may act as the person. The path is resolved once with its symbolic links, and the result must be a Unix socket that the user owns. Every folder above it must be owned by the user or by root, and no other user may write to it unless it is sticky. The link points at the resolved path. When the client leaves, the link moves to the client before it. With none left, it points at the daemon's own SSH_AUTH_SOCK when that passes the same checks, or is removed. The daemon removes its links at start, at stop and when the option is off.

Request:

{"verb": "ssh-agent-path", "params": {"session": "work"}}

Response:

{"result": {"type": "ssh_agent_path", "session": "work", "path": "/run/user/1000/tuios/agent-3f2a9c1d.sock", "follow": true, "target": "/tmp/ssh-XXXXabc/agent.4242"}}

target is absent when there is no link. The verb reads one session: a pane needs read and the session in reach. Over a link it needs list.

The hub side: open-host-connection takes ssh_auth_sock, the caller's socket, because the caller's hello goes to the host and not to this daemon. While ssh_agent is "follow", this daemon keeps one link for each host whose link forwards the agent, agent-link-<host>-<hash>.sock. It points at the socket of the client that opened a connection to that host, or sent input through one, last. Input is the keys, pastes and mouse events a client sends. A state push or a pane resize that a client sends on its own is not input. Input counts at most once a second. The link ssh to such a host starts with SSH_AUTH_SOCK naming that host's link. The link ssh to any other host starts with the daemon's environment, unchanged. A daemon too old to know ssh_auth_sock refuses it with invalid_params, and the client asks again without it.

display-env

Report the display a new pane of a session gets now. With [daemon] display = "follow", the default, a daemon with no WAYLAND_DISPLAY or DISPLAY of its own gives new panes the display of the local client that attached to the session or used it last.

Params: session (required).

The client sends display in its hello: wayland_display, xdg_runtime_dir, display and xauthority, each as the client has it. Only tuios attach and tuios new send it, and never through a host. A daemon that predates the field ignores it. The daemon follows a client only when the client is on its own socket, not over a link, has the daemon's uid by peer credentials, and may act as the person. A wayland_display name is looked up in the client's xdg_runtime_dir, then the daemon's, then /run/user/<uid>. The resolved path must be a Unix socket the user owns, with every folder above it owned by the user or root and not writable by another user unless sticky. display must be :N or :N.S, with a socket in /tmp/.X11-unix owned by the user or root. xauthority must be a file the user owns. The session's link, wayland-<session id>.sock beside the daemon socket, points at the newest client's Wayland socket. When the client leaves, the session uses the client before it, and with none left the link is removed.

Request:

{"verb": "display-env", "params": {"session": "work"}}

Response:

{"result": {"type": "display_env", "session": "work", "follow": true, "own": false, "link": "/tmp/tuios-1000/wayland-3f2a9c1d.sock", "target": "/run/user/1000/wayland-1", "env": {"WAYLAND_DISPLAY": "/tmp/tuios-1000/wayland-3f2a9c1d.sock", "DISPLAY": ":1"}}}

target is absent when there is no link, and env is empty when the session has no display to give. The verb reads one session: a pane needs read and the session in reach. Over a link it needs list.

session-info

Report details about one session.

Params: session (optional).

Request:

{"verb": "session-info", "params": {"session": "work"}}

Response:

{"result": {
  "type": "session_info",
  "session_name": "work",
  "session_id": "5f...",
  "current_workspace": 1,
  "num_workspaces": 9,
  "window_count": 3,
  "tiling_mode": "tiling",
  "layout_mode": "bsp",
  "width": 120,
  "height": 40,
  "tui_attached": true,
  "host_focus": "focused",
  "window_size": "latest",
  "session_width": 120,
  "session_height": 40
}}

window_size is the size policy in use for the session: smallest, largest or latest (see SESSIONS.md). It is smallest while a client from before the option is attached, whatever the session is set to. session_width and session_height are the size the daemon gave the session under that policy. width and height are the size the last client sent with its state. A daemon that predates the option omits all three.

host_focus is whether the person can be looking at the session. Each TUI client asks its terminal for focus events (DECSET 1004) and reports every change to the daemon. It is focused when any attached client's terminal has focus, unfocused when every attached client's terminal reported losing it, and unknown when no client is attached or a terminal never reports focus. A daemon that predates the field omits it.

tiling_mode says only whether tiling is on (tiling or floating) and keeps doing so, because callers already dispatch on those two values. layout_mode says which tiling layout is in use (bsp, master-stack, scrolling, or unknown when no client has reported one yet).

kill-session

Terminate a session and everything in it.

Params: session (required).

Request:

{"verb": "kill-session", "params": {"session": "work"}}

Response:

{"result": {"type": "ok"}}

set-session-space

File a session under a space, a named group of related sessions, or take it out of any. A space is only a label on its sessions: it has no record of its own, exists while at least one session is in it, and is saved and restored with each session. list-sessions carries space on every session that is in one.

Params: session (the most recently active when omitted), space, global. An empty or omitted space takes the session out of any space.

global sets or clears the session's global mark. true marks the session global and takes it out of its space. With a space as well, it is refused with invalid_params. false takes the mark off before the space is set, so one call can move a global session into a space. An omitted global leaves the mark as it is.

{"verb": "set-session-space", "params": {"session": "work", "global": true}}

Request:

{"verb": "set-session-space", "params": {"session": "work", "space": "payments"}}

Response:

{"result": {"type": "session_space_set", "session": "work", "space": "payments", "global": false}}

Surrounding whitespace is trimmed first. A space name then follows the session name rules and is at most 64 bytes. Any other is refused with invalid_params on space. A global session cannot be in a space, so filing one without global: false is refused with invalid_params (a global session cannot be in a space) and nothing changes. new-session takes the same space param, refused the same way, and files the session as it is made, so it never exists in no space. Its result echoes space. Only these two verbs write a session's space: a client's state sync never moves it. A pane needs the admin grant, and over a link the verb needs write.

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