Protocol Verbs

Events and waiting

Events and waiting: 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.

subscribe Added in v0.8.0

Open a long-lived event stream on this connection. Without after_seq, events start at the moment of subscription. With after_seq, the stream first replays the retained events after that seq, so a reconnecting subscriber gets what it missed, and sends a gap marker with a reason when it cannot.

The connection stays open after the reply.

ParamTypeRequiredDefaultDescription
sessionstringOnly deliver events from this session. Omit for events from every session. Unlike most verbs, an omitted session does not mean the most recently active one.
windowstringOnly deliver events about this window id. Omit for every window.
types[]stringOnly deliver these event types. Omit for all of them. One of window-created, window-closed, window-exit, window-retitled, window-focused, window-moved, window-minimized, window-restored, workspace-switched, workspace-renamed, layout-changed, agent-state, agent-seen, agent-message, output, bell, notification, mode-changed, session-created, session-closed, session-labelled, client-session-changed, gap, attention, host-changed, prompt, command-started, command-finished, agent-activity, transcript, transfer, transfer-progress, transfer-file, daemon-upgraded, tml-event, tml-surface, task-claimed, task-finished, task-changed, task-dispatch, keep-awake or worktree-removed.
queueint256Buffered events before the stream marks a gap. A size above 4096 is lowered to 4096.
after_seqintResume: replay the retained events with a seq above this one before streaming live. Pass the seq of the last event received. 0 replays everything the daemon still holds. Output events are not retained.
boot_idstringThe boot_id the after_seq came with. If the daemon has restarted since, the stream starts with a gap marker with reason boot_changed instead of a replay. Needs after_seq.
hostsboolfalseAlso deliver the agent-state, session-created and session-closed events this daemon relays from its linked hosts, each carrying host, and let session and window match events of other machines. Without it an event about another machine reaches only a subscriber that names no session or window, and only an attention or host-changed event.
Result fieldTypeDescription
seqintThe last seq assigned when the stream went live. Every live event has a higher seq, and every replayed event has this seq or lower.
boot_idstringRandom id of this daemon start. Keep it with the seq, and pass both back to resume.
replayedintWith after_seq only: how many events are replayed before the live stream.
{"id":1,"verb":"subscribe","params":{"session":"work","types":["window-created","window-closed"]}}
{"id":1,"verb":"subscribe","params":{"types":["agent-state"],"after_seq":118,"boot_id":"9f2c41d07a3e8b65"}}

unsubscribe Added in v0.8.0

Close this connection's event stream.

No params.

{"id":1,"verb":"unsubscribe"}

wait-for Added in v0.8.0

Block until a condition matches, or fail with the timeout code.

ParamTypeRequiredDefaultDescription
conditionstringCondition to wait for. One of session-exists, window-output, window-exit, window-idle, agent-state, agent-message or command-finished.
sessionstringSession name. session-exists requires it: it is the session to wait for. For the other conditions, omit it from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
any_sessionboolfalseFor agent-state only: watch every session on the daemon, including ones created during the wait. Takes no session or window. The result names the session that matched.
patternstringRegular expression, required by window-output.
sourcestringrecentWhich buffer window-output matches against. The default includes scrollback, so output that has already scrolled past still matches. One of visible or recent.
newboolfalseFor window-output: match only the output the pane writes after the wait starts. Text already on the screen or in the scrollback does not match. A program that redraws its screen writes its text again, and that text matches. Takes no source.
idleint500Milliseconds of silence that count as idle, for window-idle.
untilstringAgent state(s) to wait for, comma-separated, required by agent-state. With no window, any window in the session reaching one of them matches. One of none, working, needs_input, idle, done, errored, unknown or limit_reached.
threadintNarrow agent-message to one thread. Pass any message id in the thread. A thread the ring holds nothing from never matches.
command_seqintFor command-finished with a window: match once the pane has finished more commands than this, which is already true when the command finished before the wait. Read it from list-windows or a run timeout. Without it, the next command to finish after the wait starts matches.
timeoutint30000Milliseconds to wait before failing with the timeout code, at most 86400000 (24 hours). The wait also ends when the caller closes the connection.
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). For agent-state only: watch the agent panes it matches, in every session, including panes that open during the wait. Takes no session, window or any_session. Put the state to wait for in until, not in the selector.
everyboolfalseWith select: match only when at least one pane matches and every matched pane is in one of the until states, and answer with all of them in panes. Without it, the first matched pane to reach one matches.
Result fieldTypeDescription
conditionstringThe condition that matched.
windowstringThe window that matched, for a condition about a window.
exit_codeintFor window-exit and command-finished: the exit status, -1 when a signal ended the process. Omitted when it is not known, such as for a window on another machine.
signalintFor window-exit: the signal that ended the process. Omitted when it exited on its own.
newboolFor window-output: true when the wait matched only output written after it started.
{"id":1,"verb":"wait-for","params":{"condition":"window-output","session":"work","pattern":"done","timeout":10000}}
{"id":1,"verb":"wait-for","params":{"condition":"agent-state","session":"work","until":"needs_input,idle"}}
{"id":1,"verb":"wait-for","params":{"condition":"agent-message","session":"work","window":"$TUIOS_PANE_ID"}}
{"id":1,"verb":"wait-for","params":{"condition":"agent-message","session":"work","window":"$TUIOS_PANE_ID","thread":12}}
{"id":1,"verb":"wait-for","params":{"condition":"agent-state","any_session":true,"until":"needs_input"}}
{"id":1,"verb":"wait-for","params":{"condition":"command-finished","session":"work","window":"build","command_seq":4,"timeout":600000}}
{"id":1,"verb":"wait-for","params":{"condition":"agent-state","select":"group:fan/add-retry","until":"idle,done","every":true}}
{"id":1,"verb":"wait-for","params":{"condition":"window-output","session":"work","window":"build","pattern":"BUILD OK","new":true}}

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